Source file src/pkg/go/build/doc.go
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 is a line comment beginning with the directive +build
61 // that lists the conditions under which a file should be included in the package.
62 // Constraints may appear in any kind of source file (not just Go), but
63 // they must be appear near the top of the file, preceded
64 // only by blank lines and other line comments.
65 //
66 // A build constraint is evaluated as the OR of space-separated options;
67 // each option evaluates as the AND of its comma-separated terms;
68 // and each term is an alphanumeric word or, preceded by !, its negation.
69 // That is, the build constraint:
70 //
71 // // +build linux,386 darwin,!cgo
72 //
73 // corresponds to the boolean formula:
74 //
75 // (linux AND 386) OR (darwin AND (NOT cgo))
76 //
77 // During a particular build, the following words are satisfied:
78 //
79 // - the target operating system, as spelled by runtime.GOOS
80 // - the target architecture, as spelled by runtime.GOARCH
81 // - "cgo", if ctxt.CgoEnabled is true
82 // - any additional words listed in ctxt.BuildTags
83 //
84 // If a file's name, after stripping the extension and a possible _test suffix,
85 // matches *_GOOS, *_GOARCH, or *_GOOS_GOARCH for any known operating
86 // system and architecture values, then the file is considered to have an implicit
87 // build constraint requiring those terms.
88 //
89 // To keep a file from being considered for the build:
90 //
91 // // +build ignore
92 //
93 // (any other unsatisfied word will work as well, but ``ignore'' is conventional.)
94 //
95 // To build a file only when using cgo, and only on Linux and OS X:
96 //
97 // // +build linux,cgo darwin,cgo
98 //
99 // Such a file is usually paired with another file implementing the
100 // default functionality for other systems, which in this case would
101 // carry the constraint:
102 //
103 // // +build !linux !darwin !cgo
104 //
105 // Naming a file dns_windows.go will cause it to be included only when
106 // building the package for Windows; similarly, math_386.s will be included
107 // only when building the package for 32-bit x86.
108 //
109 package build