package modload

import "cmd/go/internal/modload"

Index

Variables 

var (
	Target module.Version

	CmdModInit   bool   // running 'go mod init'
	CmdModModule string // module argument for 'go mod init'

	// SilenceMissingStdImports indicates that LoadALL should not print an error
	// or terminate the process if an imported package is missing, and the import
	// path looks like it might be in the standard library (perhaps in a future
	// Go version).
	SilenceMissingStdImports bool
)
var HelpGoMod = &base.Command{
	UsageLine: "go.mod",
	Short:     "the go.mod file",
	Long:      "" /* 3450 byte string literal not displayed */,
}
var HelpModules = &base.Command{
	UsageLine: "modules",
	Short:     "modules, module versions, and more",
	Long:      "" /* 20342 byte string literal not displayed */,
}
var LoadTests bool

LoadTests controls whether the loaders load tests of the root packages.

Functions

func AllowMissingModuleImports 

func AllowMissingModuleImports()

AllowMissingModuleImports allows import paths to be resolved to modules when there is no module root. Normally, this is forbidden because it's slow and there's no way to make the result reproducible, but some commands like 'go get' are expected to do this.

func AllowWriteGoMod 

func AllowWriteGoMod()

AllowWriteGoMod undoes the effect of DisallowWriteGoMod: future calls to WriteGoMod will update go.mod if needed. Note that any past calls have been discarded, so typically a call to AlowWriteGoMod should be followed by a call to WriteGoMod.

func Allowed 

func Allowed(m module.Version) bool

Allowed reports whether module m is allowed (not excluded) by the main module's go.mod.

func BinDir 

func BinDir() string

func BuildList 

func BuildList() []module.Version

BuildList returns the module build list, typically constructed by a previous call to LoadBuildList or ImportPaths. The caller must not modify the returned list.

func DirImportPath 

func DirImportPath(dir string) string

DirImportPath returns the effective import path for dir, provided it is within the main module, or else returns ".".

func DisallowWriteGoMod 

func DisallowWriteGoMod()

DisallowWriteGoMod causes future calls to WriteGoMod to do nothing at all.

func Enabled 

func Enabled() bool

Enabled reports whether modules are (or must be) enabled. If modules are enabled but there is no main module, Enabled returns true and then the first use of module information will call die (usually through MustModRoot).

func HasModRoot 

func HasModRoot() bool

HasModRoot reports whether a main module is present. HasModRoot may return false even if Enabled returns true: for example, 'get' does not require a main module.

func Import 

func Import(path string) (m module.Version, dir string, err error)

Import finds the module and directory in the build list containing the package with the given import path. The answer must be unique: Import returns an error if multiple modules attempt to provide the same package. Import can return a module with an empty m.Path, for packages in the standard library. Import can return an empty directory string, for fake packages like "C" and "unsafe".

If the package cannot be found in the current build list, Import returns an ImportMissingError as the error. If Import can identify a module that could be added to supply the package, the ImportMissingError records that module.

func ImportFromFiles 

func ImportFromFiles(gofiles []string)

ImportFromFiles adds modules to the build list as needed to satisfy the imports in the named Go source files.

func ImportMap 

func ImportMap(path string) string

ImportMap returns the actual package import path for an import path found in source code. If the given import path does not appear in the source code for the packages that have been loaded, ImportMap returns the empty string.

func ImportPaths 

func ImportPaths(patterns []string) []*search.Match

ImportPaths returns the set of packages matching the args (patterns), on the target platform. Modules may be added to the build list to satisfy new imports.

func ImportPathsQuiet 

func ImportPathsQuiet(patterns []string, tags map[string]bool) []*search.Match

ImportPathsQuiet is like ImportPaths but does not warn about patterns with no matches. It also lets the caller specify a set of build tags to match packages. The build tags should typically be imports.Tags() or imports.AnyTags(); a nil map has no special meaning.

func Init 

func Init()

Init determines whether module mode is enabled, locates the root of the current module (if any), sets environment variables for Git subprocesses, and configures the cfg, codehost, load, modfetch, and search packages for use with modules.

func InitMod 

func InitMod()

InitMod sets Target and, if there is a main module, parses the initial build list from its go.mod file, creating and populating that file if needed.

As a side-effect, InitMod sets a default for cfg.BuildMod if it does not already have an explicit value.

func ListModules 

func ListModules(args []string, listU, listVersions bool) []*modinfo.ModulePublic

func LoadALL 

func LoadALL() []string

LoadALL returns the set of all packages in the current module and their dependencies in any other modules, without filtering due to build tags, except "+build ignore". It adds modules to the build list as needed to satisfy new imports. This set is useful for deciding whether a particular import is needed anywhere in a module.

func LoadBuildList 

