From cd69218bdffc08e3c17023ac604bbb1a995b8602 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 27 Oct 2014 22:47:50 -0700 Subject: [PATCH] doc/go1.4.html: much of the go command's changes still need to do internal and import comments LGTM=adg R=golang-codereviews, adg CC=golang-codereviews https://golang.org/cl/160600043 --- doc/go1.4.html | 178 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 127 insertions(+), 51 deletions(-) diff --git a/doc/go1.4.html b/doc/go1.4.html index 7f5a12d0bf7..592b8661f15 100644 --- a/doc/go1.4.html +++ b/doc/go1.4.html @@ -87,7 +87,35 @@ may now be nil. TODO news about foobarblatz

-

Changes to the runtime

+

Changes to the compatibility guidelines

+ +

+The unsafe package allows one +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. +The answer, of course, is that we can make no promise of compatibility +for code that does unsafe things. +

+ +

+We have clarified this situation in the documentation included in the release. +The Go compatibilty guidelines and the +docs for the unsafe package +are now explicit that unsafe code is not guaranteed to remain compatible. +

+ +

+Updating: Nothing technical has changed; this is just a clarification +of the documentation. +

+ + +

Changes to the implementations and tools

+ +

Changes to the runtime

Up to Go 1.4, the runtime (garbage collector, concurrency support, interface management, @@ -140,58 +168,114 @@ so the effect is minimal, but programs that store integers (for example) in interfaces will see more allocations.

-

Changes to the compatibility guidelines

- -

-The unsafe package allows one -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. -The answer, of course, is that we can make no promise of compatibility -for code that does unsafe things. -

- -

-We have clarified this situation in the documentation included in the release. -The Go compatibilty guidelines and the -docs for the unsafe package -are now explicit that unsafe code is not guaranteed to remain compatible. -

- -

-Updating: Nothing technical has changed; this is just a clarification -of the documentation. -

- - -

Changes to the implementations and tools

- -

Changes to the garbage collector

- -

-TODO news about garbage collection -

- -

Stack

- -

-TODO news about stacks -

-

Status of gccgo

TODO gccgo news

-

Changes to the go command

+

Internal packages

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

Import comments

+ +
+TODO prose for these
+cmd/go: import comments (CL 124940043)
+
+ +

The go generate subcommand

-TODO go command news +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 +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 +tool in the go.tools repository.

+

+For more information, see the +design document. +

+ +

Change to file name handling

+ +

+Build constraints, also known as build tags, control compilation by including or excluding files +(see the documentation /go/build). +Compilation can also be controlled by the name of the file itself by "tagging" the file with +a suffix (before the .go or .s extension) with an underscore +and the name of the architecture or operating system. +For instance, the file gopher_arm.go will only be compiled if the target +processor is an ARM. +

+ +

+Before Go 1.4, a file called just arm.go was similarly tagged, but this behavior +can break sources when new architectures are added, causing files to suddenly become tagged. +In 1.4, therefore, a file will be tagged in this manner only if the tag (architecture or operating +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 +have explicit build tags added to the source or be renamed to something like +os_windows.go or support_arm64.go. +

+ +

Other changes to the go command

+ +

+There were a number of minor changes to the +cmd/go +command worth noting. +

+ + +

Changes to cgo

@@ -285,14 +369,6 @@ See the relevant package documentation for more information about each change. 

 
 cmd/6l, liblink: use pc-relative addressing for all memory references, so that linking Go binaries at high addresses works (CL 125140043). This cuts the maximum size of a Go binary's text+data+bss from 4GB to 2GB.
-cmd/go: import comments (CL 124940043)
-cmd/go: implement "internal" (CL 120600043)
-cmd/go: implement "generate" (CL 125580044)
-cmd/go: disallow C sources except when using cgo (CL 149720043)
-cmd/go: add test -o flag (CL 149070043)
-cmd/go: redefine build -a to skip standard library in releases (CL 151730045)
-cmd/go: compile and link all _test.go files during 'go test', even in packages where there are no Test functions (CL 150980043)
-cmd/go: (via go/build): a GOOS prefix acts as a tag only if preceded by an underscore. this is a breaking change. (CL 147690043)
 
 asm: make textflag.h available outside of cmd/ld (CL 128050043)
 bufio: handling of empty tokens at EOF changed, may require scanner change (CL 145390043)