base

package standard library
go1.22.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 3, 2024 License: BSD-3-Clause Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const CompilerBootstrap = false

CompilerBootstrap reports whether the current compiler binary was built with -tags=compiler_bootstrap.

View Source 
const EnableTrace = false

To enable tracing support (-t flag), set EnableTrace to true.

Variables

View Source 
var AutogeneratedPos src.XPos
View Source 
var Ctxt *obj.Link
View Source 
var DebugSSA func(phase, flag string, val int, valString string) string

DebugSSA is called to set a -d ssa/... option. If nil, those options are reported as invalid options. If DebugSSA returns a non-empty string, that text is reported as a compiler error.

View Source 
var Pos src.XPos

Pos is the current source position being processed, printed by Errorf, ErrorfLang, Fatalf, and Warnf.

View Source 
var ReservedImports = map[string]bool{
	"go":   true,
	"type": true,
}

ReservedImports are import paths used internally for generated symbols by the compiler.

The linker uses the magic symbol prefixes "go:" and "type:". Avoid potential confusion between import paths and symbols by rejecting these reserved imports for now. Also, people "can do weird things in GOPATH and we'd prefer they didn't do _that_ weird thing" (per rsc). See also #4257.

Functions

func AdjustStartingHeap added in go1.20 

func AdjustStartingHeap(requestedHeapGoal uint64)

AdjustStartingHeap modifies GOGC so that GC should not occur until the heap grows to the requested size. This is intended but not promised, though it is true-mostly, depending on when the adjustment occurs and on the compiler's input and behavior. Once this size is approximately reached GOGC is reset to 100; subsequent GCs may reduce the heap below the requested size, but this function does not affect that.

-d=gcadjust=1 enables logging of GOGC adjustment events.

NOTE: If you think this code would help startup time in your own application and you decide to use it, please benchmark first to see if it actually works for you (it may not: the Go compiler is not typical), and whatever the outcome, please leave a comment on bug #56546. This code uses supported interfaces, but depends more than we like on current+observed behavior of the garbage collector, so if many people need this feature, we should consider/propose a better way to accomplish it.

func Assert added in go1.18 

func Assert(b bool)

Assert reports "assertion failed" with Fatalf, unless b is true.

func Assertf added in go1.18 

func Assertf(b bool, format string, args ...interface{})

Assertf reports a fatal error with Fatalf, unless b is true.

func AssertfAt added in go1.18 

func AssertfAt(b bool, pos src.XPos, format string, args ...interface{})

AssertfAt reports a fatal error with FatalfAt, unless b is true.

func AtExit 

func AtExit(f func())

func DebugHashMatchPkgFunc added in go1.21.0 

func DebugHashMatchPkgFunc(pkg, fn string) bool

DebugHashMatchPkgFunc reports whether debug variable Gossahash

  1. is empty (returns true; this is a special more-quickly implemented case of 4 below)

  2. is "y" or "Y" (returns true)

  3. is "n" or "N" (returns false)

  4. does not explicitly exclude the sha1 hash of pkgAndName (see step 6)

  5. is a suffix of the sha1 hash of pkgAndName (returns true)

  6. OR if the (non-empty) value is in the regular language "(-[01]+/)+?([01]+(/[01]+)+?" (exclude..)(....include...) test the [01]+ exclude substrings, if any suffix-match, return false (4 above) test the [01]+ include substrings, if any suffix-match, return true The include substrings AFTER the first slash are numbered 0,1, etc and are named fmt.Sprintf("%s%d", varname, number) As an extra-special case for multiple failure search, an excludes-only string ending in a slash (terminated, not separated) implicitly specifies the include string "0/1", that is, match everything. (Exclude strings are used for automated search for multiple failures.) Clause 6 is not really intended for human use and only matters for failures that require multiple triggers.

Otherwise it returns false.

Unless Flags.Gossahash is empty, when DebugHashMatchPkgFunc returns true the message 

"%s triggered %s\n", varname, pkgAndName

