From bd1169dd2144abbe58767bf2dfaa3f20e8cf553b Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Tue, 28 Oct 2014 10:51:28 -0700 Subject: [PATCH] doc/go1.4.html: vanity imports and internal packages LGTM=rsc R=golang-codereviews, rsc CC=golang-codereviews https://golang.org/cl/165800043 --- doc/go1.4.html | 107 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 93 insertions(+), 14 deletions(-) diff --git a/doc/go1.4.html b/doc/go1.4.html index 592b8661f1..ffabdb82c0 100644 --- a/doc/go1.4.html +++ b/doc/go1.4.html @@ -95,7 +95,7 @@ to defeat Go's type system by exploiting internal details of the implementation or machine representation of data. It was never explicitly specified what use of unsafe meant with respect to compatibility as specified in the -Go compatibilty guidelines. +Go compatibility guidelines. The answer, of course, is that we can make no promise of compatibility for code that does unsafe things.

@@ -175,25 +175,103 @@ TODO gccgo news

Internal packages

-
-TODO prose for these
-cmd/go: implement "internal" (CL 120600043)
-
-

Import comments

+

+Go's package system makes it easy to structure programs into components with clean boundaries, +but there are only two forms of access: local (unexported) and global (exported). +Sometimes one wishes to have components that are not exported, +for instance to avoid acquiring clients of interfaces to code that is part of a public repository +but not intended for use outside the program to which it belongs. +

+ +

+The Go language does not have the power to enforce this distinction, but as of Go 1.4 the +go command introduces +a mechanism to define "internal" packages that may not be imported by packages outside +the source subtree in which they reside. +

+ +

+To create such a package, place it in a directory named internal or in a subdirectory of a directory +named internal. +When the go command sees an import of a package with internal in its path, +it verifies that the package doing the import +is within the tree rooted at the parent of the internal directory. +For example, a package .../a/b/c/internal/d/e/f +can be imported only by code in the directory tree rooted at .../a/b/c. +It cannot be imported by code in .../a/b/g or in any other repository. +

+ +

+For Go 1.4, the internal package mechanism is enforced for the main Go repository; +from 1.5 and onward it will be enforced for any repository. +

+ +

+Full details of the mechanism are in +the design document. +

+ +

Canonical import paths

+ +

+Code often lives in repositories hosted by public services such as github.com, +meaning that the import paths for packages begin with the name of the hosting service, +github.com/rsc/pdf for example. +One can use +an existing mechanism +to provide a "custom" or "vanity" import path such as +rsc.io/pdf, but +that creates two valid import paths for the package. +That is a problem: one may inadvertently import the package through the two +distinct paths in a single program, which is wasteful; +miss an update to a package because the path being used is not recognized to be +out of date; +or break clients using the old path by moving the package to a different hosting service. +

+ +

+Go 1.4 introduces an annotation for package clauses in Go source that identify a canonical +import path for the package. +If an import is attempted using a path that is not canonical, +the go command +will refuse to compile the importing package. +

+ +

+The syntax is simple: put an identifying comment on the package line. +For our example, the package clause would read: +

-TODO prose for these
-cmd/go: import comments (CL 124940043)
+package pdf // import "rsc.io/pdf"
+

+With this in place, +the go command will +refuse to compile a package that imports github.com/rsc/pdf, +ensuring that the code can be moved without breaking users. +

+ +

+The check is at build time, not download time, so if go get +fails because of this check, the mis-imported package has been copied to the local machine +and should be removed manually. +

+ +

+Further information is in +the design document. +

+

The go generate subcommand

The go command has a new subcommand, go generate, to automate the running of tools to generate source code before compilation. -For example, it can be used to run the yacc +For example, it can be used to run the yacc compiler-compiler on a .y file to produce the Go source file implementing the grammar, or to automate the generation of String methods for typed constants using the new stringer @@ -226,9 +304,9 @@ system name) is preceded by an underscore.

Updating: Packages that depend on the old behavior will no longer compile correctly. -Files with names like windows.go or arm64.go should either +Files with names like windows.go or amd64.go should either have explicit build tags added to the source or be renamed to something like -os_windows.go or support_arm64.go. +os_windows.go or support_amd64.go.

Other changes to the go command

@@ -261,14 +339,15 @@ The non-functional -file flag has been removed.
  • The go test -will compile and link all *_test.go files in the package, +subcommand will compile and link all *_test.go files in the package, even when there are no Test functions in them. It previously ignored such files.
  • The behavior of the -go build's +go build +subcommand's -a flag has been changed for non-development installations. For installations running a released distribution, the -a flag will no longer rebuild the standard library and commands, to avoid overwriting the installation's files. @@ -376,7 +455,6 @@ compress/flate, compress/gzip, compress/zlib: Reset support (https://codereview. crypto/tls: add support for ALPN (RFC 7301) (CL 108710046) crypto/tls: support programmatic selection of server certificates (CL 107400043) encoding/asn1: optional elements with a default value will now only be omitted if they have that value (CL 86960045) -flag: it is now an error to set a flag multiple times (CL 156390043) fmt: print type *map[T]T as &map[k:v] (CL 154870043) encoding/csv: do not quote empty strings, quote \. (CL 164760043) encoding/gob: remove unsafe (CL 102680045) @@ -390,6 +468,7 @@ reflect: Value is one word smaller runtime: implement monotonic clocks on windows (CL 108700045) runtime: MemStats.Mallocs now counts very small allocations missed in Go 1.3. This may break tests using runtime.ReadMemStats or testing.AllocsPerRun by giving a more accurate answer than Go 1.3 did (CL 143150043). runtime/race: freebsd is supported (CL 107270043) +runtime: add PauseEnd array to MemStats and GCStats (CL 153670043) swig: Due to runtime changes Go 1.4 will require SWIG 3.0.3 (not yet released) sync/atomic: add Value (CL 136710045) syscall: Setuid, Setgid are disabled on linux platforms. On linux those syscalls operate on the calling thread, not the whole process. This does not match the semantics of other platforms, nor the expectations of the caller, so the operations have been disabled until issue 1435 is resolved (CL 106170043) -- 2.48.1