...
Run Format

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, 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	//	- any additional words listed in ctxt.BuildTags
   104	//
   105	// If a file's name, after stripping the extension and a possible _test suffix,
   106	// matches any of the following patterns:
   107	//	*_GOOS
   108	// 	*_GOARCH
   109	// 	*_GOOS_GOARCH
   110	// (example: source_windows_amd64.go) or the literals:
   111	//	GOOS
   112	// 	GOARCH
   113	// (example: windows.go) where GOOS and GOARCH represent any known operating
   114	// system and architecture values respectively, then the file is considered to
   115	// have an implicit build constraint requiring those terms.
   116	//
   117	// To keep a file from being considered for the build:
   118	//
   119	//	// +build ignore
   120	//
   121	// (any other unsatisfied word will work as well, but ``ignore'' is conventional.)
   122	//
   123	// To build a file only when using cgo, and only on Linux and OS X:
   124	//
   125	//	// +build linux,cgo darwin,cgo
   126	//
   127	// Such a file is usually paired with another file implementing the
   128	// default functionality for other systems, which in this case would
   129	// carry the constraint:
   130	//
   131	//	// +build !linux,!darwin !cgo
   132	//
   133	// Naming a file dns_windows.go will cause it to be included only when
   134	// building the package for Windows; similarly, math_386.s will be included
   135	// only when building the package for 32-bit x86.
   136	//
   137	package build
   138	

View as plain text