is printed on the file named in environment variable GSHS_LOGFILE, or standard out if that is empty. "Varname" is either the name of the variable or the name of the substring, depending on which matched.

Typical use:

  1. you make a change to the compiler, say, adding a new phase

  2. it is broken in some mystifying way, for example, make.bash builds a broken compiler that almost works, but crashes compiling a test in run.bash.

  3. add this guard to the code, which by default leaves it broken, but does not run the broken new code if Flags.Gossahash is non-empty and non-matching:

    if !base.DebugHashMatch(ir.PkgFuncName(fn)) { return nil // early exit, do nothing }

  4. rebuild w/o the bad code, GOCOMPILEDEBUG=gossahash=n ./all.bash to verify that you put the guard in the right place with the right sense of the test.

  5. use github.com/dr2chase/gossahash to search for the error:

    go install github.com/dr2chase/gossahash@latest

    gossahash -- <the thing that fails>

    for example: GOMAXPROCS=1 gossahash -- ./all.bash

  6. gossahash should return a single function whose miscompilation causes the problem, and you can focus on that.

func DebugHashMatchPos added in go1.21.0 

func DebugHashMatchPos(pos src.XPos) bool

func ErrorExit 

func ErrorExit()

ErrorExit handles an error-status exit. It flushes any pending errors, removes the output file, and exits.

func Errorf 

func Errorf(format string, args ...interface{})

Errorf reports a formatted error at the current line.

func ErrorfAt 

func ErrorfAt(pos src.XPos, code errors.Code, format string, args ...interface{})

ErrorfAt reports a formatted error message at pos.

func Errors 

func Errors() int

Errors returns the number of errors reported.

func Exit 

func Exit(code int)

func ExitIfErrors 

func ExitIfErrors()

ExitIfErrors calls ErrorExit if any errors have been reported.

func Fatalf 

func Fatalf(format string, args ...interface{})

Fatalf reports a fatal error - an internal problem - at the current line and exits. If other errors have already been printed, then Fatalf just quietly exits. (The internal problem may have been caused by incomplete information after the already-reported errors, so best to let users fix those and try again without being bothered about a spurious internal error.)

But if no errors have been printed, or if -d panic has been specified, Fatalf prints the error as an "internal compiler error". In a released build, it prints an error asking to file a bug report. In development builds, it prints a stack trace.

If -h has been specified, Fatalf panics to force the usual runtime info dump.

func FatalfAt 

func FatalfAt(pos src.XPos, format string, args ...interface{})

FatalfAt reports a fatal error - an internal problem - at pos and exits. If other errors have already been printed, then FatalfAt just quietly exits. (The internal problem may have been caused by incomplete information after the already-reported errors, so best to let users fix those and try again without being bothered about a spurious internal error.)

But if no errors have been printed, or if -d panic has been specified, FatalfAt prints the error as an "internal compiler error". In a released build, it prints an error asking to file a bug report. In development builds, it prints a stack trace.

If -h has been specified, FatalfAt panics to force the usual runtime info dump.

func FlushErrors 

func FlushErrors()

FlushErrors sorts errors seen so far by line number, prints them to stdout, and empties the errors array.

func FmtPos 

func FmtPos(pos src.XPos) string

FmtPos formats pos as a file:line string.

func HasDebugHash added in go1.20 

func HasDebugHash() bool

HasDebugHash returns true if Flags.Gossahash is non-empty, which results in hashDebug being not-nil. I.e., if !HasDebugHash(), there is no need to create the string for hashing and testing.

func Linkname 

func Linkname(name string, abi obj.ABI) *obj.LSym

Linkname returns the linker symbol for the given name as it might appear within a //go:linkname directive.

func MapFile added in go1.18 

func MapFile(f *os.File, offset, length int64) (string, error)

MapFile returns length bytes from the file starting at the specified offset as a string.

func ParseFlags 

func ParseFlags()

ParseFlags parses the command-line flags into Flag.

func PkgLinksym 

func PkgLinksym(prefix, name string, abi obj.ABI) *obj.LSym

PkgLinksym returns the linker symbol for name within the given package prefix. For user packages, prefix should be the package path encoded with objabi.PathToPrefix.

func SyntaxErrors 

func SyntaxErrors() int

SyntaxErrors returns the number of syntax errors reported.

func UpdateErrorDot 

func UpdateErrorDot(line string, name, expr string)

UpdateErrorDot is a clumsy hack that rewrites the last error, if it was "LINE: undefined: NAME", to be "LINE: undefined: NAME in EXPR". It is used to give better error messages for dot (selector) expressions.

func Warn 

func Warn(format string, args ...interface{})

Warn reports a formatted warning at the current line. In general the Go compiler does NOT generate warnings, so this should be used only when the user has opted in to additional output by setting a particular flag.

func WarnfAt 

func WarnfAt(pos src.XPos, format string, args ...interface{})

WarnfAt reports a formatted warning at pos. In general the Go compiler does NOT generate warnings, so this should be used only when the user has opted in to additional output by setting a particular flag.

Types

type CmdFlags 

type CmdFlags struct {
	// Single letters
	B CountFlag    "help:\"disable bounds checking\""
	C CountFlag    "help:\"disable printing of columns in error messages\""
	D string       "help:\"set relative `path` for local imports\""
	E CountFlag    "help:\"debug symbol export\""
	I func(string) "help:\"add `directory` to import search path\""
	K CountFlag    "help:\"debug missing line numbers\""
	L CountFlag    "help:\"also show actual source file names in error messages for positions affected by //line directives\""
	N CountFlag    "help:\"disable optimizations\""
	S CountFlag    "help:\"print assembly listing\""
	// V is added by objabi.AddVersionFlag
	W CountFlag "help:\"debug parse tree after type checking\""

	LowerC int        "help:\"concurrency during compilation (1 means no concurrency)\""
	LowerD flag.Value "help:\"enable debugging settings; try -d help\""
	LowerE CountFlag  "help:\"no limit on number of errors reported\""
	LowerH CountFlag  "help:\"halt on error\""
	LowerJ CountFlag  "help:\"debug runtime-initialized variables\""
	LowerL CountFlag  "help:\"disable inlining\""
	LowerM CountFlag  "help:\"print optimization decisions\""
	LowerO string     "help:\"write output to `file`\""
	LowerP *string    "help:\"set expected package import `path`\"" // &Ctxt.Pkgpath, set below
	LowerR CountFlag  "help:\"debug generated wrappers\""
	LowerT bool       "help:\"enable tracing for debugging the compiler\""
	LowerW CountFlag  "help:\"debug type checking\""
	LowerV *bool      "help:\"increase debug verbosity\""

	// Special characters
	Percent          CountFlag "flag:\"%\" help:\"debug non-static initializers\""
	CompilingRuntime bool      "flag:\"+\" help:\"compiling runtime\""

	// Longer names
	AsmHdr             string       "help:\"write assembly header to `file`\""
	ASan               bool         "help:\"build code compatible with C/C++ address sanitizer\""
	Bench              string       "help:\"append benchmark times to `file`\""
	BlockProfile       string       "help:\"write block profile to `file`\""
	BuildID            string       "help:\"record `id` as the build id in the export metadata\""
	CPUProfile         string       "help:\"write cpu profile to `file`\""
	Complete           bool         "help:\"compiling complete package (no C or assembly)\""
	ClobberDead        bool         "help:\"clobber dead stack slots (for debugging)\""
	ClobberDeadReg     bool         "help:\"clobber dead registers (for debugging)\""
	Dwarf              bool         "help:\"generate DWARF symbols\""
	DwarfBASEntries    *bool        "help:\"use base address selection entries in DWARF\""                        // &Ctxt.UseBASEntries, set below
	DwarfLocationLists *bool        "help:\"add location lists to DWARF in optimized mode\""                      // &Ctxt.Flag_locationlists, set below
	Dynlink            *bool        "help:\"support references to Go symbols defined in other shared libraries\"" // &Ctxt.Flag_dynlink, set below
	EmbedCfg           func(string) "help:\"read go:embed configuration from `file`\""
	Env                func(string) "help:\"add `definition` of the form key=value to environment\""
	GenDwarfInl        int          "help:\"generate DWARF inline info records\"" // 0=disabled, 1=funcs, 2=funcs+formals/locals
	GoVersion          string       "help:\"required version of the runtime\""
	ImportCfg          func(string) "help:\"read import configuration from `file`\""
	InstallSuffix      string       "help:\"set pkg directory `suffix`\""
	JSON               string       "help:\"version,file for JSON compiler/optimizer detail output\""
	Lang               string       "help:\"Go language version source code expects\""
	LinkObj            string       "help:\"write linker-specific object to `file`\""
	LinkShared         *bool        "help:\"generate code that will be linked against Go shared libraries\"" // &Ctxt.Flag_linkshared, set below
	Live               CountFlag    "help:\"debug liveness analysis\""
	MSan               bool         "help:\"build code compatible with C/C++ memory sanitizer\""
	MemProfile         string       "help:\"write memory profile to `file`\""
	MemProfileRate     int          "help:\"set runtime.MemProfileRate to `rate`\""
	MutexProfile       string       "help:\"write mutex profile to `file`\""
	NoLocalImports     bool         "help:\"reject local (relative) imports\""
	CoverageCfg        func(string) "help:\"read coverage configuration from `file`\""
	Pack               bool         "help:\"write to file.a instead of file.o\""
	Race               bool         "help:\"enable race detector\""
	Shared             *bool        "help:\"generate code that can be linked into a shared library\"" // &Ctxt.Flag_shared, set below
	SmallFrames        bool         "help:\"reduce the size limit for stack allocated objects\""      // small stacks, to diagnose GC latency; see golang.org/issue/27732
	Spectre            string       "help:\"enable spectre mitigations in `list` (all, index, ret)\""
	Std                bool         "help:\"compiling standard library\""
	SymABIs            string       "help:\"read symbol ABIs from `file`\""
	TraceProfile       string       "help:\"write an execution trace to `file`\""
	TrimPath           string       "help:\"remove `prefix` from recorded source file paths\""
	WB                 bool         "help:\"enable write barrier\"" // TODO: remove
	PgoProfile         string       "help:\"read profile from `file`\""
	ErrorURL           bool         "help:\"print explanatory URL with error message if applicable\""

	// Configuration derived from flags; not a flag itself.
	Cfg struct {
		Embed struct {
			Patterns map[string][]string
			Files    map[string]string
		}
		ImportDirs   []string                 // appended to by -I
		ImportMap    map[string]string        // set by -importcfg
		PackageFile  map[string]string        // set by -importcfg; nil means not in use
		CoverageInfo *covcmd.CoverFixupConfig // set by -coveragecfg
		SpectreIndex bool                     // set by -spectre=index or -spectre=all
		// Whether we are adding any sort of code instrumentation, such as
		// when the race detector is enabled.
		Instrumenting bool
	}
}

CmdFlags defines the command-line flags (see var Flag). Each struct field is a different flag, by default named for the lower-case of the field name. If the flag name is a single letter, the default flag name is left upper-case. If the flag name is "Lower" followed by a single letter, the default flag name is the lower-case of the last letter.

If this default flag name can't be made right, the `flag` struct tag can be used to replace it, but this should be done only in exceptional circumstances: it helps everyone if the flag name is obvious from the field name when the flag is used elsewhere in the compiler sources. The `flag:"-"` struct tag makes a field invisible to the flag logic and should also be used sparingly.

Each field must have a `help` struct tag giving the flag help message.

The allowed field types are bool, int, string, pointers to those (for values stored elsewhere), CountFlag (for a counting flag), and func(string) (for a flag that uses special code for parsing). 

var Flag CmdFlags

Flag holds the parsed command-line flags. See ParseFlag for non-zero defaults.

type CountFlag 

type CountFlag int

A CountFlag is a counting integer flag. It accepts -name=value to set the value directly, but it also accepts -name with no =value to increment the count.

type DebugFlags 

type DebugFlags struct {
	Append                int    `help:"print information about append compilation"`
	Checkptr              int    `` /* 203-byte string literal not displayed */
	Closure               int    `help:"print information about closure compilation"`
	Defer                 int    `help:"print information about defer compilation"`
	DisableNil            int    `help:"disable nil checks" concurrent:"ok"`
	DumpInlFuncProps      string `help:"dump function properties from inl heuristics to specified file"`
	DumpInlCallSiteScores int    `help:"dump scored callsites during inlining"`
	InlScoreAdj           string `help:"set inliner score adjustments (ex: -d=inlscoreadj=panicPathAdj:10/passConstToNestedIfAdj:-90)"`
	InlBudgetSlack        int    `help:"amount to expand the initial inline budget when new inliner enabled. Defaults to 80 if option not set." concurrent:"ok"`
	DumpPtrs              int    `help:"show Node pointers values in dump output"`
	DwarfInl              int    `help:"print information about DWARF inlined function creation"`
	EscapeMutationsCalls  int    `help:"print extra escape analysis diagnostics about mutations and calls" concurrent:"ok"`
	Export                int    `help:"print export data"`
	Fmahash               string `help:"hash value for use in debugging platform-dependent multiply-add use" concurrent:"ok"`
	GCAdjust              int    `help:"log adjustments to GOGC" concurrent:"ok"`
	GCCheck               int    `help:"check heap/gc use by compiler" concurrent:"ok"`
	GCProg                int    `help:"print dump of GC programs"`
	Gossahash             string `help:"hash value for use in debugging the compiler"`
	InlFuncsWithClosures  int    `help:"allow functions with closures to be inlined" concurrent:"ok"`
	InlStaticInit         int    `help:"allow static initialization of inlined calls" concurrent:"ok"`
	Libfuzzer             int    `help:"enable coverage instrumentation for libfuzzer"`
	LoopVar               int    `help:"shared (0, default), 1 (private loop variables), 2, private + log"`
	LoopVarHash           string `help:"for debugging changes in loop behavior. Overrides experiment and loopvar flag."`
	LocationLists         int    `help:"print information about DWARF location list creation"`
	MaxShapeLen           int    `help:"hash shape names longer than this threshold (default 500)" concurrent:"ok"`
	Nil                   int    `help:"print information about nil checks"`
	NoOpenDefer           int    `help:"disable open-coded defers" concurrent:"ok"`
	NoRefName             int    `help:"do not include referenced symbol names in object file" concurrent:"ok"`
	PCTab                 string `help:"print named pc-value table\nOne of: pctospadj, pctofile, pctoline, pctoinline, pctopcdata"`
	Panic                 int    `help:"show all compiler panics"`
	Reshape               int    `help:"print information about expression reshaping"`
	Shapify               int    `help:"print information about shaping recursive types"`
	Slice                 int    `help:"print information about slice compilation"`
	SoftFloat             int    `help:"force compiler to emit soft-float code" concurrent:"ok"`
	StaticCopy            int    `help:"print information about missed static copies" concurrent:"ok"`
	SyncFrames            int    `help:"how many writer stack frames to include at sync points in unified export data"`
	TypeAssert            int    `help:"print information about type assertion inlining"`
	WB                    int    `help:"print information about write barriers"`
	ABIWrap               int    `help:"print information about ABI wrapper generation"`
	MayMoreStack          string `help:"call named function before all stack growth checks" concurrent:"ok"`
	PGODebug              int    `help:"debug profile-guided optimizations"`
	PGOHash               string `help:"hash value for debugging profile-guided optimizations" concurrent:"ok"`
	PGOInline             int    `help:"enable profile-guided inlining" concurrent:"ok"`
	PGOInlineCDFThreshold string `help:"cumulative threshold percentage for determining call sites as hot candidates for inlining" concurrent:"ok"`
	PGOInlineBudget       int    `help:"inline budget for hot functions" concurrent:"ok"`
	PGODevirtualize       int    `` /* 154-byte string literal not displayed */
	RangeFuncCheck        int    `help:"insert code to check behavior of range iterator functions" concurrent:"ok"`
	WrapGlobalMapDbg      int    `help:"debug trace output for global map init wrapping"`
	WrapGlobalMapCtl      int    `help:"global map init wrap control (0 => default, 1 => off, 2 => stress mode, no size cutoff)"`
	ZeroCopy              int    `help:"enable zero-copy string->[]byte conversions" concurrent:"ok"`

	ConcurrentOk bool // true if only concurrentOk flags seen
}

DebugFlags defines the debugging configuration values (see var Debug). Each struct field is a different value, named for the lower-case of the field name. Each field must be an int or string and must have a `help` struct tag.

The -d option takes a comma-separated list of settings. Each setting is name=value; for ints, name is short for name=1. 

var Debug DebugFlags

Debug holds the parsed debugging configuration values.

type HashDebug added in go1.20 

type HashDebug struct {
	// contains filtered or unexported fields
}
var FmaHash *HashDebug // for debugging fused-multiply-add floating point changes

var LoopVarHash *HashDebug // for debugging shared/private loop variable changes

var PGOHash *HashDebug // for debugging PGO optimization decisions

func NewHashDebug added in go1.20 

func NewHashDebug(ev, s string, file io.Writer) *HashDebug

NewHashDebug returns a new hash-debug tester for the environment variable ev. If ev is not set, it returns nil, allowing a lightweight check for normal-case behavior.

func (*HashDebug) MatchPkgFunc added in go1.21.0 

func (d *HashDebug) MatchPkgFunc(pkg, fn string, note func() string) bool

MatchPkgFunc returns true if either the variable used to create d is unset, or if its value is y, or if it is a suffix of the base-two representation of the hash of pkg and fn. If the variable is not nil, then a true result is accompanied by stylized output to d.logfile, which is used for automated bug search.

func (*HashDebug) MatchPos added in go1.21.0 

func (d *HashDebug) MatchPos(pos src.XPos, desc func() string) bool

MatchPos is similar to MatchPkgFunc, but for hash computation it uses the source position including all inlining information instead of package name and path. Note that the default answer for no environment variable (d == nil) is "yes", do the thing.

func (*HashDebug) MatchPosWithInfo added in go1.22.0 

func (d *HashDebug) MatchPosWithInfo(pos src.XPos, info any, desc func() string) bool

MatchPosWithInfo is similar to MatchPos, but with additional information that is included for hash computation, so it can distinguish multiple matches on the same source location. Note that the default answer for no environment variable (d == nil) is "yes", do the thing.

func (*HashDebug) SetInlineSuffixOnly added in go1.21.0 

func (d *HashDebug) SetInlineSuffixOnly(b bool) *HashDebug

SetInlineSuffixOnly controls whether hashing and reporting use the entire inline position, or just the most-inline suffix. Compiler debugging tends to want the whole inlining, debugging user problems (loopvarhash, e.g.) typically does not need to see the entire inline tree, there is just one copy of the source code.

type Timings 

type Timings struct {
	// contains filtered or unexported fields
}

Timings collects the execution times of labeled phases which are added through a sequence of Start/Stop calls. Events may be associated with each phase via AddEvent. 

var Timer Timings

func (*Timings) AddEvent 

func (t *Timings) AddEvent(size int64, unit string)

AddEvent associates an event, i.e., a count, or an amount of data, with the most recently started or stopped phase; or the very first phase if Start or Stop hasn't been called yet. The unit specifies the unit of measurement (e.g., MB, lines, no. of funcs, etc.).

func (*Timings) Start 

func (t *Timings) Start(labels ...string)

Start marks the beginning of a new phase and implicitly stops the previous phase. The phase name is the colon-separated concatenation of the labels.

func (*Timings) Stop 

func (t *Timings) Stop(labels ...string)

Stop marks the end of a phase and implicitly starts a new phase. The labels are added to the labels of the ended phase.

func (*Timings) Write 

func (t *Timings) Write(w io.Writer, prefix string)

Write prints the phase times to w. The prefix is printed at the start of each line.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.