1 // Copyright 2011 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 // Package build gathers information about Go packages.
6 //
7 // # Build Constraints
8 //
9 // A build constraint, also known as a build tag, is a condition under which a
10 // file should be included in the package. Build constraints are given by a
11 // line comment that begins
12 //
13 // //go:build
14 //
15 // Build constraints may also be part of a file's name
16 // (for example, source_windows.go will only be included if the target
17 // operating system is windows).
18 //
19 // See 'go help buildconstraint'
20 // (https://pkg.go.dev/cmd/go#hdr-Build_constraints) for details.
21 //
22 // # Go Path
23 //
24 // The Go path is a list of directory trees containing Go source code.
25 // It is consulted to resolve imports that cannot be found in the standard
26 // Go tree. The default path is the value of the GOPATH environment
27 // variable, interpreted as a path list appropriate to the operating system
28 // (on Unix, the variable is a colon-separated string;
29 // on Windows, a semicolon-separated string;
30 // on Plan 9, a list).
31 //
32 // Each directory listed in the Go path must have a prescribed structure:
33 //
34 // The src/ directory holds source code. The path below 'src' determines
35 // the import path or executable name.
36 //
37 // The pkg/ directory holds installed package objects.
38 // As in the Go tree, each target operating system and
39 // architecture pair has its own subdirectory of pkg
40 // (pkg/GOOS_GOARCH).
41 //
42 // If DIR is a directory listed in the Go path, a package with
43 // source in DIR/src/foo/bar can be imported as "foo/bar" and
44 // has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a"
45 // (or, for gccgo, "DIR/pkg/gccgo/foo/libbar.a").
46 //
47 // The bin/ directory holds compiled commands.
48 // Each command is named for its source directory, but only
49 // using the final element, not the entire path. That is, the
50 // command with source in DIR/src/foo/quux is installed into
51 // DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped
52 // so that you can add DIR/bin to your PATH to get at the
53 // installed commands.
54 //
55 // Here's an example directory layout:
56 //
57 // GOPATH=/home/user/gocode
58 //
59 // /home/user/gocode/
60 // src/
61 // foo/
62 // bar/ (go code in package bar)
63 // x.go
64 // quux/ (go code in package main)
65 // y.go
66 // bin/
67 // quux (installed command)
68 // pkg/
69 // linux_amd64/
70 // foo/
71 // bar.a (installed package object)
72 //
73 // # Binary-Only Packages
74 //
75 // In Go 1.12 and earlier, it was possible to distribute packages in binary
76 // form without including the source code used for compiling the package.
77 // The package was distributed with a source file not excluded by build
78 // constraints and containing a "//go:binary-only-package" comment. Like a
79 // build constraint, this comment appeared at the top of a file, preceded
80 // only by blank lines and other line comments and with a blank line
81 // following the comment, to separate it from the package documentation.
82 // Unlike build constraints, this comment is only recognized in non-test
83 // Go source files.
84 //
85 // The minimal source code for a binary-only package was therefore:
86 //
87 // //go:binary-only-package
88 //
89 // package mypkg
90 //
91 // The source code could include additional Go code. That code was never
92 // compiled but would be processed by tools like godoc and might be useful
93 // as end-user documentation.
94 //
95 // "go build" and other commands no longer support binary-only-packages.
96 // [Import] and [ImportDir] will still set the BinaryOnly flag in packages
97 // containing these comments for use in tools and error messages.
98 package build
99