src/internal/goexperiment/flags.go

   1 // Copyright 2021 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 // Package goexperiment implements support for toolchain experiments.
   6 //
   7 // Toolchain experiments are controlled by the GOEXPERIMENT
   8 // environment variable. GOEXPERIMENT is a comma-separated list of
   9 // experiment names. GOEXPERIMENT can be set at make.bash time, which
  10 // sets the default experiments for binaries built with the tool
  11 // chain; or it can be set at build time. GOEXPERIMENT can also be set
  12 // to "none", which disables any experiments that were enabled at
  13 // make.bash time.
  14 //
  15 // Experiments are exposed to the build in the following ways:
  16 //
  17 // - Build tag goexperiment.x is set if experiment x (lower case) is
  18 // enabled.
  19 //
  20 // - For each experiment x (in camel case), this package contains a
  21 // boolean constant x and an integer constant xInt.
  22 //
  23 // - In runtime assembly, the macro GOEXPERIMENT_x is defined if
  24 // experiment x (lower case) is enabled.
  25 //
  26 // In the toolchain, the set of experiments enabled for the current
  27 // build should be accessed via objabi.Experiment.
  28 //
  29 // The set of experiments is included in the output of runtime.Version()
  30 // and "go version <binary>" if it differs from the default experiments.
  31 //
  32 // For the set of experiments supported by the current toolchain, see
  33 // "go doc goexperiment.Flags".
  34 //
  35 // Note that this package defines the set of experiments (in Flags)
  36 // and records the experiments that were enabled when the package
  37 // was compiled (as boolean and integer constants).
  38 //
  39 // Note especially that this package does not itself change behavior
  40 // at run time based on the GOEXPERIMENT variable.
  41 // The code used in builds to interpret the GOEXPERIMENT variable
  42 // is in the separate package internal/buildcfg.
  43 package goexperiment
  44
  45 //go:generate go run mkconsts.go
  46
  47 // Flags is the set of experiments that can be enabled or disabled in
  48 // the current toolchain.
  49 //
  50 // When specified in the GOEXPERIMENT environment variable or as build
  51 // tags, experiments use the strings.ToLower of their field name.
  52 //
  53 // For the baseline experimental configuration, see
  54 // objabi.experimentBaseline.
  55 //
  56 // If you change this struct definition, run "go generate".
  57 type Flags struct {
  58         FieldTrack        bool
  59         PreemptibleLoops  bool
  60         StaticLockRanking bool
  61         BoringCrypto      bool
  62
  63         // Regabi is split into several sub-experiments that can be
  64         // enabled individually. Not all combinations work.
  65         // The "regabi" GOEXPERIMENT is an alias for all "working"
  66         // subexperiments.
  67
  68         // RegabiWrappers enables ABI wrappers for calling between
  69         // ABI0 and ABIInternal functions. Without this, the ABIs are
  70         // assumed to be identical so cross-ABI calls are direct.
  71         RegabiWrappers bool
  72         // RegabiArgs enables register arguments/results in all
  73         // compiled Go functions.
  74         //
  75         // Requires wrappers (to do ABI translation), and reflect (so
  76         // reflection calls use registers).
  77         RegabiArgs bool
  78
  79         // HeapMinimum512KiB reduces the minimum heap size to 512 KiB.
  80         //
  81         // This was originally reduced as part of PacerRedesign, but
  82         // has been broken out to its own experiment that is disabled
  83         // by default.
  84         HeapMinimum512KiB bool
  85
  86         // CoverageRedesign enables the new compiler-based code coverage
  87         // tooling.
  88         CoverageRedesign bool
  89
  90         // Arenas causes the "arena" standard library package to be visible
  91         // to the outside world.
  92         Arenas bool
  93
  94         // PageTrace enables GODEBUG=pagetrace=/path/to/result. This feature
  95         // is a GOEXPERIMENT due to a security risk with setuid binaries:
  96         // this compels the Go runtime to write to some arbitrary file, which
  97         // may be exploited.
  98         PageTrace bool
  99
 100         // CgoCheck2 enables an expensive cgo rule checker.
 101         // When this experiment is enabled, cgo rule checks occur regardless
 102         // of the GODEBUG=cgocheck setting provided at runtime.
 103         CgoCheck2 bool
 104
 105         // LoopVar changes loop semantics so that each iteration gets its own
 106         // copy of the iteration variable.
 107         LoopVar bool
 108
 109         // CacheProg adds support to cmd/go to use a child process to implement
 110         // the build cache; see https://github.com/golang/go/issues/59719.
 111         CacheProg bool
 112
 113         // NewInliner enables a new+improved version of the function
 114         // inlining phase within the Go compiler.
 115         NewInliner bool
 116
 117         // RangeFunc enables range over func.
 118         RangeFunc bool
 119 }