|
| 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 |
0 commit comments