func LoadBuildList() []module.Version

LoadBuildList loads and returns the build list from go.mod. The loading of the build list happens automatically in ImportPaths: LoadBuildList need only be called if ImportPaths is not (typically in commands that care about the module but no particular package).

func LoadVendor 

func LoadVendor() []string

LoadVendor is like LoadALL but only follows test dependencies for tests in the main module. Tests in dependency modules are ignored completely. This set is useful for identifying the which packages to include in a vendor directory.

func Lookup 

func Lookup(parentPath string, parentIsStd bool, path string) (dir, realPath string, err error)

Lookup returns the source directory, import path, and any loading error for the package at path as imported from the package in parentDir. Lookup requires that one of the Load functions in this package has already been called.

func MinReqs 

func MinReqs() mvs.Reqs

MinReqs returns a Reqs with minimal additional dependencies of Target, as will be written to go.mod.

func ModFile 

func ModFile() *modfile.File

ModFile returns the parsed go.mod file.

Note that after calling ImportPaths or LoadBuildList, the require statements in the modfile.File are no longer the source of truth and will be ignored: edits made directly will be lost at the next call to WriteGoMod. To make permanent changes to the require statements in go.mod, edit it before calling ImportPaths or LoadBuildList.

func ModFilePath 

func ModFilePath() string

ModFilePath returns the effective path of the go.mod file. Normally, this "go.mod" in the directory returned by ModRoot, but the -modfile flag may change its location. ModFilePath calls base.Fatalf if there is no main module, even if -modfile is set.

func ModInfoProg 

func ModInfoProg(info string, isgccgo bool) []byte

func ModRoot 

func ModRoot() string

ModRoot returns the root of the main module. It calls base.Fatalf if there is no main module.

func ModuleHasRootPackage 

func ModuleHasRootPackage(m module.Version) (bool, error)

ModuleHasRootPackage returns whether module m contains a package m.Path.

func ModuleInfo 

func ModuleInfo(path string) *modinfo.ModulePublic

func ModuleUsedDirectly 

func ModuleUsedDirectly(path string) bool

ModuleUsedDirectly reports whether the main module directly imports some package in the module with the given path.

func PackageBuildInfo 

func PackageBuildInfo(path string, deps []string) string

PackageBuildInfo returns a string containing module version information for modules providing packages named by path and deps. path and deps must name packages that were resolved successfully with ImportPaths or one of the Load functions.

func PackageDir 

func PackageDir(path string) string

PackageDir returns the directory containing the source code for the package named by the import path.

func PackageImports 

func PackageImports(path string) (imports, testImports []string)

PackageImports returns the imports for the package named by the import path. Test imports will be returned as well if tests were loaded for the package (i.e., if "all" was loaded or if LoadTests was set and the path was matched by a command line argument). PackageImports will return nil for unknown package paths.

func PackageModule 

func PackageModule(path string) module.Version

PackageModule returns the module providing the package named by the import path.

func PackageModuleInfo 

func PackageModuleInfo(pkgpath string) *modinfo.ModulePublic

PackageModuleInfo returns information about the module that provides a given package. If modules are not enabled or if the package is in the standard library or if the package was not successfully loaded with ImportPaths or a similar loading function, nil is returned.

func Query 

func Query(path, query, current string, allowed func(module.Version) bool) (*modfetch.RevInfo, error)

Query looks up a revision of a given module given a version query string. The module must be a complete module path. The version must take one of the following forms:

current denotes the current version of the module; it may be "" if the current version is unknown or should not be considered. If query is "upgrade" or "patch", current will be returned if it is a newer semantic version or a chronologically later pseudo-version than the version that would otherwise be chosen. This prevents accidental downgrades from newer pre-release or development versions.

If the allowed function is non-nil, Query excludes any versions for which allowed returns false.

If path is the path of the main module and the query is "latest", Query returns Target.Version as the version.

func ReloadBuildList 

func ReloadBuildList() []module.Version

func Replacement 

func Replacement(mod module.Version) module.Version

Replacement returns the replacement for mod, if any, from go.mod. If there is no replacement for mod, Replacement returns a module.Version with Path == "".

func Reqs 

func Reqs() mvs.Reqs

Reqs returns the current module requirement graph. Future calls to SetBuildList do not affect the operation of the returned Reqs.

func SetBuildList 

func SetBuildList(list []module.Version)

SetBuildList sets the module build list. The caller is responsible for ensuring that the list is valid. SetBuildList does not retain a reference to the original list.

func TargetPackages 

func TargetPackages(pattern string) *search.Match

TargetPackages returns the list of packages in the target (top-level) module matching pattern, which may be relative to the working directory, under all build tag settings.

func TidyBuildList 

func TidyBuildList()

