libgo/go/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 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