mirror of
https://github.com/golang/go
synced 2024-09-24 05:10:13 -06:00
cmd/go: document relative imports
Fixes #3524. R=golang-dev, iant, r CC=golang-dev https://golang.org/cl/14296043
This commit is contained in:
Russ Cox
parent
95d85d90d8
commit
e0867738fc
@ -32,10 +32,10 @@ Use "go help [command]" for more information about a command.
|
||||
|
||||
Additional help topics:
|
||||
|
||||
c calling between Go and C/C++
|
||||
c calling between Go and C
|
||||
gopath GOPATH environment variable
|
||||
importpath import path syntax
|
||||
packages description of package lists
|
||||
remote remote import path syntax
|
||||
testflag description of testing flags
|
||||
testfunc description of testing functions
|
||||
|
||||
@ -247,7 +247,7 @@ retrieves the most recent version of the package.
|
||||
For more about specifying packages, see 'go help packages'.
|
||||
|
||||
For more about how 'go get' finds source code to
|
||||
download, see 'go help remote'.
|
||||
download, see 'go help importpath'.
|
||||
|
||||
See also: go build, go install, go clean.
|
||||
|
||||
@ -544,66 +544,40 @@ but new packages are always downloaded into the first directory
|
||||
in the list.
|
||||
|
||||
|
||||
Description of package lists
|
||||
|
||||
Many commands apply to a set of packages:
|
||||
|
||||
go action [packages]
|
||||
|
||||
Usually, [packages] is a list of import paths.
|
||||
|
||||
An import path that is a rooted path or that begins with
|
||||
a . or .. element is interpreted as a file system path and
|
||||
denotes the package in that directory.
|
||||
|
||||
Otherwise, the import path P denotes the package found in
|
||||
the directory DIR/src/P for some DIR listed in the GOPATH
|
||||
environment variable (see 'go help gopath').
|
||||
|
||||
If no import paths are given, the action applies to the
|
||||
package in the current directory.
|
||||
|
||||
There are three reserved names for paths that should not be used
|
||||
for packages to be built with the go tool:
|
||||
|
||||
- "main" denotes the top-level package in a stand-alone executable.
|
||||
|
||||
- "all" expands to all package directories found in all the GOPATH
|
||||
trees. For example, 'go list all' lists all the packages on the local
|
||||
system.
|
||||
|
||||
- "std" is like all but expands to just the packages in the standard
|
||||
Go library.
|
||||
|
||||
An import path is a pattern if it includes one or more "..." wildcards,
|
||||
each of which can match any string, including the empty string and
|
||||
strings containing slashes. Such a pattern expands to all package
|
||||
directories found in the GOPATH trees with names matching the
|
||||
patterns. As a special case, x/... matches x as well as x's subdirectories.
|
||||
For example, net/... expands to net and packages in its subdirectories.
|
||||
|
||||
An import path can also name a package to be downloaded from
|
||||
a remote repository. Run 'go help remote' for details.
|
||||
|
||||
Every package in a program must have a unique import path.
|
||||
By convention, this is arranged by starting each path with a
|
||||
unique prefix that belongs to you. For example, paths used
|
||||
internally at Google all begin with 'google', and paths
|
||||
denoting remote repositories begin with the path to the code,
|
||||
such as 'code.google.com/p/project'.
|
||||
|
||||
As a special case, if the package list is a list of .go files from a
|
||||
single directory, the command is applied to a single synthesized
|
||||
package made up of exactly those files, ignoring any build constraints
|
||||
in those files and ignoring any other files in the directory.
|
||||
|
||||
File names that begin with "." or "_" are ignored by the go tool.
|
||||
|
||||
|
||||
Remote import path syntax
|
||||
Import path syntax
|
||||
|
||||
An import path (see 'go help packages') denotes a package
|
||||
stored in the local file system. Certain import paths also
|
||||
stored in the local file system. In general, an import path denotes
|
||||
either a standard package (such as "unicode/utf8") or a package
|
||||
found in one of the work spaces (see 'go help gopath').
|
||||
|
||||
Relative import paths
|
||||
|
||||
An import path beginning with ./ or ../ is called a relative path.
|
||||
The toolchain supports relative import paths as a shortcut in two ways.
|
||||
|
||||
First, a relative path can be used as a shorthand on the command line.
|
||||
If you are working in the directory containing the code imported as
|
||||
"unicode" and want to run the tests for "unicode/utf8", you can type
|
||||
"go test ./utf8" instead of needing to specify the full path.
|
||||
Similarly, in the reverse situation, "go test .." will test "unicode" from
|
||||
the "unicode/utf8" directory. Relative patterns are also allowed, like
|
||||
"go test ./..." to test all subdirectories. See 'go help packages' for details
|
||||
on the pattern syntax.
|
||||
|
||||
Second, if you are compiling a Go program not in a work space,
|
||||
you can use a relative path in an import statement in that program
|
||||
to refer to nearby code also not in a work space.
|
||||
This makes it easy to experiment with small multipackage programs
|
||||
outside of the usual work spaces, but such programs cannot be
|
||||
installed with "go install" (there is no work space in which to install them),
|
||||
so they are rebuilt from scratch each time they are built.
|
||||
To avoid ambiguity, Go programs cannot use relative import paths
|
||||
within a work space.
|
||||
|
||||
Remote import paths
|
||||
|
||||
Certain import paths also
|
||||
describe how to obtain the source code for the package using
|
||||
a revision control system.
|
||||
|
||||
@ -714,6 +688,62 @@ package appropriate for the Go release being used.
|
||||
Run 'go help install' for more.
|
||||
|
||||
|
||||
Description of package lists
|
||||
|
||||
Many commands apply to a set of packages:
|
||||
|
||||
go action [packages]
|
||||
|
||||
Usually, [packages] is a list of import paths.
|
||||
|
||||
An import path that is a rooted path or that begins with
|
||||
a . or .. element is interpreted as a file system path and
|
||||
denotes the package in that directory.
|
||||
|
||||
Otherwise, the import path P denotes the package found in
|
||||
the directory DIR/src/P for some DIR listed in the GOPATH
|
||||
environment variable (see 'go help gopath').
|
||||
|
||||
If no import paths are given, the action applies to the
|
||||
package in the current directory.
|
||||
|
||||
There are three reserved names for paths that should not be used
|
||||
for packages to be built with the go tool:
|
||||
|
||||
- "main" denotes the top-level package in a stand-alone executable.
|
||||
|
||||
- "all" expands to all package directories found in all the GOPATH
|
||||
trees. For example, 'go list all' lists all the packages on the local
|
||||
system.
|
||||
|
||||
- "std" is like all but expands to just the packages in the standard
|
||||
Go library.
|
||||
|
||||
An import path is a pattern if it includes one or more "..." wildcards,
|
||||
each of which can match any string, including the empty string and
|
||||
strings containing slashes. Such a pattern expands to all package
|
||||
directories found in the GOPATH trees with names matching the
|
||||
patterns. As a special case, x/... matches x as well as x's subdirectories.
|
||||
For example, net/... expands to net and packages in its subdirectories.
|
||||
|
||||
An import path can also name a package to be downloaded from
|
||||
a remote repository. Run 'go help importpath' for details.
|
||||
|
||||
Every package in a program must have a unique import path.
|
||||
By convention, this is arranged by starting each path with a
|
||||
unique prefix that belongs to you. For example, paths used
|
||||
internally at Google all begin with 'google', and paths
|
||||
denoting remote repositories begin with the path to the code,
|
||||
such as 'code.google.com/p/project'.
|
||||
|
||||
As a special case, if the package list is a list of .go files from a
|
||||
single directory, the command is applied to a single synthesized
|
||||
package made up of exactly those files, ignoring any build constraints
|
||||
in those files and ignoring any other files in the directory.
|
||||
|
||||
File names that begin with "." or "_" are ignored by the go tool.
|
||||
|
||||
|
||||
Description of testing flags
|
||||
|
||||
The 'go test' command takes both flags that apply to 'go test' itself
|
||||
|
||||
@ -49,7 +49,7 @@ retrieves the most recent version of the package.
|
||||
For more about specifying packages, see 'go help packages'.
|
||||
|
||||
For more about how 'go get' finds source code to
|
||||
download, see 'go help remote'.
|
||||
download, see 'go help importpath'.
|
||||
|
||||
See also: go build, go install, go clean.
|
||||
`,
|
||||
|
||||
@ -6,7 +6,7 @@ package main
|
||||
|
||||
var helpC = &Command{
|
||||
UsageLine: "c",
|
||||
Short: "calling between Go and C/C++",
|
||||
Short: "calling between Go and C",
|
||||
Long: `
|
||||
There are two different ways to call between Go and C/C++ code.
|
||||
|
||||
@ -67,7 +67,7 @@ patterns. As a special case, x/... matches x as well as x's subdirectories.
|
||||
For example, net/... expands to net and packages in its subdirectories.
|
||||
|
||||
An import path can also name a package to be downloaded from
|
||||
a remote repository. Run 'go help remote' for details.
|
||||
a remote repository. Run 'go help importpath' for details.
|
||||
|
||||
Every package in a program must have a unique import path.
|
||||
By convention, this is arranged by starting each path with a
|
||||
@ -85,13 +85,43 @@ File names that begin with "." or "_" are ignored by the go tool.
|
||||
`,
|
||||
}
|
||||
|
||||
var helpRemote = &Command{
|
||||
UsageLine: "remote",
|
||||
Short: "remote import path syntax",
|
||||
var helpImportPath = &Command{
|
||||
UsageLine: "importpath",
|
||||
Short: "import path syntax",
|
||||
Long: `
|
||||
|
||||
An import path (see 'go help packages') denotes a package
|
||||
stored in the local file system. Certain import paths also
|
||||
stored in the local file system. In general, an import path denotes
|
||||
either a standard package (such as "unicode/utf8") or a package
|
||||
found in one of the work spaces (see 'go help gopath').
|
||||
|
||||
Relative import paths
|
||||
|
||||
An import path beginning with ./ or ../ is called a relative path.
|
||||
The toolchain supports relative import paths as a shortcut in two ways.
|
||||
|
||||
First, a relative path can be used as a shorthand on the command line.
|
||||
If you are working in the directory containing the code imported as
|
||||
"unicode" and want to run the tests for "unicode/utf8", you can type
|
||||
"go test ./utf8" instead of needing to specify the full path.
|
||||
Similarly, in the reverse situation, "go test .." will test "unicode" from
|
||||
the "unicode/utf8" directory. Relative patterns are also allowed, like
|
||||
"go test ./..." to test all subdirectories. See 'go help packages' for details
|
||||
on the pattern syntax.
|
||||
|
||||
Second, if you are compiling a Go program not in a work space,
|
||||
you can use a relative path in an import statement in that program
|
||||
to refer to nearby code also not in a work space.
|
||||
This makes it easy to experiment with small multipackage programs
|
||||
outside of the usual work spaces, but such programs cannot be
|
||||
installed with "go install" (there is no work space in which to install them),
|
||||
so they are rebuilt from scratch each time they are built.
|
||||
To avoid ambiguity, Go programs cannot use relative import paths
|
||||
within a work space.
|
||||
|
||||
Remote import paths
|
||||
|
||||
Certain import paths also
|
||||
describe how to obtain the source code for the package using
|
||||
a revision control system.
|
||||
|
||||
|
||||
@ -90,8 +90,8 @@ var commands = []*Command{
|
||||
|
||||
helpC,
|
||||
helpGopath,
|
||||
helpImportPath,
|
||||
helpPackages,
|
||||
helpRemote,
|
||||
helpTestflag,
|
||||
helpTestfunc,
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user