TidyBuildList trims the build list to the minimal requirements needed to retain the same versions of all packages from the preceding Load* or ImportPaths* call.

func Why 

func Why(path string) string

Why returns the "go mod why" output stanza for the given package, without the leading # comment. The package graph must have been loaded already, usually by LoadALL. If there is no reason for the package to be in the current build, Why returns an empty string.

func WhyDepth 

func WhyDepth(path string) int

WhyDepth returns the number of steps in the Why listing. If there is no reason for the package to be in the current build, WhyDepth returns 0.

func WillBeEnabled 

func WillBeEnabled() bool

WillBeEnabled checks whether modules should be enabled but does not initialize modules by installing hooks. If Init has already been called, WillBeEnabled returns the same result as Enabled.

This function is needed to break a cycle. The main package needs to know whether modules are enabled in order to install the module or GOPATH version of 'go get', but Init reads the -modfile flag in 'go get', so it shouldn't be called until the command is installed and flags are parsed. Instead of calling Init and Enabled, the main package can call this function.

func WriteGoMod 

func WriteGoMod()

WriteGoMod writes the current build list back to go.mod.

Types

type AmbiguousImportError 

type AmbiguousImportError struct {
	Dirs    []string
	Modules []module.Version // Either empty or 1:1 with Dirs.
	// contains filtered or unexported fields
}

An AmbiguousImportError indicates an import of a package found in multiple modules in the build list, or found in both the main module and its vendor directory.

func (*AmbiguousImportError) Error 

func (e *AmbiguousImportError) Error() string

func (*AmbiguousImportError) ImportPath 

func (e *AmbiguousImportError) ImportPath() string

type ImportMissingError 

type ImportMissingError struct {
	Path     string
	Module   module.Version
	QueryErr error
	// contains filtered or unexported fields
}

func (*ImportMissingError) Error 

func (e *ImportMissingError) Error() string

func (*ImportMissingError) ImportPath 

func (e *ImportMissingError) ImportPath() string

func (*ImportMissingError) Unwrap 

func (e *ImportMissingError) Unwrap() error

type NoMatchingVersionError 

type NoMatchingVersionError struct {
	// contains filtered or unexported fields
}

A NoMatchingVersionError indicates that Query found a module at the requested path, but not at any versions satisfying the query string and allow-function.

NOTE: NoMatchingVersionError MUST NOT implement Is(os.ErrNotExist).

If the module came from a proxy, that proxy had to return a successful status code for the versions it knows about, and thus did not have the opportunity to return a non-400 status code to suppress fallback.

func (*NoMatchingVersionError) Error 

func (e *NoMatchingVersionError) Error() string

type PackageNotInModuleError 

type PackageNotInModuleError struct {
	Mod         module.Version
	Replacement module.Version
	Query       string
	Pattern     string
}

A PackageNotInModuleError indicates that QueryPattern found a candidate module at the requested version, but that module did not contain any packages matching the requested pattern.

NOTE: PackageNotInModuleError MUST NOT implement Is(os.ErrNotExist).

If the module came from a proxy, that proxy had to return a successful status code for the versions it knows about, and thus did not have the opportunity to return a non-400 status code to suppress fallback.

func (*PackageNotInModuleError) Error 

func (e *PackageNotInModuleError) Error() string

func (*PackageNotInModuleError) ImportPath 

func (e *PackageNotInModuleError) ImportPath() string

type QueryResult 

type QueryResult struct {
	Mod      module.Version
	Rev      *modfetch.RevInfo
	Packages []string
}

func QueryPackage 

func QueryPackage(path, query string, allowed func(module.Version) bool) ([]QueryResult, error)

QueryPackage looks up the module(s) containing path at a revision matching query. The results are sorted by module path length in descending order.

If the package is in the main module, QueryPackage considers only the main module and only the version "latest", without checking for other possible modules.

func QueryPattern 

func QueryPattern(pattern, query string, allowed func(module.Version) bool) ([]QueryResult, error)

QueryPattern looks up the module(s) containing at least one package matching the given pattern at the given version. The results are sorted by module path length in descending order.

QueryPattern queries modules with package paths up to the first "..." in the pattern. For the pattern "example.com/a/b.../c", QueryPattern would consider prefixes of "example.com/a". If multiple modules have versions that match the query and packages that match the pattern, QueryPattern picks the one with the longest module path.

If any matching package is in the main module, QueryPattern considers only the main module and only the version "latest", without checking for other possible modules.

Source Files

build.go help.go import.go init.go list.go load.go modfile.go mvs.go query.go search.go stat_unix.go vendor.go

Version
v1.15.10
Published
Mar 11, 2021
Platform
linux/amd64
Imports
35 packages
Last checked
59 seconds ago –

Tools for package owners.