Go 1.6 Release Notes

Introduction to Go 1.6

The latest Go release, version 1.6, arrives six months after 1.5. Most of its changes are in the implementation of the language, runtime, and libraries. There are no changes to the language specification. As always, the release maintains the Go 1 promise of compatibility. We expect almost all Go programs to continue to compile and run as before.

The release adds new ports to Linux on 64-bit MIPS and Android on 32-bit x86; defined and enforced rules for sharing Go pointers with C; transparent, automatic support for HTTP/2; and a new mechanism for template reuse.

Changes to the language

There are no language changes in this release.

Ports

Go 1.6 adds experimental ports to Linux on 64-bit MIPS (linux/mips64 and linux/mips64le). These ports support cgo but only with internal linking.

Go 1.6 also adds an experimental port to Android on 32-bit x86 (android/386).

On FreeBSD, Go 1.6 defaults to using clang, not gcc, as the external C compiler.

On Linux on little-endian 64-bit PowerPC (linux/ppc64le), Go 1.6 now supports cgo with external linking and is roughly feature complete.

On NaCl, Go 1.5 required SDK version pepper-41. Go 1.6 adds support for later SDK versions.

On 32-bit x86 systems using the -dynlink or -shared compilation modes, the register CX is now overwritten by certain memory references and should be avoided in hand-written assembly. See the assembly documentation for details.

Tools

Cgo

There is one major change to cgo, along with one minor change.

The major change is the definition of rules for sharing Go pointers with C code, to ensure that such C code can coexist with Go’s garbage collector. Briefly, Go and C may share memory allocated by Go when a pointer to that memory is passed to C as part of a cgo call, provided that the memory itself contains no pointers to Go-allocated memory, and provided that C does not retain the pointer after the call returns. These rules are checked by the runtime during program execution: if the runtime detects a violation, it prints a diagnosis and crashes the program. The checks can be disabled by setting the environment variable GODEBUG=cgocheck=0, but note that the vast majority of code identified by the checks is subtly incompatible with garbage collection in one way or another. Disabling the checks will typically only lead to more mysterious failure modes. Fixing the code in question should be strongly preferred over turning off the checks. See the cgo documentation for more details.

The minor change is the addition of explicit C.complexfloat and C.complexdouble types, separate from Go’s complex64 and complex128. Matching the other numeric types, C’s complex types and Go’s complex type are no longer interchangeable.

Compiler Toolchain

The compiler toolchain is mostly unchanged. Internally, the most significant change is that the parser is now hand-written instead of generated from yacc.

The compiler, linker, and go command have a new flag -msan, analogous to -race and only available on linux/amd64, that enables interoperation with the Clang MemorySanitizer. Such interoperation is useful mainly for testing a program containing suspect C or C++ code.

The linker has a new option -libgcc to set the expected location of the C compiler support library when linking cgo code. The option is only consulted when using -linkmode=internal, and it may be set to none to disable the use of a support library.

The implementation of build modes started in Go 1.5 has been expanded to more systems. This release adds support for the c-shared mode on android/386, android/amd64, android/arm64, linux/386, and linux/arm64; for the shared mode on linux/386, linux/arm, linux/amd64, and linux/ppc64le; and for the new pie mode (generating position-independent executables) on android/386, android/amd64, android/arm, android/arm64, linux/386, linux/amd64, linux/arm, linux/arm64, and linux/ppc64le. See the design document for details.

As a reminder, the linker’s -X flag changed in Go 1.5. In Go 1.4 and earlier, it took two arguments, as in

-X importpath.name value

Go 1.5 added an alternative syntax using a single argument that is itself a name=value pair:

-X importpath.name=value

In Go 1.5 the old syntax was still accepted, after printing a warning suggesting use of the new syntax instead. Go 1.6 continues to accept the old syntax and print the warning. Go 1.7 will remove support for the old syntax.

Gccgo

The release schedules for the GCC and Go projects do not coincide. GCC release 5 contains the Go 1.4 version of gccgo. The next release, GCC 6, will have the Go 1.6.1 version of gccgo.

Go command

The go command’s basic operation is unchanged, but there are a number of changes worth noting.

Go 1.5 introduced experimental support for vendoring, enabled by setting the GO15VENDOREXPERIMENT environment variable to 1. Go 1.6 keeps the vendoring support, no longer considered experimental, and enables it by default. It can be disabled explicitly by setting the GO15VENDOREXPERIMENT environment variable to 0. Go 1.7 will remove support for the environment variable.

The most likely problem caused by enabling vendoring by default happens in source trees containing an existing directory named vendor that does not expect to be interpreted according to new vendoring semantics. In this case, the simplest fix is to rename the directory to anything other than vendor and update any affected import paths.

For details about vendoring, see the documentation for the go command and the design document.

There is a new build flag, -msan, that compiles Go with support for the LLVM memory sanitizer. This is intended mainly for use when linking against C or C++ code that is being checked with the memory sanitizer.

Go doc command

