diff options
Diffstat (limited to 'man/go-list.1')
| -rw-r--r-- | man/go-list.1 | 353 |
1 files changed, 353 insertions, 0 deletions
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). |