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 // # Build Constraints 8 // 9 // A build constraint, also known as a build tag, is a condition under which a 10 // file should be included in the package. Build constraints are given by a 11 // line comment that begins 12 // 13 // //go:build 14 // 15 // Build constraints may also be part of a file's name 16 // (for example, source_windows.go will only be included if the target 17 // operating system is windows). 18 // 19 // See 'go help buildconstraint' 20 // (https://pkg.go.dev/cmd/go#hdr-Build_constraints) for details. 21 // 22 // # Go Path 23 // 24 // The Go path is a list of directory trees containing Go source code. 25 // It is consulted to resolve imports that cannot be found in the standard 26 // Go tree. The default path is the value of the GOPATH environment 27 // variable, interpreted as a path list appropriate to the operating system 28 // (on Unix, the variable is a colon-separated string; 29 // on Windows, a semicolon-separated string; 30 // on Plan 9, a list). 31 // 32 // Each directory listed in the Go path must have a prescribed structure: 33 // 34 // The src/ directory holds source code. The path below 'src' determines 35 // the import path or executable name. 36 // 37 // The pkg/ directory holds installed package objects. 38 // As in the Go tree, each target operating system and 39 // architecture pair has its own subdirectory of pkg 40 // (pkg/GOOS_GOARCH). 41 // 42 // If DIR is a directory listed in the Go path, a package with 43 // source in DIR/src/foo/bar can be imported as "foo/bar" and 44 // has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a" 45 // (or, for gccgo, "DIR/pkg/gccgo/foo/libbar.a"). 46 // 47 // The bin/ directory holds compiled commands. 48 // Each command is named for its source directory, but only 49 // using the final element, not the entire path. That is, the 50 // command with source in DIR/src/foo/quux is installed into 51 // DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped 52 // so that you can add DIR/bin to your PATH to get at the 53 // installed commands. 54 // 55 // Here's an example directory layout: 56 // 57 // GOPATH=/home/user/gocode 58 // 59 // /home/user/gocode/ 60 // src/ 61 // foo/ 62 // bar/ (go code in package bar) 63 // x.go 64 // quux/ (go code in package main) 65 // y.go 66 // bin/ 67 // quux (installed command) 68 // pkg/ 69 // linux_amd64/ 70 // foo/ 71 // bar.a (installed package object) 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