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// # Go Path
8//
9// The Go path is a list of directory trees containing Go source code.
10// It is consulted to resolve imports that cannot be found in the standard
11// Go tree. The default path is the value of the GOPATH environment
12// variable, interpreted as a path list appropriate to the operating system
13// (on Unix, the variable is a colon-separated string;
14// on Windows, a semicolon-separated string;
15// on Plan 9, a list).
16//
17// Each directory listed in the Go path must have a prescribed structure:
18//
19// The src/ directory holds source code. The path below 'src' determines
20// the import path or executable name.
21//
22// The pkg/ directory holds installed package objects.
23// As in the Go tree, each target operating system and
24// architecture pair has its own subdirectory of pkg
25// (pkg/GOOS_GOARCH).
26//
27// If DIR is a directory listed in the Go path, a package with
28// source in DIR/src/foo/bar can be imported as "foo/bar" and
29// has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a"
30// (or, for gccgo, "DIR/pkg/gccgo/foo/libbar.a").
31//
32// The bin/ directory holds compiled commands.
33// Each command is named for its source directory, but only
34// using the final element, not the entire path. That is, the
35// command with source in DIR/src/foo/quux is installed into
36// DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped
37// so that you can add DIR/bin to your PATH to get at the
38// installed commands.
39//
40// Here's an example directory layout:
41//
42//	GOPATH=/home/user/gocode
43//
44//	/home/user/gocode/
45//	    src/
46//	        foo/
47//	            bar/               (go code in package bar)
48//	                x.go
49//	            quux/              (go code in package main)
50//	                y.go
51//	    bin/
52//	        quux                   (installed command)
53//	    pkg/
54//	        linux_amd64/
55//	            foo/
56//	                bar.a          (installed package object)
57//
58// # Build Constraints
59//
60// A build constraint, also known as a build tag, is a condition under which a
61// file should be included in the package. Build constraints are given by a
62// line comment that begins
63//
64//	//go:build
65//
66// Build constraints may also be part of a file's name
67// (for example, source_windows.go will only be included if the target
68// operating system is windows).
69//
70// See 'go help buildconstraint'
71// (https://golang.org/cmd/go/#hdr-Build_constraints) for details.
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.
98package build
99