cmd/go: add go1.1 build tag, add -installsuffix flag

The new build tag "go1.1" will be satisfied by any Go 1.z release >= 1.1.
In general, the build tag "go1.x" will be satisfied by any Go 1.z release >= 1.x.
What happens when we reach Go 2 is yet to be decided.

The tags "go1" or "go1.0" are missing, because +build tags did not exist
before then, and also because the Go 1.0 releases do not recognize them.

The new -installsuffix flag gives access to the build context's InstallSuffix
(formerly named InstallTag, but not part of Go 1.0), for use in isolating
builds to custom directories. For example -race implies -installsuffix race,
and an AppEngine-specific build might use -tags appengine -installsuffix appengine.

Fixes #4116.
Fixes #4443.

R=golang-dev, bradfitz, r
CC=golang-dev
https://golang.org/cl/7794043

Author: rsc

src/cmd/dist/build.c

@@ -1046,7 +1046,7 @@ install(char *dir)
 static bool
 matchfield(char *f)
 {
-	return streq(f, goos) || streq(f, goarch) || streq(f, "cmd_go_bootstrap");
+	return streq(f, goos) || streq(f, goarch) || streq(f, "cmd_go_bootstrap") || streq(f, "go1.1");
 }
 
 // shouldbuild reports whether we should build this file.

src/cmd/go/build.go

@@ -40,9 +40,13 @@ build writes the resulting executable to output.
 Otherwise build compiles the packages but discards the results,
 serving only as a check that the packages can be built.
 
-The -o flag specifies the output file name.  If not specified, the
-name is packagename.a (for a non-main package) or the base
-name of the first source file (for a main package).
+The -o flag specifies the output file name. If not specified, the
+output file name depends on the arguments and derives from the name
+of the package, such as p.a for package p, unless p is 'main'. If
+the package is main and file names are provided, the file name
+derives from the first file name mentioned, such as f1 for 'go build
+f1.go f2.go'; with no files provided ('go build'), the output file
+name is the base name of the containing directory.
 
 The build flags are shared by the build, install, run, and test commands:
 
@@ -53,27 +57,32 @@ The build flags are shared by the build, install, run, and test commands:
 	-p n
 		the number of builds that can be run in parallel.
 		The default is the number of CPUs available.
+	-race
+		enable data race detection.
+		Supported only on linux/amd64, darwin/amd64 and windows/amd64.
 	-v
 		print the names of packages as they are compiled.
 	-work
 		print the name of the temporary work directory and
 		do not delete it when exiting.
 	-x
 		print the commands.
-	-race
-		enable data race detection.
-		Supported only on linux/amd64, darwin/amd64 and windows/amd64.
 
 	-ccflags 'arg list'
-		arguments to pass on each 5c, 6c, or 8c compiler invocation
+		arguments to pass on each 5c, 6c, or 8c compiler invocation.
 	-compiler name
-		name of compiler to use, as in runtime.Compiler (gccgo or gc)
+		name of compiler to use, as in runtime.Compiler (gccgo or gc).
 	-gccgoflags 'arg list'
-		arguments to pass on each gccgo compiler/linker invocation
+		arguments to pass on each gccgo compiler/linker invocation.
 	-gcflags 'arg list'
-		arguments to pass on each 5g, 6g, or 8g compiler invocation
+		arguments to pass on each 5g, 6g, or 8g compiler invocation.
+	-installsuffix suffix
+		a suffix to use in the name of the package installation directory,
+		in order to keep output separate from default builds.
+		If using the -race flag, the install suffix is automatically set to race
+		or, if set explicitly, has _race appended to it.
 	-ldflags 'flag list'
-		arguments to pass on each 5l, 6l, or 8l linker invocation
+		arguments to pass on each 5l, 6l, or 8l linker invocation.
 	-tags 'tag list'
 		a list of build tags to consider satisfied during the build.
 		See the documentation for the go/build package for
