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.
43package 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".
57type 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	// CgoCheck2 enables an expensive cgo rule checker.
95	// When this experiment is enabled, cgo rule checks occur regardless
96	// of the GODEBUG=cgocheck setting provided at runtime.
97	CgoCheck2 bool
98
99	// LoopVar changes loop semantics so that each iteration gets its own
100	// copy of the iteration variable.
101	LoopVar bool
102
103	// CacheProg adds support to cmd/go to use a child process to implement
104	// the build cache; see https://github.com/golang/go/issues/59719.
105	CacheProg bool
106
107	// NewInliner enables a new+improved version of the function
108	// inlining phase within the Go compiler.
109	NewInliner bool
110
111	// RangeFunc enables range over func.
112	RangeFunc bool
113
114	// AliasTypeParams enables type parameters for alias types.
115	// Requires that gotypesalias=1 is set with GODEBUG.
116	// This flag will be removed with Go 1.24.
117	AliasTypeParams bool
118}
119