diff options
Diffstat (limited to 'src/go/build/doc.go')
| -rw-r--r-- | src/go/build/doc.go | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/src/go/build/doc.go b/src/go/build/doc.go new file mode 100644 index 0000000..2c6f0a8 --- /dev/null +++ b/src/go/build/doc.go @@ -0,0 +1,98 @@ +// 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 line comment that begins +// +// // +build +// +// that lists the conditions under which a file should be included in the +// package. 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 |