mirror of https://go.googlesource.com/go
99 lines
3.7 KiB
Go
99 lines
3.7 KiB
Go
// Copyright 2011 The Go Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
// Package build gathers information about Go packages.
|
|
//
|
|
// # Go Path
|
|
//
|
|
// The Go path is a list of directory trees containing Go source code.
|
|
// It is consulted to resolve imports that cannot be found in the standard
|
|
// Go tree. The default path is the value of the GOPATH environment
|
|
// variable, interpreted as a path list appropriate to the operating system
|
|
// (on Unix, the variable is a colon-separated string;
|
|
// on Windows, a semicolon-separated string;
|
|
// on Plan 9, a list).
|
|
//
|
|
// Each directory listed in the Go path must have a prescribed structure:
|
|
//
|
|
// The src/ directory holds source code. The path below 'src' determines
|
|
// the import path or executable name.
|
|
//
|
|
// The pkg/ directory holds installed package objects.
|
|
// As in the Go tree, each target operating system and
|
|
// architecture pair has its own subdirectory of pkg
|
|
// (pkg/GOOS_GOARCH).
|
|
//
|
|
// If DIR is a directory listed in the Go path, a package with
|
|
// source in DIR/src/foo/bar can be imported as "foo/bar" and
|
|
// has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a"
|
|
// (or, for gccgo, "DIR/pkg/gccgo/foo/libbar.a").
|
|
//
|
|
// The bin/ directory holds compiled commands.
|
|
// Each command is named for its source directory, but only
|
|
// using the final element, not the entire path. That is, the
|
|
// command with source in DIR/src/foo/quux is installed into
|
|
// DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped
|
|
// so that you can add DIR/bin to your PATH to get at the
|
|
// installed commands.
|
|
//
|
|
// Here's an example directory layout:
|
|
//
|
|
// GOPATH=/home/user/gocode
|
|
//
|
|
// /home/user/gocode/
|
|
// src/
|
|
// foo/
|
|
// bar/ (go code in package bar)
|
|
// x.go
|
|
// quux/ (go code in package main)
|
|
// y.go
|
|
// bin/
|
|
// quux (installed command)
|
|
// pkg/
|
|
// linux_amd64/
|
|
// foo/
|
|
// bar.a (installed package object)
|
|
//
|
|
// # Build Constraints
|
|
//
|
|
// A build constraint, also known as a build tag, is a condition under which a
|
|
// file should be included in the package. Build constraints are given by a
|
|
// line comment that begins
|
|
//
|
|
// //go:build
|
|
//
|
|
// Build constraints may also be part of a file's name
|
|
// (for example, source_windows.go will only be included if the target
|
|
// operating system is windows).
|
|
//
|
|
// See 'go help buildconstraint'
|
|
// (https://golang.org/cmd/go/#hdr-Build_constraints) for details.
|
|
//
|
|
// # Binary-Only Packages
|
|
//
|
|
// In Go 1.12 and earlier, it was possible to distribute packages in binary
|
|
// form without including the source code used for compiling the package.
|
|
// The package was distributed with a source file not excluded by build
|
|
// constraints and containing a "//go:binary-only-package" comment. Like a
|
|
// build constraint, this comment appeared at the top of a file, preceded
|
|
// only by blank lines and other line comments and with a blank line
|
|
// following the comment, to separate it from the package documentation.
|
|
// Unlike build constraints, this comment is only recognized in non-test
|
|
// Go source files.
|
|
//
|
|
// The minimal source code for a binary-only package was therefore:
|
|
//
|
|
// //go:binary-only-package
|
|
//
|
|
// package mypkg
|
|
//
|
|
// The source code could include additional Go code. That code was never
|
|
// compiled but would be processed by tools like godoc and might be useful
|
|
// as end-user documentation.
|
|
//
|
|
// "go build" and other commands no longer support binary-only-packages.
|
|
// [Import] and [ImportDir] will still set the BinaryOnly flag in packages
|
|
// containing these comments for use in tools and error messages.
|
|
package build
|