package gcimporter

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

Dependency Relation
	imports 24 packages, and imported by one package

Involved Source Files bimport.go exportdata.go Package gcimporter provides various functions for reading gc-generated object files that can be used to implement the Importer interface defined by the Go 1.5 standard library package. The encoding is deterministic: if the encoder is applied twice to the same types.Package data structure, both encodings are equal. This property may be important to avoid spurious changes in applications such as build systems. However, the encoder is not necessarily idempotent. Importing an exported package may yield a types.Package that, while it represents the same set of Go types as the original, may differ in the details of its internal representation. Because of these differences, re-encoding the imported package may yield a different, but equally valid, encoding of the package. iexport.go iimport.go predeclared.go support.go ureader_yes.go
Package-Level Type Names (total 24, in which 3 are exported)
/* sort exporteds by: | */
A GetPackagesFunc function obtains the non-nil symbols for a set of packages, creating and recursively importing them as needed. An implementation should store each package symbol is in the Pkg field of the items array. Any error causes importing to fail. This can be used to quickly read the import manifest of an export data file without fully decoding it.
A GetPackagesItem is a request from the importer for the package symbol of the specified name and path. Name string Path string // to be filled in by GetPackagesFunc call
ReportFunc is the type of a function used to report formatted bugs.
Package-Level Functions (total 34, in which 15 are exported)
FindExportData positions the reader r at the beginning of the export data section of an underlying cmd/compile created archive file by reading from it. The reader must be positioned at the start of the file before calling this function. This returns the length of the export data in bytes. This function is needed by [gcexportdata.Read], which must accept inputs produced by the last two releases of cmd/compile, plus tip.
FindPackageDefinition positions the reader r at the beginning of a package definition file ("__.PKGDEF") within a GC-created archive by reading from it, and returns the size of the package definition file in the archive. The reader must be positioned at the start of the archive file before calling this function, and "__.PKGDEF" is assumed to be the first file in the archive. See cmd/internal/archive for details on the archive format.
FindPkg returns the filename and unique package id for an import path based on package information provided by build.Import (using the build.Default build.Context). A relative srcDir is interpreted relative to the current working directory. FindPkg is only used in tests within x/tools.
GetPackagesFromMap returns a GetPackagesFunc that retrieves packages from the given map of package path to package. The returned function may mutate m: each requested package that is not found is created with types.NewPackage and inserted into m.
IExportBundle writes an indexed export bundle for pkgs to out.
IExportData writes indexed export data for pkg to out. If no file set is provided, position info will be missing. The package path of the top-level package will not be recorded, so that calls to IImportData can override with a provided package path.
IExportShallow encodes "shallow" export data for the specified package. For types, we use "shallow" export data. Historically, the Go compiler always produced a summary of the types for a given package that included types from other packages that it indirectly referenced: "deep" export data. This had the advantage that the compiler (and analogous tools such as gopls) need only load one file per direct import. However, it meant that the files tended to get larger based on the level of the package in the import graph. For example, higher-level packages in the kubernetes module have over 1MB of "deep" export data, even when they have almost no content of their own, merely because they mention a major type that references many others. In pathological cases the export data was 300x larger than the source for a package due to this quadratic growth. "Shallow" export data means that the serialized types describe only a single package. If those types mention types from other packages, the type checker may need to request additional packages beyond just the direct imports. Type information for the entire transitive closure of imports is provided (lazily) by the DAG. No promises are made about the encoding other than that it can be decoded by the same version of IIExportShallow. If you plan to save export data in the file system, be sure to include a cryptographic digest of the executable in the key to avoid version skew. If the provided reportf func is non-nil, it is used for reporting bugs (e.g. recovered panics) encountered during export, enabling us to obtain via telemetry the stack that would otherwise be lost by merely returning an error.
IImportBundle imports a set of packages from the serialized package bundle.
IImportData imports a package from the serialized package data and returns 0 and a reference to the package. If the export data version is not recognized or the format is otherwise compromised, an error is returned.
IImportShallow decodes "shallow" types.Package data encoded by [IExportShallow] in the same executable. This function cannot import data from cmd/compile or gcexportdata.Write. The importer calls getPackages to obtain package symbols for all packages mentioned in the export data, including the one being decoded. If the provided reportf func is non-nil, it will be used for reporting bugs encountered during import. TODO(rfindley): remove reportf when we are confident enough in the new objectpath encoding.
Import imports a gc-generated package given its import path and srcDir, adds the corresponding package object to the packages map, and returns the object. The packages map must contain all packages already imported. Import is only used in tests.
ReadExportDataHeader reads the export data header and format from r. It returns the number of bytes read, or an error if the format is no longer supported or it failed to read. The only currently supported format is binary export data in the unified export format.
ReadObjectHeaders reads object headers from the reader. Object headers are lines that do not start with an end-of-section marker "$$". The first header is the objabi header. On success, the reader will be positioned at the beginning of the end-of-section marker. It returns an error if any header does not fit in r.Size() bytes.
ReadUnified reads the contents of the unified export data from a reader r that contains the contents of a GC-created archive file. On success, the reader will be positioned after the end-of-section marker "\n$$\n". Supported GC-created archive files have 4 layers of nesting: - An archive file containing a package definition file. - The package definition file contains headers followed by a data section. Headers are lines (≤ 4kb) that do not start with "$$". - The data section starts with "$$B\n" followed by export data followed by an end of section marker "\n$$\n". (The section start "$$\n" is no longer supported.) - The export data starts with a format byte ('u') followed by the <data> in the given format. (See ReadExportDataHeader for older formats.) Putting this together, the bytes in a GC-created archive files are expected to look like the following. See cmd/internal/archive for more details on ar file headers. | <!arch>\n | ar file signature | __.PKGDEF...size...\n | ar header for __.PKGDEF including size. | go object <...>\n | objabi header | <optional headers>\n | other headers such as build id | $$B\n | binary format marker | u<data>\n | unified export <data> | $$\n | end-of-section marker | [optional padding] | padding byte (0x0A) if size is odd | [ar file header] | other ar files | [ar file data] |
func UImportData(fset *token.FileSet, imports map[string]*types.Package, data []byte, path string) (_ int, pkg *types.Package, err error)
Package-Level Variables (total 7, none are exported)
Package-Level Constants (total 35, none are exported)