diff options
Diffstat (limited to 'man/go-build.1')
| -rw-r--r-- | man/go-build.1 | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/man/go-build.1 b/man/go-build.1 new file mode 100644 index 0000000..22f0186 --- /dev/null +++ b/man/go-build.1 @@ -0,0 +1,216 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-BUILD 1 "2022-08-02" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-build \- compile the packages named by the import paths +.SH SYNOPSIS +.B go build +.RB [ \-o +.IR output ] +.RI [ "build flags" ] +.RI [ packages ] +.SH DESCRIPTION +Build compiles the packages named by the import paths, +along with their dependencies, but it does not install the results. +.P +If the arguments to build are a list of .go files from a single directory, +build treats them as a list of source files specifying a single package. +.P +When compiling packages, build ignores files that end in \(oq_test.go\(cq. +.P +When compiling a single main package, build writes +the resulting executable to an output file named after +the first source file (\(oqgo build ed.go rx.go\(cq writes \(oqed\(cq or \(oqed.exe\(cq) +or the source code directory (\(oqgo build unix/sam\(cq writes \(oqsam\(cq or \(oqsam.exe\(cq). +The \(oq.exe\(cq suffix is added when writing a Windows executable. +.P +When compiling multiple packages or a single non-main package, +build compiles the packages but discards the resulting object, +serving only as a check that the packages can be built. +.P +The \-o flag forces build to write the resulting executable or object +to the named output file or directory, instead of the default behavior described +in the last two paragraphs. If the named output is an existing directory or +ends with a slash or backslash, then any resulting executables +will be written to that directory. +.P +The \-i flag installs the packages that are dependencies of the target. +.br +The \-i flag is deprecated. Compiled packages are cached automatically. +.SH OPTIONS +The build flags are shared by the build, clean, get, install, list, run, +and test commands: +.TP +.B \-a +force rebuilding of packages that are already up-to-date. +.TP +.B \-n +print the commands but do not run them. +.TP +.BI "\-p " n +the number of programs, such as build commands or +test binaries, that can be run in parallel. +.br +The default is GOMAXPROCS, normally the number of CPUs available. +.TP +.B \-race +enable data race detection. +.br +Supported only on linux/amd64, freebsd/amd64, darwin/amd64, darwin/arm64, windows/amd64, +linux/ppc64le and linux/arm64 (only for 48-bit VMA). +.TP +.B \-msan +enable interoperation with memory sanitizer. +Supported only on linux/amd64, linux/arm64 +and only with Clang/LLVM as the host C compiler. +On linux/arm64, pie build mode will be used. +.TP +.B \-asan +enable interoperation with address sanitizer. +Supported only on linux/arm64, linux/amd64. +Supported only on linux/amd64 or linux/arm64 and only with GCC 7 and higher +or Clang/LLVM 9 and higher. +.TP +.B \-v +print the names of packages as they are compiled. +.TP +.B \-work +print the name of the temporary work directory and +do not delete it when exiting. +.TP +.B \-x +print the commands. + +.TP +.BI "\-asmflags '[pattern=]" "arg list" ' +arguments to pass on each go tool asm invocation. +.TP +.BI \-buildmode " mode" +build mode to use. See \(oqgo help buildmode\(cq for more. +.TP +.B \-buildvcs +Whether to stamp binaries with version control information. By default, +version control information is stamped into a binary if the main package +and the main module containing it are in the repository containing the +current directory (if there is a repository). Use \-buildvcs=false to +omit version control information. +.TP +.BI \-compiler " name" +name of compiler to use, as in runtime.Compiler (gccgo or gc) +.TP +.BI "\-gccgoflags '" "arg list" ' +arguments to pass on each gccgo compiler/linker invocation +.TP +.BI "\-gcflags '" "arg list" ' +arguments to pass on each go tool compile invocation. +.TP +.BI "\-installsuffix " suffix +a suffix to use in the name of the package installation directory, +in order to keep output separate from default builds. +If using the -race flag, the install suffix is automatically set to race +or, if set explicitly, has _race appended to it. Likewise for the \-msan +and \-asan flag. Using a \-buildmode option that requires non-default compile +flags has a similar effect. +.TP +.BI "\-ldflags '" "flag list" ' +arguments to pass on each go tool link invocation. +.TP +.B \-linkshared +build code that will be linked against shared libraries previously +created with \-buildmode=shared. +.TP +.BI "\-mod " mode +module download mode to use: readonly, vendor, or mod. +By default, if a vendor directory is present and the go version in go.mod +is 1.14 or higher, the go command acts as if -mod=vendor were set. +Otherwise, the go command acts as if -mod=readonly were set. +See https://golang.org/ref/mod#build-commands for details. +.TP +.B \-modcacherw +leave newly-created directories in the module cache read-write +instead of making them read-only. +.TP +.BI "\-modfile " file +in module aware mode, read (and possibly write) an alternate go.mod +file instead of the one in the module root directory. A file named +"go.mod" must still be present in order to determine the module root +directory, but it is not accessed. When -modfile is specified, an +alternate go.sum file is also used: its path is derived from the +\-modfile flag by trimming the ".mod" extension and appending ".sum". +.TP +.BI "\-overlay " file +read a JSON config file that provides an overlay for build operations. +The file is a JSON struct with a single field, named \(oqReplace\(cq, that +maps each disk file path (a string) to its backing file path, so that +a build will run as if the disk file path exists with the contents +given by the backing file paths, or as if the disk file path does not +exist if its backing file path is empty. Support for the -overlay flag +has some limitations: importantly, cgo files included from outside the +include path must be in the same directory as the Go package they are +included from, and overlays will not appear when binaries and tests are +run through go run and go test respectively. +.TP +.BI "\-pkgdir " dir +install and load all packages from dir instead of the usual locations. +For example, when building with a non-standard configuration, +use \-pkgdir to keep generated packages in a separate location. +.TP +.BR "\-tags " tag,list +a comma-separated list of additional build tags to consider satisfied +during the build. For more information about build tags, see +\(oqgo help buildconstraint\(cq. (Earlier versions of Go used a +space-separated list, and that form is deprecated but still recognized.) +.TP +.B \-trimpath +remove all file system paths from the resulting executable. +Instead of absolute file system paths, the recorded file names +will begin either a module path@version (when using modules), +or a plain import path (when using the standard library, or GOPATH). +.TP +.BI "\-toolexec '" "cmd args" ' +a program to use to invoke toolchain programs like vet and asm. +For example, instead of running asm, the go command will run +\(oqcmd args /path/to/asm <arguments for asm>\(cq. +.br +The TOOLEXEC_IMPORTPATH environment variable will be set, +matching \(oqgo list -f {{.ImportPath}}\(cq for the package being built. + +.P +The \-asmflags, \-gccgoflags, \-gcflags, and \-ldflags flags accept a +space-separated list of arguments to pass to an underlying tool +during the build. To embed spaces in an element in the list, surround +it with either single or double quotes. The argument list may be +preceded by a package pattern and an equal sign, which restricts +the use of that argument list to the building of packages matching +that pattern (see \(oqgo help packages\(cq for a description of package +patterns). Without a pattern, the argument list applies only to the +packages named on the command line. The flags may be repeated +with different patterns in order to specify different arguments for +different sets of packages. If a package matches patterns given in +multiple flags, the latest match on the command line wins. +For example, \(oqgo build \-gcflags=-S fmt\(cq prints the disassembly +only for package fmt, while \(oqgo build \-gcflags=all=-S fmt\(cq +prints the disassembly for fmt and all its dependencies. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.br +For more about where packages and binaries are installed, see \fBgo-gopath\fP(1). +.br +For more about calling between Go and C/C++, run \(oqgo help c\(cq. +.P +Note: Build adheres to certain conventions such as those described +by \(oqgo help gopath\(cq. Not all projects can follow these conventions, +however. Installations that have their own conventions or that use +a separate software build system may choose to use lower-level +invocations such as \(oqgo tool compile\(cq and \(oqgo tool link\(cq to avoid +some of the overheads and design decisions of the build tool. +.SH SEE ALSO +.BR go-install (1), +.BR go-get (1), +.BR go-clean (1). +.SH AUTHOR +This manual page was written by Michael Stapelberg <stapelberg@debian.org> +and is maintained by the +Debian Go Compiler Team <team+go-compiler@tracker.debian.org> +based on the output of \(oqgo help build\(cq +for the Debian project (and may be used by others). |