Source file src/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 condition under which a
    61  // file should be included in the package. Build constraints are given by a
    62  // line comment that begins
    63  //
    64  //	//go:build
    65  //
    66  // Build constraints may also be part of a file's name
    67  // (for example, source_windows.go will only be included if the target
    68  // operating system is windows).
    69  //
    70  // See 'go help buildconstraint'
    71  // (https://golang.ir/cmd/go/#hdr-Build_constraints) for details.
    72  //
    73  // # Binary-Only Packages
    74  //
    75  // In Go 1.12 and earlier, it was possible to distribute packages in binary
    76  // form without including the source code used for compiling the package.
    77  // The package was distributed with a source file not excluded by build
    78  // constraints and containing a "//go:binary-only-package" comment. Like a
    79  // build constraint, this comment appeared at the top of a file, preceded
    80  // only by blank lines and other line comments and with a blank line
    81  // following the comment, to separate it from the package documentation.
    82  // Unlike build constraints, this comment is only recognized in non-test
    83  // Go source files.
    84  //
    85  // The minimal source code for a binary-only package was therefore:
    86  //
    87  //	//go:binary-only-package
    88  //
    89  //	package mypkg
    90  //
    91  // The source code could include additional Go code. That code was never
    92  // compiled but would be processed by tools like godoc and might be useful
    93  // as end-user documentation.
    94  //
    95  // "go build" and other commands no longer support binary-only-packages.
    96  // [Import] and [ImportDir] will still set the BinaryOnly flag in packages
    97  // containing these comments for use in tools and error messages.
    98  package build
    99  

View as plain text