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 line comment that begins 61 // 62 // // +build 63 // 64 // that lists the conditions under which a file should be included in the package. 65 // Constraints may appear in any kind of source file (not just Go), but 66 // they must appear near the top of the file, preceded 67 // only by blank lines and other line comments. These rules mean that in Go 68 // files a build constraint must appear before the package clause. 69 // 70 // To distinguish build constraints from package documentation, a series of 71 // build constraints must be followed by a blank line. 72 // 73 // A build constraint is evaluated as the OR of space-separated options. 74 // Each option evaluates as the AND of its comma-separated terms. 75 // Each term consists of letters, digits, underscores, and dots. 76 // A term may be negated with a preceding !. 77 // For example, the build constraint: 78 // 79 // // +build linux,386 darwin,!cgo 80 // 81 // corresponds to the boolean formula: 82 // 83 // (linux AND 386) OR (darwin AND (NOT cgo)) 84 // 85 // A file may have multiple build constraints. The overall constraint is the AND 86 // of the individual constraints. That is, the build constraints: 87 // 88 // // +build linux darwin 89 // // +build 386 90 // 91 // corresponds to the boolean formula: 92 // 93 // (linux OR darwin) AND 386 94 // 95 // During a particular build, the following words are satisfied: 96 // 97 // - the target operating system, as spelled by runtime.GOOS 98 // - the target architecture, as spelled by runtime.GOARCH 99 // - the compiler being used, either "gc" or "gccgo" 100 // - "cgo", if ctxt.CgoEnabled is true 101 // - "go1.1", from Go version 1.1 onward 102 // - "go1.2", from Go version 1.2 onward 103 // - "go1.3", from Go version 1.3 onward 104 // - "go1.4", from Go version 1.4 onward 105 // - "go1.5", from Go version 1.5 onward 106 // - "go1.6", from Go version 1.6 onward 107 // - "go1.7", from Go version 1.7 onward 108 // - "go1.8", from Go version 1.8 onward 109 // - "go1.9", from Go version 1.9 onward 110 // - "go1.10", from Go version 1.10 onward 111 // - "go1.11", from Go version 1.11 onward 112 // - "go1.12", from Go version 1.12 onward 113 // - "go1.13", from Go version 1.13 onward 114 // - any additional words listed in ctxt.BuildTags 115 // 116 // There are no build tags for beta or minor releases. 117 // 118 // If a file's name, after stripping the extension and a possible _test suffix, 119 // matches any of the following patterns: 120 // *_GOOS 121 // *_GOARCH 122 // *_GOOS_GOARCH 123 // (example: source_windows_amd64.go) where GOOS and GOARCH represent 124 // any known operating system and architecture values respectively, then 125 // the file is considered to have an implicit build constraint requiring 126 // those terms (in addition to any explicit constraints in the file). 127 // 128 // To keep a file from being considered for the build: 129 // 130 // // +build ignore 131 // 132 // (any other unsatisfied word will work as well, but ``ignore'' is conventional.) 133 // 134 // To build a file only when using cgo, and only on Linux and OS X: 135 // 136 // // +build linux,cgo darwin,cgo 137 // 138 // Such a file is usually paired with another file implementing the 139 // default functionality for other systems, which in this case would 140 // carry the constraint: 141 // 142 // // +build !linux,!darwin !cgo 143 // 144 // Naming a file dns_windows.go will cause it to be included only when 145 // building the package for Windows; similarly, math_386.s will be included 146 // only when building the package for 32-bit x86. 147 // 148 // Using GOOS=android matches build tags and files as for GOOS=linux 149 // in addition to android tags and files. 150 // 151 // Using GOOS=illumos matches build tags and files as for GOOS=solaris 152 // in addition to illumos tags and files. 153 // 154 // Binary-Only Packages 155 // 156 // In Go 1.12 and earlier, it was possible to distribute packages in binary 157 // form without including the source code used for compiling the package. 158 // The package was distributed with a source file not excluded by build 159 // constraints and containing a "//go:binary-only-package" comment. Like a 160 // build constraint, this comment appeared at the top of a file, preceded 161 // only by blank lines and other line comments and with a blank line 162 // following the comment, to separate it from the package documentation. 163 // Unlike build constraints, this comment is only recognized in non-test 164 // Go source files. 165 // 166 // The minimal source code for a binary-only package was therefore: 167 // 168 // //go:binary-only-package 169 // 170 // package mypkg 171 // 172 // The source code could include additional Go code. That code was never 173 // compiled but would be processed by tools like godoc and might be useful 174 // as end-user documentation. 175 // 176 // "go build" and other commands no longer support binary-only-packages. 177 // Import and ImportDir will still set the BinaryOnly flag in packages 178 // containing these comments for use in tools and error messages. 179 // 180 package build 181