...
Run Format

Source file src/go/build/doc.go

Documentation: go/build

     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  // and each term is an alphanumeric word or, preceded by !, its negation.
    76  // That is, the build constraint:
    77  //
    78  //	// +build linux,386 darwin,!cgo
    79  //
    80  // corresponds to the boolean formula:
    81  //
    82  //	(linux AND 386) OR (darwin AND (NOT cgo))
    83  //
    84  // A file may have multiple build constraints. The overall constraint is the AND
    85  // of the individual constraints. That is, the build constraints:
    86  //
    87  //	// +build linux darwin
    88  //	// +build 386
    89  //
    90  // corresponds to the boolean formula:
    91  //
    92  //	(linux OR darwin) AND 386
    93  //
    94  // During a particular build, the following words are satisfied:
    95  //
    96  //	- the target operating system, as spelled by runtime.GOOS
    97  //	- the target architecture, as spelled by runtime.GOARCH
    98  //	- the compiler being used, either "gc" or "gccgo"
    99  //	- "cgo", if ctxt.CgoEnabled is true
   100  //	- "go1.1", from Go version 1.1 onward
   101  //	- "go1.2", from Go version 1.2 onward
   102  //	- "go1.3", from Go version 1.3 onward
   103  //	- "go1.4", from Go version 1.4 onward
   104  //	- "go1.5", from Go version 1.5 onward
   105  //	- "go1.6", from Go version 1.6 onward
   106  //	- "go1.7", from Go version 1.7 onward
   107  //	- "go1.8", from Go version 1.8 onward
   108  //	- "go1.9", from Go version 1.9 onward
   109  //	- "go1.10", from Go version 1.10 onward
   110  //	- any additional words listed in ctxt.BuildTags
   111  //
   112  // If a file's name, after stripping the extension and a possible _test suffix,
   113  // matches any of the following patterns:
   114  //	*_GOOS
   115  // 	*_GOARCH
   116  // 	*_GOOS_GOARCH
   117  // (example: source_windows_amd64.go) where GOOS and GOARCH represent
   118  // any known operating system and architecture values respectively, then
   119  // the file is considered to have an implicit build constraint requiring
   120  // those terms (in addition to any explicit constraints in the file).
   121  //
   122  // To keep a file from being considered for the build:
   123  //
   124  //	// +build ignore
   125  //
   126  // (any other unsatisfied word will work as well, but ``ignore'' is conventional.)
   127  //
   128  // To build a file only when using cgo, and only on Linux and OS X:
   129  //
   130  //	// +build linux,cgo darwin,cgo
   131  //
   132  // Such a file is usually paired with another file implementing the
   133  // default functionality for other systems, which in this case would
   134  // carry the constraint:
   135  //
   136  //	// +build !linux,!darwin !cgo
   137  //
   138  // Naming a file dns_windows.go will cause it to be included only when
   139  // building the package for Windows; similarly, math_386.s will be included
   140  // only when building the package for 32-bit x86.
   141  //
   142  // Using GOOS=android matches build tags and files as for GOOS=linux
   143  // in addition to android tags and files.
   144  //
   145  // Binary-Only Packages
   146  //
   147  // It is possible to distribute packages in binary form without including the
   148  // source code used for compiling the package. To do this, the package must
   149  // be distributed with a source file not excluded by build constraints and
   150  // containing a "//go:binary-only-package" comment.
   151  // Like a build constraint, this comment must appear near the top of the file,
   152  // preceded only by blank lines and other line comments and with a blank line
   153  // following the comment, to separate it from the package documentation.
   154  // Unlike build constraints, this comment is only recognized in non-test
   155  // Go source files.
   156  //
   157  // The minimal source code for a binary-only package is therefore:
   158  //
   159  //	//go:binary-only-package
   160  //
   161  //	package mypkg
   162  //
   163  // The source code may include additional Go code. That code is never compiled
   164  // but will be processed by tools like godoc and might be useful as end-user
   165  // documentation.
   166  //
   167  package build
   168  

View as plain text