Adding upstream version 1.16.10.upstream/1.16.10upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 258 insertions, 0 deletions

diff --git a/src/cmd/compile/doc.go b/src/cmd/compile/doc.go
new file mode 100644
index 0000000..46d4722
--- /dev/null
+++ b/src/cmd/compile/doc.go
@@ -0,0 +1,258 @@
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Compile, typically invoked as ``go tool compile,'' compiles a single Go package
+comprising the files named on the command line. It then writes a single
+object file named for the basename of the first source file with a .o suffix.
+The object file can then be combined with other objects into a package archive
+or passed directly to the linker (``go tool link''). If invoked with -pack, the compiler
+writes an archive directly, bypassing the intermediate object file.
+
+The generated files contain type information about the symbols exported by
+the package and about types used by symbols imported by the package from
+other packages. It is therefore not necessary when compiling client C of
+package P to read the files of P's dependencies, only the compiled output of P.
+
+Command Line
+
+Usage:
+
+	go tool compile [flags] file...
+
+The specified files must be Go source files and all part of the same package.
+The same compiler is used for all target operating systems and architectures.
+The GOOS and GOARCH environment variables set the desired target.
+
+Flags:
+
+	-D path
+		Set relative path for local imports.
+	-I dir1 -I dir2
+		Search for imported packages in dir1, dir2, etc,
+		after consulting $GOROOT/pkg/$GOOS_$GOARCH.
+	-L
+		Show complete file path in error messages.
+	-N
+		Disable optimizations.
+	-S
+		Print assembly listing to standard output (code only).
+	-S -S
+		Print assembly listing to standard output (code and data).
+	-V
+		Print compiler version and exit.
+	-asmhdr file
+		Write assembly header to file.
+	-buildid id
+		Record id as the build id in the export metadata.
+	-blockprofile file
+		Write block profile for the compilation to file.
+	-c int
+		Concurrency during compilation. Set 1 for no concurrency (default is 1).
+	-complete
+		Assume package has no non-Go components.
+	-cpuprofile file
+		Write a CPU profile for the compilation to file.
+	-dynlink
+		Allow references to Go symbols in shared libraries (experimental).
+	-e
+		Remove the limit on the number of errors reported (default limit is 10).
+	-goversion string
+		Specify required go tool version of the runtime.
+		Exits when the runtime go version does not match goversion.
+	-h
+		Halt with a stack trace at the first error detected.
+	-importcfg file
+		Read import configuration from file.
+		In the file, set importmap, packagefile to specify import resolution.
+	-importmap old=new
+		Interpret import "old" as import "new" during compilation.
+		The option may be repeated to add multiple mappings.
+	-installsuffix suffix
+		Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix
+		instead of $GOROOT/pkg/$GOOS_$GOARCH.
+	-l
+		Disable inlining.
+	-lang version
+		Set language version to compile, as in -lang=go1.12.
+		Default is current version.
+	-linkobj file
+		Write linker-specific object to file and compiler-specific
+		object to usual output file (as specified by -o).
+		Without this flag, the -o output is a combination of both
+		linker and compiler input.
+	-m
+		Print optimization decisions.
+	-memprofile file
+		Write memory profile for the compilation to file.
+	-memprofilerate rate
+		Set runtime.MemProfileRate for the compilation to rate.
+	-msan
+		Insert calls to C/C++ memory sanitizer.
+	-mutexprofile file
+		Write mutex profile for the compilation to file.
+	-nolocalimports
+		Disallow local (relative) imports.
+	-o file
+		Write object to file (default file.o or, with -pack, file.a).
+	-p path
+		Set expected package import path for the code being compiled,
+		and diagnose imports that would cause a circular dependency.
+	-pack
+		Write a package (archive) file rather than an object file
+	-race
+		Compile with race detector enabled.
+	-s
+		Warn about composite literals that can be simplified.
+	-shared
+		Generate code that can be linked into a shared library.
+	-spectre list
+		Enable spectre mitigations in list (all, index, ret).
+	-traceprofile file
+		Write an execution trace to file.
+	-trimpath prefix
+		Remove prefix from recorded source file paths.
+
+Flags related to debugging information:
+
+	-dwarf
+		Generate DWARF symbols.
+	-dwarflocationlists
+		Add location lists to DWARF in optimized mode.
+	-gendwarfinl int
+		Generate DWARF inline info records (default 2).
+
+Flags to debug the compiler itself:
+
+	-E
+		Debug symbol export.
+	-K
+		Debug missing line numbers.
+	-d list
+		Print debug information about items in list. Try -d help for further information.
+	-live
+		Debug liveness analysis.
+	-v
+		Increase debug verbosity.
+	-%
+		Debug non-static initializers.
+	-W
+		Debug parse tree after type checking.
+	-f
+		Debug stack frames.
+	-i
+		Debug line number stack.
+	-j
+		Debug runtime-initialized variables.
+	-r
+		Debug generated wrappers.
+	-w
+		Debug type checking.
+
+Compiler Directives
+
+The compiler accepts directives in the form of comments.
+To distinguish them from non-directive comments, directives
+require no space between the comment opening and the name of the directive. However, since
+they are comments, tools unaware of the directive convention or of a particular
+directive can skip over a directive like any other comment.
+*/
+// Line directives come in several forms:
+//
+// 	//line :line
+// 	//line :line:col
+// 	//line filename:line
+// 	//line filename:line:col
+// 	/*line :line*/
+// 	/*line :line:col*/
+// 	/*line filename:line*/
+// 	/*line filename:line:col*/
+//
+// In order to be recognized as a line directive, the comment must start with
+// //line or /*line followed by a space, and must contain at least one colon.
+// The //line form must start at the beginning of a line.
+// A line directive specifies the source position for the character immediately following
+// the comment as having come from the specified file, line and column:
+// For a //line comment, this is the first character of the next line, and
+// for a /*line comment this is the character position immediately following the closing */.
+// If no filename is given, the recorded filename is empty if there is also no column number;
+// otherwise it is the most recently recorded filename (actual filename or filename specified
+// by previous line directive).
+// If a line directive doesn't specify a column number, the column is "unknown" until
+// the next directive and the compiler does not report column numbers for that range.
+// The line directive text is interpreted from the back: First the trailing :ddd is peeled
+// off from the directive text if ddd is a valid number > 0. Then the second :ddd
+// is peeled off the same way if it is valid. Anything before that is considered the filename
+// (possibly including blanks and colons). Invalid line or column values are reported as errors.
+//
+// Examples:
+//
+//	//line foo.go:10      the filename is foo.go, and the line number is 10 for the next line
+//	//line C:foo.go:10    colons are permitted in filenames, here the filename is C:foo.go, and the line is 10
+//	//line  a:100 :10     blanks are permitted in filenames, here the filename is " a:100 " (excluding quotes)
+//	/*line :10:20*/x      the position of x is in the current file with line number 10 and column number 20
+//	/*line foo: 10 */     this comment is recognized as invalid line directive (extra blanks around line number)
+//
+// Line directives typically appear in machine-generated code, so that compilers and debuggers
+// will report positions in the original input to the generator.
+/*
+The line directive is a historical special case; all other directives are of the form
+//go:name, indicating that they are defined by the Go toolchain.
+Each directive must be placed its own line, with only leading spaces and tabs
+allowed before the comment.
+Each directive applies to the Go code that immediately follows it,
+which typically must be a declaration.
+
+	//go:noescape
+
+The //go:noescape directive must be followed by a function declaration without
+a body (meaning that the function has an implementation not written in Go).
+It specifies that the function does not allow any of the pointers passed as
+arguments to escape into the heap or into the values returned from the function.
+This information can be used during the compiler's escape analysis of Go code
+calling the function.
+
+	//go:uintptrescapes
+
+The //go:uintptrescapes directive must be followed by a function declaration.
+It specifies that the function's uintptr arguments may be pointer values
+that have been converted to uintptr and must be treated as such by the
+garbage collector. The conversion from pointer to uintptr must appear in
+the argument list of any call to this function. This directive is necessary
+for some low-level system call implementations and should be avoided otherwise.
+
+	//go:noinline
+
+The //go:noinline directive must be followed by a function declaration.
+It specifies that calls to the function should not be inlined, overriding
+the compiler's usual optimization rules. This is typically only needed
+for special runtime functions or when debugging the compiler.
+
+	//go:norace
+
+The //go:norace directive must be followed by a function declaration.
+It specifies that the function's memory accesses must be ignored by the
+race detector. This is most commonly used in low-level code invoked
+at times when it is unsafe to call into the race detector runtime.
+
+	//go:nosplit
+
+The //go:nosplit directive must be followed by a function declaration.
+It specifies that the function must omit its usual stack overflow check.
+This is most commonly used by low-level runtime code invoked
+at times when it is unsafe for the calling goroutine to be preempted.
+
+	//go:linkname localname [importpath.name]
+
+This special directive does not apply to the Go code that follows it.
+Instead, the //go:linkname directive instructs the compiler to use ``importpath.name''
+as the object file symbol name for the variable or function declared as ``localname''
+in the source code.
+If the ``importpath.name'' argument is omitted, the directive uses the
+symbol's default object file symbol name and only has the effect of making
+the symbol accessible to other packages.
+Because this directive can subvert the type system and package
+modularity, it is only enabled in files that have imported "unsafe".
+*/
+package main