@@ -153,6 +162,7 @@ func addBuildFlags(cmd *Command) {
 	cmd.Flag.BoolVar(&buildA, "a", false, "")
 	cmd.Flag.BoolVar(&buildN, "n", false, "")
 	cmd.Flag.IntVar(&buildP, "p", buildP, "")
+	cmd.Flag.StringVar(&buildContext.InstallSuffix, "installsuffix", "", "")
 	cmd.Flag.BoolVar(&buildV, "v", false, "")
 	cmd.Flag.BoolVar(&buildX, "x", false, "")
 	cmd.Flag.BoolVar(&buildWork, "work", false, "")
@@ -2084,6 +2094,9 @@ func raceInit() {
 	buildGcflags = append(buildGcflags, "-race")
 	buildLdflags = append(buildLdflags, "-race")
 	buildCcflags = append(buildCcflags, "-D", "RACE")
-	buildContext.InstallTag = "race"
+	if buildContext.InstallSuffix != "" {
+		buildContext.InstallSuffix += "_"
+	}
+	buildContext.InstallSuffix += "race"
 	buildContext.BuildTags = append(buildContext.BuildTags, "race")
 }

src/cmd/go/doc.go

@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// DO NOT EDIT THIS FILE. GENERATED BY mkdoc.sh.
+// Edit the documentation in other files and rerun mkdoc.sh to generate this one.
+
 /*
 Go is a tool for managing Go source code.
 
@@ -70,32 +73,35 @@ The build flags are shared by the build, install, run, and test commands:
 		force rebuilding of packages that are already up-to-date.
 	-n
 		print the commands but do not run them.
-	-o file
-		specify output file name; see description above.
 	-p n
 		the number of builds that can be run in parallel.
 		The default is the number of CPUs available.
+	-race
+		enable data race detection.
+		Supported only on linux/amd64, darwin/amd64 and windows/amd64.
 	-v
 		print the names of packages as they are compiled.
 	-work
 		print the name of the temporary work directory and
 		do not delete it when exiting.
 	-x
 		print the commands.
-	-race
-		enable data race detection.
-		Supported only on linux/amd64, darwin/amd64 and windows/amd64.
 
 	-ccflags 'arg list'
-		arguments to pass on each 5c, 6c, or 8c compiler invocation
+		arguments to pass on each 5c, 6c, or 8c compiler invocation.
 	-compiler name
-		name of compiler to use, as in runtime.Compiler (gccgo or gc)
+		name of compiler to use, as in runtime.Compiler (gccgo or gc).
 	-gccgoflags 'arg list'
-		arguments to pass on each gccgo compiler/linker invocation
+		arguments to pass on each gccgo compiler/linker invocation.
 	-gcflags 'arg list'
-		arguments to pass on each 5g, 6g, or 8g compiler invocation
+		arguments to pass on each 5g, 6g, or 8g compiler invocation.
+	-installsuffix suffix
+		a suffix to use in the name of the package installation directory,
+		in order to keep output separate from default builds.
+		If using the -race flag, the install suffix is automatically set to race
+		or, if set explicitly, has _race appended to it.
 	-ldflags 'flag list'
-		arguments to pass on each 5l, 6l, or 8l linker invocation
+		arguments to pass on each 5l, 6l, or 8l linker invocation.
 	-tags 'tag list'
 		a list of build tags to consider satisfied during the build.
 		See the documentation for the go/build package for

src/cmd/go/go11.go

@@ -0,0 +1,10 @@
+// Copyright 2013 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.
+
+// +build go1.1
+
+package main
+
+// Test that go1.1 tag above is included in builds. main.go refers to this definition.
+const go11tag = true

src/cmd/go/main.go

@@ -108,6 +108,7 @@ func setExitStatus(n int) {
 }
 
 func main() {
+	_ = go11tag
 	flag.Usage = usage
 	flag.Parse()
 	log.SetFlags(0)
@@ -189,6 +190,9 @@ var documentationTemplate = `// Copyright 2011 The Go Authors.  All rights reser
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// DO NOT EDIT THIS FILE. GENERATED BY mkdoc.sh.
+// Edit the documentation in other files and rerun mkdoc.sh to generate this one.
+
 /*
 {{range .}}{{if .Short}}{{.Short | capitalize}}
 

src/pkg/go/build/build.go

@@ -27,15 +27,31 @@ import (
 
 // A Context specifies the supporting context for a build.
 type Context struct {
-	GOARCH      string   // target architecture
-	GOOS        string   // target operating system
-	GOROOT      string   // Go root
-	GOPATH      string   // Go path
-	CgoEnabled  bool     // whether cgo can be used
-	BuildTags   []string // additional tags to recognize in +build lines
-	InstallTag  string   // package install directory suffix
-	UseAllFiles bool     // use files regardless of +build lines, file names
-	Compiler    string   // compiler to assume when computing target paths
+	GOARCH      string // target architecture
+	GOOS        string // target operating system
+	GOROOT      string // Go root
+	GOPATH      string // Go path
+	CgoEnabled  bool   // whether cgo can be used
+	UseAllFiles bool   // use files regardless of +build lines, file names
+	Compiler    string // compiler to assume when computing target paths
+
+	// The build and release tags specify build constraints
+	// that should be considered satisfied when processing +build lines.
+	// Clients creating a new context may customize BuildTags, which
+	// defaults to empty, but it is usually an error to customize ReleaseTags,
+	// which defaults to the list of Go releases the current release is compatible with.
+	// In addition to the BuildTags and ReleaseTags, build constraints
+	// consider the values of GOARCH and GOOS as satisfied tags.
+	BuildTags   []string
+	ReleaseTags []string
+
+	// The install suffix specifies a suffix to use in the name of the installation
+	// directory. By default it is empty, but custom builds that need to keep
+	// their outputs separate can set InstallSuffix to do so. For example, when
+	// using the race detector, the go command uses InstallSuffix = "race", so
+	// that on a Linux/386 system, packages are written to a directory named
+	// "linux_386_race" instead of the usual "linux_386".
+	InstallSuffix string
 
 	// By default, Import uses the operating system's file system calls
 	// to read directories and files.  To read from other sources,
@@ -267,6 +283,17 @@ func defaultContext() Context {
 	c.GOPATH = envOr("GOPATH", "")
 	c.Compiler = runtime.Compiler
 
+	// Each major Go release in the Go 1.x series should add a tag here.
+	// Old tags should not be removed. That is, the go1.x tag is present
+	// in all releases >= Go 1.x. Code that requires Go 1.x or later should
+	// say "+build go1.x", and code that should only be built before Go 1.x
+	// (perhaps it is the stub to use in that case) should say "+build !go1.x".
+	//
+	// When we reach Go 1.3 the line will read
+	//	c.ReleaseTags = []string{"go1.1", "go1.2", "go1.3"}
+	// and so on.
+	c.ReleaseTags = []string{"go1.1"}
+
 	switch os.Getenv("CGO_ENABLED") {
 	case "1":
 		c.CgoEnabled = true
@@ -397,11 +424,11 @@ func (ctxt *Context) Import(path string, srcDir string, mode ImportMode) (*Packa
 		dir, elem := pathpkg.Split(p.ImportPath)
 		pkga = "pkg/gccgo/" + dir + "lib" + elem + ".a"
 	case "gc":
-		tag := ""
-		if ctxt.InstallTag != "" {
-			tag = "_" + ctxt.InstallTag
+		suffix := ""
+		if ctxt.InstallSuffix != "" {
+			suffix = "_" + ctxt.InstallSuffix
 		}
-		pkga = "pkg/" + ctxt.GOOS + "_" + ctxt.GOARCH + tag + "/" + p.ImportPath + ".a"
+		pkga = "pkg/" + ctxt.GOOS + "_" + ctxt.GOARCH + suffix + "/" + p.ImportPath + ".a"
 	default:
 		// Save error for end of function.
 		pkgerr = fmt.Errorf("import %q: unknown compiler %q", path, ctxt.Compiler)
@@ -970,8 +997,8 @@ func splitQuoted(s string) (r []string, err error) {
 //	!cgo (if cgo is disabled)
 //	ctxt.Compiler
 //	!ctxt.Compiler
-//	tag (if tag is listed in ctxt.BuildTags)
-//	!tag (if tag is not listed in ctxt.BuildTags)
+//	tag (if tag is listed in ctxt.BuildTags or ctxt.ReleaseTags)
+//	!tag (if tag is not listed in ctxt.BuildTags or ctxt.ReleaseTags)
 //	a comma-separated list of any of these
 //
 func (ctxt *Context) match(name string) bool {
@@ -989,10 +1016,10 @@ func (ctxt *Context) match(name string) bool {
 		return len(name) > 1 && !ctxt.match(name[1:])
 	}
 
-	// Tags must be letters, digits, underscores.
+	// Tags must be letters, digits, underscores or dots.
 	// Unlike in Go identifiers, all digits are fine (e.g., "386").
 	for _, c := range name {
-		if !unicode.IsLetter(c) && !unicode.IsDigit(c) && c != '_' {
+		if !unicode.IsLetter(c) && !unicode.IsDigit(c) && c != '_' && c != '.' {
 			return false
 		}
 	}
@@ -1011,6 +1038,11 @@ func (ctxt *Context) match(name string) bool {
 			return true
 		}
 	}
+	for _, tag := range ctxt.ReleaseTags {
+		if tag == name {
+			return true
+		}
+	}
 
 	return false
 }