package packages

Import Path
	golang.org/x/tools/go/packages (on go.dev)

Dependency Relation
	imports 30 packages, and imported by one package


Involved Source Files

	
		Package packages loads Go packages for inspection and analysis.
		
		The [Load] function takes as input a list of patterns and returns a
		list of [Package] values describing individual packages matched by those
		patterns.
		A [Config] specifies configuration options, the most important of which is
		the [LoadMode], which controls the amount of detail in the loaded packages.
		
		Load passes most patterns directly to the underlying build tool.
		The default build tool is the go command.
		Its supported patterns are described at
		https://pkg.go.dev/cmd/go#hdr-Package_lists_and_patterns.
		Other build systems may be supported by providing a "driver";
		see [The driver protocol].
		
		All patterns with the prefix "query=", where query is a
		non-empty string of letters from [a-z], are reserved and may be
		interpreted as query operators.
		
		Two query operators are currently supported: "file" and "pattern".
		
		The query "file=path/to/file.go" matches the package or packages enclosing
		the Go source file path/to/file.go.  For example "file=~/go/src/fmt/print.go"
		might return the packages "fmt" and "fmt [fmt.test]".
		
		The query "pattern=string" causes "string" to be passed directly to
		the underlying build tool. In most cases this is unnecessary,
		but an application can use Load("pattern=" + x) as an escaping mechanism
		to ensure that x is not interpreted as a query operator if it contains '='.
		
		All other query operators are reserved for future use and currently
		cause Load to report an error.
		
		The Package struct provides basic information about the package, including
		
		  - ID, a unique identifier for the package in the returned set;
		  - GoFiles, the names of the package's Go source files;
		  - Imports, a map from source import strings to the Packages they name;
		  - Types, the type information for the package's exported symbols;
		  - Syntax, the parsed syntax trees for the package's source code; and
		  - TypesInfo, the result of a complete type-check of the package syntax trees.
		
		(See the documentation for type Package for the complete list of fields
		and more detailed descriptions.)
		
		For example,
		
			Load(nil, "bytes", "unicode...")
		
		returns four Package structs describing the standard library packages
		bytes, unicode, unicode/utf16, and unicode/utf8. Note that one pattern
		can match multiple packages and that a package might be matched by
		multiple patterns: in general it is not possible to determine which
		packages correspond to which patterns.
		
		Note that the list returned by Load contains only the packages matched
		by the patterns. Their dependencies can be found by walking the import
		graph using the Imports fields.
		
		The Load function can be configured by passing a pointer to a Config as
		the first argument. A nil Config is equivalent to the zero Config, which
		causes Load to run in [LoadFiles] mode, collecting minimal information.
		See the documentation for type Config for details.
		
		As noted earlier, the Config.Mode controls the amount of detail
		reported about the loaded packages. See the documentation for type LoadMode
		for details.
		
		Most tools should pass their command-line arguments (after any flags)
		uninterpreted to Load, so that it can interpret them
		according to the conventions of the underlying build system.
		
		See the Example function for typical usage.
		See also [golang.org/x/tools/go/packages/internal/linecount]
		for an example application.
		
		# The driver protocol
		
		Load may be used to load Go packages even in Go projects that use
		alternative build systems, by installing an appropriate "driver"
		program for the build system and specifying its location in the
		GOPACKAGESDRIVER environment variable.
		For example,
		https://github.com/bazelbuild/rules_go/wiki/Editor-and-tool-integration
		explains how to use the driver for Bazel.
		
		The driver program is responsible for interpreting patterns in its
		preferred notation and reporting information about the packages that
		those patterns identify. Drivers must also support the special "file="
		and "pattern=" patterns described above.
		
		The patterns are provided as positional command-line arguments. A
		JSON-encoded [DriverRequest] message providing additional information
		is written to the driver's standard input. The driver must write a
		JSON-encoded [DriverResponse] message to its standard output. (This
		message differs from the JSON schema produced by 'go list'.)
		
		The value of the PWD environment variable seen by the driver process
		is the preferred name of its working directory. (The working directory
		may have other aliases due to symbolic links; see the comment on the
		Dir field of [exec.Cmd] for related information.)
		When the driver process emits in its response the name of a file
		that is a descendant of this directory, it must use an absolute path
		that has the value of PWD as a prefix, to ensure that the returned
		filenames satisfy the original query.

	    external.go
	    golist.go
	    golist_overlay.go
	    loadmode_string.go
	    packages.go
	    visit.go


