From e0867738fc3df8fcf5ff4392e29901c87ffed115 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Wed, 2 Oct 2013 21:42:23 -0400 Subject: [PATCH] cmd/go: document relative imports Fixes #3524. R=golang-dev, iant, r CC=golang-dev https://golang.org/cl/14296043 --- src/cmd/go/doc.go | 152 +++++++++++++++++++++++++++------------------ src/cmd/go/get.go | 2 +- src/cmd/go/help.go | 42 +++++++++++-- src/cmd/go/main.go | 2 +- 4 files changed, 129 insertions(+), 69 deletions(-) diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go index ffb2ee33a4..ebb2f37fd1 100644 --- a/src/cmd/go/doc.go +++ b/src/cmd/go/doc.go @@ -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 diff --git a/src/cmd/go/get.go b/src/cmd/go/get.go index b6a3d5ba05..e61da7e2ad 100644 --- a/src/cmd/go/get.go +++ b/src/cmd/go/get.go @@ -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. `, diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go index d10043efe1..71e55175a0 100644 --- a/src/cmd/go/help.go +++ b/src/cmd/go/help.go @@ -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. diff --git a/src/cmd/go/main.go b/src/cmd/go/main.go index ac2a7ea286..df0cf1b3fd 100644 --- a/src/cmd/go/main.go +++ b/src/cmd/go/main.go @@ -90,8 +90,8 @@ var commands = []*Command{ helpC, helpGopath, + helpImportPath, helpPackages, - helpRemote, helpTestflag, helpTestfunc, }