22// Use of this source code is governed by a BSD-style
33// license that can be found in the LICENSE file.
44
5- // This file enables an external tool to intercept package requests.
6- // If the tool is present then its results are used in preference to
7- // the go list command.
8-
95package packages
106
7+ // This file defines the protocol that enables an external "driver"
8+ // tool to supply package metadata in place of 'go list'.
9+
1110import (
1211 "bytes"
1312 "encoding/json"
@@ -17,31 +16,71 @@ import (
1716 "strings"
1817)
1918
20- // The Driver Protocol
19+ // DriverRequest defines the schema of a request for package metadata
20+ // from an external driver program. The JSON-encoded DriverRequest
21+ // message is provided to the driver program's standard input. The
22+ // query patterns are provided as command-line arguments.
2123//
22- // The driver, given the inputs to a call to Load, returns metadata about the packages specified.
23- // This allows for different build systems to support go/packages by telling go/packages how the
24- // packages' source is organized.
25- // The driver is a binary, either specified by the GOPACKAGESDRIVER environment variable or in
26- // the path as gopackagesdriver. It's given the inputs to load in its argv. See the package
27- // documentation in doc.go for the full description of the patterns that need to be supported.
28- // A driver receives as a JSON-serialized driverRequest struct in standard input and will
29- // produce a JSON-serialized driverResponse (see definition in packages.go) in its standard output.
30-
31- // driverRequest is used to provide the portion of Load's Config that is needed by a driver.
32- type driverRequest struct {
24+ // See the package documentation for an overview.
25+ type DriverRequest struct {
3326 Mode LoadMode `json:"mode"`
27+
3428 // Env specifies the environment the underlying build system should be run in.
3529 Env []string `json:"env"`
30+
3631 // BuildFlags are flags that should be passed to the underlying build system.
3732 BuildFlags []string `json:"build_flags"`
33+
3834 // Tests specifies whether the patterns should also return test packages.
3935 Tests bool `json:"tests"`
36+
4037 // Overlay maps file paths (relative to the driver's working directory) to the byte contents
4138 // of overlay files.
4239 Overlay map [string ][]byte `json:"overlay"`
4340}
4441
42+ // DriverResponse defines the schema of a response from an external
43+ // driver program, providing the results of a query for package
44+ // metadata. The driver program must write a JSON-encoded
45+ // DriverResponse message to its standard output.
46+ //
47+ // See the package documentation for an overview.
48+ type DriverResponse struct {
49+ // NotHandled is returned if the request can't be handled by the current
50+ // driver. If an external driver returns a response with NotHandled, the
51+ // rest of the DriverResponse is ignored, and go/packages will fallback
52+ // to the next driver. If go/packages is extended in the future to support
53+ // lists of multiple drivers, go/packages will fall back to the next driver.
54+ NotHandled bool
55+
56+ // Compiler and Arch are the arguments pass of types.SizesFor
57+ // to get a types.Sizes to use when type checking.
58+ Compiler string
59+ Arch string
60+
61+ // Roots is the set of package IDs that make up the root packages.
62+ // We have to encode this separately because when we encode a single package
63+ // we cannot know if it is one of the roots as that requires knowledge of the
64+ // graph it is part of.
65+ Roots []string `json:",omitempty"`
66+
67+ // Packages is the full set of packages in the graph.
68+ // The packages are not connected into a graph.
69+ // The Imports if populated will be stubs that only have their ID set.
70+ // Imports will be connected and then type and syntax information added in a
71+ // later pass (see refine).
72+ Packages []* Package
73+
74+ // GoVersion is the minor version number used by the driver
75+ // (e.g. the go command on the PATH) when selecting .go files.
76+ // Zero means unknown.
77+ GoVersion int
78+ }
79+
80+ // driver is the type for functions that query the build system for the
81+ // packages named by the patterns.
82+ type driver func (cfg * Config , patterns ... string ) (* DriverResponse , error )
83+
4584// findExternalDriver returns the file path of a tool that supplies
4685// the build system package structure, or "" if not found."
4786// If GOPACKAGESDRIVER is set in the environment findExternalTool returns its
@@ -64,8 +103,8 @@ func findExternalDriver(cfg *Config) driver {
64103 return nil
65104 }
66105 }
67- return func (cfg * Config , words ... string ) (* driverResponse , error ) {
68- req , err := json .Marshal (driverRequest {
106+ return func (cfg * Config , words ... string ) (* DriverResponse , error ) {
107+ req , err := json .Marshal (DriverRequest {
69108 Mode : cfg .Mode ,
70109 Env : cfg .Env ,
71110 BuildFlags : cfg .BuildFlags ,
@@ -92,7 +131,7 @@ func findExternalDriver(cfg *Config) driver {
92131 fmt .Fprintf (os .Stderr , "%s stderr: <<%s>>\n " , cmdDebugStr (cmd ), stderr )
93132 }
94133
95- var response driverResponse
134+ var response DriverResponse
96135 if err := json .Unmarshal (buf .Bytes (), & response ); err != nil {
97136 return nil , err
98137 }
0 commit comments