Code Examples

	
		package main
		
		import (
			"flag"
			"fmt"
			"os"
		
			"golang.org/x/tools/go/packages"
		)
		
		func main() {
			flag.Parse()
		
			// Many tools pass their command-line arguments (after any flags)
			// uninterpreted to packages.Load so that it can interpret them
			// according to the conventions of the underlying build system.
			cfg := &packages.Config{Mode: packages.NeedFiles | packages.NeedSyntax}
			pkgs, err := packages.Load(cfg, flag.Args()...)
			if err != nil {
				fmt.Fprintf(os.Stderr, "load: %v\n", err)
				os.Exit(1)
			}
			if packages.PrintErrors(pkgs) > 0 {
				os.Exit(1)
			}
		
			// Print the names of the source files
			// for each package listed on the command line.
			for _, pkg := range pkgs {
				fmt.Println(pkg.ID, pkg.GoFiles)
			}
		}




Package-Level Type Names (total 21, in which 9 are exported)


	/* sort exporteds by:  |  */
	
		A Config specifies details about how packages should be loaded.
		The zero value is a valid configuration.
		
		Calls to [Load] do not modify this struct.

		
			
				BuildFlags is a list of command-line flags to be passed through to
				the build system's query tool.

			
				Context specifies the context for the load operation.
				Cancelling the context may cause [Load] to abort and
				return an error.

			
				Dir is the directory in which to run the build system's query tool
				that provides information about the packages.
				If Dir is empty, the tool is run in the current directory.

			
				Env is the environment to use when invoking the build system's query tool.
				If Env is nil, the current environment is used.
				As in os/exec's Cmd, only the last value in the slice for
				each environment key is used. To specify the setting of only
				a few variables, append to the current environment, as in:
				
					opt.Env = append(os.Environ(), "GOOS=plan9", "GOARCH=386")

			
				Fset provides source position information for syntax trees and types.
				If Fset is nil, Load will use a new fileset, but preserve Fset's value.

			
				Logf is the logger for the config.
				If the user provides a logger, debug logging is enabled.
				If the GOPACKAGESDEBUG environment variable is set to true,
				but the logger is nil, default to log.Printf.

			
				Mode controls the level of information returned for each package.

			
				Overlay is a mapping from absolute file paths to file contents.
				
				For each map entry, [Load] uses the alternative file
				contents provided by the overlay mapping instead of reading
				from the file system. This mechanism can be used to enable
				editor-integrated tools to correctly analyze the contents
				of modified but unsaved buffers, for example.
				
				The overlay mapping is passed to the build system's driver
				(see "The driver protocol") so that it too can report
				consistent package metadata about unsaved files. However,
				drivers may vary in their level of support for overlays.

			
				ParseFile is called to read and parse each file
				when preparing a package's type-checked syntax tree.
				It must be safe to call ParseFile simultaneously from multiple goroutines.
				If ParseFile is nil, the loader will uses parser.ParseFile.
				
				ParseFile should parse the source from src and use filename only for
				recording position information.
				
				An application may supply a custom implementation of ParseFile
				to change the effective file contents or the behavior of the parser,
				or to modify the syntax tree. For example, selectively eliminating
				unwanted function bodies can significantly accelerate type checking.

			
				If Tests is set, the loader includes not just the packages
				matching a particular pattern but also any related test packages,
				including test-only variants of the package and the test executable.
				
				For example, when using the go command, loading "fmt" with Tests=true
				returns four packages, with IDs "fmt" (the standard package),
				"fmt [fmt.test]" (the package as compiled for the test),
				"fmt_test" (the test functions from source files in package fmt_test),
				and "fmt.test" (the test binary).
				
				In build systems with explicit names for tests,
				setting Tests may have no effect.

		
			
		
			func Load(cfg *Config, patterns ...string) ([]*Package, error)
			


	
		DriverRequest defines the schema of a request for package metadata
		from an external driver program. The JSON-encoded DriverRequest
		message is provided to the driver program's standard input. The
		query patterns are provided as command-line arguments.
		
		See the package documentation for an overview.

		
			
				BuildFlags are flags that should be passed to the underlying build system.

			
				Env specifies the environment the underlying build system should be run in.

			Mode LoadMode
			
				Overlay maps file paths (relative to the driver's working directory)
				to the contents of overlay files (see Config.Overlay).

			
				Tests specifies whether the patterns should also return test packages.



	
		DriverResponse defines the schema of a response from an external
		driver program, providing the results of a query for package
		metadata. The driver program must write a JSON-encoded
		DriverResponse message to its standard output.
		
		See the package documentation for an overview.

		
			Arch string
			
				Compiler and Arch are the arguments pass of types.SizesFor
				to get a types.Sizes to use when type checking.

			
				GoVersion is the minor version number used by the driver
				(e.g. the go command on the PATH) when selecting .go files.
				Zero means unknown.

			
				NotHandled is returned if the request can't be handled by the current
				driver. If an external driver returns a response with NotHandled, the
				rest of the DriverResponse is ignored, and go/packages will fallback
				to the next driver. If go/packages is extended in the future to support
				lists of multiple drivers, go/packages will fall back to the next driver.

			
				Packages is the full set of packages in the graph.
				The packages are not connected into a graph.
				The Imports if populated will be stubs that only have their ID set.
				Imports will be connected and then type and syntax information added in a
				later pass (see refine).

			
				Roots is the set of package IDs that make up the root packages.
				We have to encode this separately because when we encode a single package
				we cannot know if it is one of the roots as that requires knowledge of the
				graph it is part of.

		
			
		
			


	
		An Error describes a problem with a package's metadata, syntax, or types.

		
			Kind ErrorKind
			Msg string
			
				// "file:line:col" or "file:line" or "" or "-"

		
			( Error) Error() string
		
			 Error : error


	
		ErrorKind describes the source of the error, allowing the user to
		differentiate between errors generated by the driver, the parser, or the
		type-checker.

		
			const ListError
			const ParseError
			const TypeError
			const UnknownError


	
		A LoadMode controls the amount of detail to return when loading.
		The bits below can be combined to specify which fields should be
		filled in the result packages.
		
		The zero value is a special case, equivalent to combining
		the NeedName, NeedFiles, and NeedCompiledGoFiles bits.
		
		ID and Errors (if present) will always be filled.
		[Load] may return more information than requested.
		
		The Mode flag is a union of several bits named NeedName,
		NeedFiles, and so on, each of which determines whether
		a given field of Package (Name, Files, etc) should be
		populated.
		
		For convenience, we provide named constants for the most
		common combinations of Need flags:
		
			[LoadFiles]     lists of files in each package
			[LoadImports]   ... plus imports
			[LoadTypes]     ... plus type information
			[LoadSyntax]    ... plus type-annotated syntax
			[LoadAllSyntax] ... for all dependencies
		
		Unfortunately there are a number of open bugs related to
		interactions among the LoadMode bits:
		  - https://go.dev/issue/56633
		  - https://go.dev/issue/56677
		  - https://go.dev/issue/58726
		  - https://go.dev/issue/63517

		
			( LoadMode) String() string
		
			 LoadMode : expvar.Var
			 LoadMode : fmt.Stringer
			
		
			
		
			
		
			const LoadAllSyntax
			const LoadFiles
			const LoadImports
			const LoadSyntax
			const LoadTypes
			const NeedCompiledGoFiles
			const NeedDeps
			const NeedEmbedFiles
			const NeedEmbedPatterns
			const NeedExportFile
			const NeedExportsFile
			const NeedFiles
			const NeedForTest
			const NeedImports
			const NeedModule
			const NeedName
			const NeedSyntax
			const NeedTarget
			const NeedTypes
			const NeedTypesInfo
			const NeedTypesSizes
			


	
		Module provides module information for a package.
		
		It also defines part of the JSON schema of [DriverResponse].
		See the package documentation for an overview.

		
			
				// directory holding files for this module, if any

			
				// error loading module

			
				// path to go.mod file used when loading this module, if any

			
				// go version used in module

			
				// is this module only an indirect dependency of main module?

			
				// is this the main module?

			
				// module path

			
				// replaced by this module

			
				// time version was created

			
				// module version

		
			
		
			


	
		ModuleError holds errors loading a module.

		
			
				// the error itself



	
		A Package describes a loaded Go package.
		
		It also defines part of the JSON schema of [DriverResponse].
		See the package documentation for an overview.

		
			
				CompiledGoFiles lists the absolute file paths of the package's source
				files that are suitable for type checking.
				This may differ from GoFiles if files are processed before compilation.

			
				Dir is the directory associated with the package, if it exists.
				
				For packages listed by the go command, this is the directory containing
				the package files.

			
				EmbedFiles lists the absolute file paths of the package's files
				embedded with go:embed.

			
				EmbedPatterns lists the absolute file patterns of the package's
				files embedded with go:embed.

			
				Errors contains any errors encountered querying the metadata
				of the package, or while parsing or type-checking its files.

			
				ExportFile is the absolute path to a file containing type
				information for the package as provided by the build system.

			
				ForTest is the package under test, if any.

			
				Fset provides position information for Types, TypesInfo, and Syntax.
				It is set only when Types is set.

			
				GoFiles lists the absolute file paths of the package's Go source files.
				It may include files that should not be compiled, for example because
				they contain non-matching build tags, are documentary pseudo-files such as
				unsafe/unsafe.go or builtin/builtin.go, or are subject to cgo preprocessing.

			
				ID is a unique identifier for a package,
				in a syntax provided by the underlying build system.
				
				Because the syntax varies based on the build system,
				clients should treat IDs as opaque and not attempt to
				interpret them.

			
				IgnoredFiles lists source files that are not part of the package
				using the current build configuration but that might be part of
				the package using other build configurations.

			
				IllTyped indicates whether the package or any dependency contains errors.
				It is set only when Types is set.

			
				Imports maps import paths appearing in the package's Go source files
				to corresponding loaded Packages.

			
				Module is the module information for the package if it exists.
				
				Note: it may be missing for std and cmd; see Go issue #65816.

			
				Name is the package name as it appears in the package source code.

			
				OtherFiles lists the absolute file paths of the package's non-Go source files,
				including assembly, C, C++, Fortran, Objective-C, SWIG, and so on.

			
				PkgPath is the package path as used by the go/types package.

			
				Syntax is the package's syntax trees, for the files listed in CompiledGoFiles.
				
				The NeedSyntax LoadMode bit populates this field for packages matching the patterns.
				If NeedDeps and NeedImports are also set, this field will also be populated
				for dependencies.
				
				Syntax is kept in the same order as CompiledGoFiles, with the caveat that nils are
				removed.  If parsing returned nil, Syntax may be shorter than CompiledGoFiles.

			
				Target is the absolute install path of the .a file, for libraries,
				and of the executable file, for binaries.

			
				TypeErrors contains the subset of errors produced during type checking.

			
				Types provides type information for the package.
				The NeedTypes LoadMode bit sets this field for packages matching the
				patterns; type information for dependencies may be missing or incomplete,
				unless NeedDeps and NeedImports are also set.
				
				Each call to [Load] returns a consistent set of type
				symbols, as defined by the comment at [types.Identical].
				Avoid mixing type information from two or more calls to [Load].

			
				TypesInfo provides type information about the package's syntax trees.
				It is set only when Syntax is set.

			
				TypesSizes provides the effective size function for types in TypesInfo.

			
		
			
				MarshalJSON returns the Package in its JSON form.
				For the most part, the structure fields are written out unmodified, and
				the type and syntax fields are skipped.
				The imports are written out as just a map of path to package id.
				The errors are written using a custom type that tries to preserve the
				structure of error types we know about.
				
				This method exists to enable support for additional build systems.  It is
				not intended for use by clients of the API and we may change the format.

			(*Package) String() string
			
				UnmarshalJSON reads in a Package from its JSON format.
				See MarshalJSON for details about the format accepted.

		
			*Package : encoding/json.Marshaler
			*Package : encoding/json.Unmarshaler
			*Package : expvar.Var
			*Package : fmt.Stringer
			
		
			func Load(cfg *Config, patterns ...string) ([]*Package, error)
			
		
			func PrintErrors(pkgs []*Package) int
			func Visit(pkgs []*Package, pre func(*Package) bool, post func(*Package))
			


	


Package-Level Functions (total 22, in which 3 are exported)


	
		Load loads and returns the Go packages named by the given patterns.
		
		The cfg parameter specifies loading options; nil behaves the same as an empty [Config].
		
		The [Config.Mode] field is a set of bits that determine what kinds
		of information should be computed and returned. Modes that require
		more information tend to be slower. See [LoadMode] for details
		and important caveats. Its zero value is equivalent to
		[NeedName] | [NeedFiles] | [NeedCompiledGoFiles].
		
		Each call to Load returns a new set of [Package] instances.
		The Packages and their Imports form a directed acyclic graph.
		
		If the [NeedTypes] mode flag was set, each call to Load uses a new
		[types.Importer], so [types.Object] and [types.Type] values from
		different calls to Load must not be mixed as they will have
		inconsistent notions of type identity.
		
		If any of the patterns was invalid as defined by the
		underlying build system, Load returns an error.
		It may return an empty list of packages without an error,
		for instance for an empty expansion of a valid wildcard.
		Errors associated with a particular package are recorded in the
		corresponding Package's Errors list, and do not cause Load to
		return an error. Clients may need to handle such errors before
		proceeding with further analysis. The [PrintErrors] function is
		provided for convenient display of all errors.


	
		PrintErrors prints to os.Stderr the accumulated errors of all
		packages in the import graph rooted at pkgs, dependencies first.
		PrintErrors returns the number of errors printed.


	
		Visit visits all the packages in the import graph whose roots are
		pkgs, calling the optional pre function the first time each package
		is encountered (preorder), and the optional post function after a
		package's dependencies have been visited (postorder).
		The boolean result of pre(pkg) determines whether
		the imports of package pkg are visited.


	


Package-Level Variables (total 4, none are exported)

	


Package-Level Constants (total 27, in which 25 are exported)


	
		LoadAllSyntax loads typed syntax for the initial packages and all dependencies.


	
		LoadFiles loads the name and file names for the initial packages.


	
		LoadImports loads the name, file names, and import mapping for the initial packages.


	
		LoadSyntax loads typed syntax for the initial packages.


	
		LoadTypes loads exported type information for the initial packages.


	
		NeedCompiledGoFiles adds CompiledGoFiles.


	
		NeedDeps adds the fields requested by the LoadMode in the packages in Imports.


	
		NeedEmbedFiles adds EmbedFiles.


	
		NeedEmbedPatterns adds EmbedPatterns.


	
		NeedExportFile adds ExportFile.


	
		Deprecated: NeedExportsFile is a historical misspelling of NeedExportFile.


	
		NeedFiles adds Dir, GoFiles, OtherFiles, and IgnoredFiles


	
		NeedForTest adds ForTest.
		
		Tests must also be set on the context for this field to be populated.


	
		NeedImports adds Imports. If NeedDeps is not set, the Imports field will contain
		"placeholder" Packages with only the ID set.


	
		NeedModule adds Module.


	
		NeedName adds Name and PkgPath.


	
		NeedSyntax adds Syntax and Fset.


	
		NeedTarget adds Target.


	
		NeedTypes adds Types, Fset, and IllTyped.


	
		NeedTypesInfo adds TypesInfo and Fset.


	
		NeedTypesSizes adds TypesSizes.