package packages

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

Dependency Relation
	imports 31 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 return a list of Package
		structs describing individual packages matched by those patterns.
		The LoadMode controls the amount of detail in the loaded packages.

		Load passes most patterns directly to the underlying build tool,
		but 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
		  - TypeInfo, 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 the loader, so that the loader can interpret them
		according to the conventions of the underlying build system.
		See the Example function for typical usage.

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


Code Examples

	
		package main
		
		import (
			"flag"
			"fmt"
			"golang.org/x/tools/go/packages"
			"os"
		)
		
		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 8 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.
				If the context is cancelled, the loader may stop early
				and return an ErrCancelled error.
				If Context is nil, the load cannot be cancelled.

			
				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 provides a mapping of absolute file paths to file contents.
				If the file with the given path already exists, the parser will use the
				alternative file contents provided by the map.

				Overlays provide incomplete support for when a given file doesn't
				already exist on disk. See the package doc above for more details.

			
				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)
			


	
		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.

		
			( 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 NeedImports
			const NeedModule
			const NeedName
			const NeedSyntax
			const NeedTypes
			const NeedTypesInfo
			const NeedTypesSizes
			


	
		Module provides module information for a package.

		
			
				// 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



	
		OverlayJSON is the format overlay files are expected to be in.
		The Replace map maps from overlaid paths to replacement paths:
		the Go command will forward all reads trying to open
		each overlaid path to its replacement path, or consider the overlaid
		path not to exist if the replacement path is empty.

		From golang/go#39958.

		
			Replace map[string]string


	
		A Package describes a loaded Go package.

		
			
				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.

			
				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.

			
				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.

			
				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.

			
				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.

			
				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.

			
				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 26, in which 3 are exported)


	
		Load loads and returns the Go packages named by the given patterns.

		Config specifies loading options;
		nil behaves the same as an empty Config.

		Load returns an error if any of the patterns was invalid
		as defined by the underlying build system.
		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 26, in which 23 are exported)


	
		Deprecated: LoadAllSyntax exists for historical compatibility
		and should not be used. Please directly specify the needed fields using the Need values.


	
		Deprecated: LoadFiles exists for historical compatibility
		and should not be used. Please directly specify the needed fields using the Need values.


	
		Deprecated: LoadImports exists for historical compatibility
		and should not be used. Please directly specify the needed fields using the Need values.


	
		Deprecated: LoadSyntax exists for historical compatibility
		and should not be used. Please directly specify the needed fields using the Need values.


	
		Deprecated: LoadTypes exists for historical compatibility
		and should not be used. Please directly specify the needed fields using the Need values.


	
		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 GoFiles and OtherFiles.


	
		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.


	
		NeedTypes adds Types, Fset, and IllTyped.


	
		NeedTypesInfo adds TypesInfo.


	
		NeedTypesSizes adds TypesSizes.