Source file 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  
   120  	// Range enables range over int and func.
   121  	Range bool
   122  
   123  	// AllocHeaders enables a different, more efficient way for the GC to
   124  	// manage heap metadata.
   125  	AllocHeaders bool
   126  
   127  	// ExecTracer2 controls whether to use the new execution trace
   128  	// implementation.
   129  	ExecTracer2 bool
   130  }
   131  

View as plain text