.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools@v0.0.0-20201105173854-bc9fc8d8c4bc/go/packages/doc.go

   1 // Copyright 2018 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 /*
   6 Package packages loads Go packages for inspection and analysis.
   7
   8 The Load function takes as input a list of patterns and return a list of Package
   9 structs describing individual packages matched by those patterns.
  10 The LoadMode controls the amount of detail in the loaded packages.
  11
  12 Load passes most patterns directly to the underlying build tool,
  13 but all patterns with the prefix "query=", where query is a
  14 non-empty string of letters from [a-z], are reserved and may be
  15 interpreted as query operators.
  16
  17 Two query operators are currently supported: "file" and "pattern".
  18
  19 The query "file=path/to/file.go" matches the package or packages enclosing
  20 the Go source file path/to/file.go.  For example "file=~/go/src/fmt/print.go"
  21 might return the packages "fmt" and "fmt [fmt.test]".
  22
  23 The query "pattern=string" causes "string" to be passed directly to
  24 the underlying build tool. In most cases this is unnecessary,
  25 but an application can use Load("pattern=" + x) as an escaping mechanism
  26 to ensure that x is not interpreted as a query operator if it contains '='.
  27
  28 All other query operators are reserved for future use and currently
  29 cause Load to report an error.
  30
  31 The Package struct provides basic information about the package, including
  32
  33   - ID, a unique identifier for the package in the returned set;
  34   - GoFiles, the names of the package's Go source files;
  35   - Imports, a map from source import strings to the Packages they name;
  36   - Types, the type information for the package's exported symbols;
  37   - Syntax, the parsed syntax trees for the package's source code; and
  38   - TypeInfo, the result of a complete type-check of the package syntax trees.
  39
  40 (See the documentation for type Package for the complete list of fields
  41 and more detailed descriptions.)
  42
  43 For example,
  44
  45         Load(nil, "bytes", "unicode...")
  46
  47 returns four Package structs describing the standard library packages
  48 bytes, unicode, unicode/utf16, and unicode/utf8. Note that one pattern
  49 can match multiple packages and that a package might be matched by
  50 multiple patterns: in general it is not possible to determine which
  51 packages correspond to which patterns.
  52
  53 Note that the list returned by Load contains only the packages matched
  54 by the patterns. Their dependencies can be found by walking the import
  55 graph using the Imports fields.
  56
  57 The Load function can be configured by passing a pointer to a Config as
  58 the first argument. A nil Config is equivalent to the zero Config, which
  59 causes Load to run in LoadFiles mode, collecting minimal information.
  60 See the documentation for type Config for details.
  61
  62 As noted earlier, the Config.Mode controls the amount of detail
  63 reported about the loaded packages. See the documentation for type LoadMode
  64 for details.
  65
  66 Most tools should pass their command-line arguments (after any flags)
  67 uninterpreted to the loader, so that the loader can interpret them
  68 according to the conventions of the underlying build system.
  69 See the Example function for typical usage.
  70
  71 */
  72 package packages // import "golang.org/x/tools/go/packages"
  73
  74 /*
  75
  76 Motivation and design considerations
  77
  78 The new package's design solves problems addressed by two existing
  79 packages: go/build, which locates and describes packages, and
  80 golang.org/x/tools/go/loader, which loads, parses and type-checks them.
  81 The go/build.Package structure encodes too much of the 'go build' way
  82 of organizing projects, leaving us in need of a data type that describes a
  83 package of Go source code independent of the underlying build system.
  84 We wanted something that works equally well with go build and vgo, and
  85 also other build systems such as Bazel and Blaze, making it possible to
  86 construct analysis tools that work in all these environments.
  87 Tools such as errcheck and staticcheck were essentially unavailable to
  88 the Go community at Google, and some of Google's internal tools for Go
  89 are unavailable externally.
  90 This new package provides a uniform way to obtain package metadata by
  91 querying each of these build systems, optionally supporting their
  92 preferred command-line notations for packages, so that tools integrate
  93 neatly with users' build environments. The Metadata query function
  94 executes an external query tool appropriate to the current workspace.
  95
  96 Loading packages always returns the complete import graph "all the way down",
  97 even if all you want is information about a single package, because the query
  98 mechanisms of all the build systems we currently support ({go,vgo} list, and
  99 blaze/bazel aspect-based query) cannot provide detailed information
 100 about one package without visiting all its dependencies too, so there is
 101 no additional asymptotic cost to providing transitive information.
 102 (This property might not be true of a hypothetical 5th build system.)
 103
 104 In calls to TypeCheck, all initial packages, and any package that
 105 transitively depends on one of them, must be loaded from source.
 106 Consider A->B->C->D->E: if A,C are initial, A,B,C must be loaded from
 107 source; D may be loaded from export data, and E may not be loaded at all
 108 (though it's possible that D's export data mentions it, so a
 109 types.Package may be created for it and exposed.)
 110
 111 The old loader had a feature to suppress type-checking of function
 112 bodies on a per-package basis, primarily intended to reduce the work of
 113 obtaining type information for imported packages. Now that imports are
 114 satisfied by export data, the optimization no longer seems necessary.
 115
 116 Despite some early attempts, the old loader did not exploit export data,
 117 instead always using the equivalent of WholeProgram mode. This was due
 118 to the complexity of mixing source and export data packages (now
 119 resolved by the upward traversal mentioned above), and because export data
 120 files were nearly always missing or stale. Now that 'go build' supports
 121 caching, all the underlying build systems can guarantee to produce
 122 export data in a reasonable (amortized) time.
 123
 124 Test "main" packages synthesized by the build system are now reported as
 125 first-class packages, avoiding the need for clients (such as go/ssa) to
 126 reinvent this generation logic.
 127
 128 One way in which go/packages is simpler than the old loader is in its
 129 treatment of in-package tests. In-package tests are packages that
 130 consist of all the files of the library under test, plus the test files.
 131 The old loader constructed in-package tests by a two-phase process of
 132 mutation called "augmentation": first it would construct and type check
 133 all the ordinary library packages and type-check the packages that
 134 depend on them; then it would add more (test) files to the package and
 135 type-check again. This two-phase approach had four major problems:
 136 1) in processing the tests, the loader modified the library package,
 137    leaving no way for a client application to see both the test
 138    package and the library package; one would mutate into the other.
 139 2) because test files can declare additional methods on types defined in
 140    the library portion of the package, the dispatch of method calls in
 141    the library portion was affected by the presence of the test files.
 142    This should have been a clue that the packages were logically
 143    different.
 144 3) this model of "augmentation" assumed at most one in-package test
 145    per library package, which is true of projects using 'go build',
 146    but not other build systems.
 147 4) because of the two-phase nature of test processing, all packages that
 148    import the library package had to be processed before augmentation,
 149    forcing a "one-shot" API and preventing the client from calling Load
 150    in several times in sequence as is now possible in WholeProgram mode.
 151    (TypeCheck mode has a similar one-shot restriction for a different reason.)
 152
 153 Early drafts of this package supported "multi-shot" operation.
 154 Although it allowed clients to make a sequence of calls (or concurrent
 155 calls) to Load, building up the graph of Packages incrementally,
 156 it was of marginal value: it complicated the API
 157 (since it allowed some options to vary across calls but not others),
 158 it complicated the implementation,
 159 it cannot be made to work in Types mode, as explained above,
 160 and it was less efficient than making one combined call (when this is possible).
 161 Among the clients we have inspected, none made multiple calls to load
 162 but could not be easily and satisfactorily modified to make only a single call.
 163 However, applications changes may be required.
 164 For example, the ssadump command loads the user-specified packages
 165 and in addition the runtime package.  It is tempting to simply append
 166 "runtime" to the user-provided list, but that does not work if the user
 167 specified an ad-hoc package such as [a.go b.go].
 168 Instead, ssadump no longer requests the runtime package,
 169 but seeks it among the dependencies of the user-specified packages,
 170 and emits an error if it is not found.
 171
 172 Overlays: The Overlay field in the Config allows providing alternate contents
 173 for Go source files, by providing a mapping from file path to contents.
 174 go/packages will pull in new imports added in overlay files when go/packages
 175 is run in LoadImports mode or greater.
 176 Overlay support for the go list driver isn't complete yet: if the file doesn't
 177 exist on disk, it will only be recognized in an overlay if it is a non-test file
 178 and the package would be reported even without the overlay.
 179
 180 Questions & Tasks
 181
 182 - Add GOARCH/GOOS?
 183   They are not portable concepts, but could be made portable.
 184   Our goal has been to allow users to express themselves using the conventions
 185   of the underlying build system: if the build system honors GOARCH
 186   during a build and during a metadata query, then so should
 187   applications built atop that query mechanism.
 188   Conversely, if the target architecture of the build is determined by
 189   command-line flags, the application can pass the relevant
 190   flags through to the build system using a command such as:
 191     myapp -query_flag="--cpu=amd64" -query_flag="--os=darwin"
 192   However, this approach is low-level, unwieldy, and non-portable.
 193   GOOS and GOARCH seem important enough to warrant a dedicated option.
 194
 195 - How should we handle partial failures such as a mixture of good and
 196   malformed patterns, existing and non-existent packages, successful and
 197   failed builds, import failures, import cycles, and so on, in a call to
 198   Load?
 199
 200 - Support bazel, blaze, and go1.10 list, not just go1.11 list.
 201
 202 - Handle (and test) various partial success cases, e.g.
 203   a mixture of good packages and:
 204   invalid patterns
 205   nonexistent packages
 206   empty packages
 207   packages with malformed package or import declarations
 208   unreadable files
 209   import cycles
 210   other parse errors
 211   type errors
 212   Make sure we record errors at the correct place in the graph.
 213
 214 - Missing packages among initial arguments are not reported.
 215   Return bogus packages for them, like golist does.
 216
 217 - "undeclared name" errors (for example) are reported out of source file
 218   order. I suspect this is due to the breadth-first resolution now used
 219   by go/types. Is that a bug? Discuss with gri.
 220
 221 */