diff options
| -rw-r--r-- | man/go-build.1 | 216 | ||||
| -rw-r--r-- | man/go-clean.1 | 103 | ||||
| -rw-r--r-- | man/go-env.1 | 41 | ||||
| -rw-r--r-- | man/go-fix.1 | 29 | ||||
| -rw-r--r-- | man/go-fmt.1 | 38 | ||||
| -rw-r--r-- | man/go-get.1 | 100 | ||||
| -rw-r--r-- | man/go-gopath-get.1 | 81 | ||||
| -rw-r--r-- | man/go-install.1 | 73 | ||||
| -rw-r--r-- | man/go-list.1 | 353 | ||||
| -rw-r--r-- | man/go-mod.1 | 48 | ||||
| -rw-r--r-- | man/go-packages.7 | 104 | ||||
| -rw-r--r-- | man/go-path.7 | 177 | ||||
| -rw-r--r-- | man/go-remote.7 | 166 | ||||
| -rw-r--r-- | man/go-run.1 | 66 | ||||
| -rw-r--r-- | man/go-test.1 | 150 | ||||
| -rw-r--r-- | man/go-testflag.7 | 323 | ||||
| -rw-r--r-- | man/go-testfunc.7 | 90 | ||||
| -rw-r--r-- | man/go-tool.1 | 29 | ||||
| -rw-r--r-- | man/go-version.1 | 34 | ||||
| -rw-r--r-- | man/go-vet.1 | 65 | ||||
| -rw-r--r-- | man/go.1 | 141 | ||||
| -rw-r--r-- | man/gofmt.1 | 138 |
22 files changed, 2565 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). diff --git a/man/go-clean.1 b/man/go-clean.1 new file mode 100644 index 0000000..b652e95 --- /dev/null +++ b/man/go-clean.1 @@ -0,0 +1,103 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-CLEAN 1 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-clean \- remove object files and cached files +.SH SYNOPSIS +.B go clean +.RB [ \-i ] +.RB [ \-r ] +.RB [ \-n ] +.RB [ \-x ] +.RI [ packages ] +.SH DESCRIPTION +Clean removes object files from package source directories. +The go command builds most objects in a temporary directory, +so go clean is mainly concerned with object files left by other +tools or by manual invocations of go build. +.P +If a package argument is given or the \-i or \-r flag is set, +clean removes the following files from each of the +source directories corresponding to the import paths: +.TP +.B _obj/ +old object directory, left from Makefiles +.TP +.B _test/ +old test directory, left from Makefiles +.TP +.B _testmain.go +old gotest file, left from Makefiles +.TP +.B test.out +old test log, left from Makefiles +.TP +.B build.out +old test log, left from Makefiles +.TP +.B *.[568ao] +object files, left from Makefiles + +.TP +.B DIR(.exe) +from go build +.TP +.B DIR.test(.exe) +from go test \-c +.TP +.B MAINFILE(.exe) +from go build MAINFILE.go +.TP +.B *.so +from SWIG +.P +In the list, DIR represents the final path element of the +directory, and MAINFILE is the base name of any Go source +file in the directory that is not included when building +the package. +.SH OPTIONS +.TP +.B \-i +The \-i flag causes clean to remove the corresponding installed +archive or binary (what \(oqgo install\(cq would create). +.TP +.B \-n +The \-n flag causes clean to print the remove commands it would execute, +but not run them. +.TP +.B \-r +The \-r flag causes clean to be applied recursively to all the +dependencies of the packages named by the import paths. +.TP +.B \-x +The \-x flag causes clean to print remove commands as it executes them. +.TP +.B \-cache +The \-cache flag causes clean to remove the entire go build cache. +.TP +.B \-testcache +The -testcache flag causes clean to expire all test results in the +go build cache. +.TP +.B \-modcache +The \-modcache flag causes clean to remove the entire module +download cache, including unpacked source code of versioned +dependencies. +.TP +.B \-fuzzcache +The \-fuzzcache flag causes clean to remove files stored in the Go build +cache for fuzz testing. The fuzzing engine caches files that expand +code coverage, so removing them may make fuzzing less effective until +new inputs are found that provide the same coverage. These files are +distinct from those stored in testdata directory; clean does not remove +those files. +.P +For more about build flags, see \fBgo-build\fP(1). +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.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 clean\(cq +for the Debian project (and may be used by others). diff --git a/man/go-env.1 b/man/go-env.1 new file mode 100644 index 0000000..746a0ab --- /dev/null +++ b/man/go-env.1 @@ -0,0 +1,41 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-ENV 1 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-env \- print Go environment information +.SH SYNOPSIS +.B go env +.RB [ +.IR "var ..." +.RB ] +.SH DESCRIPTION +.P +Env prints Go environment information. +.P +By default env prints information as a shell script +(on Windows, a batch file). If one or more variable +names is given as arguments, env prints the value of +each named variable on its own line. +.TP +.B \-json +prints the environment in JSON format +instead of as a shell script. +.TP +.B \-u +requires one or more arguments and unsets +the default setting for the named environment variables, +if one has been set with \(oqgo env -w\(cq. +.TP +.B \-w +requires one or more arguments of the +form NAME=VALUE and changes the default settings +of the named environment variables to the given values. +.P +For more about environment variables, see \(oqgo help environment\(cq. +.SH AUTHOR +.P +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 env\(cq +for the Debian project (and may be used by others). diff --git a/man/go-fix.1 b/man/go-fix.1 new file mode 100644 index 0000000..b1bba88 --- /dev/null +++ b/man/go-fix.1 @@ -0,0 +1,29 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-FIX 1 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-fix \- update packages to use new APIs +.SH SYNOPSIS +.B go fix +.RI [ packages ] +.SH DESCRIPTION +Fix runs the Go fix command on the packages named by the import paths. +.P +The \-fix flag sets a comma-separated list of fixes to run. +The default is all known fixes. +(Its value is passed to \(oqgo tool fix \-r\(cq.) +.P +For more about fix, see \(oqgo doc cmd/fix\(cq. +.br +For more about specifying packages, see \fBgo-packages\fP(7). +.P +To run fix with other options, run \(oqgo tool fix\(cq. +.SH SEE ALSO +.BR go-fmt (1), +.BR go-vet (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 fix\(cq +for the Debian project (and may be used by others). diff --git a/man/go-fmt.1 b/man/go-fmt.1 new file mode 100644 index 0000000..603cb8b --- /dev/null +++ b/man/go-fmt.1 @@ -0,0 +1,38 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-FMT 1 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-fmt \- gofmt (reformat) package sources +.SH SYNOPSIS +.B go fmt +.RB [ \-n ] +.RB [ \-x ] +.RI [ packages ] +.SH DESCRIPTION +Fmt runs the command \(oqgofmt \-l \-w\(cq on the packages named +by the import paths. It prints the names of the files that are modified. +.P +For more about gofmt, see \(oqgo doc cmd/gofmt\(cq. +.br +For more about specifying packages, see \fBgo-packages\fP(7). +.TP +.B \-n +The \-n flag prints commands that would be executed. +.TP +.B \-x +The \-x flag prints commands as they are executed. +.TP +.B \-mod +The \-mod flag\(cqs value sets which module download mode +to use: readonly or vendor. See \(oqgo help modules\(cq for more. +.P +To run gofmt with specific options, run gofmt itself. +.SH SEE ALSO +.BR go-fix (1), +.BR go-vet (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 fmt\(cq +for the Debian project (and may be used by others). diff --git a/man/go-get.1 b/man/go-get.1 new file mode 100644 index 0000000..ae73af5 --- /dev/null +++ b/man/go-get.1 @@ -0,0 +1,100 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-GET 1 "2021-10-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-get \- add dependencies to current module and install them +.SH SYNOPSIS +.B go get +.RB [\|\-t\|] +.RB [\|\-u\|] +.RB [\|\-v\|] +.RI [ "build flags" ] +.RI [ packages ] +.SH DESCRIPTION +Get resolves its command-line arguments to packages at specific module versions, +updates go.mod to require those versions, and downloads source code into the +module cache. +.P +To add a dependency for a package or upgrade it to its latest version: + +.Vb 6 +\& go get example.com/pkg +.Ve +.P +To upgrade or downgrade a package to a specific version: + +.Vb 6 +\& go get example.com/pkg@v1.2.3 +.Ve +.P +To remove a dependency on a module and downgrade modules that require it: + +.Vb 6 +\& go get example.com/mod@none +.Ve +.P +See https://golang.org/ref/mod#go-get for details. +.P +In earlier versions of Go, \(oqgo get\(cq was used to build and install packages. +Now, \(oqgo get\(cq is dedicated to adjusting dependencies in go.mod. \(oqgo install' +may be used to build and install commands instead. When a version is specified, +\(oqgo install\(cq runs in module-aware mode and ignores the go.mod file in the +current directory. For example: + +.Vb 6 +\& go install example.com/pkg@v1.2.3 +\& go install example.com/pkg@latest +.Ve +.P +See \(oqgo help install\(cq or https://golang.org/ref/mod#go-install for details. +.P +\(oqgo get\(cq accepts the following flags. +.TP +.B \-t +The \-t flag instructs get to consider modules needed to build tests of +packages specified on the command line. +.TP +.B \-u +The \-u flag instructs get to update modules providing dependencies +of packages named on the command line to use newer minor or patch +releases when available. +.TP +.BI \-u= patch +The \-u=\fIpatch\fP flag (not \-u \fIpatch\fP) also instructs get to update dependencies, +but changes the default to select patch releases. +.P +When the \-t and \-u flags are used together, get will update +test dependencies as well. +.TP +.B \-x +The \-x flag prints commands as they are executed. This is useful for +debugging version control commands when a module is downloaded directly +from a repository. +.P +For more about modules, see https://golang.org/ref/mod. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +This text describes the behavior of get using modules to manage source +code and dependencies. If instead the go command is running in GOPATH +mode, the details of get's flags and effects change, as does \(oqgo help get'. +See \(oqgo help gopath-get\(cq or \fBgo-gopath-get\fP(1). +.SH SEE ALSO +.BR go-build (1), +.BR go-install (1), +.BR go-clean (1). +.BR go-mod (1). +.SH AUTHOR +This manual page and is maintained by the +Debian Go Compiler Team <team+go-compiler@tracker.debian.org> +based on the output of \(oqgo help get' +for the Debian project (and may be used by others). diff --git a/man/go-gopath-get.1 b/man/go-gopath-get.1 new file mode 100644 index 0000000..36fdf75 --- /dev/null +++ b/man/go-gopath-get.1 @@ -0,0 +1,81 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-GOPATH-GET 1 "2021-10-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-get \- legacy GOPATH go get +.SH SYNOPSIS +The 'go get' command changes behavior depending on whether the +go command is running in module-aware mode or legacy GOPATH mode. +This help text, accessible as 'go help gopath-get' even in module-aware mode, +describes 'go get' as it operates in legacy GOPATH mode. +.P +.B go get +.RB [\|\-d\|] +.RB [\|\-f\|] +.RB [\|\-t\|] +.RB [\|\-u\|] +.RB [\|\-v\|] +.RB [\|\-fix\|] +.RI [ "build flags" ] +.RI [ packages ] +.SH DESCRIPTION +Get downloads the packages named by the import paths, along with their +dependencies. It then installs the named packages, like 'go install'. +.TP +.B \-d +The \-d flag instructs get to stop after downloading the packages; that is, +it instructs get not to install the packages. +.TP +.B \-f +The \-f flag, valid only when \-u is set, forces get \-u not to verify that +each package has been checked out from the source control repository +implied by its import path. This can be useful if the source is a local fork +of the original. +.TP +.B \-fix +The \-fix flag instructs get to run the fix tool on the downloaded packages +before resolving dependencies or building the code. +.TP +.B \-t +The \-t flag instructs get to also download the packages required to build +the tests for the specified packages. +.TP +.B \-u +The \-u flag instructs get to use the network to update the named packages +and their dependencies. By default, get uses the network to check out +missing packages but does not use it to look for updates to existing packages. +.TP +.B \-v +The \-v flag enables verbose progress and debug output. +.P +Get also accepts build flags to control the installation. +See \fBgo-build\fP(1). +.P +When checking out a new package, get creates the target directory +GOPATH/src/<import-path>. If the GOPATH contains multiple entries, +get uses the first one. For more details see: 'go help gopath'. +.P +When checking out or updating a package, get looks for a branch or tag +that matches the locally installed version of Go. The most important +rule is that if the local installation is running version "go1", get +searches for a branch or tag named "go1". If no such version exists +it retrieves the default branch of the package. +.P +When go get checks out or updates a Git repository, +it also updates any git submodules referenced by the repository. +.P +Get never checks out or updates code stored in vendor directories. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +For more about how 'go get' finds source code to download, see \fBgo-remote\fP(7). +.SH SEE ALSO +.BR go-build (1), +.BR go-install (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 'go help gopath-get' +for the Debian project (and may be used by others). diff --git a/man/go-install.1 b/man/go-install.1 new file mode 100644 index 0000000..5b1d9d8 --- /dev/null +++ b/man/go-install.1 @@ -0,0 +1,73 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-INSTALL 1 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go install +.RI [ "build flags" ] +.RI [ packages ] +.SH DESCRIPTION +Install compiles and installs the packages named by the import paths. +.P +Executables are installed in the directory named by the GOBIN environment +variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH +environment variable is not set. Executables in $GOROOT +are installed in $GOROOT/bin or $GOTOOLDIR instead of $GOBIN. +.P +If the arguments have version suffixes (like @latest or @v1.0.0), "go install" +builds packages in module-aware mode, ignoring the go.mod file in the current +directory or any parent directory, if there is one. This is useful for +installing executables without affecting the dependencies of the main module. +To eliminate ambiguity about which module versions are used in the build, the +arguments must satisfy the following constraints: +.IP \[bu] 2 +Arguments must be package paths or package patterns (with "..." wildcards). +They must not be standard packages (like fmt), meta-patterns (std, cmd, +all), or relative or absolute file paths. +.IP \[bu] +All arguments must have the same version suffix. Different queries are not +allowed, even if they refer to the same version. +.IP \[bu] +All arguments must refer to packages in the same module at the same version. +.IP \[bu] +Package path arguments must refer to main packages. Pattern arguments +will only match main packages. +.IP \[bu] +No module is considered the "main" module. If the module containing +packages named on the command line has a go.mod file, it must not contain +directives (replace and exclude) that would cause it to be interpreted +differently than if it were the main module. The module must not require +a higher version of itself. +.IP \[bu] +Vendor directories are not used in any module. (Vendor directories are not +included in the module zip files downloaded by \(oqgo install\(cq.) +.P +If the arguments don\(cqt have version suffixes, "go install" may run in +module-aware mode or GOPATH mode, depending on the GO111MODULE environment +variable and the presence of a go.mod file. See \(oqgo help modules\(cq for details. +If module-aware mode is enabled, "go install" runs in the context of the main +module. +.P +When module-aware mode is disabled, other packages are installed in the +directory $GOPATH/pkg/$GOOS_$GOARCH. When module-aware mode is enabled, +other packages are built and cached but not installed. +.P +The \-i flag installs the dependencies of the named packages as well. +.br +The \-i flag is deprecated. Compiled packages are cached automatically. +.P +For more about the build flags, see \fBgo-build\fP(1). +.br +For more about specifying packages, see \fBgo-packages\fP(7). +.SH SEE ALSO +.BR go-build (1), +.BR go-get (1), +.BR go-clean (1). +.SH AUTHOR +.PP +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 install\(cq +for the Debian project (and may be used by others). diff --git a/man/go-list.1 b/man/go-list.1 new file mode 100644 index 0000000..12849b4 --- /dev/null +++ b/man/go-list.1 @@ -0,0 +1,353 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-LIST 1 "2022-08-02" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-list \- list packages or modules +.SH SYNOPSIS +.B go list +.RB [ \-f +.IR format ] +.RB [ \-json ] +.RB [ \-m ] +.RI [ "list flags" ] +.RI [ "build flags" ] +.RI [ packages ] +.SH DESCRIPTION +List lists the packages named by the import paths, one per line. +.br +The most commonly-used flags are \-f and \-json, which control the form +of the output printed for each package. Other list flags, documented below, +control more specific details. +.P +The default output shows the package import path: + +.Vb 6 +\& bytes +\& encoding/json +\& github.com/gorilla/mux +\& golang.org/x/net/html +.Ve +.SH OPTIONS +.TP +.B \-f +The \-f flag specifies an alternate format for the list, using the +syntax of package template. The default output is equivalent +to \-f '{{.ImportPath}}'. The struct being passed to the template is: + +.Vb 6 +\& type Package struct { +\& Dir string // directory containing package sources +\& ImportPath string // import path of package in dir +\& ImportComment string // path in import comment on package statement +\& Name string // package name +\& Doc string // package documentation string +\& Target string // install path +\& Shlib string // the shared library that contains this package (only set when -linkshared) +\& Goroot bool // is this package in the Go root? +\& Standard bool // is this package part of the standard Go library? +\& Stale bool // would 'go install' do anything for this package? +\& StaleReason string // explanation for Stale==true +\& Root string // Go root or Go path dir containing this package +\& ConflictDir string // this directory shadows Dir in $GOPATH +\& BinaryOnly bool // binary-only package (no longer supported) +\& ForTest string // package is only for use in named test +\& Export string // file containing export data (when using -export) +\& BuildID string // build ID of the compiled package (when using -export) +\& Module *Module // info about package's containing module, if any (can be nil) +\& Match []string // command-line patterns matching this package +\& DepOnly bool // package is only a dependency, not explicitly listed +\& +\& // Source files +\& GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) +\& CgoFiles []string // .go source files that import "C" +\& CompiledGoFiles []string // .go files presented to compiler (when using -compiled) +\& IgnoredGoFiles []string // .go source files ignored due to build constraints +\& IgnoredOtherFiles []string // non-.go source files ignored due to build constraints +\& CFiles []string // .c source files +\& CXXFiles []string // .cc, .cxx and .cpp source files +\& MFiles []string // .m source files +\& HFiles []string // .h, .hh, .hpp and .hxx source files +\& FFiles []string // .f, .F, .for and .f90 Fortran source files +\& SFiles []string // .s source files +\& SwigFiles []string // .swig files +\& SwigCXXFiles []string // .swigcxx files +\& SysoFiles []string // .syso object files to add to archive +\& TestGoFiles []string // _test.go files in package +\& XTestGoFiles []string // _test.go files outside package +\& +\& // Embedded files +\& EmbedPatterns []string // //go:embed patterns +\& EmbedFiles []string // files matched by EmbedPatterns +\& TestEmbedPatterns []string // //go:embed patterns in TestGoFiles +\& TestEmbedFiles []string // files matched by TestEmbedPatterns +\& XTestEmbedPatterns []string // //go:embed patterns in XTestGoFiles +\& XTestEmbedFiles []string // files matched by XTestEmbedPatterns +\& +\& // Cgo directives +\& CgoCFLAGS []string // cgo: flags for C compiler +\& CgoCPPFLAGS []string // cgo: flags for C preprocessor +\& CgoCXXFLAGS []string // cgo: flags for C++ compiler +\& CgoFFLAGS []string // cgo: flags for Fortran compiler +\& CgoLDFLAGS []string // cgo: flags for linker +\& CgoPkgConfig []string // cgo: pkg-config names +\& +\& // Dependency information +\& Imports []string // import paths used by this package +\& ImportMap map[string]string // map from source import to ImportPath (identity entries omitted) +\& Deps []string // all (recursively) imported dependencies +\& TestImports []string // imports from TestGoFiles +\& XTestImports []string // imports from XTestGoFiles +\& +\& // Error information +\& Incomplete bool // this package or a dependency has an error +\& Error *PackageError // error loading package +\& DepsErrors []*PackageError // errors loading dependencies +\& } +.Ve + +Packages stored in vendor directories report an ImportPath that includes the +path to the vendor directory (for example, "d/vendor/p" instead of "p"), +so that the ImportPath uniquely identifies a given copy of a package. +The Imports, Deps, TestImports, and XTestImports lists also contain these +expanded import paths. See golang.org/s/go15vendor for more about vendoring. + +The error information, if any, is + +.Vb 6 +\& type PackageError struct { +\& ImportStack []string // shortest path from package named on command line to this one +\& Pos string // position of error (if present, file:line:col) +\& Err string // the error itself +\& } +.Ve + +The module information is a Module struct, defined in the discussion +of list \-m below. + +The template function "join" calls strings.Join. + +The template function "context" returns the build context, defined as: + +.Vb 6 +\& type Context struct { +\& GOARCH string // target architecture +\& GOOS string // target operating system +\& GOROOT string // Go root +\& GOPATH string // Go path +\& CgoEnabled bool // whether cgo can be used +\& UseAllFiles bool // use files regardless of +build lines, file names +\& Compiler string // compiler to assume when computing target paths +\& BuildTags []string // build constraints to match in +build lines +\& ToolTags []string // toolchain-specific build constraints +\& ReleaseTags []string // releases the current release is compatible with +\& InstallSuffix string // suffix to use in the name of the install dir +\& } +.Ve + +For more information about the meaning of these fields see the documentation +for the go/build package's Context type. +.TP +.B \-json +The \-json flag causes the package data to be printed in JSON format +instead of using the template format. The JSON flag can optionally be +provided with a set of comma-separated required field names to be output. +If so, those required fields will always appear in JSON output, but +others may be omitted to save work in computing the JSON struct. +.TP +.B \-compiled +The \-compiled flag causes list to set CompiledGoFiles to the Go source +files presented to the compiler. Typically this means that it repeats +the files listed in GoFiles and then also adds the Go code generated +by processing CgoFiles and SwigFiles. The Imports list contains the +union of all imports from both GoFiles and CompiledGoFiles. +.TP +.B \-deps +The \-deps flag causes list to iterate over not just the named packages +but also all their dependencies. It visits them in a depth-first post-order +traversal, so that a package is listed only after all its dependencies. +Packages not explicitly listed on the command line will have the DepOnly +field set to true. +.TP +.B \-e +The \-e flag changes the handling of erroneous packages, those that +cannot be found or are malformed. By default, the list command +prints an error to standard error for each erroneous package and +omits the packages from consideration during the usual printing. +With the \-e flag, the list command never prints errors to standard +error and instead processes the erroneous packages with the usual +printing. Erroneous packages will have a non-empty ImportPath and +a non-nil Error field; other information may or may not be missing +(zeroed). +.TP +.B \-export +The \-export flag causes list to set the Export field to the name of a +file containing up-to-date export information for the given package, +and the BuildID field to the build ID of the compiled package. +.TP +.B \-find +The \-find flag causes list to identify the named packages but not +resolve their dependencies: the Imports and Deps lists will be empty. +.TP +.B \-test +The \-test flag causes list to report not only the named packages +but also their test binaries (for packages with tests), to convey to +source code analysis tools exactly how test binaries are constructed. +The reported import path for a test binary is the import path of +the package followed by a ".test" suffix, as in "math/rand.test". +When building a test, it is sometimes necessary to rebuild certain +dependencies specially for that test (most commonly the tested +package itself). The reported import path of a package recompiled +for a particular test binary is followed by a space and the name of +the test binary in brackets, as in "math/rand [math/rand.test]" +or "regexp [sort.test]". The ForTest field is also set to the name +of the package being tested ("math/rand" or "sort" in the previous +examples). +.P +The Dir, Target, Shlib, Root, ConflictDir, and Export file paths +are all absolute paths. +.P +By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir +(that is, paths relative to Dir, not absolute paths). +The generated files added when using the \-compiled and \-test flags +are absolute paths referring to cached copies of generated Go source files. +Although they are Go source files, the paths may not end in ".go". +.TP +.B \-m +The \-m flag causes list to list modules instead of packages. + +When listing modules, the \-f flag still specifies a format template +applied to a Go struct, but now a Module struct: + +.Vb 6 +\& type Module struct { +\& Path string // module path +\& Query string // version query corresponding to this version +\& Version string // module version +\& Versions []string // available module versions +\& Replace *Module // replaced by this module +\& Time *time.Time // time version was created +\& Update *Module // available update (with -u) +\& Main bool // is this the main module? +\& Indirect bool // module is only indirectly needed by main module +\& Dir string // directory holding local copy of files, if any +\& GoMod string // path to go.mod file describing module, if any +\& GoVersion string // go version used in module +\& Retracted []string // retraction information, if any (with -retracted or -u) +\& Deprecated string // deprecation message, if any (with -u) +\& Error *ModuleError // error loading module +\& Origin any // provenance of module +\& Reuse bool // reuse of old module info is safe +\& } +\& +\& type ModuleError struct { +\& Err string // the error itself +\& } +.Ve + +The file GoMod refers to may be outside the module directory if the +module is in the module cache or if the \-modfile flag is used. + +The default output is to print the module path and then +information about the version and replacement if any. +For example, 'go list \-m all' might print: + +.Vb 6 +\& my/main/module +\& golang.org/x/text v0.3.0 => /tmp/text +\& rsc.io/pdf v0.1.1 +.Ve + +The Module struct has a String method that formats this +line of output, so that the default format is equivalent +to \-f '{{.String}}'. + +Note that when a module has been replaced, its Replace field +describes the replacement module, and its Dir field is set to +the replacement's source code, if present. (That is, if Replace +is non-nil, then Dir is set to Replace.Dir, with no access to +the replaced source code.) +.TP +.B \-u +The \-u flag adds information about available upgrades. +When the latest version of a given module is newer than +the current one, list \-u sets the Module's Update field +to information about the newer module. list \-u will also set +the module's Retracted field if the current version is retracted. +The Module's String method indicates an available upgrade by +formatting the newer version in brackets after the current version. +If a version is retracted, the string "(retracted)" will follow it. +For example, 'go list \-m \-u all' might print: + +.Vb 6 +\& my/main/module +\& golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text +\& rsc.io/pdf v0.1.1 (retracted) [v0.1.2] +.Ve + +(For tools, 'go list \-m \-u \-json all' may be more convenient to parse.) +.TP +.B \-versions +The \-versions flag causes list to set the Module's Versions field +to a list of all known versions of that module, ordered according +to semantic versioning, earliest to latest. The flag also changes +the default output format to display the module path followed by the +space-separated version list. +.TP +.B \-retracted +The \-retracted flag causes list to report information about retracted +module versions. When \-retracted is used with \-f or \-json, the Retracted +field will be set to a string explaining why the version was retracted. +The string is taken from comments on the retract directive in the +module's go.mod file. When \-retracted is used with \-versions, retracted +versions are listed together with unretracted versions. The \-retracted +flag may be used with or without \-m. +.P +The arguments to list \-m are interpreted as a list of modules, not packages. +The main module is the module containing the current directory. +The active modules are the main module and its dependencies. +With no arguments, list \-m shows the main module. +With arguments, list \-m shows the modules specified by the arguments. +Any of the active modules can be specified by its module path. +The special pattern "all" specifies all the active modules, first the main +module and then dependencies sorted by module path. +A pattern containing "..." specifies the active modules whose +module paths match the pattern. +A query of the form path@version specifies the result of that query, +which is not limited to active modules. +See 'go help modules' for more about module queries. +.P +The template function "module" takes a single string argument +that must be a module path or query and returns the specified +module as a Module struct. If an error occurs, the result will +be a Module struct with a non-nil Error field. +.P +When using \-m, the \-reuse=old.json flag accepts the name of file containing +the JSON output of a previous \(oqgo list \-m \-json\(cq invocation with the +same set of modifier flags (such as \-u, \-retracted, and \-versions). +The go command may use this file to determine that a module is unchanged +since the previous invocation and avoid redownloading information about it. +Modules that are not redownloaded will be marked in the new output by +setting the Reuse field to true. Normally the module cache provides this +kind of reuse automatically; the \-reuse flag can be useful on systems that +do not preserve the module cache. +.P +For more about build flags, see \fBgo-build\fP(1) or 'go help build'. +.P +For more about specifying packages, see \fBgo-packages\fP(7) or 'go help packages'. +.P +For more about modules, see https://golang.org/ref/mod. +.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 'go help list' +for the Debian project (and may be used by others). diff --git a/man/go-mod.1 b/man/go-mod.1 new file mode 100644 index 0000000..bd998ac --- /dev/null +++ b/man/go-mod.1 @@ -0,0 +1,48 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO 1 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-mod \- module maintenance +.SH SYNOPSIS +.B go mod +.I command +.RI [ arguments ] +.SH DESCRIPTION +Go mod provides access to operations on modules. +.P +Note that support for modules is built into all the go commands, +not just 'go mod'. For example, day-to-day adding, removing, upgrading, +and downgrading of dependencies should be done using 'go get'. +See 'go help modules' for an overview of module functionality. +.SH COMMANDS +.TP +.B download +download modules to local cache +.TP +.B edit +edit go.mod from tools or scripts +.TP +.B graph +print module requirement graph +.TP +.B init +initialize new module in current directory +.TP +.B tidy +add missing and remove unused modules +.TP +.B vendor +make vendored copy of dependencies +.TP +.B verify +verify dependencies have expected content +.TP +.B why +explain why packages or modules are needed +.P +Use "go help mod <command>" for more information about a command. +.SH AUTHOR +This manual page and is maintained by the +Debian Go Compiler Team <team+go-compiler@tracker.debian.org> +based on the output of 'go help mod' +for the Debian project (and may be used by others). diff --git a/man/go-packages.7 b/man/go-packages.7 new file mode 100644 index 0000000..eb546bf --- /dev/null +++ b/man/go-packages.7 @@ -0,0 +1,104 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-PACKAGES 7 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +Many commands apply to a set of packages: + +.Vb 6 +\& go action [packages] +.Ve + +.P +Usually, [packages] is a list of import paths. +.P +An import path that is a rooted path or that begins with +a . or .. element is interpreted as a file system path and +denotes the package in that directory. +.P +Otherwise, the import path P denotes the package found in +the directory DIR/src/P for some DIR listed in the GOPATH +environment variable (For more details see: 'go help gopath'). +.P +If no import paths are given, the action applies to the +package in the current directory. +.P +There are four reserved names for paths that should not be used +for packages to be built with the go tool: +.IP \[bu] 2 +"main" denotes the top-level package in a stand-alone executable. +.IP \[bu] +"all" expands to all packages found in all the GOPATH +trees. For example, 'go list all' lists all the packages on the local +system. When using modules, "all" expands to all packages in +the main module and their dependencies, including dependencies +needed by tests of any of those. +.IP \[bu] +"std" is like all but expands to just the packages in the standard +Go library. +.IP \[bu] +"cmd" expands to the Go repository's commands and their +internal libraries. +.P +Import paths beginning with "cmd/" only match source code in +the Go repository. +.P +An import path is a pattern if it includes one or more "..." wildcards, +each of which can match any string, including the empty string and +strings containing slashes. Such a pattern expands to all package +directories found in the GOPATH trees with names matching the +patterns. +.P +To make common patterns more convenient, there are two special cases. +First, /... at the end of the pattern can match an empty string, +so that net/... matches both net and packages in its subdirectories, like net/http. +Second, any slash-separated pattern element containing a wildcard never +participates in a match of the "vendor" element in the path of a vendored +package, so that ./... does not match packages in subdirectories of ./vendor +or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do. +Note, however, that a directory named vendor that itself contains code +is not a vendored package: cmd/vendor would be a command named vendor, +and the pattern cmd/... matches it. +See golang.org/s/go15vendor for more about vendoring. +.P +An import path can also name a package to be downloaded from +a remote repository. Run 'go help importpath' for details. +.P +Every package in a program must have a unique import path. +By convention, this is arranged by starting each path with a +unique prefix that belongs to you. For example, paths used +internally at Google all begin with 'google', and paths +denoting remote repositories begin with the path to the code, +such as 'github.com/user/repo'. +.P +Packages in a program need not have unique package names, +but there are two reserved package names with special meaning. +The name main indicates a command, not a library. +Commands are built into binaries and cannot be imported. +The name documentation indicates documentation for +a non-Go program in the directory. Files in package documentation +are ignored by the go command. +.P +As a special case, if the package list is a list of .go files from a +single directory, the command is applied to a single synthesized +package made up of exactly those files, ignoring any build constraints +in those files and ignoring any other files in the directory. +.P +Directory and file names that begin with "." or "_" are ignored +by the go tool, as are directories named "testdata". +.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 'go help packages' +for the Debian project (and may be used by others). diff --git a/man/go-path.7 b/man/go-path.7 new file mode 100644 index 0000000..9b8be48 --- /dev/null +++ b/man/go-path.7 @@ -0,0 +1,177 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-PATH 7 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +The Go path is used to resolve import statements. +It is implemented by and documented in the go/build package. + +The GOPATH environment variable lists places to look for Go code. +On Unix, the value is a colon-separated string. +On Windows, the value is a semicolon-separated string. +On Plan 9, the value is a list. + +If the environment variable is unset, GOPATH defaults +to a subdirectory named "go" in the user's home directory +($HOME/go on Unix, %USERPROFILE%\go on Windows), +unless that directory holds a Go distribution. +Run "go env GOPATH" to see the current GOPATH. + +See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH. + +Each directory listed in GOPATH must have a prescribed structure: + +The src directory holds source code. The path below src +determines the import path or executable name. + +The pkg directory holds installed package objects. +As in the Go tree, each target operating system and +architecture pair has its own subdirectory of pkg +(pkg/GOOS_GOARCH). + +If DIR is a directory listed in the GOPATH, a package with +source in DIR/src/foo/bar can be imported as "foo/bar" and +has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". + +The bin directory holds compiled commands. +Each command is named for its source directory, but only +the final element, not the entire path. That is, the +command with source in DIR/src/foo/quux is installed into +DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped +so that you can add DIR/bin to your PATH to get at the +installed commands. If the GOBIN environment variable is +set, commands are installed to the directory it names instead +of DIR/bin. GOBIN must be an absolute path. + +Here's an example directory layout: + +.Vb 4 +\& GOPATH=/home/user/gocode +\& +\& /home/user/gocode/ +\& src/ +\& foo/ +\& bar/ (go code in package bar) +\& x.go +\& quux/ (go code in package main) +\& y.go +\& bin/ +\& quux (installed command) +\& pkg/ +\& linux_amd64/ +\& foo/ +\& bar.a (installed package object) +.Ve + +Go searches each directory listed in GOPATH to find source code, +but new packages are always downloaded into the first directory +in the list. + +See https://golang.org/doc/code.html for an example. +. +.SS GOPATH and Modules +. +When using modules, GOPATH is no longer used for resolving imports. +However, it is still used to store downloaded source code (in GOPATH/pkg/mod) +and compiled commands (in GOPATH/bin). +. +.SS Internal Directories +. +Code in or below a directory named "internal" is importable only +by code in the directory tree rooted at the parent of "internal". +Here's an extended version of the directory layout above: + +.Vb 4 +\& /home/user/go/ +\& src/ +\& crash/ +\& bang/ (go code in package bang) +\& b.go +\& foo/ (go code in package foo) +\& f.go +\& bar/ (go code in package bar) +\& x.go +\& internal/ +\& baz/ (go code in package baz) +\& z.go +\& quux/ (go code in package main) +\& y.go +.Ve + +The code in z.go is imported as "foo/internal/baz", but that +import statement can only appear in source files in the subtree +rooted at foo. The source files foo/f.go, foo/bar/x.go, and +foo/quux/y.go can all import "foo/internal/baz", but the source file +crash/bang/b.go cannot. + +See https://golang.org/s/go14internal for details. +. +.SS Vendor Directories + +Go 1.6 includes support for using local copies of external dependencies +to satisfy imports of those dependencies, often referred to as vendoring. + +Code below a directory named "vendor" is importable only +by code in the directory tree rooted at the parent of "vendor", +and only using an import path that omits the prefix up to and +including the vendor element. + +Here's the example from the previous section, +but with the "internal" directory renamed to "vendor" +and a new foo/vendor/crash/bang directory added: + +.Vb 4 +\& /home/user/go/ +\& src/ +\& crash/ +\& bang/ (go code in package bang) +\& b.go +\& foo/ (go code in package foo) +\& f.go +\& bar/ (go code in package bar) +\& x.go +\& vendor/ +\& crash/ +\& bang/ (go code in package bang) +\& b.go +\& baz/ (go code in package baz) +\& z.go +\& quux/ (go code in package main) +\& y.go +.Ve + +The same visibility rules apply as for internal, but the code +in z.go is imported as "baz", not as "foo/vendor/baz". + +Code in vendor directories deeper in the source tree shadows +code in higher directories. Within the subtree rooted at foo, an import +of "crash/bang" resolves to "foo/vendor/crash/bang", not the +top-level "crash/bang". + +Code in vendor directories is not subject to import path +checking (see 'go help importpath'). + +When 'go get' checks out or updates a git repository, it now also +updates submodules. + +Vendor directories do not affect the placement of new repositories +being checked out for the first time by 'go get': those are always +placed in the main GOPATH, never in a vendor subtree. + +See https://golang.org/s/go15vendor for details. +.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 'go help gopath' +for the Debian project (and may be used by others). diff --git a/man/go-remote.7 b/man/go-remote.7 new file mode 100644 index 0000000..a1ca7a9 --- /dev/null +++ b/man/go-remote.7 @@ -0,0 +1,166 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-REMOTE 7 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +An import path (see \fBgo-importpath\fP(1)) denotes a package +stored in the local file system. Certain import paths also +describe how to obtain the source code for the package using +a revision control system. + +A few common code hosting sites have special syntax: + +.TP +.B BitBucket (Mercurial) +.Vb 4 +\&import "bitbucket.org/user/project" +\&import "bitbucket.org/user/project/sub/directory" +.Ve + +.TP +.B GitHub (Git) +.Vb 4 +\&import "github.com/user/project" +\&import "github.com/user/project/sub/directory" +.Ve + +.TP +.B Google Code Project Hosting (Git, Mercurial, Subversion) +.Vb 4 +\&import "code.google.com/p/project" +\&import "code.google.com/p/project/sub/directory" +.Ve + +.Vb 4 +\&import "code.google.com/p/project.subrepository" +\&import "code.google.com/p/project.subrepository/sub/directory" +.Ve + +.TP +.B Launchpad (Bazaar) + +.Vb 4 +\&import "launchpad.net/project" +\&import "launchpad.net/project/series" +\&import "launchpad.net/project/series/sub/directory" +.Ve + +.Vb 4 +\&import "launchpad.net/~user/project/branch" +\&import "launchpad.net/~user/project/branch/sub/directory" +.Ve + +.P +For code hosted on other servers, import paths may either be qualified +with the version control type, or the go tool can dynamically fetch +the import path over https/http and discover where the code resides +from a <meta> tag in the HTML. + +To declare the code location, an import path of the form + +.Vb 6 +\& repository.vcs/path +.Ve + +specifies the given repository, with or without the .vcs suffix, +using the named version control system, and then the path inside +that repository. The supported version control systems are: + +.TP +.B Bazaar + .bzr +.TP +.B Git + .git +.TP +.B Mercurial + .hg +.TP +.B Subversion + .svn + +.P +For example, + +.Vb 6 +\& import "example.org/user/foo.hg" +.Ve + +denotes the root directory of the Mercurial repository at +example.org/user/foo or foo.hg, and + +.Vb 6 +\& import "example.org/repo.git/foo/bar" +.Ve + +denotes the foo/bar directory of the Git repository at +example.com/repo or repo.git. + +When a version control system supports multiple protocols, +each is tried in turn when downloading. For example, a Git +download tries git://, then https://, then http://. + +If the import path is not a known code hosting site and also lacks a +version control qualifier, the go tool attempts to fetch the import +over https/http and looks for a <meta> tag in the document's HTML +<head>. + +The meta tag has the form: + +.Vb 6 +\& <meta name="go-import" content="import-prefix vcs repo-root"> +.Ve + +The import-prefix is the import path corresponding to the repository +root. It must be a prefix or an exact match of the package being +fetched with "go get". If it's not an exact match, another http +request is made at the prefix to verify the <meta> tags match. + +The vcs is one of "git", "hg", "svn", etc, + +The repo-root is the root of the version control system +containing a scheme and not containing a .vcs qualifier. + +For example, + +.Vb 6 +\& import "example.org/pkg/foo" +.Ve + +will result in the following request(s): + +.Vb 6 +\& https://example.org/pkg/foo?go-get=1 (preferred) +\& http://example.org/pkg/foo?go-get=1 (fallback) +.Ve + +If that page contains the meta tag + +.Vb 6 +\& <meta name="go-import" content="example.org git https://code.org/r/p/exproj"> +.Ve + +the go tool will verify that https://example.org/?go-get=1 contains the +same meta tag and then git clone https://code.org/r/p/exproj into +GOPATH/src/example.org. + +New downloaded packages are written to the first directory +listed in the GOPATH environment variable (see \fBgo-path\fP(1)). + +The go command attempts to download the version of the +package appropriate for the Go release being used. +See \fBgo-install\fP(1) for more. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/man/go-run.1 b/man/go-run.1 new file mode 100644 index 0000000..baf1c20 --- /dev/null +++ b/man/go-run.1 @@ -0,0 +1,66 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-RUN 1 "2022-08-02" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-run \- compile and run Go program +.SH SYNOPSIS +.B go run +.RI [ "build flags" ] +.RB [ \-exec +.IR xprog ] +.I package +.RI [ arguments... ] +.SH DESCRIPTION +Run compiles and runs the named main Go package. +.br +Typically the package is specified as a list of .go source files from a single +directory, but it may also be an import path, file system path, or pattern +matching a single known package, as in 'go run .' or 'go run my/cmd'. +.P +If the package argument has a version suffix (like @latest or @v1.0.0), +"go run" builds the program in module-aware mode, ignoring the go.mod file in +the current directory or any parent directory, if there is one. This is useful +for running programs without affecting the dependencies of the main module. +.P +By default, 'go run' runs the compiled binary directly: 'a.out arguments...'. +.br +If the \-exec flag is given, 'go run' invokes the binary using xprog: + +.Vb 1 +\& 'xprog a.out arguments...'. +.Ve +.P +If the \-exec flag is not given, GOOS or GOARCH is different from the system +default, and a program named go_$GOOS_$GOARCH_exec can be found +on the current search path, 'go run' invokes the binary using that program, +for example 'go_js_wasm_exec a.out arguments...'. This allows execution of +cross-compiled programs when a simulator or other execution method is +available. +.P +By default, \(oqgo run\(cq compiles the binary without generating the information +used by debuggers, to reduce build time. To include debugger information in +the binary, use \(oqgo build\(cq. +.P +The exit status of Run is not the exit status of the compiled binary. +.P +For more about build flags, see 'go help build'. +.br +For more about specifying packages, see 'go help packages'. +.SH SEE ALSO +.BR go-build (1). +.SH AUTHOR +.PP +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 'go help run' +for the Debian project (and may be used by others). diff --git a/man/go-test.1 b/man/go-test.1 new file mode 100644 index 0000000..8636e67 --- /dev/null +++ b/man/go-test.1 @@ -0,0 +1,150 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TEST 1 "2022-08-02" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-test \- test packages +.SH SYNOPSIS +.B go test +.RI [ "build/test flags" ] +.RI [ packages ] +.RI [ "build/test flags & test binary flags" ] +.SH DESCRIPTION +"Go test" automates testing the packages named by the import paths. +It prints a summary of the test results in the format: + +.Vb 6 +\& ok archive/tar 0.011s +\& FAIL archive/zip 0.022s +\& ok compress/gzip 0.033s +\& ... +.Ve + +followed by detailed output for each failed package. +.P +"Go test" recompiles each package along with any files with names matching +the file pattern "*_test.go". +These additional files can contain test functions, benchmark functions, fuzz +tests and example functions. See \(oqgo help testfunc\(cq for more. +.br +Each listed package causes the execution of a separate test binary. +Files whose names begin with "_" (including "_test.go") or "." are ignored. +.P +Test files that declare a package with the suffix "_test" will be compiled as a +separate package, and then linked and run with the main test binary. +.P +The go tool will ignore a directory named "testdata", making it available +to hold ancillary data needed by the tests. +.P +As part of building a test binary, go test runs go vet on the package +and its test source files to identify significant problems. If go vet +finds any problems, go test reports those and does not run the test +binary. Only a high-confidence subset of the default go vet checks are +used. That subset is: \(oqatomic\(cq, \(oqbool\(cq, \(oqbuildtags\(cq, \(oqerrorsas\(cq, \(oqifaceassert\(cq, \(oqnilfunc\(cq, \(oqprintf\(cq, and \(oqstringintconv\(cq. You can see +the documentation for these and other vet tests via "go doc cmd/vet". +To disable the running of go vet, use the \-vet=off flag. To run all +checks, use the \-vet=all flag. +.P +All test output and summary lines are printed to the go command\(cqs +standard output, even if the test printed them to its own standard +error. (The go command\(cqs standard error is reserved for printing +errors building the tests.) +.P +Go test runs in two different modes: +.P +The first, called local directory mode, occurs when go test is +invoked with no package arguments (for example, \(oqgo test\(cq or \(oqgo +test \-v\(cq). In this mode, go test compiles the package sources and +tests found in the current directory and then runs the resulting +test binary. In this mode, caching (discussed below) is disabled. +After the package test finishes, go test prints a summary line +showing the test status (\(oqok\(cq or \(oqFAIL\(cq), package name, and elapsed +time. +.P +The second, called package list mode, occurs when go test is invoked +with explicit package arguments (for example \(oqgo test math\(cq, \(oqgo +test ./...\(cq, and even \(oqgo test .\(cq). In this mode, go test compiles +and tests each of the packages listed on the command line. If a +package test passes, go test prints only the final \(oqok\(cq summary +line. If a package test fails, go test prints the full test output. +If invoked with the \-bench or \-v flag, go test prints the full +output even for passing package tests, in order to display the +requested benchmark results or verbose logging. After the package +tests for all of the listed packages finish, and their output is +printed, go test prints a final \(oqFAIL\(cq status if any package test +has failed. +.P +In package list mode only, go test caches successful package test +results to avoid unnecessary repeated running of tests. When the +result of a test can be recovered from the cache, go test will +redisplay the previous output instead of running the test binary +again. When this happens, go test prints \(oq(cached)\(cq in place of the +elapsed time in the summary line. +.P +The rule for a match in the cache is that the run involves the same +test binary and the flags on the command line come entirely from a +restricted set of \[oq]cacheable\[cq] test flags, defined as \-benchtime, \-cpu, +\-list, \-parallel, \-run, \-short, \-timeout, \-failfast, and \-v. +If a run of go test has any test or non-test flags outside this set, +the result is not cached. To disable test caching, use any test flag +or argument other than the cacheable flags. The idiomatic way to disable +test caching explicitly is to use \-count=1. Tests that open files within +the package\(cqs source root (usually $GOPATH) or that consult environment +variables only match future runs in which the files and environment +variables are unchanged. A cached test result is treated as executing +in no time at all, so a successful package test result will be cached and +reused regardless of \-timeout setting. +.SH OPTIONS +In addition to the build flags, the flags handled by \(oqgo test\(cq itself are: +.TP +.B \-args +Pass the remainder of the command line (everything after \-args) +to the test binary, uninterpreted and unchanged. +Because this flag consumes the remainder of the command line, +the package list (if present) must appear before this flag. +.TP +.B \-c +Compile the test binary to pkg.test but do not run it +(where pkg is the last element of the package\(cqs import path). +The file name can be changed with the \-o flag. +.TP +.BI "\-exec " xprog +Run the test binary using xprog. The behavior is the same as +in \(oqgo run\(cq. See \(oqgo help run\(cq for details. +.TP +.B \-i +Install packages that are dependencies of the test. +Do not run the test. +.TP +.B \-json +Convert test output to JSON suitable for automated processing. +See \(oqgo doc test2json\(cq for the encoding details. +.TP +.BI "\-o " file +Compile the test binary to the named file. +The test still runs (unless \-c or \-i is specified). +.P +The test binary also accepts flags that control execution of the test; these +flags are also accessible by \(oqgo test\(cq. See \fBgo-testflag\fP(7) for details. +.P +For more about build flags, see \fBgo-build\fP(1). +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.SH SEE ALSO +.BR go-build (1), +.BR go-vet (1). +.SH AUTHOR +.PP +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 test\(cq +for the Debian project (and may be used by others). diff --git a/man/go-testflag.7 b/man/go-testflag.7 new file mode 100644 index 0000000..aabd409 --- /dev/null +++ b/man/go-testflag.7 @@ -0,0 +1,323 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TESTFLAG 7 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +The \(oqgo test\(cq command takes both flags that apply to \(oqgo test\(cq itself +and flags that apply to the resulting test binary. + +Several of the flags control profiling and write an execution profile +suitable for "go tool pprof"; run "go tool pprof \-h" for more +information. The \-\-alloc_space, \-\-alloc_objects, and \-\-show_bytes +options of pprof control how the information is presented. + +The following flags are recognized by the \(oqgo test\(cq command and +control the execution of any test: +.TP +.BI \-bench " regexp" +Run only those benchmarks matching a regular expression. +By default, no benchmarks are run. +To run all benchmarks, use \(oq\-bench .\(cq or \(oq\-bench=.\(cq. +The regular expression is split by unbracketed slash (/) +characters into a sequence of regular expressions, and each +part of a benchmark\[cq]s identifier must match the corresponding +element in the sequence, if any. Possible parents of matches +are run with b.N=1 to identify sub-benchmarks. For example, +given \-bench=X/Y, top-level benchmarks matching X are run +with b.N=1 to find any sub-benchmarks matching Y, which are +then run in full. +.TP +.BI \-benchtime " t" +Run enough iterations of each benchmark to take \fIt\fP, specified +as a time.Duration (for example, \-benchtime 1h30s). +.br +The default is 1 second (1s). +.br +The special syntax \fIN\fPx means to run the benchmark \fIN\fP times +(for example, \-benchtime 100x). +.TP +.BI \-count " n" +Run each test, benchmark, and fuzz seed \fIn\fP times (default 1). +.br +If \-cpu is set, run n times for each GOMAXPROCS value. +.br +Examples are always run once. \-count does not apply to +fuzz tests matched by \-fuzz. +.TP +.B \-cover +Enable coverage analysis. +.br +Note that because coverage works by annotating the source +code before compilation, compilation and test failures with +coverage enabled may report line numbers that don\(cqt correspond +to the original sources. +.TP +.BR \-covermode " set,count,atomic" +Set the mode for coverage analysis for the package[s] +being tested. The default is "set" unless \-race is enabled, +in which case it is "atomic". +.br +The values: + set: bool: does this statement run? + count: int: how many times does this statement run? + atomic: int: count, but correct in multithreaded tests; + significantly more expensive. +.br +Sets \-cover. +.TP +.BI "\-coverpkg " pattern1 , pattern2 , pattern3 +Apply coverage analysis in each test to packages matching the patterns. +The default is for each test to analyze only the package being tested. +.br +See \(oqgo help packages\(cq for a description of package patterns. +.br +Sets \-cover. +.TP +.BI "\-cpu " 1 , 2 , 4 +Specify a list of GOMAXPROCS values for which the tests, benchmarks or +fuzz tests should be executed. The default is the current value +of GOMAXPROCS. \-cpu does not apply to fuzz tests matched by \-fuzz. +.TP +.B \-failfast +Do not start new tests after the first test failure. +.TP +.BI \-fuzz " regexp" +Run the fuzz test matching the regular expression. When specified, +the command line argument must match exactly one package within the +main module, and regexp must match exactly one fuzz test within +that package. Fuzzing will occur after tests, benchmarks, seed corpora +of other fuzz tests, and examples have completed. See the Fuzzing +section of the testing package documentation for details. +.TP +.BI \-fuzztime " t" +Run enough iterations of the fuzz target during fuzzing to take \fIt\fP, +specified as a time.Duration (for example, \-fuzztime 1h30s). + The default is to run forever. +.br +The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times +(for example, \-fuzztime 1000x). +.TP +.BI \-fuzzminimizetime " t" +Run enough iterations of the fuzz target during each minimization +attempt to take \fIt\fP, as specified as a time.Duration (for example, +\-fuzzminimizetime 30s). + The default is 60s. +.br +The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times +(for example, \-fuzzminimizetime 100x). +.TP +.B \-json +Log verbose output and test results in JSON. This presents the +same information as the \-v flag in a machine-readable format. +.TP +.BI \-list " regexp" +List tests, benchmarks, fuzz tests, or examples matching the regular +expression. No tests, benchmarks, fuzz tests, or examples will be run. +This will only list top-level tests. No subtest or subbenchmarks will be +shown. +.TP +.BI \-parallel " n" +Allow parallel execution of test functions that call t.Parallel, and +fuzz targets that call t.Parallel when running the seed corpus. +The value of this flag is the maximum number of tests to run +simultaneously. +.br +While fuzzing, the value of this flag is the maximum number of +subprocesses that may call the fuzz function simultaneously, regardless of +whether T.Parallel is called. +.br +By default, \-parallel is set to the value of GOMAXPROCS. +Setting \-parallel to values higher than GOMAXPROCS may cause degraded +performance due to CPU contention, especially when fuzzing. +Note that \-parallel only applies within a single test binary. +The \(oqgo test\(cq command may run tests for different packages +in parallel as well, according to the setting of the \-p flag +(see \(oqgo help build\(cq). +.TP +.BI \-run " regexp" +Run only those tests, examples, and fuzz tests matching the regular +expression. For tests, the regular expression is split by unbracketed +slash (/) characters into a sequence of regular expressions, and each +part of a test\(cqs identifier must match the corresponding element in +the sequence, if any. Note that possible parents of matches are +run too, so that \-run=X/Y matches and runs and reports the result +of all tests matching X, even those without sub-tests matching Y, +because it must run them to look for those sub-tests. +.TP +.B \-short +Tell long-running tests to shorten their run time. +It is off by default but set during all.bash so that installing +the Go tree can run a sanity check but not spend time running +exhaustive tests. +.TP +.BR "\-shuffle " off,on,N +Randomize the execution order of tests and benchmarks. +It is off by default. If \-shuffle is set to on, then it will seed +the randomizer using the system clock. If \-shuffle is set to an +integer N, then N will be used as the seed value. In both cases, +the seed will be reported for reproducibility. +.TP +.BI \-timeout " d" +If a test binary runs longer than duration \fId\fP, panic. +.br +If \fId\fP is 0, the timeout is disabled. +.br +The default is 10 minutes (10m). +.TP +.B \-v +Verbose output: log all tests as they are run. Also print all +text from Log and Logf calls even if the test succeeds. +.TP +.BI \-vet " list" +Configure the invocation of "go vet" during "go test" +to use the comma-separated list of vet checks. +.br +If list is empty, "go test" runs "go vet" with a curated list of +checks believed to be always worth addressing. +.br +If list is "off", "go test" does not run "go vet" at all. +.P +The following flags are also recognized by \(oqgo test\(cq and can be used to +profile the tests during execution: +.TP +.B \-benchmem +Print memory allocation statistics for benchmarks. +.TP +.B \-blockprofile \fRblock.out +Write a goroutine blocking profile to the specified file +when all tests are complete. +.br +Writes test binary as \-c would. +.TP +.BI \-blockprofilerate " n" +Control the detail provided in goroutine blocking profiles by +calling runtime.SetBlockProfileRate with \fIn\fP. +.br +See \(oqgo doc runtime.SetBlockProfileRate\(cq. +.br +The profiler aims to sample, on average, one blocking event every +n nanoseconds the program spends blocked. By default, +if \-test.blockprofile is set without this flag, all blocking events +are recorded, equivalent to \-test.blockprofilerate=1. +.TP +.B \-coverprofile \fRcover.out +Write a coverage profile to the file after all tests have passed. +.br +Sets \-cover. +.TP +.B \-cpuprofile \fRcpu.out +Write a CPU profile to the specified file before exiting. +.br +Writes test binary as \-c would. +.TP +.B \-memprofile \fRmem.out +Write an allocation profile to the file after all tests have passed. +.br +Writes test binary as \-c would. +.TP +.BI \-memprofilerate " n" +Enable more precise (and expensive) memory allocation profiles by +setting runtime.MemProfileRate. See \(oqgo doc runtime.MemProfileRate\(cq. +To profile all memory allocations, use \-test.memprofilerate=1. +.TP +.B \-mutexprofile \fRmutex.out +Write a mutex contention profile to the specified file +when all tests are complete. +.br +Writes test binary as \-c would. +.TP +.BI \-mutexprofilefraction " n" +Sample 1 in \fIn\fP stack traces of goroutines holding a +contended mutex. +.TP +.B \-outputdir \fIdirectory +Place output files from profiling in the specified directory, +by default the directory in which "go test" is running. +.TP +.B \-trace trace.out +Write an execution trace to the specified file before exiting. +.P +Each of these flags is also recognized with an optional \(oqtest.\(cq prefix, +as in \-test.v. When invoking the generated test binary (the result of +\(oqgo test \-c\(cq) directly, however, the prefix is mandatory. + +The \(oqgo test\(cq command rewrites or removes recognized flags, +as appropriate, both before and after the optional package list, +before invoking the test binary. + +For instance, the command + + go test \-v \-myflag testdata \-cpuprofile=prof.out \-x + +will compile the test binary and then run it as + + pkg.test \-test.v \-myflag testdata \-test.cpuprofile=prof.out + +(The \-x flag is removed because it applies only to the go command\(cqs +execution, not to the test itself.) + +The test flags that generate profiles (other than for coverage) also +leave the test binary in pkg.test for use when analyzing the profiles. + +When \(oqgo test\(cq runs a test binary, it does so from within the +corresponding package\(cqs source code directory. Depending on the test, +it may be necessary to do the same when invoking a generated test +binary directly. Because that directory may be located within the +module cache, which may be read-only and is verified by checksums, the +test must not write to it or any other directory within the module +unless explicitly requested by the user (such as with the \-fuzz flag, +which writes failures to testdata/fuzz). + +The command-line package list, if present, must appear before any +flag not known to the go test command. Continuing the example above, +the package list would have to appear before \-myflag, but could appear +on either side of \-v. + +When \(oqgo test\(cq runs in package list mode, \(oqgo test\(cq caches successful +package test results to avoid unnecessary repeated running of tests. To +disable test caching, use any test flag or argument other than the +cacheable flags. The idiomatic way to disable test caching explicitly +is to use \-count=1. + +To keep an argument for a test binary from being interpreted as a +known flag or a package name, use \-args (see \(oqgo help test\(cq) which +passes the remainder of the command line through to the test binary +uninterpreted and unaltered. + +For instance, the command + + go test \-v \-args \-x \-v + +will compile the test binary and then run it as + + pkg.test \-test.v \-x \-v + +Similarly, + + go test \-args math + +will compile the test binary and then run it as + + pkg.test math + +In the first example, the \-x and the second \-v are passed through to the +test binary unchanged and with no effect on the go command itself. +In the second example, the argument math is passed through to the test +binary, instead of being interpreted as the package list. +.SH AUTHOR +.PP +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 testflag\(cq +for the Debian project (and may be used by others). diff --git a/man/go-testfunc.7 b/man/go-testfunc.7 new file mode 100644 index 0000000..b890934 --- /dev/null +++ b/man/go-testfunc.7 @@ -0,0 +1,90 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TESTFUNC 7 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +The \(oqgo test\(cq command expects to find test, benchmark, and example functions +in the "*_test.go" files corresponding to the package under test. + +A test function is one named TestXxx (where Xxx does not start with a +lower case letter) and should have the signature, + +.Vb 6 +\& func TestXxx(t *testing.T) { ... } +.Ve + +A benchmark function is one named BenchmarkXxx and should have the signature, + +.Vb 6 +\& func BenchmarkXxx(b *testing.B) { ... } +.Ve + +A fuzz test is one named FuzzXxx and should have the signature, + +.Vb 6 +\& func FuzzXxx(f *testing.F) { ... } +.Ve + +An example function is similar to a test function but, instead of using +*testing.T to report success or failure, prints output to os.Stdout. +If the last comment in the function starts with "Output:" then the output +is compared exactly against the comment (see examples below). If the last +comment begins with "Unordered output:" then the output is compared to the +comment, however the order of the lines is ignored. An example with no such +comment is compiled but not executed. An example with no text after +"Output:" is compiled, executed, and expected to produce no output. + +Godoc displays the body of ExampleXxx to demonstrate the use +of the function, constant, or variable Xxx. An example of a method M with +receiver type T or *T is named ExampleT_M. There may be multiple examples +for a given function, constant, or variable, distinguished by a trailing _xxx, +where xxx is a suffix not beginning with an upper case letter. + +Here is an example of an example: + +.Vb 6 +\& func ExamplePrintln() { +\& Println("The output of\\nthis example.") +\& // Output: The output of +\& // this example. +\& } +.Ve + +Here is another example where the ordering of the output is ignored: + +.Vb 6 +\& func ExamplePerm() { +\& for _, value := range Perm(4) { +\& fmt.Println(value) +\& } +\& +\& // Unordered output: 4 +\& // 2 +\& // 1 +\& // 3 +\& // 0 +\& } +.Ve + +The entire test file is presented as the example when it contains a single +example function, at least one other function, type, variable, or constant +declaration, and no tests, benchmarks, or fuzz tests. + +See the documentation of the testing package for more information. +.SH AUTHOR +.PP +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 testfunc\(cq +for the Debian project (and may be used by others). diff --git a/man/go-tool.1 b/man/go-tool.1 new file mode 100644 index 0000000..ae582a3 --- /dev/null +++ b/man/go-tool.1 @@ -0,0 +1,29 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-TOOL 1 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-tool \- tool for managing Go source code +.SH SYNOPSIS +.B go tool +.RB [\|\-n\|] +.IR command +.RB [ +.IR args... +.RB ] +.SH DESCRIPTION +Tool runs the go tool command identified by the arguments. +With no arguments it prints the list of known tools. +.SH OPTIONS +.TP +.B \-n +The \-n flag causes tool to print the command that would be +executed but not execute it. +.P +For more about each tool command, see 'go tool command \-h'. +.SH AUTHOR +.PP +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 'go help tool' +for the Debian project (and may be used by others). diff --git a/man/go-version.1 b/man/go-version.1 new file mode 100644 index 0000000..81b0c56 --- /dev/null +++ b/man/go-version.1 @@ -0,0 +1,34 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-VERSION 1 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-version \- print the build information for Go executables +.SH SYNOPSIS +.B go version +.RB [ \-m ] +.RB [ \-v ] +.RI [ "file ..." ] +.SH DESCRIPTION +Go version reports the Go version used to build each of the named +executable files. +.P +If no files are named on the command line, go version prints its own +version information. +.P +If a directory is named, go version walks that directory, recursively, +looking for recognized Go binaries and reporting their versions. +By default, go version does not report unrecognized files found +during a directory scan. The \-v flag causes it to report unrecognized files. +.P +The \-m flag causes go version to print each executable's embedded +module version information, when available. In the output, the module +information consists of multiple lines following the version line, each +indented by a leading tab character. +.SH SEE ALSO +go doc runtime/debug.BuildInfo. +.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 'go help version' +for the Debian project (and may be used by others). diff --git a/man/go-vet.1 b/man/go-vet.1 new file mode 100644 index 0000000..69e8765 --- /dev/null +++ b/man/go-vet.1 @@ -0,0 +1,65 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-VET 1 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-vet \- report likely mistakes in packages +.SH SYNOPSIS +.B go vet +.RB [ \-n ] +.RB [ \-x ] +.RB [ \-vettool +.IR prog ] +.RI [ "build flags" ] +.RI [ "vet flags" ] +.RI [ packages ] +.SH DESCRIPTION +Vet runs the Go vet command on the packages named by the import paths. +.P +For more about vet and its flags, see 'go doc cmd/vet'. +.br +For more about specifying packages, see \fBgo-packages\fP(7). +.br +For a list of checkers and their flags, see 'go tool vet help'. +.br +For details of a specific checker such as 'printf', see 'go tool vet help printf'. +.SH OPTIONS +.TP +.B \-n +The \-n flag prints commands that would be executed. +.TP +.B \-x +The \-x flag prints commands as they are executed. +.TP +.BI \-vettool= prog +The \-vettool=prog flag selects a different analysis tool with alternative +or additional checks. +.br +For example, the 'shadow' analyzer can be built and run using these commands: + +.Vb 6 +\& go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow +\& go vet \-vettool=$(which shadow) +.Ve +.P +The build flags supported by go vet are those that control package resolution +and execution, such as \-n, \-x, \-v, \-tags, and \-toolexec. +For more about these flags, see 'go help build'. +.SH SEE ALSO +.BR go-fmt (1), +.BR go-fix (1). +.SH AUTHOR +.PP +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 'go help vet' +for the Debian project (and may be used by others). diff --git a/man/go.1 b/man/go.1 new file mode 100644 index 0000000..3a62ca5 --- /dev/null +++ b/man/go.1 @@ -0,0 +1,141 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO 1 "2022-03-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go +.RI command +.RI [ arguments ] +.SH DESCRIPTION +.P +The Go distribution includes a command, named \fBgo\fP, that automates the +downloading, building, installation, and testing of Go packages and commands. +.SH COMMANDS +Each command is documented in its own manpage. For example, the \fBbuild\fP +command is documented in \fBgo-build\fP(1). The commands are: +.TP +.B bug +start a bug report +.TP +.B build +compile packages and dependencies +.TP +.B clean +remove object files and cached files +.TP +.B doc +show documentation for package or symbol +.TP +.B env +print Go environment information +.TP +.B fix +update packages to use new APIs +.TP +.B fmt +gofmt (reformat) package sources +.TP +.B generate +generate Go files by processing source +.TP +.B get +add dependencies to current module and install them +.TP +.B install +compile and install packages and dependencies +.TP +.B list +list packages or modules +.TP +.B mod +module maintenance +.TP +.B work +workspace maintenance +.TP +.B run +compile and run Go program +.TP +.B test +test packages +.TP +.B tool +run specified go tool +.TP +.B version +print Go version +.TP +.B vet +report likely mistakes in packages +.P +Use "go help <command>" for more information about a command. +.SH ADDITIONAL HELP TOPICS +.TP +.B buildconstraint +build constraints +.TP +.B buildmode +build modes +.TP +.B c +calling between Go and C +.TP +.B cache +build and test caching +.TP +.B environment +environment variables +.TP +.B filetype +file types +.TP +.B go.mod +the go.mod file +.TP +.B gopath +GOPATH environment variable +.TP +.B gopath-get +legacy GOPATH go get +.TP +.B goproxy +module proxy protocol +.TP +.B importpath +import path syntax +.TP +.B modules +modules, module versions, and more +.TP +.B module-get +module-aware go get +.TP +.B module-auth +module authentication using go.sum +.TP +.B packages +package lists and patterns +.TP +.B private +configuration for downloading non-public code +.TP +.B testflag +testing flags +.TP +.B testfunc +testing functions +.TP +.B vcs +controlling version control with GOVCS +.P +Use "go help <topic>" for more information about that topic. +.SH SEE ALSO +.BR go-build (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\(cq +for the Debian project (and may be used by others). diff --git a/man/gofmt.1 b/man/gofmt.1 new file mode 100644 index 0000000..656d3de --- /dev/null +++ b/man/gofmt.1 @@ -0,0 +1,138 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GOFMT 1 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +gofmt \- format Go programs +.SH SYNOPSIS +.B gofmt +.RI [ flags ] +.RI [ "path ..." ] +.SH DESCRIPTION +Gofmt formats Go programs. It uses tabs for indentation and blanks for +alignment. Alignment assumes that an editor is using a fixed-width font. +.P +Without an explicit path, it processes the standard input. Given a file, it +operates on that file; given a directory, it operates on all .go files in +that directory, recursively. (Files starting with a period are ignored.) By +default, gofmt prints the reformatted sources to standard output. +.SH OPTIONS +.TP +.B \-d +Do not print reformatted sources to standard output. +If a file's formatting is different than gofmt's, print diffs +to standard output. +.TP +.B \-e +Print all (including spurious) errors. +.TP +.B \-l +Do not print reformatted sources to standard output. +If a file's formatting is different from gofmt's, print its name +to standard output. +.TP +.B \-r rule +Apply the rewrite rule to the source before reformatting. +.TP +.B \-s +Try to simplify code (after applying the rewrite rule, if any). +.TP +.B \-w +Do not print reformatted sources to standard output. +If a file's formatting is different from gofmt's, overwrite it +with gofmt's version. If an error occurred during overwriting, +the original file is restored from an automatic backup. +.P +Debugging support: +.TP +.BI "\-cpuprofile " filename +Write cpu profile to the specified file. +.P +The rewrite rule specified with the \-r flag must be a string of the +form: + +.Vb 6 +\& pattern -> replacement +.Ve +.P +Both pattern and replacement must be valid Go expressions. In the pattern, +single-character lowercase identifiers serve as wildcards matching arbitrary +sub-expressions; those expressions will be substituted for the same +identifiers in the replacement. +.P +When gofmt reads from standard input, it accepts either a full Go program or +a program fragment. A program fragment must be a syntactically valid +declaration list, statement list, or expression. When formatting such a +fragment, gofmt preserves leading indentation as well as leading and +trailing spaces, so that individual sections of a Go program can be +formatted by piping them through gofmt. +. +.SH EXAMPLES +To check files for unnecessary parentheses: + +.Vb 6 +\& gofmt \-r '(a) \-> a' \-l *.go +.Ve + +To remove the parentheses: + +.Vb 6 +\& gofmt \-r '(a) \-> a' \-w *.go +.Ve + +To convert the package tree from explicit slice upper bounds to implicit +ones: + +.Vb 6 +\& gofmt \-r 'α[β:len(α)] \-> α[β:]' \-w $GOROOT/src/pkg +.Ve +. +.SS The simplify command +. +When invoked with \-s gofmt will make the following source transformations +where possible. + +.Vb 6 +\& An array, slice, or map composite literal of the form: +\& []T{T{}, T{}} +\& will be simplified to: +\& []T{{}, {}} +.Ve + +.Vb 6 +\& A slice expression of the form: +\& s[a:len(s)] +\& will be simplified to: +\& s[a:] +.Ve + +.Vb 6 +\& A range of the form: +\& for x, _ = range v {...} +\& will be simplified to: +\& for x = range v {...} +.Ve + +.Vb 6 +\& A range of the form: +\& for _ = range v {...} +\& will be simplified to: +\& for range v {...} +.Ve +.P +This may result in changes that are incompatible with earlier versions of +Go. +.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 'go doc cmd/gofmt' +for the Debian project (and may be used by others). |