Go 1.5 introduced the go doc command, which allows references to packages using only the package name, as in go doc http. In the event of ambiguity, the Go 1.5 behavior was to use the package with the lexicographically earliest import path. In Go 1.6, ambiguity is resolved by preferring import paths with fewer elements, breaking ties using lexicographic comparison. An important effect of this change is that original copies of packages are now preferred over vendored copies. Successful searches also tend to run faster.

Go vet command

The go vet command now diagnoses passing function or method values as arguments to Printf, such as when passing f where f() was intended.

Performance

As always, the changes are so general and varied that precise statements about performance are difficult to make. Some programs may run faster, some slower. On average the programs in the Go 1 benchmark suite run a few percent faster in Go 1.6 than they did in Go 1.5. The garbage collector’s pauses are even lower than in Go 1.5, especially for programs using a large amount of memory.

There have been significant optimizations bringing more than 10% improvements to implementations of the compress/bzip2, compress/gzip, crypto/aes, crypto/elliptic, crypto/ecdsa, and sort packages.

Core library

HTTP/2

Go 1.6 adds transparent support in the net/http package for the new HTTP/2 protocol. Go clients and servers will automatically use HTTP/2 as appropriate when using HTTPS. There is no exported API specific to details of the HTTP/2 protocol handling, just as there is no exported API specific to HTTP/1.1.

Programs that must disable HTTP/2 can do so by setting Transport.TLSNextProto (for clients) or Server.TLSNextProto (for servers) to a non-nil, empty map.

Programs that must adjust HTTP/2 protocol-specific details can import and use golang.org/x/net/http2, in particular its ConfigureServer and ConfigureTransport functions.

Runtime

The runtime has added lightweight, best-effort detection of concurrent misuse of maps. As always, if one goroutine is writing to a map, no other goroutine should be reading or writing the map concurrently. If the runtime detects this condition, it prints a diagnosis and crashes the program. The best way to find out more about the problem is to run the program under the race detector, which will more reliably identify the race and give more detail.

For program-ending panics, the runtime now by default prints only the stack of the running goroutine, not all existing goroutines. Usually only the current goroutine is relevant to a panic, so omitting the others significantly reduces irrelevant output in a crash message. To see the stacks from all goroutines in crash messages, set the environment variable GOTRACEBACK to all or call debug.SetTraceback before the crash, and rerun the program. See the runtime documentation for details.

Updating: Uncaught panics intended to dump the state of the entire program, such as when a timeout is detected or when explicitly handling a received signal, should now call debug.SetTraceback("all") before panicking. Searching for uses of signal.Notify may help identify such code.

On Windows, Go programs in Go 1.5 and earlier forced the global Windows timer resolution to 1ms at startup by calling timeBeginPeriod(1). Go no longer needs this for good scheduler performance, and changing the global timer resolution caused problems on some systems, so the call has been removed.

When using -buildmode=c-archive or -buildmode=c-shared to build an archive or a shared library, the handling of signals has changed. In Go 1.5 the archive or shared library would install a signal handler for most signals. In Go 1.6 it will only install a signal handler for the synchronous signals needed to handle run-time panics in Go code: SIGBUS, SIGFPE, SIGSEGV. See the os/signal package for more details.

Reflect

The reflect package has resolved a long-standing incompatibility between the gc and gccgo toolchains regarding embedded unexported struct types containing exported fields. Code that walks data structures using reflection, especially to implement serialization in the spirit of the encoding/json and encoding/xml packages, may need to be updated.

The problem arises when using reflection to walk through an embedded unexported struct-typed field into an exported field of that struct. In this case, reflect had incorrectly reported the embedded field as exported, by returning an empty Field.PkgPath. Now it correctly reports the field as unexported but ignores that fact when evaluating access to exported fields contained within the struct.

Updating: Typically, code that previously walked over structs and used

f.PkgPath != ""

to exclude inaccessible fields should now use

f.PkgPath != "" && !f.Anonymous

For example, see the changes to the implementations of encoding/json and encoding/xml.

Sorting

In the sort package, the implementation of Sort has been rewritten to make about 10% fewer calls to the Interface’s Less and Swap methods, with a corresponding overall time savings. The new algorithm does choose a different ordering than before for values that compare equal (those pairs for which Less(i, j) and Less(j, i) are false).

Updating: The definition of Sort makes no guarantee about the final order of equal values, but the new behavior may still break programs that expect a specific order. Such programs should either refine their Less implementations to report the desired order or should switch to Stable, which preserves the original input order of equal values.

Templates

In the text/template package, there are two significant new features to make writing templates easier.

First, it is now possible to trim spaces around template actions, which can make template definitions more readable. A minus sign at the beginning of an action says to trim space before the action, and a minus sign at the end of an action says to trim space after the action. For example, the template

{{23 -}}
   <
{{- 45}}

formats as 23<45.

Second, the new {{block}} action, combined with allowing redefinition of named templates, provides a simple way to define pieces of a template that can be replaced in different instantiations. There is an example in the text/template package that demonstrates this new feature.

Minor changes to the library