Documentation ¶
Overview ¶
Package load loads packages.
Index ¶
- Constants
- Variables
- func ClearPackageCache()
- func ClearPackageCachePartial(args []string)
- func FindVendor(path string) (index int, ok bool)
- func ImportPaths(args []string) []*search.Match
- func LinkerDeps(p *Package) []string
- func MatchPackage(pattern, cwd string) func(*Package) bool
- func ResolveImportPath(parent *Package, path string) (found string)
- func SafeArg(name string) bool
- type CoverVar
- type ImportPathError
- type ImportStack
- type NoGoError
- type Package
- func GoFilesPackage(gofiles []string) *Package
- func LoadImport(path, srcDir string, parent *Package, stk *ImportStack, ...) *Package
- func LoadImportWithFlags(path, srcDir string, parent *Package, stk *ImportStack, ...) *Package
- func PackageList(roots []*Package) []*Package
- func Packages(args []string) []*Package
- func PackagesAndErrors(patterns []string) []*Package
- func PackagesForBuild(args []string) []*Package
- func ReloadPackageNoFlags(arg string, stk *ImportStack) *Package
- func TestPackageList(roots []*Package) []*Package
- func TestPackagesAndErrors(p *Package, cover *TestCover) (pmain, ptest, pxtest *Package)
- func TestPackagesFor(p *Package, cover *TestCover) (pmain, ptest, pxtest *Package, err error)
- func (p *Package) AllFiles() []string
- func (p *Package) DefaultExecName() string
- func (p *Package) Desc() string
- func (p *Package) InternalAllGoFiles() []string
- func (p *Package) InternalGoFiles() []string
- func (p *Package) InternalXGoFiles() []string
- func (p *Package) Resolve(imports []string) []string
- func (p *Package) UsesCgo() bool
- func (p *Package) UsesSwig() bool
- type PackageError
- type PackageInternal
- type PackagePublic
- type PerPackageFlag
- type TargetDir
- type TestCover
Constants ¶
const ( // ResolveImport means that loadImport should do import path expansion. // That is, ResolveImport means that the import path came from // a source file and has not been expanded yet to account for // vendoring or possible module adjustment. // Every import path should be loaded initially with ResolveImport, // and then the expanded version (for example with the /vendor/ in it) // gets recorded as the canonical import path. At that point, future loads // of that package must not pass ResolveImport, because // disallowVendor will reject direct use of paths containing /vendor/. ResolveImport = 1 << iota // ResolveModule is for download (part of "go get") and indicates // that the module adjustment should be done, but not vendor adjustment. ResolveModule // GetTestDeps is for download (part of "go get") and indicates // that test dependencies should be fetched too. GetTestDeps )
Mode flags for loadImport and download (in get.go).
Variables ¶
var ( // module initialization hook; never nil, no-op if module use is disabled ModInit func() // module hooks; nil if module use is disabled ModBinDir func() string // return effective bin directory ModLookup func(parentPath string, parentIsStd bool, path string) (dir, realPath string, err error) // lookup effective meaning of import ModPackageModuleInfo func(path string) *modinfo.ModulePublic // return module info for Package struct ModImportPaths func(args []string) []*search.Match // expand import paths ModPackageBuildInfo func(main string, deps []string) string // return module info to embed in binary ModInfoProg func(info string, isgccgo bool) []byte // wrap module info in .go code for binary ModImportFromFiles func([]string) // update go.mod to add modules for imports in these files ModDirImportPath func(string) string // return effective import path for directory )
var IgnoreImports bool // control whether we ignore imports in packages
var TestMainDeps = []string{
"os",
"testing",
"testing/internal/testdeps",
}
Functions ¶
func ClearPackageCache ¶
func ClearPackageCache()
ClearPackageCache clears the in-memory package cache and the preload caches. It is only for use by GOPATH-based "go get". TODO(jayconrod): When GOPATH-based "go get" is removed, delete this function.
func ClearPackageCachePartial ¶
func ClearPackageCachePartial(args []string)
ClearPackageCachePartial clears packages with the given import paths from the in-memory package cache and the preload caches. It is only for use by GOPATH-based "go get". TODO(jayconrod): When GOPATH-based "go get" is removed, delete this function.
func FindVendor ¶
FindVendor looks for the last non-terminating "vendor" path element in the given import path. If there isn't one, FindVendor returns ok=false. Otherwise, FindVendor returns ok=true and the index of the "vendor".
Note that terminating "vendor" elements don't count: "x/vendor" is its own package, not the vendored copy of an import "" (the empty import path). This will allow people to have packages or commands named vendor. This may help reduce breakage, or it may just be confusing. We'll see.
func ImportPaths ¶
func LinkerDeps ¶
LinkerDeps returns the list of linker-induced dependencies for main package p.
func MatchPackage ¶
MatchPackage(pattern, cwd)(p) reports whether package p matches pattern in the working directory cwd.
func ResolveImportPath ¶
ResolveImportPath returns the true meaning of path when it appears in parent. There are two different resolutions applied. First, there is Go 1.5 vendoring (golang.org/s/go15vendor). If vendor expansion doesn't trigger, then the path is also subject to Go 1.11 module legacy conversion (golang.org/issue/25069).
func SafeArg ¶
SafeArg reports whether arg is a "safe" command-line argument, meaning that when it appears in a command-line, it probably doesn't have some special meaning other than its own name. Obviously args beginning with - are not safe (they look like flags). Less obviously, args beginning with @ are not safe (they look like GNU binutils flagfile specifiers, sometimes called "response files"). To be conservative, we reject almost any arg beginning with non-alphanumeric ASCII. We accept leading . _ and / as likely in file system paths. There is a copy of this function in cmd/compile/internal/gc/noder.go.
Types ¶
type CoverVar ¶
CoverVar holds the name of the generated coverage variables targeting the named file.
type ImportPathError ¶
ImportPathError is a type of error that prevents a package from being loaded for a given import path. When such a package is loaded, a *Package is returned with Err wrapping an ImportPathError: the error is attached to the imported package, not the importing package.
The string returned by ImportPath must appear in the string returned by Error. Errors that wrap ImportPathError (such as PackageError) may omit the import path.
func ImportErrorf ¶
func ImportErrorf(path, format string, args ...interface{}) ImportPathError
type ImportStack ¶
type ImportStack []string
An ImportStack is a stack of import paths, possibly with the suffix " (test)" appended. The import path of a test package is the import path of the corresponding non-test package with the suffix "_test" added.
func (*ImportStack) Copy ¶
func (s *ImportStack) Copy() []string
func (*ImportStack) Pop ¶
func (s *ImportStack) Pop()
func (*ImportStack) Push ¶
func (s *ImportStack) Push(p string)
type Package ¶
type Package struct { PackagePublic // visible in 'go list' Internal PackageInternal // for use inside go command only }
A Package describes a single package found in a directory.
func GoFilesPackage ¶
GoFilesPackage creates a package for building a collection of Go files (typically named on the command line). The target is named p.a for package p or named after the first Go file for package main.
func LoadImport ¶
func LoadImport(path, srcDir string, parent *Package, stk *ImportStack, importPos []token.Position, mode int) *Package
LoadImport scans the directory named by path, which must be an import path, but possibly a local import path (an absolute file system path or one beginning with ./ or ../). A local relative path is interpreted relative to srcDir. It returns a *Package describing the package found in that directory. LoadImport does not set tool flags and should only be used by this package, as part of a bigger load operation, and by GOPATH-based "go get". TODO(rsc): When GOPATH-based "go get" is removed, unexport this function.
func LoadImportWithFlags ¶
func LoadImportWithFlags(path, srcDir string, parent *Package, stk *ImportStack, importPos []token.Position, mode int) *Package
LoadImportWithFlags loads the package with the given import path and sets tool flags on that package. This function is useful loading implicit dependencies (like sync/atomic for coverage). TODO(jayconrod): delete this function and set flags automatically in LoadImport instead.
func PackageList ¶
PackageList returns the list of packages in the dag rooted at roots as visited in a depth-first post-order traversal.
func Packages ¶
Packages returns the packages named by the command line arguments 'args'. If a named package cannot be loaded at all (for example, if the directory does not exist), then packages prints an error and does not include that package in the results. However, if errors occur trying to load dependencies of a named package, the named package is still returned, with p.Incomplete = true and details in p.DepsErrors.
func PackagesAndErrors ¶
PackagesAndErrors is like 'packages' but returns a *Package for every argument, even the ones that cannot be loaded at all. The packages that fail to load will have p.Error != nil.
func PackagesForBuild ¶
PackagesForBuild is like Packages but exits if any of the packages or their dependencies have errors (cannot be built).
func ReloadPackageNoFlags ¶
func ReloadPackageNoFlags(arg string, stk *ImportStack) *Package
ReloadPackageNoFlags is like LoadImport but makes sure not to use the package cache. It is only for use by GOPATH-based "go get". TODO(rsc): When GOPATH-based "go get" is removed, delete this function.
func TestPackageList ¶
TestPackageList returns the list of packages in the dag rooted at roots as visited in a depth-first post-order traversal, including the test imports of the roots. This ignores errors in test packages.
func TestPackagesAndErrors ¶
TestPackagesAndErrors returns three packages:
- pmain, the package main corresponding to the test binary (running tests in ptest and pxtest).
- ptest, the package p compiled with added "package p" test files.
- pxtest, the result of compiling any "package p_test" (external) test files.
If the package has no "package p_test" test files, pxtest will be nil. If the non-test compilation of package p can be reused (for example, if there are no "package p" test files and package p need not be instrumented for coverage or any other reason), then the returned ptest == p.
An error is returned if the testmain source cannot be completely generated (for example, due to a syntax error in a test file). No error will be returned for errors loading packages, but the Error or DepsError fields of the returned packages may be set.
The caller is expected to have checked that len(p.TestGoFiles)+len(p.XTestGoFiles) > 0, or else there's no point in any of this.
func TestPackagesFor ¶
TestPackagesFor is like TestPackagesAndErrors but it returns an error if the test packages or their dependencies have errors. Only test packages without errors are returned.
func (*Package) AllFiles ¶
AllFiles returns the names of all the files considered for the package. This is used for sanity and security checks, so we include all files, even IgnoredGoFiles, because some subcommands consider them. The go/build package filtered others out (like foo_wrongGOARCH.s) and that's OK.
func (*Package) DefaultExecName ¶
DefaultExecName returns the default executable name for a package
func (*Package) InternalAllGoFiles ¶
InternalGoFiles returns the list of all Go files possibly relevant for the package, using absolute paths. "Possibly relevant" means that files are not excluded due to build tags, but files with names beginning with . or _ are still excluded.
func (*Package) InternalGoFiles ¶
InternalGoFiles returns the list of Go files being built for the package, using absolute paths.
func (*Package) InternalXGoFiles ¶
InternalXGoFiles returns the list of Go files being built for the XTest package, using absolute paths.
func (*Package) Resolve ¶
Resolve returns the resolved version of imports, which should be p.TestImports or p.XTestImports, NOT p.Imports. The imports in p.TestImports and p.XTestImports are not recursively loaded during the initial load of p, so they list the imports found in the source file, but most processing should be over the vendor-resolved import paths. We do this resolution lazily both to avoid file system work and because the eventual real load of the test imports (during 'go test') can produce better error messages if it starts with the original paths. The initial load of p loads all the non-test imports and rewrites the vendored paths, so nothing should ever call p.vendored(p.Imports).
type PackageError ¶
type PackageError struct { ImportStack []string // shortest path from package named on command line to this one Pos string // position of error Err error // the error itself IsImportCycle bool // the error is an import cycle Hard bool // whether the error is soft or hard; soft errors are ignored in some places }
A PackageError describes an error loading information about a package.
func (*PackageError) Error ¶
func (p *PackageError) Error() string
func (*PackageError) MarshalJSON ¶
func (p *PackageError) MarshalJSON() ([]byte, error)
PackageError implements MarshalJSON so that Err is marshaled as a string and non-essential fields are omitted.
type PackageInternal ¶
type PackageInternal struct { // Unexported fields are not part of the public API. Build *build.Package Imports []*Package // this package's direct imports CompiledImports []string // additional Imports necessary when using CompiledGoFiles (all from standard library) RawImports []string // this package's original imports as they appear in the text of the program ForceLibrary bool // this package is a library (even if named "main") CmdlineFiles bool // package built from files listed on command line CmdlinePkg bool // package listed on command line CmdlinePkgLiteral bool // package listed as literal on command line (not via wildcard) Local bool // imported via local path (./ or ../) LocalPrefix string // interpret ./ and ../ imports relative to this prefix ExeName string // desired name for temporary executable CoverMode string // preprocess Go source files with the coverage tool in this mode CoverVars map[string]*CoverVar // variables created by coverage analysis OmitDebug bool // tell linker not to write debug information GobinSubdir bool // install target would be subdir of GOBIN BuildInfo string // add this info to package main TestmainGo *[]byte // content for _testmain.go Asmflags []string // -asmflags for this package Gcflags []string // -gcflags for this package Ldflags []string // -ldflags for this package Gccgoflags []string // -gccgoflags for this package }
type PackagePublic ¶
type PackagePublic struct { // Note: These fields are part of the go command's public API. // See list.go. It is okay to add fields, but not to change or // remove existing ones. Keep in sync with list.go Dir string `json:",omitempty"` // directory containing package sources ImportPath string `json:",omitempty"` // import path of package in dir ImportComment string `json:",omitempty"` // path in import comment on package statement Name string `json:",omitempty"` // package name Doc string `json:",omitempty"` // package documentation string Target string `json:",omitempty"` // installed target for this package (may be executable) Shlib string `json:",omitempty"` // the shared library that contains this package (only set when -linkshared) Root string `json:",omitempty"` // Go root, Go path dir, or module root dir containing this package ConflictDir string `json:",omitempty"` // Dir is hidden by this other directory ForTest string `json:",omitempty"` // package is only for use in named test Export string `json:",omitempty"` // file containing export data (set by go list -export) Module *modinfo.ModulePublic `json:",omitempty"` // info about package's module, if any Match []string `json:",omitempty"` // command-line patterns matching this package Goroot bool `json:",omitempty"` // is this package found in the Go root? Standard bool `json:",omitempty"` // is this package part of the standard Go library? DepOnly bool `json:",omitempty"` // package is only as a dependency, not explicitly listed BinaryOnly bool `json:",omitempty"` // package cannot be recompiled Incomplete bool `json:",omitempty"` // was there an error loading this package or dependencies? // Stale and StaleReason remain here *only* for the list command. // They are only initialized in preparation for list execution. // The regular build determines staleness on the fly during action execution. Stale bool `json:",omitempty"` // would 'go install' do anything for this package? StaleReason string `json:",omitempty"` // why is Stale true? // Source files // If you add to this list you MUST add to p.AllFiles (below) too. // Otherwise file name security lists will not apply to any new additions. GoFiles []string `json:",omitempty"` // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) CgoFiles []string `json:",omitempty"` // .go source files that import "C" CompiledGoFiles []string `json:",omitempty"` // .go output from running cgo on CgoFiles IgnoredGoFiles []string `json:",omitempty"` // .go source files ignored due to build constraints CFiles []string `json:",omitempty"` // .c source files CXXFiles []string `json:",omitempty"` // .cc, .cpp and .cxx source files MFiles []string `json:",omitempty"` // .m source files HFiles []string `json:",omitempty"` // .h, .hh, .hpp and .hxx source files FFiles []string `json:",omitempty"` // .f, .F, .for and .f90 Fortran source files SFiles []string `json:",omitempty"` // .s source files SwigFiles []string `json:",omitempty"` // .swig files SwigCXXFiles []string `json:",omitempty"` // .swigcxx files SysoFiles []string `json:",omitempty"` // .syso system object files added to package // Cgo directives CgoCFLAGS []string `json:",omitempty"` // cgo: flags for C compiler CgoCPPFLAGS []string `json:",omitempty"` // cgo: flags for C preprocessor CgoCXXFLAGS []string `json:",omitempty"` // cgo: flags for C++ compiler CgoFFLAGS []string `json:",omitempty"` // cgo: flags for Fortran compiler CgoLDFLAGS []string `json:",omitempty"` // cgo: flags for linker CgoPkgConfig []string `json:",omitempty"` // cgo: pkg-config names // Dependency information Imports []string `json:",omitempty"` // import paths used by this package ImportMap map[string]string `json:",omitempty"` // map from source import to ImportPath (identity entries omitted) Deps []string `json:",omitempty"` // all (recursively) imported dependencies // Error information // Incomplete is above, packed into the other bools Error *PackageError `json:",omitempty"` // error loading this package (not dependencies) DepsErrors []*PackageError `json:",omitempty"` // errors loading dependencies // Test information // If you add to this list you MUST add to p.AllFiles (below) too. // Otherwise file name security lists will not apply to any new additions. TestGoFiles []string `json:",omitempty"` // _test.go files in package TestImports []string `json:",omitempty"` // imports from TestGoFiles XTestGoFiles []string `json:",omitempty"` // _test.go files outside package XTestImports []string `json:",omitempty"` // imports from XTestGoFiles }
type PerPackageFlag ¶
type PerPackageFlag struct {
// contains filtered or unexported fields
}
A PerPackageFlag is a command-line flag implementation (a flag.Value) that allows specifying different effective flags for different packages. See 'go help build' for more details about per-package flags.
var ( BuildAsmflags PerPackageFlag // -asmflags BuildGcflags PerPackageFlag // -gcflags BuildLdflags PerPackageFlag // -ldflags BuildGccgoflags PerPackageFlag // -gccgoflags )
func (*PerPackageFlag) For ¶
func (f *PerPackageFlag) For(p *Package) []string
For returns the flags to use for the given package.
func (*PerPackageFlag) Present ¶
func (f *PerPackageFlag) Present() bool
Present reports whether the flag appeared on the command line.
func (*PerPackageFlag) Set ¶
func (f *PerPackageFlag) Set(v string) error
Set is called each time the flag is encountered on the command line.
func (*PerPackageFlag) String ¶
func (f *PerPackageFlag) String() string
String is required to implement flag.Value. It is not used, because cmd/go never calls flag.PrintDefaults.
type TargetDir ¶
type TargetDir int
func InstallTargetDir ¶
InstallTargetDir reports the target directory for installing the command p.