From 1e4de0584ea7dce1e31bcaba5de4d81319ba6d6c Mon Sep 17 00:00:00 2001 From: Alan Donovan Date: Wed, 10 Apr 2024 15:40:00 -0400 Subject: [PATCH] cmd/compile: describe export data Updates #30074 Change-Id: Ic74d482943d992c20f69edb106c666a7b26291c1 Reviewed-on: https://go-review.googlesource.com/c/go/+/578055 LUCI-TryBot-Result: Go LUCI Reviewed-by: Than McIntosh Reviewed-by: Cuong Manh Le --- src/cmd/compile/README.md | 49 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/src/cmd/compile/README.md b/src/cmd/compile/README.md index 9b99a1b105..3fc7ca6ec6 100644 --- a/src/cmd/compile/README.md +++ b/src/cmd/compile/README.md @@ -140,6 +140,55 @@ a series of obj.Prog instructions. These are passed to the assembler final object file. The object file will also contain reflect data, export data, and debugging information. +### 7a. Export + +In addition to writing a file of object code for the linker, the +compiler also writes a file of "export data" for downstream +compilation units. The export data file holds all the information +computed during compilation of package P that may be needed when +compiling a package Q that directly imports P. It includes type +information for all exported declarations, IR for bodies of functions +that are candidates for inlining, IR for bodies of generic functions +that may be instantiated in another package, and a summary of the +findings of escape analysis on function parameters. + +The format of the export data file has gone through a number of +iterations. Its current form is called "unified", and it is a +serialized representation of an object graph, with an index allowing +lazy decoding of parts of the whole (since most imports are used to +provide only a handful of symbols). + +The GOROOT repository contains a reader and a writer for the unified +format; it encodes from/decodes to the compiler's IR. +The golang.org/x/tools repository also provides a public API for an export +data reader (using the go/types representation) that always supports the +compiler's current file format and a small number of historic versions. +(It is used by x/tools/go/packages in modes that require type information +but not type-annotated syntax.) + +The x/tools repository also provides public APIs for reading and +writing exported type information (but nothing more) using the older +"indexed" format. (For example, gopls uses this version for its +database of workspace information, which includes types.) + +Export data usually provides a "deep" summary, so that compilation of +package Q can read the export data files only for each direct import, +and be assured that these provide all necessary information about +declarations in indirect imports, such as the methods and struct +fields of types referred to in P's public API. Deep export data is +simpler for build systems, since only one file is needed per direct +dependency. However, it does have a tendency to grow as one gets +higher up the import graph of a big repository: if there is a set of +very commonly used types with a large API, nearly every package's +export data will include a copy. This problem motivated the "indexed" +design, which allowed partial loading on demand. +(gopls does less work than the compiler for each import and is thus +more sensitive to export data overheads. For this reason, it uses +"shallow" export data, in which indirect information is not recorded +at all. This demands random access to the export data files of all +dependencies, so is not suitable for distributed build systems.) + + ### 8. Tips #### Getting Started -- 2.48.1