Updatify / Go lang | Release notes

Create your changelog

Go lang

https://go.dev/ ↗

Go is a high-level, general-purpose programming language that is statically typed and compiled. It is known for the simplicity of its syntax and the efficiency of development that it enables through the inclusion of a large standard library supplying many needs for common projects.

Update Aug 15, 2016 tracked by Updatify

go1.7 (released 2016-08-15)

Introduction to Go 1.7

The latest Go release, version 1.7, arrives six months after 1.6. Most of its changes are in the implementation of the toolchain, runtime, and libraries. There is one minor change 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 a port to IBM LinuxOne; updates the x86-64 compiler back end to generate more efficient code; includes the context package, promoted from the x/net subrepository and now used in the standard library; and adds support in the testing package for creating hierarchies of tests and benchmarks. The release also finalizes the vendoring support started in Go 1.5, making it a standard feature.

Changes to the language

There is one tiny language change in this release. The section on terminating statements clarifies that to determine whether a statement list ends in a terminating statement, the “final non-empty statement” is considered the end, matching the existing behavior of the gc and gccgo compiler toolchains. In earlier releases the definition referred only to the “final statement,” leaving the effect of trailing empty statements at the least unclear. The go/types package has been updated to match the gc and gccgo compiler toolchains in this respect. This change has no effect on the correctness of existing programs.

Ports

Go 1.7 adds support for macOS 10.12 Sierra. Binaries built with versions of Go before 1.7 will not work correctly on Sierra.

Go 1.7 adds an experimental port to Linux on z Systems ( linux/s390x) and the beginning of a port to Plan 9 on ARM ( plan9/arm).

The experimental ports to Linux on 64-bit MIPS ( linux/mips64 and linux/mips64le) added in Go 1.6 now have full support for cgo and external linking.

The experimental port to Linux on little-endian 64-bit PowerPC ( linux/ppc64le) now requires the POWER8 architecture or later. Big-endian 64-bit PowerPC ( linux/ppc64) only requires the POWER5 architecture.

The OpenBSD port now requires OpenBSD 5.6 or later, for access to the getentropy (2) system call.

Known Issues

There are some instabilities on FreeBSD that are known but not understood. These can lead to program crashes in rare cases. See issue 16136, issue 15658, and issue 16396. Any help in solving these FreeBSD-specific issues would be appreciated.

Tools

Assembler

For 64-bit ARM systems, the vector register names have been corrected to V0 through V31; previous releases incorrectly referred to them as V32 through V63.

For 64-bit x86 systems, the following instructions have been added: PCMPESTRI, RORXL, RORXQ, VINSERTI128, VPADDD, VPADDQ, VPALIGNR, VPBLENDD, VPERM2F128, VPERM2I128, VPOR, VPSHUFB, VPSHUFD, VPSLLD, VPSLLDQ, VPSLLQ, VPSRLD, VPSRLDQ, and VPSRLQ.

Compiler Toolchain

This release includes a new code generation back end for 64-bit x86 systems, following a proposal from 2015 that has been under development since then. The new back end, based on SSA, generates more compact, more efficient code and provides a better platform for optimizations such as bounds check elimination. The new back end reduces the CPU time required by our benchmark programs by 5-35%.

For this release, the new back end can be disabled by passing -ssa=0 to the compiler. If you find that your program compiles or runs successfully only with the new back end disabled, please file a bug report.

The format of exported metadata written by the compiler in package archives has changed: the old textual format has been replaced by a more compact binary format. This results in somewhat smaller package archives and fixes a few long-standing corner case bugs.

For this release, the new export format can be disabled by passing -newexport=0 to the compiler. If you find that your program compiles or runs successfully only with the new export format disabled, please file a bug report.

The linker’s -X option no longer supports the unusual two-argument form -X name value, as announced in the Go 1.6 release and in warnings printed by the linker. Use -X name=value instead.

The compiler and linker have been optimized and run significantly faster in this release than in Go 1.6, although they are still slower than we would like and will continue to be optimized in future releases.

Due to changes across the compiler toolchain and standard library, binaries built with this release should typically be smaller than binaries built with Go 1.6, sometimes by as much as 20-30%.

On x86-64 systems, Go programs now maintain stack frame pointers as expected by profiling tools like Linux’s perf and Intel’s VTune, making it easier to analyze and optimize Go programs using these tools. The frame pointer maintenance has a small run-time overhead that varies but averages around 2%. We hope to reduce this cost in future releases. To build a toolchain that does not use frame pointers, set GOEXPERIMENT=noframepointer when running make.bash, make.bat, or make.rc.

Cgo

Packages using cgo may now include Fortran source files (in addition to C, C++, Objective C, and SWIG), although the Go bindings must still use C language APIs.

Go bindings may now use a new helper function C.CBytes. In contrast to C.CString, which takes a Go string and returns a *C.byte (a C char*), C.CBytes takes a Go []byte and returns an unsafe.Pointer (a C void*).

Packages and binaries built using cgo have in past releases produced different output on each build, due to the embedding of temporary directory names. When using this release with new enough versions of GCC or Clang (those that support the -fdebug-prefix-map option), those builds should finally be deterministic.

Gccgo

Due to the alignment of Go’s semiannual release schedule with GCC’s annual release schedule, GCC release 6 contains the Go 1.6.1 version of gccgo. The next release, GCC 7, will likely have the Go 1.8 version of gccgo.

Go command

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

This release removes support for the GO15VENDOREXPERIMENT environment variable, as announced in the Go 1.6 release. Vendoring support is now a standard feature of the go command and toolchain.

The Package data structure made available to “ go list ” now includes a StaleReason field explaining why a particular package is or is not considered stale (in need of rebuilding). This field is available to the -f or -json options and is useful for understanding why a target is being rebuilt.

The “ go get ” command now supports import paths referring to git.openstack.org.

This release adds experimental, minimal support for building programs using binary-only packages, packages distributed in binary form without the corresponding source code. This feature is needed in some commercial settings but is not intended to be fully integrated into the rest of the toolchain. For example, tools that assume access to complete source code will not work with such packages, and there are no plans to support such packages in the “ go get ” command.

Go doc

The “ go doc ” command now groups constructors with the type they construct, following godoc.

Go vet

The “ go vet ” command has more accurate analysis in its -copylock and -printf checks, and a new -tests check that checks the name and signature of likely test functions. To avoid confusion with the new -tests check, the old, unadvertised -test option has been removed; it was equivalent to -all -shadow.

The vet command also has a new check, -lostcancel, which detects failure to call the cancellation function returned by the WithCancel, WithTimeout, and WithDeadline functions in Go 1.7’s new context package (see below). Failure to call the function prevents the new Context from being reclaimed until its parent is canceled. (The background context is never canceled.)

Go tool dist

The new subcommand “ go tool dist list ” prints all supported operating system/architecture pairs.

Go tool trace

The “ go tool trace ” command, introduced in Go 1.5, has been refined in various ways.

First, collecting traces is significantly more efficient than in past releases. In this release, the typical execution-time overhead of collecting a trace is about 25%; in past releases it was at least 400%. Second, trace files now include file and line number information, making them more self-contained and making the original executable optional when running the trace tool. Third, the trace tool now breaks up large traces to avoid limits in the browser-based viewer.

Although the trace file format has changed in this release, the Go 1.7 tools can still read traces from earlier releases.

Performance

As always, the changes are so general and varied that precise statements about performance are difficult to make. Most programs should run a bit faster, due to speedups in the garbage collector and optimizations in the core library. On x86-64 systems, many programs will run significantly faster, due to improvements in generated code brought by the new compiler back end. As noted above, in our own benchmarks, the code generation changes alone typically reduce program CPU time by 5-35%.

There have been significant optimizations bringing more than 10% improvements to implementations in the crypto/sha1, crypto/sha256, encoding/binary, fmt, hash/adler32, hash/crc32, hash/crc64, image/color, math/big, strconv, strings, unicode, and unicode/utf16 packages.

Garbage collection pauses should be significantly shorter than they were in Go 1.6 for programs with large numbers of idle goroutines, substantial stack size fluctuation, or large package-level variables.

Standard library

Context

Go 1.7 moves the golang.org/x/net/context package into the standard library as context. This allows the use of contexts for cancellation, timeouts, and passing request-scoped data in other standard library packages, including net, net/http, and os/exec, as noted below.

For more information about contexts, see the package documentation and the Go blog post “ Go Concurrent Patterns: Context.”

HTTP Tracing

Go 1.7 introduces net/http/httptrace, a package that provides mechanisms for tracing events within HTTP requests.

Testing

The testing package now supports the definition of tests with subtests and benchmarks with sub-benchmarks. This support makes it easy to write table-driven benchmarks and to create hierarchical tests. It also provides a way to share common setup and tear-down code. See the package documentation for details.

Runtime

All panics started by the runtime now use panic values that implement both the builtin error, and runtime.Error, as required by the language specification.

During panics, if a signal’s name is known, it will be printed in the stack trace. Otherwise, the signal’s number will be used, as it was before Go1.7.

The new function KeepAlive provides an explicit mechanism for declaring that an allocated object must be considered reachable at a particular point in a program, typically to delay the execution of an associated finalizer.

The new function CallersFrames translates a PC slice obtained from Callers into a sequence of frames corresponding to the call stack. This new API should be preferred instead of direct use of FuncForPC, because the frame sequence can more accurately describe call stacks with inlined function calls.

The new function SetCgoTraceback facilitates tighter integration between Go and C code executing in the same process called using cgo.

On 32-bit systems, the runtime can now use memory allocated by the operating system anywhere in the address space, eliminating the “memory allocated by OS not in usable range” failure common in some environments.

The runtime can now return unused memory to the operating system on all architectures. In Go 1.6 and earlier, the runtime could not release memory on ARM64, 64-bit PowerPC, or MIPS.

On Windows, Go programs in Go 1.5 and earlier forced the global Windows timer resolution to 1ms at startup by calling timeBeginPeriod(1). Changing the global timer resolution caused problems on some systems, and testing suggested that the call was not needed for good scheduler performance, so Go 1.6 removed the call. Go 1.7 brings the call back: under some workloads the call is still needed for good scheduler performance.

Minor changes to the library

As always, there are various minor changes and updates to the library, made with the Go 1 promise of compatibility in mind.

bufio

In previous releases of Go, if Reader ’s Peek method were asked for more bytes than fit in the underlying buffer, it would return an empty slice and the error ErrBufferFull. Now it returns the entire underlying buffer, still accompanied by the error ErrBufferFull.

bytes

The new functions ContainsAny and ContainsRune have been added for symmetry with the strings package.

In previous releases of Go, if Reader ’s Read method were asked for zero bytes with no data remaining, it would return a count of 0 and no error. Now it returns a count of 0 and the error io.EOF.

The Reader type has a new method Reset to allow reuse of a Reader.

compress/flate

There are many performance optimizations throughout the package. Decompression speed is improved by about 10%, while compression for DefaultCompression is twice as fast.

In addition to those general improvements, the BestSpeed compressor has been replaced entirely and uses an algorithm similar to Snappy, resulting in about a 2.5X speed increase, although the output can be 5-10% larger than with the previous algorithm.

There is also a new compression level HuffmanOnly that applies Huffman but not Lempel-Ziv encoding. Forgoing Lempel-Ziv encoding means that HuffmanOnly runs about 3X faster than the new BestSpeed but at the cost of producing compressed outputs that are 20-40% larger than those generated by the new BestSpeed.

It is important to note that both BestSpeed and HuffmanOnly produce a compressed output that is RFC 1951 compliant. In other words, any valid DEFLATE decompressor will continue to be able to decompress these outputs.

Lastly, there is a minor change to the decompressor’s implementation of io.Reader. In previous versions, the decompressor deferred reporting io.EOF until exactly no more bytes could be read. Now, it reports io.EOF more eagerly when reading the last set of bytes.

crypto/tls

The TLS implementation sends the first few data packets on each connection using small record sizes, gradually increasing to the TLS maximum record size. This heuristic reduces the amount of data that must be received before the first packet can be decrypted, improving communication latency over low-bandwidth networks. Setting Config ’s DynamicRecordSizingDisabled field to true forces the behavior of Go 1.6 and earlier, where packets are as large as possible from the start of the connection.

The TLS client now has optional, limited support for server-initiated renegotiation, enabled by setting the Config ’s Renegotiation field. This is needed for connecting to many Microsoft Azure servers.

The errors returned by the package now consistently begin with a tls: prefix. In past releases, some errors used a crypto/tls: prefix, some used a tls: prefix, and some had no prefix at all.

When generating self-signed certificates, the package no longer sets the “Authority Key Identifier” field by default.

crypto/x509

The new function SystemCertPool provides access to the entire system certificate pool if available. There is also a new associated error type SystemRootsError.

debug/dwarf

The Reader type’s new SeekPC method and the Data type’s new Ranges method help to find the compilation unit to pass to a LineReader and to identify the specific function for a given program counter.

debug/elf

The new R_390 relocation type and its many predefined constants support the S390 port.

encoding/asn1

The ASN.1 decoder now rejects non-minimal integer encodings. This may cause the package to reject some invalid but formerly accepted ASN.1 data.

encoding/json

The Encoder ’s new SetIndent method sets the indentation parameters for JSON encoding, like in the top-level Indent function.

The Encoder ’s new SetEscapeHTML method controls whether the &, <, and > characters in quoted strings should be escaped as \u0026, \u003c, and \u003e, respectively. As in previous releases, the encoder defaults to applying this escaping, to avoid certain problems that can arise when embedding JSON in HTML.

In earlier versions of Go, this package only supported encoding and decoding maps using keys with string types. Go 1.7 adds support for maps using keys with integer types: the encoding uses a quoted decimal representation as the JSON key. Go 1.7 also adds support for encoding maps using non-string keys that implement the MarshalText (see encoding.TextMarshaler) method, as well as support for decoding maps using non-string keys that implement the UnmarshalText (see encoding.TextUnmarshaler) method. These methods are ignored for keys with string types in order to preserve the encoding and decoding used in earlier versions of Go.

When encoding a slice of typed bytes, Marshal now generates an array of elements encoded using that byte type’s MarshalJSON or MarshalText method if present, only falling back to the default base64-encoded string data if neither method is available. Earlier versions of Go accept both the original base64-encoded string encoding and the array encoding (assuming the byte type also implements UnmarshalJSON or UnmarshalText as appropriate), so this change should be semantically backwards compatible with earlier versions of Go, even though it does change the chosen encoding.

go/build

To implement the go command’s new support for binary-only packages and for Fortran code in cgo-based packages, the Package type adds new fields BinaryOnly, CgoFFLAGS, and FFiles.

go/doc

To support the corresponding change in go test described above, Example struct adds an Unordered field indicating whether the example may generate its output lines in any order.

io

The package adds new constants SeekStart, SeekCurrent, and SeekEnd, for use with Seeker implementations. These constants are preferred over os.SEEK_SET, os.SEEK_CUR, and os.SEEK_END, but the latter will be preserved for compatibility.

math/big

The Float type adds GobEncode and GobDecode methods, so that values of type Float can now be encoded and decoded using the encoding/gob package.

math/rand

The Read function and Rand ’s Read method now produce a pseudo-random stream of bytes that is consistent and not dependent on the size of the input buffer.

The documentation clarifies that Rand’s Seed and Read methods are not safe to call concurrently, though the global functions Seed and Read are (and have always been) safe.

mime/multipart

The Writer implementation now emits each multipart section’s header sorted by key. Previously, iteration over a map caused the section header to use a non-deterministic order.

net

As part of the introduction of context, the Dialer type has a new method DialContext, like Dial but adding the context.Context for the dial operation. The context is intended to obsolete the Dialer ’s Cancel and Deadline fields, but the implementation continues to respect them, for backwards compatibility.

The IP type’s String method has changed its result for invalid IP addresses. In past releases, if an IP byte slice had length other than 0, 4, or 16, String returned "?". Go 1.7 adds the hexadecimal encoding of the bytes, as in "?12ab".

The pure Go name resolution implementation now respects nsswitch.conf ’s stated preference for the priority of DNS lookups compared to local file (that is, /etc/hosts) lookups.

net/http

ResponseWriter ’s documentation now makes clear that beginning to write the response may prevent future reads on the request body. For maximal compatibility, implementations are encouraged to read the request body completely before writing any part of the response.

As part of the introduction of context, the Request has a new methods Context, to retrieve the associated context, and WithContext, to construct a copy of Request with a modified context.

In the Server implementation, Serve records in the request context both the underlying *Server using the key ServerContextKey and the local address on which the request was received (a Addr) using the key LocalAddrContextKey. For example, the address on which a request received is req.Context().Value(http.LocalAddrContextKey).(net.Addr).

The server’s Serve method now only enables HTTP/2 support if the Server.TLSConfig field is nil or includes "h2" in its TLSConfig.NextProtos.

The server implementation now pads response codes less than 100 to three digits as required by the protocol, so that w.WriteHeader(5) uses the HTTP response status 005, not just 5.

The server implementation now correctly sends only one “Transfer-Encoding” header when “chunked” is set explicitly, following RFC 7230.

The server implementation is now stricter about rejecting requests with invalid HTTP versions. Invalid requests claiming to be HTTP/0.x are now rejected (HTTP/0.9 was never fully supported), and plaintext HTTP/2 requests other than the “PRI * HTTP/2.0” upgrade request are now rejected as well. The server continues to handle encrypted HTTP/2 requests.

In the server, a 200 status code is sent back by the timeout handler on an empty response body, instead of sending back 0 as the status code.

In the client, the Transport implementation passes the request context to any dial operation connecting to the remote server. If a custom dialer is needed, the new Transport field DialContext is preferred over the existing Dial field, to allow the transport to supply a context.

The Transport also adds fields IdleConnTimeout, MaxIdleConns, and MaxResponseHeaderBytes to help control client resources consumed by idle or chatty servers.

A Client ’s configured CheckRedirect function can now return ErrUseLastResponse to indicate that the most recent redirect response should be returned as the result of the HTTP request. That response is now available to the CheckRedirect function as req.Response.

Since Go 1, the default behavior of the HTTP client is to request server-side compression using the Accept-Encoding request header and then to decompress the response body transparently, and this behavior is adjustable using the Transport ’s DisableCompression field. In Go 1.7, to aid the implementation of HTTP proxies, the Response ’s new Uncompressed field reports whether this transparent decompression took place.

DetectContentType adds support for a few new audio and video content types.

net/http/cgi

The Handler adds a new field Stderr that allows redirection of the child process’s standard error away from the host process’s standard error.

net/http/httptest

The new function NewRequest prepares a new http.Request suitable for passing to an http.Handler during a test.

The ResponseRecorder ’s new Result method returns the recorded http.Response. Tests that need to check the response’s headers or trailers should call Result and inspect the response fields instead of accessing ResponseRecorder ’s HeaderMap directly.

net/http/httputil

The ReverseProxy implementation now responds with “502 Bad Gateway” when it cannot reach a back end; in earlier releases it responded with “500 Internal Server Error.”

Both ClientConn and ServerConn have been documented as deprecated. They are low-level, old, and unused by Go’s current HTTP stack and will no longer be updated. Programs should use http.Client, http.Transport, and http.Server instead.

net/http/pprof

The runtime trace HTTP handler, installed to handle the path /debug/pprof/trace, now accepts a fractional number in its seconds query parameter, allowing collection of traces for intervals smaller than one second. This is especially useful on busy servers.

net/mail

The address parser now allows unescaped UTF-8 text in addresses following RFC 6532, but it does not apply any normalization to the result. For compatibility with older mail parsers, the address encoder, namely Address ’s String method, continues to escape all UTF-8 text following RFC 5322.

The ParseAddress function and the AddressParser.Parse method are stricter. They used to ignore any characters following an e-mail address, but will now return an error for anything other than whitespace.

net/url

The URL ’s new ForceQuery field records whether the URL must have a query string, in order to distinguish URLs without query strings (like /search) from URLs with empty query strings (like /search?).

os

IsExist now returns true for syscall.ENOTEMPTY, on systems where that error exists.

On Windows, Remove now removes read-only files when possible, making the implementation behave as on non-Windows systems.

os/exec

As part of the introduction of context, the new constructor CommandContext is like Command but includes a context that can be used to cancel the command execution.

os/user

The Current function is now implemented even when cgo is not available.

The new Group type, along with the lookup functions LookupGroup and LookupGroupId and the new field GroupIds in the User struct, provides access to system-specific user group information.

reflect

Although Value ’s Field method has always been documented to panic if the given field number i is out of range, it has instead silently returned a zero Value. Go 1.7 changes the method to behave as documented.

The new StructOf function constructs a struct type at run time. It completes the set of type constructors, joining ArrayOf, ChanOf, FuncOf, MapOf, PtrTo, and SliceOf.

StructTag ’s new method Lookup is like Get but distinguishes the tag not containing the given key from the tag associating an empty string with the given key.

The Method and NumMethod methods of Type and Value no longer return or count unexported methods.

strings

In previous releases of Go, if Reader ’s Read method were asked for zero bytes with no data remaining, it would return a count of 0 and no error. Now it returns a count of 0 and the error io.EOF.

The Reader type has a new method Reset to allow reuse of a Reader.

time

Duration ’s time.Duration.String method now reports the zero duration as "0s", not "0". ParseDuration continues to accept both forms.

The method call time.Local.String() now returns "Local" on all systems; in earlier releases, it returned an empty string on Windows.

The time zone database in $GOROOT/lib/time has been updated to IANA release 2016d. This fallback database is only used when the system time zone database cannot be found, for example on Windows. The Windows time zone abbreviation list has also been updated.

syscall

On Linux, the SysProcAttr struct (as used in os/exec.Cmd ’s SysProcAttr field) has a new Unshareflags field. If the field is nonzero, the child process created by ForkExec (as used in exec.Cmd ’s Run method) will call the unshare (2) system call before executing the new program.

unicode

The unicode package and associated support throughout the system has been upgraded from version 8.0 to Unicode 9.0.

Original source ↗

Update Feb 17, 2016 tracked by Updatify

go1.6 (released 2016-02-17)

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.

Standard 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

  • The archive/tar package’s implementation corrects many bugs in rare corner cases of the file format. One visible change is that the Reader type’s Read method now presents the content of special file types as being empty, returning io.EOF immediately.
  • In the archive/zip package, the Reader type now has a RegisterDecompressor method, and the Writer type now has a RegisterCompressor method, enabling control over compression options for individual zip files. These take precedence over the pre-existing global RegisterDecompressor and RegisterCompressor functions.
  • The bufio package’s Scanner type now has a Buffer method, to specify an initial buffer and maximum buffer size to use during scanning. This makes it possible, when needed, to scan tokens larger than MaxScanTokenSize. Also for the Scanner, the package now defines the ErrFinalToken error value, for use by split functions to abort processing or to return a final empty token.
  • The compress/flate package has deprecated its ReadError and WriteError error implementations. In Go 1.5 they were only rarely returned when an error was encountered; now they are never returned, although they remain defined for compatibility.
  • The compress/flate, compress/gzip, and compress/zlib packages now report io.ErrUnexpectedEOF for truncated input streams, instead of io.EOF.
  • The crypto/cipher package now overwrites the destination buffer in the event of a GCM decryption failure. This is to allow the AESNI code to avoid using a temporary buffer.
  • The crypto/tls package has a variety of minor changes. It now allows Listen to succeed when the Config has a nil Certificates, as long as the GetCertificate callback is set, it adds support for RSA with AES-GCM cipher suites, and it adds a RecordHeaderError to allow clients (in particular, the net/http package) to report a better error when attempting a TLS connection to a non-TLS server.
  • The crypto/x509 package now permits certificates to contain negative serial numbers (technically an error, but unfortunately common in practice), and it defines a new InsecureAlgorithmError to give a better error message when rejecting a certificate signed with an insecure algorithm like MD5.
  • The debug/dwarf and debug/elf packages together add support for compressed DWARF sections. User code needs no updating: the sections are decompressed automatically when read.
  • The debug/elf package adds support for general compressed ELF sections. User code needs no updating: the sections are decompressed automatically when read. However, compressed Sections do not support random access: they have a nil ReaderAt field.
  • The encoding/asn1 package now exports tag and class constants useful for advanced parsing of ASN.1 structures.
  • Also in the encoding/asn1 package, Unmarshal now rejects various non-standard integer and length encodings.
  • The encoding/base64 package’s Decoder has been fixed to process the final bytes of its input. Previously it processed as many four-byte tokens as possible but ignored the remainder, up to three bytes. The Decoder therefore now handles inputs in unpadded encodings (like RawURLEncoding) correctly, but it also rejects inputs in padded encodings that are truncated or end with invalid bytes, such as trailing spaces.
  • The encoding/json package now checks the syntax of a Number before marshaling it, requiring that it conforms to the JSON specification for numeric values. As in previous releases, the zero Number (an empty string) is marshaled as a literal 0 (zero).
  • The encoding/xml package’s Marshal function now supports a cdata attribute, such as chardata but encoding its argument in one or more <![CDATA[ ... ]]> tags.
  • Also in the encoding/xml package, Decoder ’s Token method now reports an error when encountering EOF before seeing all open tags closed, consistent with its general requirement that tags in the input be properly matched. To avoid that requirement, use RawToken.
  • The fmt package now allows any integer type as an argument to Printf ’s * width and precision specification. In previous releases, the argument to * was required to have type int.
  • Also in the fmt package, Scanf can now scan hexadecimal strings using %X, as an alias for %x. Both formats accept any mix of upper- and lower-case hexadecimal.
  • The image and image/color packages add NYCbCrA and NYCbCrA types, to support Y’CbCr images with non-premultiplied alpha.
  • The io package’s MultiWriter implementation now implements a WriteString method, for use by WriteString.
  • In the math/big package, Int adds Append and Text methods to give more control over printing.
  • Also in the math/big package, Float now implements encoding.TextMarshaler and encoding.TextUnmarshaler, allowing it to be serialized in a natural form by the encoding/json and encoding/xml packages.
  • Also in the math/big package, Float ’s Append method now supports the special precision argument -1. As in strconv.ParseFloat, precision -1 means to use the smallest number of digits necessary such that Parse reading the result into a Float of the same precision will yield the original value.
  • The math/rand package adds a Read function, and likewise Rand adds a Read method. These make it easier to generate pseudorandom test data. Note that, like the rest of the package, these should not be used in cryptographic settings; for such purposes, use the crypto/rand package instead.
  • The net package’s ParseMAC function now accepts 20-byte IP-over-InfiniBand (IPoIB) link-layer addresses.
  • Also in the net package, there have been a few changes to DNS lookups. First, the DNSError error implementation now implements Error, and in particular its new IsTemporary method returns true for DNS server errors. Second, DNS lookup functions such as LookupAddr now return rooted domain names (with a trailing dot) on Plan 9 and Windows, to match the behavior of Go on Unix systems.
  • The net/http package has a number of minor additions beyond the HTTP/2 support already discussed. First, the FileServer now sorts its generated directory listings by file name. Second, the ServeFile function now refuses to serve a result if the request’s URL path contains “..” (dot-dot) as a path element. Programs should typically use FileServer and Dir instead of calling ServeFile directly. Programs that need to serve file content in response to requests for URLs containing dot-dot can still call ServeContent. Third, the Client now allows user code to set the Expect: 100-continue header (see Transport.ExpectContinueTimeout). Fourth, there are five new error codes: StatusPreconditionRequired (428), StatusTooManyRequests (429), StatusRequestHeaderFieldsTooLarge (431), and StatusNetworkAuthenticationRequired (511) from RFC 6585, as well as the recently-approved StatusUnavailableForLegalReasons (451). Fifth, the implementation and documentation of CloseNotifier has been substantially changed. The Hijacker interface now works correctly on connections that have previously been used with CloseNotifier. The documentation now describes when CloseNotifier is expected to work.
  • Also in the net/http package, there are a few changes related to the handling of a Request data structure with its Method field set to the empty string. An empty Method field has always been documented as an alias for "GET" and it remains so. However, Go 1.6 fixes a few routines that did not treat an empty Method the same as an explicit "GET". Most notably, in previous releases Client followed redirects only with Method set explicitly to "GET"; in Go 1.6 Client also follows redirects for the empty Method. Finally, NewRequest accepts a method argument that has not been documented as allowed to be empty. In past releases, passing an empty method argument resulted in a Request with an empty Method field. In Go 1.6, the resulting Request always has an initialized Method field: if its argument is an empty string, NewRequest sets the Method field in the returned Request to "GET".
  • The net/http/httptest package’s ResponseRecorder now initializes a default Content-Type header using the same content-sniffing algorithm as in http.Server.
  • The net/url package’s Parse is now stricter and more spec-compliant regarding the parsing of host names. For example, spaces in the host name are no longer accepted.
  • Also in the net/url package, the Error type now implements net.Error.
  • The os package’s IsExist, IsNotExist, and IsPermission now return correct results when inquiring about an SyscallError.
  • On Unix-like systems, when a write to os.Stdout or os.Stderr (more precisely, an os.File opened for file descriptor 1 or 2) fails due to a broken pipe error, the program will raise a SIGPIPE signal. By default this will cause the program to exit; this may be changed by calling the os/signal Notify function for syscall.SIGPIPE. A write to a broken pipe on a file descriptor other 1 or 2 will simply return syscall.EPIPE (possibly wrapped in os.PathError and/or os.SyscallError) to the caller. The old behavior of raising an uncatchable SIGPIPE signal after 10 consecutive writes to a broken pipe no longer occurs.
  • In the os/exec package, Cmd ’s Output method continues to return an ExitError when a command exits with an unsuccessful status. If standard error would otherwise have been discarded, the returned ExitError now holds a prefix and suffix (currently 32 kB) of the failed command’s standard error output, for debugging or for inclusion in error messages. The ExitError ’s String method does not show the captured standard error; programs must retrieve it from the data structure separately.
  • On Windows, the path/filepath package’s Join function now correctly handles the case when the base is a relative drive path. For example, Join(c:, a`)` now returnsc:ainstead ofc:\a` as in past releases. This may affect code that expects the incorrect result. - In the [regexp](https://go.dev/pkg/regexp/) package, the [Regexp](https://go.dev/pkg/regexp/#Regexp) type has always been safe for use by concurrent goroutines. It uses a [sync.Mutex](https://go.dev/pkg/sync/#Mutex) to protect a cache of scratch spaces used during regular expression searches. Some high-concurrency servers using the sameRegexpfrom many goroutines have seen degraded performance due to contention on that mutex. To help such servers,Regexpnow has a [Copy](https://go.dev/pkg/regexp/#Regexp.Copy) method, which makes a copy of aRegexpthat shares most of the structure of the original but has its own scratch space cache. Two goroutines can use different copies of aRegexpwithout mutex contention. A copy does have additional space overhead, soCopyshould only be used when contention has been observed. - The [strconv](https://go.dev/pkg/strconv/) package adds [IsGraphic](https://go.dev/pkg/strconv/#IsGraphic), similar to [IsPrint](https://go.dev/pkg/strconv/#IsPrint). It also adds [QuoteToGraphic](https://go.dev/pkg/strconv/#QuoteToGraphic), [QuoteRuneToGraphic](https://go.dev/pkg/strconv/#QuoteRuneToGraphic), [AppendQuoteToGraphic](https://go.dev/pkg/strconv/#AppendQuoteToGraphic), and [AppendQuoteRuneToGraphic](https://go.dev/pkg/strconv/#AppendQuoteRuneToGraphic), analogous to [QuoteToASCII](https://go.dev/pkg/strconv/#QuoteToASCII), [QuoteRuneToASCII](https://go.dev/pkg/strconv/#QuoteRuneToASCII), and so on. TheASCIIfamily escapes all space characters except ASCII space (U+0020). In contrast, theGraphicfamily does not escape any Unicode space characters (category Zs). - In the [testing](https://go.dev/pkg/testing/) package, when a test calls [t.Parallel](https://go.dev/pkg/testing/#T.Parallel), that test is paused until all non-parallel tests complete, and then that test continues execution with all other parallel tests. Go 1.6 changes the time reported for such a test: previously the time counted only the parallel execution, but now it also counts the time from the start of testing until the call tot.Parallel. - The [text/template](https://go.dev/pkg/text/template/) package contains two minor changes, in addition to the [major changes](#template) described above. First, it adds a new [ExecError](https://go.dev/pkg/text/template/#ExecError) type returned for any error during [Execute](https://go.dev/pkg/text/template/#Template.Execute) that does not originate in aWriteto the underlying writer. Callers can distinguish template usage errors from I/O errors by checking forExecError. Second, the [Funcs](https://go.dev/pkg/text/template/#Template.Funcs) method now checks that the names used as keys in the [FuncMap](https://go.dev/pkg/text/template/#FuncMap) are identifiers that can appear in a template function invocation. If not,Funcspanics. - The [time](https://go.dev/pkg/time/) package’s [Parse](https://go.dev/pkg/time/#Parse) function has always rejected any day of month larger than 31, such as January 32. In Go 1.6,Parse` now also rejects February 29 in non-leap years, February 30, February 31, April 31, June 31, September 31, and November 31.
Original source ↗

Update Jan 13, 2016 tracked by Updatify

go1.5.3 (released 2016-01-13)

go1.5.3 (released 2016-01-13) includes a security fix to the math/big package affecting the crypto/tls package. See the release announcement for details.

Original source ↗

Update Aug 19, 2015 tracked by Updatify

go1.5 (released 2015-08-19)

Introduction to Go 1.5

The latest Go release, version 1.5, is a significant release, including major architectural changes to the implementation. Despite that, we expect almost all Go programs to continue to compile and run as before, because the release still maintains the Go 1 promise of compatibility.

The biggest developments in the implementation are:

  • The compiler and runtime are now written entirely in Go (with a little assembler). C is no longer involved in the implementation, and so the C compiler that was once necessary for building the distribution is gone.
  • The garbage collector is now concurrent and provides dramatically lower pause times by running, when possible, in parallel with other goroutines.
  • By default, Go programs run with GOMAXPROCS set to the number of cores available; in prior releases it defaulted to 1.
  • Support for internal packages is now provided for all repositories, not just the Go core.
  • The go command now provides experimental support for “vendoring” external dependencies.
  • A new go tool trace command supports fine-grained tracing of program execution.
  • A new go doc command (distinct from godoc) is customized for command-line use.

These and a number of other changes to the implementation and tools are discussed below.

The release also contains one small language change involving map literals.

Finally, the timing of the release strays from the usual six-month interval, both to provide more time to prepare this major release and to shift the schedule thereafter to time the release dates more conveniently.

Changes to the language

Map literals

Due to an oversight, the rule that allowed the element type to be elided from slice literals was not applied to map keys. This has been corrected in Go 1.5. An example will make this clear. As of Go 1.5, this map literal,

m := map[Point]string{
    Point{29.935523, 52.891566}:   "Persepolis",
    Point{-25.352594, 131.034361}: "Uluru",
    Point{37.422455, -122.084306}: "Googleplex",
}

may be written as follows, without the Point type listed explicitly:

m := map[Point]string{
    {29.935523, 52.891566}:   "Persepolis",
    {-25.352594, 131.034361}: "Uluru",
    {37.422455, -122.084306}: "Googleplex",
}

The Implementation

No more C

The compiler and runtime are now implemented in Go and assembler, without C. The only C source left in the tree is related to testing or to cgo. There was a C compiler in the tree in 1.4 and earlier. It was used to build the runtime; a custom compiler was necessary in part to guarantee the C code would work with the stack management of goroutines. Since the runtime is in Go now, there is no need for this C compiler and it is gone. Details of the process to eliminate C are discussed elsewhere.

The conversion from C was done with the help of custom tools created for the job. Most important, the compiler was actually moved by automatic translation of the C code into Go. It is in effect the same program in a different language. It is not a new implementation of the compiler so we expect the process will not have introduced new compiler bugs. An overview of this process is available in the slides for this presentation.

Compiler and tools

Independent of but encouraged by the move to Go, the names of the tools have changed. The old names 6g, 8g and so on are gone; instead there is just one binary, accessible as go tool compile, that compiles Go source into binaries suitable for the architecture and operating system specified by $GOARCH and $GOOS. Similarly, there is now one linker ( go tool link) and one assembler ( go tool asm). The linker was translated automatically from the old C implementation, but the assembler is a new native Go implementation discussed in more detail below.

Similar to the drop of the names 6g, 8g, and so on, the output of the compiler and assembler are now given a plain .o suffix rather than .8, .6, etc.

Garbage collector

The garbage collector has been re-engineered for 1.5 as part of the development outlined in the design document. Expected latencies are much lower than with the collector in prior releases, through a combination of advanced algorithms, better scheduling of the collector, and running more of the collection in parallel with the user program. The “stop the world” phase of the collector will almost always be under 10 milliseconds and usually much less.

For systems that benefit from low latency, such as user-responsive web sites, the drop in expected latency with the new collector may be important.

Details of the new collector were presented in a talk at GopherCon 2015.

Runtime

In Go 1.5, the order in which goroutines are scheduled has been changed. The properties of the scheduler were never defined by the language, but programs that depend on the scheduling order may be broken by this change. We have seen a few (erroneous) programs affected by this change. If you have programs that implicitly depend on the scheduling order, you will need to update them.

Another potentially breaking change is that the runtime now sets the default number of threads to run simultaneously, defined by GOMAXPROCS, to the number of cores available on the CPU. In prior releases the default was 1. Programs that do not expect to run with multiple cores may break inadvertently. They can be updated by removing the restriction or by setting GOMAXPROCS explicitly. For a more detailed discussion of this change, see the design document.

Build

Now that the Go compiler and runtime are implemented in Go, a Go compiler must be available to compile the distribution from source. Thus, to build the Go core, a working Go distribution must already be in place. (Go programmers who do not work on the core are unaffected by this change.) Any Go 1.4 or later distribution (including gccgo) will serve. For details, see the design document.

Ports

Due mostly to the industry’s move away from the 32-bit x86 architecture, the set of binary downloads provided is reduced in 1.5. A distribution for the OS X operating system is provided only for the amd64 architecture, not 386. Similarly, the ports for Snow Leopard (Apple OS X 10.6) still work but are no longer released as a download or maintained since Apple no longer maintains that version of the operating system. Also, the dragonfly/386 port is no longer supported at all because DragonflyBSD itself no longer supports the 32-bit 386 architecture.

There are however several new ports available to be built from source. These include darwin/arm and darwin/arm64. The new port linux/arm64 is mostly in place, but cgo is only supported using external linking.

Also available as experiments are ppc64 and ppc64le (64-bit PowerPC, big- and little-endian). Both these ports support cgo but only with internal linking.

On FreeBSD, Go 1.5 requires FreeBSD 8-STABLE+ because of its new use of the SYSCALL instruction.

On NaCl, Go 1.5 requires SDK version pepper-41. Later pepper versions are not compatible due to the removal of the sRPC subsystem from the NaCl runtime.

On Darwin, the use of the system X.509 certificate interface can be disabled with the ios build tag.

The Solaris port now has full support for cgo and the packages net and crypto/x509, as well as a number of other fixes and improvements.

Tools

Translating

As part of the process to eliminate C from the tree, the compiler and linker were translated from C to Go. It was a genuine (machine assisted) translation, so the new programs are essentially the old programs translated rather than new ones with new bugs. We are confident the translation process has introduced few if any new bugs, and in fact uncovered a number of previously unknown bugs, now fixed.

The assembler is a new program, however; it is described below.

Renaming

The suites of programs that were the compilers ( 6g, 8g, etc.), the assemblers ( 6a, 8a, etc.), and the linkers ( 6l, 8l, etc.) have each been consolidated into a single tool that is configured by the environment variables GOOS and GOARCH. The old names are gone; the new tools are available through the go tool mechanism as go tool compile, go tool asm, and go tool link. Also, the file suffixes .6, .8, etc. for the intermediate object files are also gone; now they are just plain .o files.

For example, to build and link a program on amd64 for Darwin using the tools directly, rather than through go build, one would run:

$ export GOOS=darwin GOARCH=amd64
$ go tool compile program.go
$ go tool link program.o

Moving

Because the go/types package has now moved into the main repository (see below), the vet and cover tools have also been moved. They are no longer maintained in the external golang.org/x/tools repository, although (deprecated) source still resides there for compatibility with old releases.

Compiler

As described above, the compiler in Go 1.5 is a single Go program, translated from the old C source, that replaces 6g, 8g, and so on. Its target is configured by the environment variables GOOS and GOARCH.

The 1.5 compiler is mostly equivalent to the old, but some internal details have changed. One significant change is that evaluation of constants now uses the math/big package rather than a custom (and less well tested) implementation of high precision arithmetic. We do not expect this to affect the results.

For the amd64 architecture only, the compiler has a new option, -dynlink, that assists dynamic linking by supporting references to Go symbols defined in external shared libraries.

Assembler

Like the compiler and linker, the assembler in Go 1.5 is a single program that replaces the suite of assemblers ( 6a, 8a, etc.) and the environment variables GOARCH and GOOS configure the architecture and operating system. Unlike the other programs, the assembler is a wholly new program written in Go.

The new assembler is very nearly compatible with the previous ones, but there are a few changes that may affect some assembler source files. See the updated assembler guide for more specific information about these changes. In summary:

First, the expression evaluation used for constants is a little different. It now uses unsigned 64-bit arithmetic and the precedence of operators ( +, -, <<, etc.) comes from Go, not C. We expect these changes to affect very few programs but manual verification may be required.

Perhaps more important is that on machines where SP or PC is only an alias for a numbered register, such as R13 for the stack pointer and R15 for the hardware program counter on ARM, a reference to such a register that does not include a symbol is now illegal. For example, SP and 4(SP) are illegal but sym+4(SP) is fine. On such machines, to refer to the hardware register use its true R name.

One minor change is that some of the old assemblers permitted the notation

constant=value

to define a named constant. Since this is always possible to do with the traditional C-like #define notation, which is still supported (the assembler includes an implementation of a simplified C preprocessor), the feature was removed.

Linker

The linker in Go 1.5 is now one Go program, that replaces 6l, 8l, etc. Its operating system and instruction set are specified by the environment variables GOOS and GOARCH.

There are several other changes. The most significant is the addition of a -buildmode option that expands the style of linking; it now supports situations such as building shared libraries and allowing other languages to call into Go libraries. Some of these were outlined in a design document. For a list of the available build modes and their use, run

$ go help buildmode

Another minor change is that the linker no longer records build time stamps in the header of Windows executables. Also, although this may be fixed, Windows cgo executables are missing some DWARF information.

Finally, the -X flag, which takes two arguments, as in

-X importpath.name value

now also accepts a more common Go flag style with a single argument that is itself a name=value pair:

-X importpath.name=value

Although the old syntax still works, it is recommended that uses of this flag in scripts and the like be updated to the new form.

Go command

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

The previous release introduced the idea of a directory internal to a package being unimportable through the go command. In 1.4, it was tested with the introduction of some internal elements in the core repository. As suggested in the design document, that change is now being made available to all repositories. The rules are explained in the design document, but in summary any package in or under a directory named internal may be imported by packages rooted in the same subtree. Existing packages with directory elements named internal may be inadvertently broken by this change, which was why it was advertised in the last release.

Another change in how packages are handled is the experimental addition of support for “vendoring”. For details, see the documentation for the go command and the design document.

There have also been several minor changes. Read the documentation for full details.

  • SWIG support has been updated such that .swig and .swigcxx now require SWIG 3.0.6 or later.
  • The install subcommand now removes the binary created by the build subcommand in the source directory, if present, to avoid problems having two binaries present in the tree.
  • The std (standard library) wildcard package name now excludes commands. A new cmd wildcard covers the commands.
  • A new -asmflags build option sets flags to pass to the assembler. However, the -ccflags build option has been dropped; it was specific to the old, now deleted C compiler .
  • A new -buildmode build option sets the build mode, described above.
  • A new -pkgdir build option sets the location of installed package archives, to help isolate custom builds.
  • A new -toolexec build option allows substitution of a different command to invoke the compiler and so on. This acts as a custom replacement for go tool.
  • The test subcommand now has a -count flag to specify how many times to run each test and benchmark. The testing package does the work here, through the -test.count flag.
  • The generate subcommand has a couple of new features. The -run option specifies a regular expression to select which directives to execute; this was proposed but never implemented in 1.4. The executing pattern now has access to two new environment variables: $GOLINE returns the source line number of the directive and $DOLLAR expands to a dollar sign.
  • The get subcommand now has a -insecure flag that must be enabled if fetching from an insecure repository, one that does not encrypt the connection.

Go vet command

The go tool vet command now does more thorough validation of struct tags.

Trace command

A new tool is available for dynamic execution tracing of Go programs. The usage is analogous to how the test coverage tool works. Generation of traces is integrated into go test, and then a separate execution of the tracing tool itself analyzes the results:

$ go test -trace=trace.out path/to/package
$ go tool trace [flags] pkg.test trace.out

The flags enable the output to be displayed in a browser window. For details, run go tool trace -help. There is also a description of the tracing facility in this talk from GopherCon 2015.

Go doc command

A few releases back, the go doc command was deleted as being unnecessary. One could always run “ godoc . ” instead. The 1.5 release introduces a new go doc command with a more convenient command-line interface than godoc ’s. It is designed for command-line usage specifically, and provides a more compact and focused presentation of the documentation for a package or its elements, according to the invocation. It also provides case-insensitive matching and support for showing the documentation for unexported symbols. For details run “ go help doc ”.

Cgo

When parsing #cgo lines, the invocation ${SRCDIR} is now expanded into the path to the source directory. This allows options to be passed to the compiler and linker that involve file paths relative to the source code directory. Without the expansion the paths would be invalid when the current working directory changes.

Solaris now has full cgo support.

On Windows, cgo now uses external linking by default.

When a C struct ends with a zero-sized field, but the struct itself is not zero-sized, Go code can no longer refer to the zero-sized field. Any such references will have to be rewritten.

Performance

As always, the changes are so general and varied that precise statements about performance are difficult to make. The changes are even broader ranging than usual in this release, which includes a new garbage collector and a conversion of the runtime to Go. 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.5 than they did in Go 1.4, while as mentioned above the garbage collector’s pauses are dramatically shorter, and almost always under 10 milliseconds.

Builds in Go 1.5 will be slower by a factor of about two. The automatic translation of the compiler and linker from C to Go resulted in unidiomatic Go code that performs poorly compared to well-written Go. Analysis tools and refactoring helped to improve the code, but much remains to be done. Further profiling and optimization will continue in Go 1.6 and future releases. For more details, see these slides and associated video.

Standard library

Flag

The flag package’s PrintDefaults function, and method on FlagSet, have been modified to create nicer usage messages. The format has been changed to be more human-friendly and in the usage messages a word quoted with backquotes is taken to be the name of the flag’s operand to display in the usage message. For instance, a flag created with the invocation,

cpuFlag = flag.Int("cpu", 1, "run `N` processes in parallel")

will show the help message,

-cpu N
        run N processes in parallel (default 1)

Also, the default is now listed only when it is not the zero value for the type.

Floats in math/big

The math/big package has a new, fundamental data type, Float, which implements arbitrary-precision floating-point numbers. A Float value is represented by a boolean sign, a variable-length mantissa, and a 32-bit fixed-size signed exponent. The precision of a Float (the mantissa size in bits) can be specified explicitly or is otherwise determined by the first operation that creates the value. Once created, the size of a Float ’s mantissa may be modified with the SetPrec method. Floats support the concept of infinities, such as are created by overflow, but values that would lead to the equivalent of IEEE 754 NaNs trigger a panic. Float operations support all IEEE-754 rounding modes. When the precision is set to 24 (53) bits, operations that stay within the range of normalized float32 ( float64) values produce the same results as the corresponding IEEE-754 arithmetic on those values.

Go types

The go/types package up to now has been maintained in the golang.org/x repository; as of Go 1.5 it has been relocated to the main repository. The code at the old location is now deprecated. There is also a modest API change in the package, discussed below.

Associated with this move, the go/constant package also moved to the main repository; it was golang.org/x/tools/exact before. The go/importer package also moved to the main repository, as well as some tools described above.

Net

The DNS resolver in the net package has almost always used cgo to access the system interface. A change in Go 1.5 means that on most Unix systems DNS resolution will no longer require cgo, which simplifies execution on those platforms. Now, if the system’s networking configuration permits, the native Go resolver will suffice. The important effect of this change is that each DNS resolution occupies a goroutine rather than a thread, so a program with multiple outstanding DNS requests will consume fewer operating system resources.

The decision of how to run the resolver applies at run time, not build time. The netgo build tag that has been used to enforce the use of the Go resolver is no longer necessary, although it still works. A new netcgo build tag forces the use of the cgo resolver at build time. To force cgo resolution at run time set GODEBUG=netdns=cgo in the environment. More debug options are documented here.

This change applies to Unix systems only. Windows, Mac OS X, and Plan 9 systems behave as before.

Reflect

The reflect package has two new functions: ArrayOf and FuncOf. These functions, analogous to the extant SliceOf function, create new types at runtime to describe arrays and functions.

Hardening

Several dozen bugs were found in the standard library through randomized testing with the go-fuzz tool. Bugs were fixed in the archive/tar, archive/zip, compress/flate, encoding/gob, fmt, html/template, image/gif, image/jpeg, image/png, and text/template, packages. The fixes harden the implementation against incorrect and malicious inputs.

Minor changes to the library

  • The archive/zip package’s Writer type now has a SetOffset method to specify the location within the output stream at which to write the archive.
  • The Reader in the bufio package now has a Discard method to discard data from the input.
  • In the bytes package, the Buffer type now has a Cap method that reports the number of bytes allocated within the buffer. Similarly, in both the bytes and strings packages, the Reader type now has a Size method that reports the original length of the underlying slice or string.
  • Both the bytes and strings packages also now have a LastIndexByte function that locates the rightmost byte with that value in the argument.
  • The crypto package has a new interface, Decrypter, that abstracts the behavior of a private key used in asymmetric decryption.
  • In the crypto/cipher package, the documentation for the Stream interface has been clarified regarding the behavior when the source and destination are different lengths. If the destination is shorter than the source, the method will panic. This is not a change in the implementation, only the documentation.
  • Also in the crypto/cipher package, there is now support for nonce lengths other than 96 bytes in AES’s Galois/Counter mode (GCM), which some protocols require.
  • In the crypto/elliptic package, there is now a Name field in the CurveParams struct, and the curves implemented in the package have been given names. These names provide a safer way to select a curve, as opposed to selecting its bit size, for cryptographic systems that are curve-dependent.
  • Also in the crypto/elliptic package, the Unmarshal function now verifies that the point is actually on the curve. (If it is not, the function returns nils). This change guards against certain attacks.
  • The crypto/sha512 package now has support for the two truncated versions of the SHA-512 hash algorithm, SHA-512/224 and SHA-512/256.
  • The crypto/tls package minimum protocol version now defaults to TLS 1.0. The old default, SSLv3, is still available through Config if needed.
  • The crypto/tls package now supports Signed Certificate Timestamps (SCTs) as specified in RFC 6962. The server serves them if they are listed in the Certificate struct, and the client requests them and exposes them, if present, in its ConnectionState struct.
  • The stapled OCSP response to a crypto/tls client connection, previously only available via the OCSPResponse method, is now exposed in the ConnectionState struct.
  • The crypto/tls server implementation will now always call the GetCertificate function in the Config struct to select a certificate for the connection when none is supplied.
  • Finally, the session ticket keys in the crypto/tls package can now be changed while the server is running. This is done through the new SetSessionTicketKeys method of the Config type.
  • In the crypto/x509 package, wildcards are now accepted only in the leftmost label as defined in the specification.
  • Also in the crypto/x509 package, the handling of unknown critical extensions has been changed. They used to cause parse errors but now they are parsed and caused errors only in Verify. The new field UnhandledCriticalExtensions of Certificate records these extensions.
  • The DB type of the database/sql package now has a Stats method to retrieve database statistics.
  • The debug/dwarf package has extensive additions to better support DWARF version 4. See for example the definition of the new type Class.
  • The debug/dwarf package also now supports decoding of DWARF line tables.
  • The debug/elf package now has support for the 64-bit PowerPC architecture.
  • The encoding/base64 package now supports unpadded encodings through two new encoding variables, RawStdEncoding and RawURLEncoding.
  • The encoding/json package now returns an UnmarshalTypeError if a JSON value is not appropriate for the target variable or component to which it is being unmarshaled.
  • The encoding/json ’s Decoder type has a new method that provides a streaming interface for decoding a JSON document: Token. It also interoperates with the existing functionality of Decode, which will continue a decode operation already started with Decoder.Token.
  • The flag package has a new function, UnquoteUsage, to assist in the creation of usage messages using the new convention described above.
  • In the fmt package, a value of type Value now prints what it holds, rather than use the reflect.Value ’s Stringer method, which produces things like <int Value>.
  • The EmptyStmt type in the go/ast package now has a boolean Implicit field that records whether the semicolon was implicitly added or was present in the source.
  • For forward compatibility the go/build package reserves GOARCH values for a number of architectures that Go might support one day. This is not a promise that it will. Also, the Package struct now has a PkgTargetRoot field that stores the architecture-dependent root directory in which to install, if known.
  • The (newly migrated) go/types package allows one to control the prefix attached to package-level names using the new Qualifier function type as an argument to several functions. This is an API change for the package, but since it is new to the core, it is not breaking the Go 1 compatibility rules since code that uses the package must explicitly ask for it at its new location. To update, run go fix on your package.
  • In the image package, the Rectangle type now implements the Image interface, so a Rectangle can serve as a mask when drawing.
  • Also in the image package, to assist in the handling of some JPEG images, there is now support for 4:1:1 and 4:1:0 YCbCr subsampling and basic CMYK support, represented by the new image.CMYK struct.
  • The image/color package adds basic CMYK support, through the new CMYK struct, the CMYKModel color model, and the CMYKToRGB function, as needed by some JPEG images.
  • Also in the image/color package, the conversion of a YCbCr value to RGBA has become more precise. Previously, the low 8 bits were just an echo of the high 8 bits; now they contain more accurate information. Because of the echo property of the old code, the operation uint8(r) to extract an 8-bit red value worked, but is incorrect. In Go 1.5, that operation may yield a different value. The correct code is, and always was, to select the high 8 bits: uint8(r>>8). Incidentally, the image/draw package provides better support for such conversions; see this blog post for more information.
  • Finally, as of Go 1.5 the closest match check in Index now honors the alpha channel.
  • The image/gif package includes a couple of generalizations. A multiple-frame GIF file can now have an overall bounds different from all the contained single frames’ bounds. Also, the GIF struct now has a Disposal field that specifies the disposal method for each frame.
  • The io package adds a CopyBuffer function that is like Copy but uses a caller-provided buffer, permitting control of allocation and buffer size.
  • The log package has a new LUTC flag that causes time stamps to be printed in the UTC time zone. It also adds a SetOutput method for user-created loggers.
  • In Go 1.4, Max was not detecting all possible NaN bit patterns. This is fixed in Go 1.5, so programs that use math.Max on data including NaNs may behave differently, but now correctly according to the IEEE754 definition of NaNs.
  • The math/big package adds a new Jacobi function for integers and a new ModSqrt method for the Int type.
  • The mime package adds a new WordDecoder type to decode MIME headers containing RFC 204-encoded words. It also provides BEncoding and QEncoding as implementations of the encoding schemes of RFC 2045 and RFC 2047.
  • The mime package also adds an ExtensionsByType function that returns the MIME extensions know to be associated with a given MIME type.
  • There is a new mime/quotedprintable package that implements the quoted-printable encoding defined by RFC 2045.
  • The net package will now Dial hostnames by trying each IP address in order until one succeeds. The [Dialer](https://go.dev/pkg/net/#Dialer).DualStack mode now implements Happy Eyeballs ( RFC 6555) by giving the first address family a 300ms head start; this value can be overridden by the new Dialer.FallbackDelay.
  • A number of inconsistencies in the types returned by errors in the net package have been tidied up. Most now return an OpError value with more information than before. Also, the OpError type now includes a Source field that holds the local network address.
  • The net/http package now has support for setting trailers from a server Handler. For details, see the documentation for ResponseWriter.
  • There is a new method to cancel a net/http Request by setting the new Request.Cancel field. It is supported by http.Transport. The Cancel field’s type is compatible with the context.Context.Done return value.
  • Also in the net/http package, there is code to ignore the zero Time value in the ServeContent function. As of Go 1.5, it now also ignores a time value equal to the Unix epoch.
  • The net/http/fcgi package exports two new errors, ErrConnClosed and ErrRequestAborted, to report the corresponding error conditions.
  • The net/http/cgi package had a bug that mishandled the values of the environment variables REMOTE_ADDR and REMOTE_HOST. This has been fixed. Also, starting with Go 1.5 the package sets the REMOTE_PORT variable.
  • The net/mail package adds an AddressParser type that can parse mail addresses.
  • The net/smtp package now has a TLSConnectionState accessor to the Client type that returns the client’s TLS state.
  • The os package has a new LookupEnv function that is similar to Getenv but can distinguish between an empty environment variable and a missing one.
  • The os/signal package adds new Ignore and Reset functions.
  • The runtime, runtime/trace, and net/http/pprof packages each have new functions to support the tracing facilities described above: ReadTrace, StartTrace, StopTrace, Start, Stop, and Trace. See the respective documentation for details.
  • The runtime/pprof package by default now includes overall memory statistics in all memory profiles.
  • The strings package has a new Compare function. This is present to provide symmetry with the bytes package but is otherwise unnecessary as strings support comparison natively.
  • The WaitGroup implementation in package sync now diagnoses code that races a call to Add against a return from Wait. If it detects this condition, the implementation panics.
  • In the syscall package, the Linux SysProcAttr struct now has a GidMappingsEnableSetgroups field, made necessary by security changes in Linux 3.19. On all Unix systems, the struct also has new Foreground and Pgid fields to provide more control when exec’ing. On Darwin, there is now a Syscall9 function to support calls with too many arguments.
  • The testing/quick will now generate nil values for pointer types, making it possible to use with recursive data structures. Also, the package now supports generation of array types.
  • In the text/template and html/template packages, integer constants too large to be represented as a Go integer now trigger a parse error. Before, they were silently converted to floating point, losing precision.
  • Also in the text/template and html/template packages, a new Option method allows customization of the behavior of the template during execution. The sole implemented option allows control over how a missing key is handled when indexing a map. The default, which can now be overridden, is as before: to continue with an invalid value.
  • The time package’s Time type has a new method AppendFormat, which can be used to avoid allocation when printing a time value.
  • The unicode package and associated support throughout the system has been upgraded from version 7.0 to Unicode 8.0.
Original source ↗

Update Dec 10, 2014 tracked by Updatify

go1.4 (released 2014-12-10)

Introduction to Go 1.4

The latest Go release, version 1.4, arrives as scheduled six months after 1.3.

It contains only one tiny language change, in the form of a backwards-compatible simple variant of for - range loop, and a possibly breaking change to the compiler involving methods on pointers-to-pointers.

The release focuses primarily on implementation work, improving the garbage collector and preparing the ground for a fully concurrent collector to be rolled out in the next few releases. Stacks are now contiguous, reallocated when necessary rather than linking on new “segments”; this release therefore eliminates the notorious “hot stack split” problem. There are some new tools available including support in the go command for build-time source code generation. The release also adds support for ARM processors on Android and Native Client (NaCl) and for AMD64 on Plan 9.

As always, Go 1.4 keeps the promise of compatibility, and almost everything will continue to compile and run without change when moved to 1.4.

Changes to the language

For-range loops

Up until Go 1.3, for - range loop had two forms

for i, v := range x {
    ...
}

and

for i := range x {
    ...
}

If one was not interested in the loop values, only the iteration itself, it was still necessary to mention a variable (probably the blank identifier, as in for _ = range x), because the form

for range x {
    ...
}

was not syntactically permitted.

This situation seemed awkward, so as of Go 1.4 the variable-free form is now legal. The pattern arises rarely but the code can be cleaner when it does.

Updating: The change is strictly backwards compatible to existing Go programs, but tools that analyze Go parse trees may need to be modified to accept this new form as the Key field of RangeStmt may now be nil.

Method calls on **T

Given these declarations,

type T int
func (T) M() {}
var x **T

both gc and gccgo accepted the method call

x.M()

which is a double dereference of the pointer-to-pointer x. The Go specification allows a single dereference to be inserted automatically, but not two, so this call is erroneous according to the language definition. It has therefore been disallowed in Go 1.4, which is a breaking change, although very few programs will be affected.

Updating: Code that depends on the old, erroneous behavior will no longer compile but is easy to fix by adding an explicit dereference.

Changes to the supported operating systems and architectures

Android

Go 1.4 can build binaries for ARM processors running the Android operating system. It can also build a .so library that can be loaded by an Android application using the supporting packages in the mobile subrepository. A brief description of the plans for this experimental port are available here.

NaCl on ARM

The previous release introduced Native Client (NaCl) support for the 32-bit x86 ( GOARCH=386) and 64-bit x86 using 32-bit pointers (GOARCH=amd64p32). The 1.4 release adds NaCl support for ARM (GOARCH=arm).

Plan9 on AMD64

This release adds support for the Plan 9 operating system on AMD64 processors, provided the kernel supports the nsec system call and uses 4K pages.

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 compatibility 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 compatibility 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

Prior to Go 1.4, the runtime (garbage collector, concurrency support, interface management, maps, slices, strings, …) was mostly written in C, with some assembler support. In 1.4, much of the code has been translated to Go so that the garbage collector can scan the stacks of programs in the runtime and get accurate information about what variables are active. This change was large but should have no semantic effect on programs.

This rewrite allows the garbage collector in 1.4 to be fully precise, meaning that it is aware of the location of all active pointers in the program. This means the heap will be smaller as there will be no false positives keeping non-pointers alive. Other related changes also reduce the heap size, which is smaller by 10%-30% overall relative to the previous release.

A consequence is that stacks are no longer segmented, eliminating the “hot split” problem. When a stack limit is reached, a new, larger stack is allocated, all active frames for the goroutine are copied there, and any pointers into the stack are updated. Performance can be noticeably better in some cases and is always more predictable. Details are available in the design document.

The use of contiguous stacks means that stacks can start smaller without triggering performance issues, so the default starting size for a goroutine’s stack in 1.4 has been reduced from 8192 bytes to 2048 bytes.

As preparation for the concurrent garbage collector scheduled for the 1.5 release, writes to pointer values in the heap are now done by a function call, called a write barrier, rather than directly from the function updating the value. In this next release, this will permit the garbage collector to mediate writes to the heap while it is running. This change has no semantic effect on programs in 1.4, but was included in the release to test the compiler and the resulting performance.

The implementation of interface values has been modified. In earlier releases, the interface contained a word that was either a pointer or a one-word scalar value, depending on the type of the concrete object stored. This implementation was problematical for the garbage collector, so as of 1.4 interface values always hold a pointer. In running programs, most interface values were pointers anyway, so the effect is minimal, but programs that store integers (for example) in interfaces will see more allocations.

As of Go 1.3, the runtime crashes if it finds a memory word that should contain a valid pointer but instead contains an obviously invalid pointer (for example, the value 3). Programs that store integers in pointer values may run afoul of this check and crash. In Go 1.4, setting the GODEBUG variable invalidptr=0 disables the crash as a workaround, but we cannot guarantee that future releases will be able to avoid the crash; the correct fix is to rewrite code not to alias integers and pointers.

Assembly

The language accepted by the assemblers cmd/5a, cmd/6a and cmd/8a has had several changes, mostly to make it easier to deliver type information to the runtime.

First, the textflag.h file that defines flags for TEXT directives has been copied from the linker source directory to a standard location so it can be included with the simple directive

#include "textflag.h"

The more important changes are in how assembler source can define the necessary type information. For most programs it will suffice to move data definitions ( DATA and GLOBL directives) out of assembly into Go files and to write a Go declaration for each assembly function. The assembly document describes what to do.

Updating: Assembly files that include textflag.h from its old location will still work, but should be updated. For the type information, most assembly routines will need no change, but all should be examined. Assembly source files that define data, functions with non-empty stack frames, or functions that return pointers need particular attention. A description of the necessary (but simple) changes is in the assembly document.

More information about these changes is in the assembly document.

Status of gccgo

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

Internal packages

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:

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.

To complement this new feature, a check has been added at update time to verify that the local package’s remote repository matches that of its custom import. The go get -u command will fail to update a package if its remote repository has changed since it was first downloaded. The new -f flag overrides this check.

Further information is in the design document.

Import paths for the subrepositories

The Go project subrepositories ( code.google.com/p/go.tools and so on) are now available under custom import paths replacing code.google.com/p/go. with golang.org/x/, as in golang.org/x/tools. We will add canonical import comments to the code around June 1, 2015, at which point Go 1.4 and later will stop accepting the old code.google.com paths.

Updating: All code that imports from subrepositories should change to use the new golang.org paths. Go 1.0 and later can resolve and import the new paths, so updating will not break compatibility with older releases. Code that has not updated will stop compiling with Go 1.4 around June 1, 2015.

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 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 golang.org/x/tools subrepository.

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 amd64.go should either have explicit build tags added to the source or be renamed to something like os_windows.go or support_amd64.go.

Other changes to the go command

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

  • Unless cgo is being used to build the package, the go command now refuses to compile C source files, since the relevant C compilers ( 6c etc.) are intended to be removed from the installation in some future release. (They are used today only to build part of the runtime.) It is difficult to use them correctly in any case, so any extant uses are likely incorrect, so we have disabled them.
  • The go test subcommand has a new flag, -o, to set the name of the resulting binary, corresponding to the same flag in other subcommands. The non-functional -file flag has been removed.
  • The go test 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 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.

Changes to package source layout

In the main Go source repository, the source code for the packages was kept in the directory src/pkg, which made sense but differed from other repositories, including the Go subrepositories. In Go 1.4, the pkg level of the source tree is now gone, so for example the fmt package’s source, once kept in directory src/pkg/fmt, now lives one level higher in src/fmt.

Updating: Tools like godoc that discover source code need to know about the new location. All tools and services maintained by the Go team have been updated.

SWIG

Due to runtime changes in this release, Go 1.4 requires SWIG 3.0.3.

Miscellany

The standard repository’s top-level misc directory used to contain Go support for editors and IDEs: plugins, initialization scripts and so on. Maintaining these was becoming time-consuming and needed external help because many of the editors listed were not used by members of the core team. It also required us to make decisions about which plugin was best for a given editor, even for editors we do not use.

The Go community at large is much better suited to managing this information. In Go 1.4, therefore, this support has been removed from the repository. Instead, there is a curated, informative list of what’s available on a wiki page.

Performance

Most programs will run about the same speed or slightly faster in 1.4 than in 1.3; some will be slightly slower. There are many changes, making it hard to be precise about what to expect.

As mentioned above, much of the runtime was translated to Go from C, which led to some reduction in heap sizes. It also improved performance slightly because the Go compiler is better at optimization, due to things like inlining, than the C compiler used to build the runtime.

The garbage collector was sped up, leading to measurable improvements for garbage-heavy programs. On the other hand, the new write barriers slow things down again, typically by about the same amount but, depending on their behavior, some programs may be somewhat slower or faster.

Library changes that affect performance are documented below.

Changes to the standard library

New packages

There are no new packages in this release.

Major changes to the library

bufio.Scanner

The Scanner type in the bufio package has had a bug fixed that may require changes to custom split functions. The bug made it impossible to generate an empty token at EOF; the fix changes the end conditions seen by the split function. Previously, scanning stopped at EOF if there was no more data. As of 1.4, the split function will be called once at EOF after input is exhausted, so the split function can generate a final empty token as the documentation already promised.

Updating: Custom split functions may need to be modified to handle empty tokens at EOF as desired.

syscall

The syscall package is now frozen except for changes needed to maintain the core repository. In particular, it will no longer be extended to support new or different system calls that are not used by the core. The reasons are described at length in a separate document.

A new subrepository, golang.org/x/sys, has been created to serve as the location for new developments to support system calls on all kernels. It has a nicer structure, with three packages that each hold the implementation of system calls for one of Unix, Windows and Plan 9. These packages will be curated more generously, accepting all reasonable changes that reflect kernel interfaces in those operating systems. See the documentation and the article mentioned above for more information.

Updating: Existing programs are not affected as the syscall package is largely unchanged from the 1.3 release. Future development that requires system calls not in the syscall package should build on golang.org/x/sys instead.

Minor changes to the library

The following list summarizes a number of minor changes to the library, mostly additions. See the relevant package documentation for more information about each change.

  • The archive/zip package’s Writer now supports a Flush method.
  • The compress/flate, compress/gzip, and compress/zlib packages now support a Reset method for the decompressors, allowing them to reuse buffers and improve performance. The compress/gzip package also has a Multistream method to control support for multistream files.
  • The crypto package now has a Signer interface, implemented by the PrivateKey types in crypto/ecdsa and crypto/rsa.
  • The crypto/tls package now supports ALPN as defined in RFC 7301.
  • The crypto/tls package now supports programmatic selection of server certificates through the new CertificateForName function of the Config struct.
  • Also in the crypto/tls package, the server now supports TLS_FALLBACK_SCSV to help clients detect fallback attacks. (The Go client does not support fallback at all, so it is not vulnerable to those attacks.)
  • The database/sql package can now list all registered Drivers.
  • The debug/dwarf package now supports UnspecifiedType s.
  • In the encoding/asn1 package, optional elements with a default value will now only be omitted if they have that value.
  • The encoding/csv package no longer quotes empty strings but does quote the end-of-data marker \. (backslash dot). This is permitted by the definition of CSV and allows it to work better with Postgres.
  • The encoding/gob package has been rewritten to eliminate the use of unsafe operations, allowing it to be used in environments that do not permit use of the unsafe package. For typical uses it will be 10-30% slower, but the delta is dependent on the type of the data and in some cases, especially involving arrays, it can be faster. There is no functional change.
  • The encoding/xml package’s Decoder can now report its input offset.
  • In the fmt package, formatting of pointers to maps has changed to be consistent with that of pointers to structs, arrays, and so on. For instance, &map[string]int{"one": 1} now prints by default as &map[one: 1] rather than as a hexadecimal pointer value.
  • The image package’s Image implementations like RGBA and Gray have specialized RGBAAt and GrayAt methods alongside the general At method.
  • The image/png package now has an Encoder type to control the compression level used for encoding.
  • The math package now has a Nextafter32 function.
  • The net/http package’s Request type has a new BasicAuth method that returns the username and password from authenticated requests using the HTTP Basic Authentication Scheme.
  • The net/http package’s Transport type has a new DialTLS hook that allows customizing the behavior of outbound TLS connections.
  • The net/http/httputil package’s ReverseProxy type has a new field, ErrorLog, that provides user control of logging.
  • The os package now implements symbolic links on the Windows operating system through the Symlink function. Other operating systems already have this functionality. There is also a new Unsetenv function.
  • The reflect package’s Type interface has a new method, Comparable, that reports whether the type implements general comparisons.
  • Also in the reflect package, the Value interface is now three instead of four words because of changes to the implementation of interfaces in the runtime. This saves memory but has no semantic effect.
  • The runtime package now implements monotonic clocks on Windows, as it already did for the other systems.
  • The runtime package’s Mallocs counter now counts very small allocations that were missed in Go 1.3. This may break tests using ReadMemStats or AllocsPerRun due to the more accurate answer.
  • In the runtime package, an array PauseEnd has been added to the MemStats and GCStats structs. This array is a circular buffer of times when garbage collection pauses ended. The corresponding pause durations are already recorded in PauseNs
  • The runtime/race package now supports FreeBSD, which means the go command’s -race flag now works on FreeBSD.
  • The sync/atomic package has a new type, Value. Value provides an efficient mechanism for atomic loads and stores of values of arbitrary type.
  • In the syscall package’s implementation on Linux, the Setuid and Setgid have been disabled because those system calls operate on the calling thread, not the whole process, which is different from other platforms and not the expected result.
  • The testing package has a new facility to provide more control over running a set of tests. If the test code contains a function func TestMain(m *[`testing.M`](https://go.dev/pkg/testing/#M)) that function will be called instead of running the tests directly. The M struct contains methods to access and run the tests.
  • Also in the testing package, a new Coverage function reports the current test coverage fraction, enabling individual tests to report how much they are contributing to the overall coverage.
  • The text/scanner package’s Scanner type has a new function, IsIdentRune, allowing one to control the definition of an identifier when scanning.
  • The text/template package’s boolean functions eq, lt, and so on have been generalized to allow comparison of signed and unsigned integers, simplifying their use in practice. (Previously one could only compare values of the same signedness.) All negative values compare less than all unsigned values.
  • The time package now uses the standard symbol for the micro prefix, the micro symbol (U+00B5 ‘µ’), to print microsecond durations. ParseDuration still accepts us but the package no longer prints microseconds as us.
    Updating: Code that depends on the output format of durations but does not use ParseDuration will need to be updated.
Original source ↗

Update Sep 30, 2014 tracked by Updatify

go1.3.3 (released 2014-09-30)

go1.3.3 (released 2014-09-30) includes further bug fixes to cgo, the runtime package, and the nacl port. See the change history for details.

Original source ↗

Update Sep 25, 2014 tracked by Updatify

go1.3.2 (released 2014-09-25)

go1.3.2 (released 2014-09-25) includes security fixes to the crypto/tls package and bug fixes to cgo. See the change history for details.

Original source ↗

Update Jun 18, 2014 tracked by Updatify

go1.3 (released 2014-06-18)

Introduction to Go 1.3

The latest Go release, version 1.3, arrives six months after 1.2, and contains no language changes. It focuses primarily on implementation work, providing precise garbage collection, a major refactoring of the compiler toolchain that results in faster builds, especially for large projects, significant performance improvements across the board, and support for DragonFly BSD, Solaris, Plan 9 and Google’s Native Client architecture (NaCl). It also has an important refinement to the memory model regarding synchronization. As always, Go 1.3 keeps the promise of compatibility, and almost everything will continue to compile and run without change when moved to 1.3.

Changes to the supported operating systems and architectures

Removal of support for Windows 2000

Microsoft stopped supporting Windows 2000 in 2010. Since it has implementation difficulties regarding exception handling (signals in Unix terminology), as of Go 1.3 it is not supported by Go either.

Support for DragonFly BSD

Go 1.3 now includes experimental support for DragonFly BSD on the amd64 (64-bit x86) and 386 (32-bit x86) architectures. It uses DragonFly BSD 3.6 or above.

Support for FreeBSD

It was not announced at the time, but since the release of Go 1.2, support for Go on FreeBSD requires FreeBSD 8 or above.

As of Go 1.3, support for Go on FreeBSD requires that the kernel be compiled with the COMPAT_FREEBSD32 flag configured.

In concert with the switch to EABI syscalls for ARM platforms, Go 1.3 will run only on FreeBSD 10. The x86 platforms, 386 and amd64, are unaffected.

Support for Native Client

Support for the Native Client virtual machine architecture has returned to Go with the 1.3 release. It runs on the 32-bit Intel architectures ( GOARCH=386) and also on 64-bit Intel, but using 32-bit pointers ( GOARCH=amd64p32). There is not yet support for Native Client on ARM. Note that this is Native Client (NaCl), not Portable Native Client (PNaCl). Details about Native Client are here; how to set up the Go version is described here.

Support for NetBSD

As of Go 1.3, support for Go on NetBSD requires NetBSD 6.0 or above.

Support for OpenBSD

As of Go 1.3, support for Go on OpenBSD requires OpenBSD 5.5 or above.

Support for Plan 9

Go 1.3 now includes experimental support for Plan 9 on the 386 (32-bit x86) architecture. It requires the Tsemacquire syscall, which has been in Plan 9 since June, 2012.

Support for Solaris

Go 1.3 now includes experimental support for Solaris on the amd64 (64-bit x86) architecture. It requires illumos, Solaris 11 or above.

Changes to the memory model

The Go 1.3 memory model adds a new rule concerning sending and receiving on buffered channels, to make explicit that a buffered channel can be used as a simple semaphore, using a send into the channel to acquire and a receive from the channel to release. This is not a language change, just a clarification about an expected property of communication.

Changes to the implementations and tools

Stack

Go 1.3 has changed the implementation of goroutine stacks away from the old, “segmented” model to a contiguous model. When a goroutine needs more stack than is available, its stack is transferred to a larger single block of memory. The overhead of this transfer operation amortizes well and eliminates the old “hot spot” problem when a calculation repeatedly steps across a segment boundary. Details including performance numbers are in this design document.

Changes to the garbage collector

For a while now, the garbage collector has been precise when examining values in the heap; the Go 1.3 release adds equivalent precision to values on the stack. This means that a non-pointer Go value such as an integer will never be mistaken for a pointer and prevent unused memory from being reclaimed.

Starting with Go 1.3, the runtime assumes that values with pointer type contain pointers and other values do not. This assumption is fundamental to the precise behavior of both stack expansion and garbage collection. Programs that use package unsafe to store integers in pointer-typed values are illegal and will crash if the runtime detects the behavior. Programs that use package unsafe to store pointers in integer-typed values are also illegal but more difficult to diagnose during execution. Because the pointers are hidden from the runtime, a stack expansion or garbage collection may reclaim the memory they point at, creating dangling pointers.

Updating: Code that uses unsafe.Pointer to convert an integer-typed value held in memory into a pointer is illegal and must be rewritten. Such code can be identified by go vet.

Map iteration

Iterations over small maps no longer happen in a consistent order. Go 1 defines that “ The iteration order over maps is not specified and is not guaranteed to be the same from one iteration to the next. ” To keep code from depending on map iteration order, Go 1.0 started each map iteration at a random index in the map. A new map implementation introduced in Go 1.1 neglected to randomize iteration for maps with eight or fewer entries, although the iteration order can still vary from system to system. This has allowed people to write Go 1.1 and Go 1.2 programs that depend on small map iteration order and therefore only work reliably on certain systems. Go 1.3 reintroduces random iteration for small maps in order to flush out these bugs.

Updating: If code assumes a fixed iteration order for small maps, it will break and must be rewritten not to make that assumption. Because only small maps are affected, the problem arises most often in tests.

The linker

As part of the general overhaul to the Go linker, the compilers and linkers have been refactored. The linker is still a C program, but now the instruction selection phase that was part of the linker has been moved to the compiler through the creation of a new library called liblink. By doing instruction selection only once, when the package is first compiled, this can speed up compilation of large projects significantly.

Updating: Although this is a major internal change, it should have no effect on programs.

Status of gccgo

GCC release 4.9 will contain the Go 1.2 (not 1.3) version of gccgo. The release schedules for the GCC and Go projects do not coincide, which means that 1.3 will be available in the development branch but that the next GCC release, 4.10, will likely have the Go 1.4 version of gccgo.

Changes to the go command

The cmd/go command has several new features. The go run and go test subcommands support a new -exec option to specify an alternate way to run the resulting binary. Its immediate purpose is to support NaCl.

The test coverage support of the go test subcommand now automatically sets the coverage mode to -atomic when the race detector is enabled, to eliminate false reports about unsafe access to coverage counters.

The go test subcommand now always builds the package, even if it has no test files. Previously, it would do nothing if no test files were present.

The go build subcommand supports a new -i option to install dependencies of the specified target, but not the target itself.

Cross compiling with cgo enabled is now supported. The CC_FOR_TARGET and CXX_FOR_TARGET environment variables are used when running all.bash to specify the cross compilers for C and C++ code, respectively.

Finally, the go command now supports packages that import Objective-C files (suffixed .m) through cgo.

Changes to cgo

The cmd/cgo command, which processes import "C" declarations in Go packages, has corrected a serious bug that may cause some packages to stop compiling. Previously, all pointers to incomplete struct types translated to the Go type *[0]byte, with the effect that the Go compiler could not diagnose passing one kind of struct pointer to a function expecting another. Go 1.3 corrects this mistake by translating each different incomplete struct to a different named type.

Given the C declaration typedef struct S T for an incomplete struct S, some Go code used this bug to refer to the types C.struct_S and C.T interchangeably. Cgo now explicitly allows this use, even for completed struct types. However, some Go code also used this bug to pass (for example) a *C.FILE from one package to another. This is not legal and no longer works: in general Go packages should avoid exposing C types and names in their APIs.

Updating: Code confusing pointers to incomplete types or passing them across package boundaries will no longer compile and must be rewritten. If the conversion is correct and must be preserved, use an explicit conversion via unsafe.Pointer.

SWIG 3.0 required for programs that use SWIG

For Go programs that use SWIG, SWIG version 3.0 is now required. The cmd/go command will now link the SWIG generated object files directly into the binary, rather than building and linking with a shared library.

Command-line flag parsing

In the gc toolchain, the assemblers now use the same command-line flag parsing rules as the Go flag package, a departure from the traditional Unix flag parsing. This may affect scripts that invoke the tool directly. For example, go tool 6a -SDfoo must now be written go tool 6a -S -D foo. (The same change was made to the compilers and linkers in Go 1.1.)

Changes to godoc

When invoked with the -analysis flag, godoc now performs sophisticated static analysis of the code it indexes. The results of analysis are presented in both the source view and the package documentation view, and include the call graph of each package and the relationships between definitions and references, types and their methods, interfaces and their implementations, send and receive operations on channels, functions and their callers, and call sites and their callees.

Miscellany

The program misc/benchcmp that compares performance across benchmarking runs has been rewritten. Once a shell and awk script in the main repository, it is now a Go program in the go.tools repo. Documentation is here.

For the few of us that build Go distributions, the tool misc/dist has been moved and renamed; it now lives in misc/makerelease, still in the main repository.

Performance

The performance of Go binaries for this release has improved in many cases due to changes in the runtime and garbage collection, plus some changes to libraries. Significant instances include:

  • The runtime handles defers more efficiently, reducing the memory footprint by about two kilobytes per goroutine that calls defer.
  • The garbage collector has been sped up, using a concurrent sweep algorithm, better parallelization, and larger pages. The cumulative effect can be a 50-70% reduction in collector pause time.
  • The race detector (see this guide) is now about 40% faster.
  • The regular expression package regexp is now significantly faster for certain simple expressions due to the implementation of a second, one-pass execution engine. The choice of which engine to use is automatic; the details are hidden from the user.

Also, the runtime now includes in stack dumps how long a goroutine has been blocked, which can be useful information when debugging deadlocks or performance issues.

Changes to the standard library

New packages

A new package debug/plan9obj was added to the standard library. It implements access to Plan 9 a.out object files.

Major changes to the library

A previous bug in crypto/tls made it possible to skip verification in TLS inadvertently. In Go 1.3, the bug is fixed: one must specify either ServerName or InsecureSkipVerify, and if ServerName is specified it is enforced. This may break existing code that incorrectly depended on insecure behavior.

There is an important new type added to the standard library: sync.Pool. It provides an efficient mechanism for implementing certain types of caches whose memory can be reclaimed automatically by the system.

The testing package’s benchmarking helper, B, now has a RunParallel method to make it easier to run benchmarks that exercise multiple CPUs.

Updating: The crypto/tls fix may break existing code, but such code was erroneous and should be updated.

Minor changes to the library

The following list summarizes a number of minor changes to the library, mostly additions. See the relevant package documentation for more information about each change.

  • In the crypto/tls package, a new DialWithDialer function lets one establish a TLS connection using an existing dialer, making it easier to control dial options such as timeouts. The package also now reports the TLS version used by the connection in the ConnectionState struct.
  • The CreateCertificate function of the crypto/tls package now supports parsing (and elsewhere, serialization) of PKCS #10 certificate signature requests.
  • The formatted print functions of the fmt package now define %F as a synonym for %f when printing floating-point values.
  • The math/big package’s Int and Rat types now implement encoding.TextMarshaler and encoding.TextUnmarshaler.
  • The complex power function, Pow, now specifies the behavior when the first argument is zero. It was undefined before. The details are in the documentation for the function.
  • The net/http package now exposes the properties of a TLS connection used to make a client request in the new Response.TLS field.
  • The net/http package now allows setting an optional server error logger with Server.ErrorLog. The default is still that all errors go to stderr.
  • The net/http package now supports disabling HTTP keep-alive connections on the server with Server.SetKeepAlivesEnabled. The default continues to be that the server does keep-alive (reuses connections for multiple requests) by default. Only resource-constrained servers or those in the process of graceful shutdown will want to disable them.
  • The net/http package adds an optional Transport.TLSHandshakeTimeout setting to cap the amount of time HTTP client requests will wait for TLS handshakes to complete. It’s now also set by default on DefaultTransport.
  • The net/http package’s DefaultTransport, used by the HTTP client code, now enables TCP keep-alives by default. Other Transport values with a nil Dial field continue to function the same as before: no TCP keep-alives are used.
  • The net/http package now enables TCP keep-alives for incoming server requests when ListenAndServe or ListenAndServeTLS are used. When a server is started otherwise, TCP keep-alives are not enabled.
  • The net/http package now provides an optional Server.ConnState callback to hook various phases of a server connection’s lifecycle (see ConnState). This can be used to implement rate limiting or graceful shutdown.
  • The net/http package’s HTTP client now has an optional Client.Timeout field to specify an end-to-end timeout on requests made using the client.
  • The net/http package’s Request.ParseMultipartForm method will now return an error if the body’s Content-Type is not multipart/form-data. Prior to Go 1.3 it would silently fail and return nil. Code that relies on the previous behavior should be updated.
  • In the net package, the Dialer struct now has a KeepAlive option to specify a keep-alive period for the connection.
  • The net/http package’s Transport now closes Request.Body consistently, even on error.
  • The os/exec package now implements what the documentation has always said with regard to relative paths for the binary. In particular, it only calls LookPath when the binary’s file name contains no path separators.
  • The SetMapIndex function in the reflect package no longer panics when deleting from a nil map.
  • If the main goroutine calls runtime.Goexit and all other goroutines finish execution, the program now always crashes, reporting a detected deadlock. Earlier versions of Go handled this situation inconsistently: most instances were reported as deadlocks, but some trivial cases exited cleanly instead.
  • The runtime/debug package now has a new function debug.WriteHeapDump that writes out a description of the heap.
  • The CanBackquote function in the strconv package now considers the DEL character, U+007F, to be non-printing.
  • The syscall package now provides SendmsgN as an alternate version of Sendmsg that returns the number of bytes written.
  • On Windows, the syscall package now supports the cdecl calling convention through the addition of a new function NewCallbackCDecl alongside the existing function NewCallback.
  • The testing package now diagnoses tests that call panic(nil), which are almost always erroneous. Also, tests now write profiles (if invoked with profiling flags) even on failure.
  • The unicode package and associated support throughout the system has been upgraded from Unicode 6.2.0 to Unicode 6.3.0.
Original source ↗

Update May 5, 2014 tracked by Updatify

go1.2.2 (released 2014-05-05)

go1.2.2 (released 2014-05-05) includes a security fix that affects the tour binary included in the binary distributions (thanks to Guillaume T).

Original source ↗

Update Mar 2, 2014 tracked by Updatify

go1.2.1 (released 2014-03-02)

go1.2.1 (released 2014-03-02) includes bug fixes to the runtime, net, and database/sql packages. See the change history for details.

Original source ↗

Update Dec 1, 2013 tracked by Updatify

go1.2 (released 2013-12-01)

Introduction to Go 1.2

Since the release of Go version 1.1 in April, 2013, the release schedule has been shortened to make the release process more efficient. This release, Go version 1.2 or Go 1.2 for short, arrives roughly six months after 1.1, while 1.1 took over a year to appear after 1.0. Because of the shorter time scale, 1.2 is a smaller delta than the step from 1.0 to 1.1, but it still has some significant developments, including a better scheduler and one new language feature. Of course, Go 1.2 keeps the promise of compatibility. The overwhelming majority of programs built with Go 1.1 (or 1.0 for that matter) will run without any changes whatsoever when moved to 1.2, although the introduction of one restriction to a corner of the language may expose already-incorrect code (see the discussion of the use of nil).

Changes to the language

In the interest of firming up the specification, one corner case has been clarified, with consequences for programs. There is also one new language feature.

Use of nil

The language now specifies that, for safety reasons, certain uses of nil pointers are guaranteed to trigger a run-time panic. For instance, in Go 1.0, given code like

type T struct {
    X [1<<24]byte
    Field int32
}

func main() {
    var x *T
    ...
}

the nil pointer x could be used to access memory incorrectly: the expression x.Field could access memory at address 1<<24. To prevent such unsafe behavior, in Go 1.2 the compilers now guarantee that any indirection through a nil pointer, such as illustrated here but also in nil pointers to arrays, nil interface values, nil slices, and so on, will either panic or return a correct, safe non-nil value. In short, any expression that explicitly or implicitly requires evaluation of a nil address is an error. The implementation may inject extra tests into the compiled program to enforce this behavior.

Further details are in the design document.

Updating: Most code that depended on the old behavior is erroneous and will fail when run. Such programs will need to be updated by hand.

Three-index slices

Go 1.2 adds the ability to specify the capacity as well as the length when using a slicing operation on an existing array or slice. A slicing operation creates a new slice by describing a contiguous section of an already-created array or slice:

var array [10]int
slice := array[2:4]

The capacity of the slice is the maximum number of elements that the slice may hold, even after reslicing; it reflects the size of the underlying array. In this example, the capacity of the slice variable is 8.

Go 1.2 adds new syntax to allow a slicing operation to specify the capacity as well as the length. A second colon introduces the capacity value, which must be less than or equal to the capacity of the source slice or array, adjusted for the origin. For instance,

slice = array[2:4:7]

sets the slice to have the same length as in the earlier example but its capacity is now only 5 elements (7-2). It is impossible to use this new slice value to access the last three elements of the original array.

In this three-index notation, a missing first index ( [:i:j]) defaults to zero but the other two indices must always be specified explicitly. It is possible that future releases of Go may introduce default values for these indices.

Further details are in the design document.

Updating: This is a backwards-compatible change that affects no existing programs.

Changes to the implementations and tools

Pre-emption in the scheduler

In prior releases, a goroutine that was looping forever could starve out other goroutines on the same thread, a serious problem when GOMAXPROCS provided only one user thread. In Go 1.2, this is partially addressed: The scheduler is invoked occasionally upon entry to a function. This means that any loop that includes a (non-inlined) function call can be pre-empted, allowing other goroutines to run on the same thread.

Limit on the number of threads

Go 1.2 introduces a configurable limit (default 10,000) to the total number of threads a single program may have in its address space, to avoid resource starvation issues in some environments. Note that goroutines are multiplexed onto threads so this limit does not directly limit the number of goroutines, only the number that may be simultaneously blocked in a system call. In practice, the limit is hard to reach.

The new SetMaxThreads function in the runtime/debug package controls the thread count limit.

Updating: Few functions will be affected by the limit, but if a program dies because it hits the limit, it could be modified to call SetMaxThreads to set a higher count. Even better would be to refactor the program to need fewer threads, reducing consumption of kernel resources.

Stack size

In Go 1.2, the minimum size of the stack when a goroutine is created has been lifted from 4KB to 8KB. Many programs were suffering performance problems with the old size, which had a tendency to introduce expensive stack-segment switching in performance-critical sections. The new number was determined by empirical testing.

At the other end, the new function SetMaxStack in the runtime/debug package controls the maximum size of a single goroutine’s stack. The default is 1GB on 64-bit systems and 250MB on 32-bit systems. Before Go 1.2, it was too easy for a runaway recursion to consume all the memory on a machine.

Updating: The increased minimum stack size may cause programs with many goroutines to use more memory. There is no workaround, but plans for future releases include new stack management technology that should address the problem better.

Cgo and C++

The cgo command will now invoke the C++ compiler to build any pieces of the linked-to library that are written in C++; the documentation has more detail.

Godoc and vet moved to the go.tools subrepository

Both binaries are still included with the distribution, but the source code for the godoc and vet commands has moved to the go.tools subrepository.

Also, the core of the godoc program has been split into a library, while the command itself is in a separate directory. The move allows the code to be updated easily and the separation into a library and command makes it easier to construct custom binaries for local sites and different deployment methods.

Updating: Since godoc and vet are not part of the library, no client Go code depends on their source and no updating is required.

The binary distributions available from golang.org include these binaries, so users of these distributions are unaffected.

When building from source, users must use “go get” to install godoc and vet. (The binaries will continue to be installed in their usual locations, not $GOPATH/bin.)

$ go get code.google.com/p/go.tools/cmd/godoc
$ go get code.google.com/p/go.tools/cmd/vet

Status of gccgo

We expect the future GCC 4.9 release to include gccgo with full support for Go 1.2. In the current (4.8.2) release of GCC, gccgo implements Go 1.1.2.

Changes to the gc compiler and linker

Go 1.2 has several semantic changes to the workings of the gc compiler suite. Most users will be unaffected by them.

The cgo command now works when C++ is included in the library being linked against. See the cgo documentation for details.

The gc compiler displayed a vestigial detail of its origins when a program had no package clause: it assumed the file was in package main. The past has been erased, and a missing package clause is now an error.

On the ARM, the toolchain supports “external linking”, which is a step towards being able to build shared libraries with the gc toolchain and to provide dynamic linking support for environments in which that is necessary.

In the runtime for the ARM, with 5a, it used to be possible to refer to the runtime-internal m (machine) and g (goroutine) variables using R9 and R10 directly. It is now necessary to refer to them by their proper names.

Also on the ARM, the 5l linker (sic) now defines the MOVBS and MOVHS instructions as synonyms of MOVB and MOVH, to make clearer the separation between signed and unsigned sub-word moves; the unsigned versions already existed with a U suffix.

Test coverage

One major new feature of go test is that it can now compute and, with help from a new, separately installed “go tool cover” program, display test coverage results.

The cover tool is part of the go.tools subrepository. It can be installed by running

$ go get code.google.com/p/go.tools/cmd/cover

The cover tool does two things. First, when “go test” is given the -cover flag, it is run automatically to rewrite the source for the package and insert instrumentation statements. The test is then compiled and run as usual, and basic coverage statistics are reported:

$ go test -cover fmt
ok      fmt 0.060s  coverage: 91.4% of statements
$

Second, for more detailed reports, different flags to “go test” can create a coverage profile file, which the cover program, invoked with “go tool cover”, can then analyze.

Details on how to generate and analyze coverage statistics can be found by running the commands

$ go help testflag
$ go tool cover -help

The go doc command is deleted

The “go doc” command is deleted. Note that the godoc tool itself is not deleted, just the wrapping of it by the go command. All it did was show the documents for a package by package path, which godoc itself already does with more flexibility. It has therefore been deleted to reduce the number of documentation tools and, as part of the restructuring of godoc, encourage better options in future.

Updating: For those who still need the precise functionality of running

$ go doc

in a directory, the behavior is identical to running

$ godoc .

Changes to the go command

The go get command now has a -t flag that causes it to download the dependencies of the tests run by the package, not just those of the package itself. By default, as before, dependencies of the tests are not downloaded.

Performance

There are a number of significant performance improvements in the standard library; here are a few of them.

  • The compress/bzip2 decompresses about 30% faster.
  • The crypto/des package is about five times faster.
  • The encoding/json package encodes about 30% faster.
  • Networking performance on Windows and BSD systems is about 30% faster through the use of an integrated network poller in the runtime, similar to what was done for Linux and OS X in Go 1.1.

Changes to the standard library

The archive/tar and archive/zip packages

The archive/tar and archive/zip packages have had a change to their semantics that may break existing programs. The issue is that they both provided an implementation of the os.FileInfo interface that was not compliant with the specification for that interface. In particular, their Name method returned the full path name of the entry, but the interface specification requires that the method return only the base name (final path element).

Updating: Since this behavior was newly implemented and a bit obscure, it is possible that no code depends on the broken behavior. If there are programs that do depend on it, they will need to be identified and fixed manually.

The new encoding package

There is a new package, encoding, that defines a set of standard encoding interfaces that may be used to build custom marshalers and unmarshalers for packages such as encoding/xml, encoding/json, and encoding/binary. These new interfaces have been used to tidy up some implementations in the standard library.

The new interfaces are called BinaryMarshaler, BinaryUnmarshaler, TextMarshaler, and TextUnmarshaler. Full details are in the documentation for the package and a separate design document.

The fmt package

The fmt package’s formatted print routines such as Printf now allow the data items to be printed to be accessed in arbitrary order by using an indexing operation in the formatting specifications. Wherever an argument is to be fetched from the argument list for formatting, either as the value to be formatted or as a width or specification integer, a new optional indexing notation [ n ] fetches argument n instead. The value of n is 1-indexed. After such an indexing operating, the next argument to be fetched by normal processing will be n +1.

For example, the normal Printf call

fmt.Sprintf("%c %c %c\n", 'a', 'b', 'c')

would create the string "a b c", but with indexing operations like this,

fmt.Sprintf("%[3]c %[1]c %c\n", 'a', 'b', 'c')

the result is “ "c a b". The [3] index accesses the third formatting argument, which is 'c', [1] accesses the first, 'a', and then the next fetch accesses the argument following that one, 'b'.

The motivation for this feature is programmable format statements to access the arguments in different order for localization, but it has other uses:

log.Printf("trace: value %v of type %[1]T\n", expensiveFunction(a.b[c]))

Updating: The change to the syntax of format specifications is strictly backwards compatible, so it affects no working programs.

The text/template and html/template packages

The text/template package has a couple of changes in Go 1.2, both of which are also mirrored in the html/template package.

First, there are new default functions for comparing basic types. The functions are listed in this table, which shows their names and the associated familiar comparison operator.

Name Operator
eq ==
ne !=
lt <
le <=
gt >
ge >=

These functions behave slightly differently from the corresponding Go operators. First, they operate only on basic types ( bool, int, float64, string, etc.). (Go allows comparison of arrays and structs as well, under some circumstances.) Second, values can be compared as long as they are the same sort of value: any signed integer value can be compared to any other signed integer value for example. (Go does not permit comparing an int8 and an int16). Finally, the eq function (only) allows comparison of the first argument with one or more following arguments. The template in this example,

{{if eq .A 1 2 3}} equal {{else}} not equal {{end}}

reports “equal” if .A is equal to any of 1, 2, or 3.

The second change is that a small addition to the grammar makes “if else if” chains easier to write. Instead of writing,

{{if eq .A 1}} X {{else}} {{if eq .A 2}} Y {{end}} {{end}}

one can fold the second “if” into the “else” and have only one “end”, like this:

{{if eq .A 1}} X {{else if eq .A 2}} Y {{end}}

The two forms are identical in effect; the difference is just in the syntax.

Updating: Neither the “else if” change nor the comparison functions affect existing programs. Those that already define functions called eq and so on through a function map are unaffected because the associated function map will override the new default function definitions.

New packages

There are two new packages.

Minor changes to the library

The following list summarizes a number of minor changes to the library, mostly additions. See the relevant package documentation for more information about each change.

  • The archive/zip package adds the DataOffset accessor to return the offset of a file’s (possibly compressed) data within the archive.
  • The bufio package adds Reset methods to Reader and Writer. These methods allow the Readers and Writers to be re-used on new input and output readers and writers, saving allocation overhead.
  • The compress/bzip2 can now decompress concatenated archives.
  • The compress/flate package adds a Reset method on the Writer, to make it possible to reduce allocation when, for instance, constructing an archive to hold multiple compressed files.
  • The compress/gzip package’s Writer type adds a Reset so it may be reused.
  • The compress/zlib package’s Writer type adds a Reset so it may be reused.
  • The container/heap package adds a Fix method to provide a more efficient way to update an item’s position in the heap.
  • The container/list package adds the MoveBefore and MoveAfter methods, which implement the obvious rearrangement.
  • The crypto/cipher package adds the new GCM mode (Galois Counter Mode), which is almost always used with AES encryption.
  • The crypto/md5 package adds a new Sum function to simplify hashing without sacrificing performance.
  • Similarly, the crypto/sha1 package adds a new Sum function.
  • Also, the crypto/sha256 package adds Sum256 and Sum224 functions.
  • Finally, the crypto/sha512 package adds Sum512 and Sum384 functions.
  • The crypto/x509 package adds support for reading and writing arbitrary extensions.
  • The crypto/tls package adds support for TLS 1.1, 1.2 and AES-GCM.
  • The database/sql package adds a SetMaxOpenConns method on DB to limit the number of open connections to the database.
  • The encoding/csv package now always allows trailing commas on fields.
  • The encoding/gob package now treats channel and function fields of structures as if they were unexported, even if they are not. That is, it ignores them completely. Previously they would trigger an error, which could cause unexpected compatibility problems if an embedded structure added such a field. The package also now supports the generic BinaryMarshaler and BinaryUnmarshaler interfaces of the encoding package described above.
  • The encoding/json package now will always escape ampersands as “\u0026” when printing strings. It will now accept but correct invalid UTF-8 in Marshal (such input was previously rejected). Finally, it now supports the generic encoding interfaces of the encoding package described above.
  • The encoding/xml package now allows attributes stored in pointers to be marshaled. It also supports the generic encoding interfaces of the encoding package described above through the new Marshaler, Unmarshaler, and related MarshalerAttr and UnmarshalerAttr interfaces. The package also adds a Flush method to the Encoder type for use by custom encoders. See the documentation for EncodeToken to see how to use it.
  • The flag package now has a Getter interface to allow the value of a flag to be retrieved. Due to the Go 1 compatibility guidelines, this method cannot be added to the existing Value interface, but all the existing standard flag types implement it. The package also now exports the CommandLine flag set, which holds the flags from the command line.
  • The go/ast package’s SliceExpr struct has a new boolean field, Slice3, which is set to true when representing a slice expression with three indices (two colons). The default is false, representing the usual two-index form.
  • The go/build package adds the AllTags field to the Package type, to make it easier to process build tags.
  • The image/draw package now exports an interface, Drawer, that wraps the standard Draw method. The Porter-Duff operators now implement this interface, in effect binding an operation to the draw operator rather than providing it explicitly. Given a paletted image as its destination, the new FloydSteinberg implementation of the Drawer interface will use the Floyd-Steinberg error diffusion algorithm to draw the image. To create palettes suitable for such processing, the new Quantizer interface represents implementations of quantization algorithms that choose a palette given a full-color image. There are no implementations of this interface in the library.
  • The image/gif package can now create GIF files using the new Encode and EncodeAll functions. Their options argument allows specification of an image Quantizer to use; if it is nil, the generated GIF will use the Plan9 color map (palette) defined in the new image/color/palette package. The options also specify a Drawer to use to create the output image; if it is nil, Floyd-Steinberg error diffusion is used.
  • The Copy method of the io package now prioritizes its arguments differently. If one argument implements WriterTo and the other implements ReaderFrom, Copy will now invoke WriterTo to do the work, so that less intermediate buffering is required in general.
  • The net package requires cgo by default because the host operating system must in general mediate network call setup. On some systems, though, it is possible to use the network without cgo, and useful to do so, for instance to avoid dynamic linking. The new build tag netgo (off by default) allows the construction of a net package in pure Go on those systems where it is possible.
  • The net package adds a new field DualStack to the Dialer struct for TCP connection setup using a dual IP stack as described in RFC 6555.
  • The net/http package will no longer transmit cookies that are incorrect according to RFC 6265. It just logs an error and sends nothing. Also, the net/http package’s ReadResponse function now permits the *Request parameter to be nil, whereupon it assumes a GET request. Finally, an HTTP server will now serve HEAD requests transparently, without the need for special casing in handler code. While serving a HEAD request, writes to a Handler ’s ResponseWriter are absorbed by the Server and the client receives an empty body as required by the HTTP specification.
  • The os/exec package’s Cmd.StdinPipe method returns an io.WriteCloser, but has changed its concrete implementation from *os.File to an unexported type that embeds *os.File, and it is now safe to close the returned value. Before Go 1.2, there was an unavoidable race that this change fixes. Code that needs access to the methods of *os.File can use an interface type assertion, such as wc.(interface{ Sync() error }).
  • The runtime package relaxes the constraints on finalizer functions in SetFinalizer: the actual argument can now be any type that is assignable to the formal type of the function, as is the case for any normal function call in Go.
  • The sort package has a new Stable function that implements stable sorting. It is less efficient than the normal sort algorithm, however.
  • The strings package adds an IndexByte function for consistency with the bytes package.
  • The sync/atomic package adds a new set of swap functions that atomically exchange the argument with the value stored in the pointer, returning the old value. The functions are SwapInt32, SwapInt64, SwapUint32, SwapUint64, SwapUintptr, and SwapPointer, which swaps an unsafe.Pointer.
  • The syscall package now implements Sendfile for Darwin.
  • The testing package now exports the TB interface. It records the methods in common with the T and B types, to make it easier to share code between tests and benchmarks. Also, the AllocsPerRun function now quantizes the return value to an integer (although it still has type float64), to round off any error caused by initialization and make the result more repeatable.
  • The text/template package now automatically dereferences pointer values when evaluating the arguments to “escape” functions such as “html”, to bring the behavior of such functions in agreement with that of other printing functions such as “printf”.
  • In the time package, the Parse function and Format method now handle time zone offsets with seconds, such as in the historical date “1871-01-01T05:33:02+00:34:08”. Also, pattern matching in the formats for those routines is stricter: a non-lowercase letter must now follow the standard words such as “Jan” and “Mon”.
  • The unicode package adds In, a nicer-to-use but equivalent version of the original IsOneOf, to see whether a character is a member of a Unicode category.
Original source ↗

Update May 13, 2013 tracked by Updatify

go1.1 (released 2013-05-13)

Introduction to Go 1.1

THE RELEASE of Go version 1 (Go 1 or Go 1.0 for short) in March of 2012 introduced a new period of stability in the Go language and libraries. That stability has helped nourish a growing community of Go users and systems around the world. Several “point” releases since then—1.0.1, 1.0.2, and 1.0.3—have been issued. These point releases fixed known bugs but made no non-critical changes to the implementation.

This new release, Go 1.1, keeps the promise of compatibility but adds a couple of significant (backwards-compatible, of course) language changes, has a long list of (again, compatible) library changes, and includes major work on the implementation of the compilers, libraries, and run-time. The focus is on performance. Benchmarking is an inexact science at best, but we see significant, sometimes dramatic speedups for many of our test programs. We trust that many of our users’ programs will also see improvements just by updating their Go installation and recompiling.

This document summarizes the changes between Go 1 and Go 1.1. Very little if any code will need modification to run with Go 1.1, although a couple of rare error cases surface with this release and need to be addressed if they arise. Details appear below; see the discussion of 64-bit ints and Unicode literals in particular.

Changes to the language

The Go compatibility document promises that programs written to the Go 1 language specification will continue to operate, and those promises are maintained. In the interest of firming up the specification, though, there are details about some error cases that have been clarified. There are also some new language features.

Integer division by zero

In Go 1, integer division by a constant zero produced a run-time panic:

func f(x int) int {
    return x/0
}

In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error.

Surrogates in Unicode literals

The definition of string and rune literals has been refined to exclude surrogate halves from the set of valid Unicode code points. See the Unicode section for more information.

Method values

Go 1.1 now implements method values, which are functions that have been bound to a specific receiver value. For instance, given a Writer value w, the expression w.Write, a method value, is a function that will always write to w; it is equivalent to a function literal closing over w:

func (p []byte) (n int, err error) {
    return w.Write(p)
}

Method values are distinct from method expressions, which generate functions from methods of a given type; the method expression (*bufio.Writer).Write is equivalent to a function with an extra first argument, a receiver of type (*bufio.Writer):

func (w *bufio.Writer, p []byte) (n int, err error) {
    return w.Write(p)
}

Updating: No existing code is affected; the change is strictly backward-compatible.

Return requirements

Before Go 1.1, a function that returned a value needed an explicit “return” or call to panic at the end of the function; this was a simple way to make the programmer be explicit about the meaning of the function. But there are many cases where a final “return” is clearly unnecessary, such as a function with only an infinite “for” loop.

In Go 1.1, the rule about final “return” statements is more permissive. It introduces the concept of a terminating statement, a statement that is guaranteed to be the last one a function executes. Examples include “for” loops with no condition and “if-else” statements in which each half ends in a “return”. If the final statement of a function can be shown syntactically to be a terminating statement, no final “return” statement is needed.

Note that the rule is purely syntactic: it pays no attention to the values in the code and therefore requires no complex analysis.

Updating: The change is backward-compatible, but existing code with superfluous “return” statements and calls to panic may be simplified manually. Such code can be identified by go vet.

Changes to the implementations and tools

Status of gccgo

The GCC release schedule does not coincide with the Go release schedule, so some skew is inevitable in gccgo ’s releases. The 4.8.0 version of GCC shipped in March, 2013 and includes a nearly-Go 1.1 version of gccgo. Its library is a little behind the release, but the biggest difference is that method values are not implemented. Sometime around July 2013, we expect 4.8.2 of GCC to ship with a gccgo providing a complete Go 1.1 implementation.

Command-line flag parsing

In the gc toolchain, the compilers and linkers now use the same command-line flag parsing rules as the Go flag package, a departure from the traditional Unix flag parsing. This may affect scripts that invoke the tool directly. For example, go tool 6c -Fw -Dfoo must now be written go tool 6c -F -w -D foo.

Size of int on 64-bit platforms

The language allows the implementation to choose whether the int type and uint types are 32 or 64 bits. Previous Go implementations made int and uint 32 bits on all systems. Both the gc and gccgo implementations now make int and uint 64 bits on 64-bit platforms such as AMD64/x86-64. Among other things, this enables the allocation of slices with more than 2 billion elements on 64-bit platforms.

Updating: Most programs will be unaffected by this change. Because Go does not allow implicit conversions between distinct numeric types, no programs will stop compiling due to this change. However, programs that contain implicit assumptions that int is only 32 bits may change behavior. For example, this code prints a positive number on 64-bit systems and a negative one on 32-bit systems:

x := ^uint32(0) // x is 0xffffffff
i := int(x)     // i is -1 on 32-bit systems, 0xffffffff on 64-bit
fmt.Println(i)

Portable code intending 32-bit sign extension (yielding -1 on all systems) would instead say:

i := int(int32(x))

Heap size on 64-bit architectures

On 64-bit architectures, the maximum heap size has been enlarged substantially, from a few gigabytes to several tens of gigabytes. (The exact details depend on the system and may change.)

On 32-bit architectures, the heap size has not changed.

Updating: This change should have no effect on existing programs beyond allowing them to run with larger heaps.

Unicode

To make it possible to represent code points greater than 65535 in UTF-16, Unicode defines surrogate halves, a range of code points to be used only in the assembly of large values, and only in UTF-16. The code points in that surrogate range are illegal for any other purpose. In Go 1.1, this constraint is honored by the compiler, libraries, and run-time: a surrogate half is illegal as a rune value, when encoded as UTF-8, or when encoded in isolation as UTF-16. When encountered, for example in converting from a rune to UTF-8, it is treated as an encoding error and will yield the replacement rune, utf8.RuneError, U+FFFD.

This program,

import "fmt"

func main() {
    fmt.Printf("%+q\n", string(0xD800))
}

printed "\ud800" in Go 1.0, but prints "\ufffd" in Go 1.1.

Surrogate-half Unicode values are now illegal in rune and string constants, so constants such as '\ud800' and "\ud800" are now rejected by the compilers. When written explicitly as UTF-8 encoded bytes, such strings can still be created, as in "\xed\xa0\x80". However, when such a string is decoded as a sequence of runes, as in a range loop, it will yield only utf8.RuneError values.

The Unicode byte order mark U+FEFF, encoded in UTF-8, is now permitted as the first character of a Go source file. Even though its appearance in the byte-order-free UTF-8 encoding is clearly unnecessary, some editors add the mark as a kind of “magic number” identifying a UTF-8 encoded file.

Updating: Most programs will be unaffected by the surrogate change. Programs that depend on the old behavior should be modified to avoid the issue. The byte-order-mark change is strictly backward-compatible.

Race detector

A major addition to the tools is a race detector, a way to find bugs in programs caused by concurrent access of the same variable, where at least one of the accesses is a write. This new facility is built into the go tool. For now, it is only available on Linux, Mac OS X, and Windows systems with 64-bit x86 processors. To enable it, set the -race flag when building or testing your program (for instance, go test -race). The race detector is documented in a separate article.

The gc assemblers

Due to the change of the int to 64 bits and a new internal representation of functions, the arrangement of function arguments on the stack has changed in the gc toolchain. Functions written in assembly will need to be revised at least to adjust frame pointer offsets.

Updating: The go vet command now checks that functions implemented in assembly match the Go function prototypes they implement.

Changes to the go command

The go command has acquired several changes intended to improve the experience for new Go users.

First, when compiling, testing, or running Go code, the go command will now give more detailed error messages, including a list of paths searched, when a package cannot be located.

$ go build foo/quxx
can't load package: package foo/quxx: cannot find package "foo/quxx" in any of:
        /home/you/go/src/pkg/foo/quxx (from $GOROOT)
        /home/you/src/foo/quxx (from $GOPATH)

Second, the go get command no longer allows $GOROOT as the default destination when downloading package source. To use the go get command, a valid $GOPATH is now required.

$ GOPATH= go get code.google.com/p/foo/quxx
package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath

Finally, as a result of the previous change, the go get command will also fail when $GOPATH and $GOROOT are set to the same value.

$ GOPATH=$GOROOT go get code.google.com/p/foo/quxx
warning: GOPATH set to GOROOT (/home/you/go) has no effect
package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath

Changes to the go test command

The go test command no longer deletes the binary when run with profiling enabled, to make it easier to analyze the profile. The implementation sets the -c flag automatically, so after running,

$ go test -cpuprofile cpuprof.out mypackage

the file mypackage.test will be left in the directory where go test was run.

The go test command can now generate profiling information that reports where goroutines are blocked, that is, where they tend to stall waiting for an event such as a channel communication. The information is presented as a blocking profile enabled with the -blockprofile option of go test. Run go help test for more information.

Changes to the go fix command

The fix command, usually run as go fix, no longer applies fixes to update code from before Go 1 to use Go 1 APIs. To update pre-Go 1 code to Go 1.1, use a Go 1.0 toolchain to convert the code to Go 1.0 first.

Build constraints

The “ go1.1 ” tag has been added to the list of default build constraints. This permits packages to take advantage of the new features in Go 1.1 while remaining compatible with earlier versions of Go.

To build a file only with Go 1.1 and above, add this build constraint:

// +build go1.1

To build a file only with Go 1.0.x, use the converse constraint:

// +build !go1.1

Additional platforms

The Go 1.1 toolchain adds experimental support for freebsd/arm, netbsd/386, netbsd/amd64, netbsd/arm, openbsd/386 and openbsd/amd64 platforms.

An ARMv6 or later processor is required for freebsd/arm or netbsd/arm.

Go 1.1 adds experimental support for cgo on linux/arm.

Cross compilation

When cross-compiling, the go tool will disable cgo support by default.

To explicitly enable cgo, set CGO_ENABLED=1.

Performance

The performance of code compiled with the Go 1.1 gc tool suite should be noticeably better for most Go programs. Typical improvements relative to Go 1.0 seem to be about 30%-40%, sometimes much more, but occasionally less or even non-existent. There are too many small performance-driven tweaks through the tools and libraries to list them all here, but the following major changes are worth noting:

  • The gc compilers generate better code in many cases, most noticeably for floating point on the 32-bit Intel architecture.
  • The gc compilers do more in-lining, including for some operations in the run-time such as append and interface conversions.
  • There is a new implementation of Go maps with significant reduction in memory footprint and CPU time.
  • The garbage collector has been made more parallel, which can reduce latencies for programs running on multiple CPUs.
  • The garbage collector is also more precise, which costs a small amount of CPU time but can reduce the size of the heap significantly, especially on 32-bit architectures.
  • Due to tighter coupling of the run-time and network libraries, fewer context switches are required on network operations.

Changes to the standard library

bufio.Scanner

The various routines to scan textual input in the bufio package, ReadBytes, ReadString and particularly ReadLine, are needlessly complex to use for simple purposes. In Go 1.1, a new type, Scanner, has been added to make it easier to do simple tasks such as read the input as a sequence of lines or space-delimited words. It simplifies the problem by terminating the scan on problematic input such as pathologically long lines, and having a simple default: line-oriented input, with each line stripped of its terminator. Here is code to reproduce the input a line at a time:

scanner := bufio.NewScanner(os.Stdin)
for scanner.Scan() {
    fmt.Println(scanner.Text()) // Println will add back the final '\n'
}
if err := scanner.Err(); err != nil {
    fmt.Fprintln(os.Stderr, "reading standard input:", err)
}

Scanning behavior can be adjusted through a function to control subdividing the input (see the documentation for SplitFunc), but for tough problems or the need to continue past errors, the older interface may still be required.

net

The protocol-specific resolvers in the net package were formerly lax about the network name passed in. Although the documentation was clear that the only valid networks for ResolveTCPAddr are "tcp", "tcp4", and "tcp6", the Go 1.0 implementation silently accepted any string. The Go 1.1 implementation returns an error if the network is not one of those strings. The same is true of the other protocol-specific resolvers ResolveIPAddr, ResolveUDPAddr, and ResolveUnixAddr.

The previous implementation of ListenUnixgram returned a UDPConn as a representation of the connection endpoint. The Go 1.1 implementation instead returns a UnixConn to allow reading and writing with its ReadFrom and WriteTo methods.

The data structures IPAddr, TCPAddr, and UDPAddr add a new string field called Zone. Code using untagged composite literals (e.g. net.TCPAddr{ip, port}) instead of tagged literals ( net.TCPAddr{IP: ip, Port: port}) will break due to the new field. The Go 1 compatibility rules allow this change: client code must use tagged literals to avoid such breakages.

Updating: To correct breakage caused by the new struct field, go fix will rewrite code to add tags for these types. More generally, go vet will identify composite literals that should be revised to use field tags.

reflect

The reflect package has several significant additions.

It is now possible to run a “select” statement using the reflect package; see the description of Select and SelectCase for details.

The new method Value.Convert (or Type.ConvertibleTo) provides functionality to execute a Go conversion or type assertion operation on a Value (or test for its possibility).

The new function MakeFunc creates a wrapper function to make it easier to call a function with existing Values, doing the standard Go conversions among the arguments, for instance to pass an actual int to a formal interface{}.

Finally, the new functions ChanOf, MapOf and SliceOf construct new Types from existing types, for example to construct the type []T given only T.

time

On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the time package returned times with microsecond precision. The Go 1.1 implementation on these systems now returns times with nanosecond precision. Programs that write to an external format with microsecond precision and read it back, expecting to recover the original value, will be affected by the loss of precision. There are two new methods of Time, Round and Truncate, that can be used to remove precision from a time before passing it to external storage.

The new method YearDay returns the one-indexed integral day number of the year specified by the time value.

The Timer type has a new method Reset that modifies the timer to expire after a specified duration.

Finally, the new function ParseInLocation is like the existing Parse but parses the time in the context of a location (time zone), ignoring time zone information in the parsed string. This function addresses a common source of confusion in the time API.

Updating: Code that needs to read and write times using an external format with lower precision should be modified to use the new methods.

Exp and old subtrees moved to go.exp and go.text subrepositories

To make it easier for binary distributions to access them if desired, the exp and old source subtrees, which are not included in binary distributions, have been moved to the new go.exp subrepository at code.google.com/p/go.exp. To access the ssa package, for example, run

$ go get code.google.com/p/go.exp/ssa

and then in Go source,

import "code.google.com/p/go.exp/ssa"

The old package exp/norm has also been moved, but to a new repository go.text, where the Unicode APIs and other text-related packages will be developed.

New packages

There are three new packages.

  • The go/format package provides a convenient way for a program to access the formatting capabilities of the go fmt command. It has two functions, Node to format a Go parser Node, and Source to reformat arbitrary Go source code into the standard format as provided by the go fmt command.
  • The net/http/cookiejar package provides the basics for managing HTTP cookies.
  • The runtime/race package provides low-level facilities for data race detection. It is internal to the race detector and does not otherwise export any user-visible functionality.

Minor changes to the library

The following list summarizes a number of minor changes to the library, mostly additions. See the relevant package documentation for more information about each change.

  • The bytes package has two new functions, TrimPrefix and TrimSuffix, with self-evident properties. Also, the Buffer type has a new method Grow that provides some control over memory allocation inside the buffer. Finally, the Reader type now has a WriteTo method so it implements the io.WriterTo interface.
  • The compress/gzip package has a new Flush method for its Writer type that flushes its underlying flate.Writer.
  • The crypto/hmac package has a new function, Equal, to compare two MACs.
  • The crypto/x509 package now supports PEM blocks (see DecryptPEMBlock for instance), and a new function ParseECPrivateKey to parse elliptic curve private keys.
  • The database/sql package has a new Ping method for its DB type that tests the health of the connection.
  • The database/sql/driver package has a new Queryer interface that a Conn may implement to improve performance.
  • The encoding/json package’s Decoder has a new method Buffered to provide access to the remaining data in its buffer, as well as a new method UseNumber to unmarshal a value into the new type Number, a string, rather than a float64.
  • The encoding/xml package has a new function, EscapeText, which writes escaped XML output, and a method on Encoder, Indent, to specify indented output.
  • In the go/ast package, a new type CommentMap and associated methods makes it easier to extract and process comments in Go programs.
  • In the go/doc package, the parser now keeps better track of stylized annotations such as TODO(joe) throughout the code, information that the godoc command can filter or present according to the value of the -notes flag.
  • The undocumented and only partially implemented “noescape” feature of the html/template package has been removed; programs that depend on it will break.
  • The image/jpeg package now reads progressive JPEG files and handles a few more subsampling configurations.
  • The io package now exports the io.ByteWriter interface to capture the common functionality of writing a byte at a time. It also exports a new error, ErrNoProgress, used to indicate a Read implementation is looping without delivering data.
  • The log/syslog package now provides better support for OS-specific logging features.
  • The math/big package’s Int type now has methods MarshalJSON and UnmarshalJSON to convert to and from a JSON representation. Also, Int can now convert directly to and from a uint64 using Uint64 and SetUint64, while Rat can do the same with float64 using Float64 and SetFloat64.
  • The mime/multipart package has a new method for its Writer, SetBoundary, to define the boundary separator used to package the output. The Reader also now transparently decodes any quoted-printable parts and removes the Content-Transfer-Encoding header when doing so.
  • The net package’s ListenUnixgram function has changed return types: it now returns a UnixConn rather than a UDPConn, which was clearly a mistake in Go 1.0. Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
  • The net package includes a new type, Dialer, to supply options to Dial.
  • The net package adds support for link-local IPv6 addresses with zone qualifiers, such as fe80::1%lo0. The address structures IPAddr, UDPAddr, and TCPAddr record the zone in a new field, and functions that expect string forms of these addresses, such as Dial, ResolveIPAddr, ResolveUDPAddr, and ResolveTCPAddr, now accept the zone-qualified form.
  • The net package adds LookupNS to its suite of resolving functions. LookupNS returns the NS records for a host name.
  • The net package adds protocol-specific packet reading and writing methods to IPConn ( ReadMsgIP and WriteMsgIP) and UDPConn ( ReadMsgUDP and WriteMsgUDP). These are specialized versions of PacketConn ’s ReadFrom and WriteTo methods that provide access to out-of-band data associated with the packets.
  • The net package adds methods to UnixConn to allow closing half of the connection ( CloseRead and CloseWrite), matching the existing methods of TCPConn.
  • The net/http package includes several new additions. ParseTime parses a time string, trying several common HTTP time formats. The PostFormValue method of Request is like FormValue but ignores URL parameters. The CloseNotifier interface provides a mechanism for a server handler to discover when a client has disconnected. The ServeMux type now has a Handler method to access a path’s Handler without executing it. The Transport can now cancel an in-flight request with CancelRequest. Finally, the Transport is now more aggressive at closing TCP connections when a Response.Body is closed before being fully consumed.
  • The net/mail package has two new functions, ParseAddress and ParseAddressList, to parse RFC 5322-formatted mail addresses into Address structures.
  • The net/smtp package’s Client type has a new method, Hello, which transmits a HELO or EHLO message to the server.
  • The net/textproto package has two new functions, TrimBytes and TrimString, which do ASCII-only trimming of leading and trailing spaces.
  • The new method os.FileMode.IsRegular makes it easy to ask if a file is a plain file.
  • The os/signal package has a new function, Stop, which stops the package delivering any further signals to the channel.
  • The regexp package now supports Unix-original leftmost-longest matches through the Regexp.Longest method, while Regexp.Split slices strings into pieces based on separators defined by the regular expression.
  • The runtime/debug package has three new functions regarding memory usage. The FreeOSMemory function triggers a run of the garbage collector and then attempts to return unused memory to the operating system; the ReadGCStats function retrieves statistics about the collector; and SetGCPercent provides a programmatic way to control how often the collector runs, including disabling it altogether.
  • The sort package has a new function, Reverse. Wrapping the argument of a call to sort.Sort with a call to Reverse causes the sort order to be reversed.
  • The strings package has two new functions, TrimPrefix and TrimSuffix with self-evident properties, and the new method Reader.WriteTo so the Reader type now implements the io.WriterTo interface.
  • The syscall package’s Fchflags function on various BSDs (including Darwin) has changed signature. It now takes an int as the first parameter instead of a string. Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
  • The syscall package also has received many updates to make it more inclusive of constants and system calls for each supported operating system.
  • The testing package now automates the generation of allocation statistics in tests and benchmarks using the new AllocsPerRun function. And the ReportAllocs method on testing.B will enable printing of memory allocation statistics for the calling benchmark. It also introduces the AllocsPerOp method of BenchmarkResult. There is also a new Verbose function to test the state of the -v command-line flag, and a new Skip method of testing.B and testing.T to simplify skipping an inappropriate test.
  • In the text/template and html/template packages, templates can now use parentheses to group the elements of pipelines, simplifying the construction of complex pipelines. Also, as part of the new parser, the Node interface got two new methods to provide better error reporting. Although this violates the Go 1 compatibility rules, no existing code should be affected because this interface is explicitly intended only to be used by the text/template and html/template packages and there are safeguards to guarantee that.
  • The implementation of the unicode package has been updated to Unicode version 6.2.0.
  • In the unicode/utf8 package, the new function ValidRune reports whether the rune is a valid Unicode code point. To be valid, a rune must be in range and not be a surrogate half.
Original source ↗

Update Sep 21, 2012 tracked by Updatify

go1.0.3 (released 2012-09-21)

go1.0.3 (released 2012-09-21) includes minor code and documentation fixes.

Original source ↗

Update Mar 28, 2012 tracked by Updatify

go1 (released 2012-03-28)

Introduction to Go 1

Go version 1, Go 1 for short, defines a language and a set of core libraries that provide a stable foundation for creating reliable products, projects, and publications.

The driving motivation for Go 1 is stability for its users. People should be able to write Go programs and expect that they will continue to compile and run without change, on a time scale of years, including in production environments such as Google App Engine. Similarly, people should be able to write books about Go, be able to say which version of Go the book is describing, and have that version number still be meaningful much later.

Code that compiles in Go 1 should, with few exceptions, continue to compile and run throughout the lifetime of that version, even as we issue updates and bug fixes such as Go version 1.1, 1.2, and so on. Other than critical fixes, changes made to the language and library for subsequent releases of Go 1 may add functionality but will not break existing Go 1 programs. The Go 1 compatibility document explains the compatibility guidelines in more detail.

Go 1 is a representation of Go as it used today, not a wholesale rethinking of the language. We avoided designing new features and instead focused on cleaning up problems and inconsistencies and improving portability. There are a number changes to the Go language and packages that we had considered for some time and prototyped but not released primarily because they are significant and backwards-incompatible. Go 1 was an opportunity to get them out, which is helpful for the long term, but also means that Go 1 introduces incompatibilities for old programs. Fortunately, the go fix tool can automate much of the work needed to bring programs up to the Go 1 standard.

This document outlines the major changes in Go 1 that will affect programmers updating existing code; its reference point is the prior release, r60 (tagged as r60.3). It also explains how to update code from r60 to run under Go 1.

Changes to the language

Append

The append predeclared variadic function makes it easy to grow a slice by adding elements to the end. A common use is to add bytes to the end of a byte slice when generating output. However, append did not provide a way to append a string to a []byte, which is another common case.

    greeting := []byte{}
    greeting = append(greeting, []byte("hello ")...)

By analogy with the similar property of copy, Go 1 permits a string to be appended (byte-wise) directly to a byte slice, reducing the friction between strings and byte slices. The conversion is no longer necessary:

    greeting = append(greeting, "world"...)

Updating: This is a new feature, so existing code needs no changes.

Close

The close predeclared function provides a mechanism for a sender to signal that no more values will be sent. It is important to the implementation of for range loops over channels and is helpful in other situations. Partly by design and partly because of race conditions that can occur otherwise, it is intended for use only by the goroutine sending on the channel, not by the goroutine receiving data. However, before Go 1 there was no compile-time checking that close was being used correctly.

To close this gap, at least in part, Go 1 disallows close on receive-only channels. Attempting to close such a channel is a compile-time error.

    var c chan int
    var csend chan<- int = c
    var crecv <-chan int = c
    close(c)     // legal
    close(csend) // legal
    close(crecv) // illegal

Updating: Existing code that attempts to close a receive-only channel was erroneous even before Go 1 and should be fixed. The compiler will now reject such code.

Composite literals

In Go 1, a composite literal of array, slice, or map type can elide the type specification for the elements’ initializers if they are of pointer type. All four of the initializations in this example are legal; the last one was illegal before Go 1.

    type Date struct {
        month string
        day   int
    }
    // Struct values, fully qualified; always legal.
    holiday1 := []Date{
        Date{"Feb", 14},
        Date{"Nov", 11},
        Date{"Dec", 25},
    }
    // Struct values, type name elided; always legal.
    holiday2 := []Date{
        {"Feb", 14},
        {"Nov", 11},
        {"Dec", 25},
    }
    // Pointers, fully qualified, always legal.
    holiday3 := []*Date{
        &Date{"Feb", 14},
        &Date{"Nov", 11},
        &Date{"Dec", 25},
    }
    // Pointers, type name elided; legal in Go 1.
    holiday4 := []*Date{
        {"Feb", 14},
        {"Nov", 11},
        {"Dec", 25},
    }

Updating: This change has no effect on existing code, but the command gofmt -s applied to existing source will, among other things, elide explicit element types wherever permitted.

Goroutines during init

The old language defined that go statements executed during initialization created goroutines but that they did not begin to run until initialization of the entire program was complete. This introduced clumsiness in many places and, in effect, limited the utility of the init construct: if it was possible for another package to use the library during initialization, the library was forced to avoid goroutines. This design was done for reasons of simplicity and safety but, as our confidence in the language grew, it seemed unnecessary. Running goroutines during initialization is no more complex or unsafe than running them during normal execution.

In Go 1, code that uses goroutines can be called from init routines and global initialization expressions without introducing a deadlock.

var PackageGlobal int

func init() {
    c := make(chan int)
    go initializationFunction(c)
    PackageGlobal = <-c
}

Updating: This is a new feature, so existing code needs no changes, although it’s possible that code that depends on goroutines not starting before main will break. There was no such code in the standard repository.

The rune type

The language spec allows the int type to be 32 or 64 bits wide, but current implementations set int to 32 bits even on 64-bit platforms. It would be preferable to have int be 64 bits on 64-bit platforms. (There are important consequences for indexing large slices.) However, this change would waste space when processing Unicode characters with the old language because the int type was also used to hold Unicode code points: each code point would waste an extra 32 bits of storage if int grew from 32 bits to 64.

To make changing to 64-bit int feasible, Go 1 introduces a new basic type, rune, to represent individual Unicode code points. It is an alias for int32, analogous to byte as an alias for uint8.

Character literals such as 'a', '語', and '\u0345' now have default type rune, analogous to 1.0 having default type float64. A variable initialized to a character constant will therefore have type rune unless otherwise specified.

Libraries have been updated to use rune rather than int when appropriate. For instance, the functions unicode.ToLower and relatives now take and return a rune.

    delta := 'δ' // delta has type rune.
    var DELTA rune
    DELTA = unicode.ToUpper(delta)
    epsilon := unicode.ToLower(DELTA + 1)
    if epsilon != 'δ'+1 {
        log.Fatal("inconsistent casing for Greek")
    }

Updating: Most source code will be unaffected by this because the type inference from := initializers introduces the new type silently, and it propagates from there. Some code may get type errors that a trivial conversion will resolve.

The error type

Go 1 introduces a new built-in type, error, which has the following definition:

    type error interface {
        Error() string
    }

Since the consequences of this type are all in the package library, it is discussed below.

Deleting from maps

In the old language, to delete the entry with key k from map m, one wrote the statement,

    m[k] = value, false

This syntax was a peculiar special case, the only two-to-one assignment. It required passing a value (usually ignored) that is evaluated but discarded, plus a boolean that was nearly always the constant false. It did the job but was odd and a point of contention.

In Go 1, that syntax has gone; instead there is a new built-in function, delete. The call

    delete(m, k)

will delete the map entry retrieved by the expression m[k]. There is no return value. Deleting a non-existent entry is a no-op.

Updating: Running go fix will convert expressions of the form m[k] = value, false into delete(m, k) when it is clear that the ignored value can be safely discarded from the program and false refers to the predefined boolean constant. The fix tool will flag other uses of the syntax for inspection by the programmer.

Iterating in maps

The old language specification did not define the order of iteration for maps, and in practice it differed across hardware platforms. This caused tests that iterated over maps to be fragile and non-portable, with the unpleasant property that a test might always pass on one machine but break on another.

In Go 1, the order in which elements are visited when iterating over a map using a for range statement is defined to be unpredictable, even if the same loop is run multiple times with the same map. Code should not assume that the elements are visited in any particular order.

This change means that code that depends on iteration order is very likely to break early and be fixed long before it becomes a problem. Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a mapl.

    m := map[string]int{"Sunday": 0, "Monday": 1}
    for name, value := range m {
        // This loop should not assume Sunday will be visited first.
        f(name, value)
    }

Updating: This is one change where tools cannot help. Most existing code will be unaffected, but some programs may break or misbehave; we recommend manual checking of all range statements over maps to verify they do not depend on iteration order. There were a few such examples in the standard repository; they have been fixed. Note that it was already incorrect to depend on the iteration order, which was unspecified. This change codifies the unpredictability.

Multiple assignment

The language specification has long guaranteed that in assignments the right-hand-side expressions are all evaluated before any left-hand-side expressions are assigned. To guarantee predictable behavior, Go 1 refines the specification further.

If the left-hand side of the assignment statement contains expressions that require evaluation, such as function calls or array indexing operations, these will all be done using the usual left-to-right rule before any variables are assigned their value. Once everything is evaluated, the actual assignments proceed in left-to-right order.

These examples illustrate the behavior.

    sa := []int{1, 2, 3}
    i := 0
    i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2

    sb := []int{1, 2, 3}
    j := 0
    sb[j], j = 2, 1 // sets sb[0] = 2, j = 1

    sc := []int{1, 2, 3}
    sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)

Updating: This is one change where tools cannot help, but breakage is unlikely. No code in the standard repository was broken by this change, and code that depended on the previous unspecified behavior was already incorrect.

Returns and shadowed variables

A common mistake is to use return (without arguments) after an assignment to a variable that has the same name as a result variable but is not the same variable. This situation is called shadowing: the result variable has been shadowed by another variable with the same name declared in an inner scope.

In functions with named return values, the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement. (It isn’t part of the specification, because this is one area we are still exploring; the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.)

This function implicitly returns a shadowed return value and will be rejected by the compiler:

func Bug() (i, j, k int) {
    for i = 0; i < 5; i++ {
        for j := 0; j < 5; j++ { // Redeclares j.
            k += i * j
            if k > 100 {
                return // Rejected: j is shadowed here.
            }
        }
    }
    return // OK: j is not shadowed here.
}

Updating: Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand. The few cases that arose in the standard repository were mostly bugs.

Copying structs with unexported fields

The old language did not allow a package to make a copy of a struct value containing unexported fields belonging to a different package. There was, however, a required exception for a method receiver; also, the implementations of copy and append have never honored the restriction.

Go 1 will allow packages to copy struct values containing unexported fields from other packages. Besides resolving the inconsistency, this change admits a new kind of API: a package can return an opaque value without resorting to a pointer or interface. The new implementations of time.Time and reflect.Value are examples of types taking advantage of this new property.

As an example, if package p includes the definitions,

    type Struct struct {
        Public int
        secret int
    }
    func NewStruct(a int) Struct {  // Note: not a pointer.
        return Struct{a, f(a)}
    }
    func (s Struct) String() string {
        return fmt.Sprintf("{%d (secret %d)}", s.Public, s.secret)
    }

a package that imports p can assign and copy values of type p.Struct at will. Behind the scenes the unexported fields will be assigned and copied just as if they were exported, but the client code will never be aware of them. The code

    import "p"

    myStruct := p.NewStruct(23)
    copyOfMyStruct := myStruct
    fmt.Println(myStruct, copyOfMyStruct)

will show that the secret field of the struct has been copied to the new value.

Updating: This is a new feature, so existing code needs no changes.

Equality

Before Go 1, the language did not define equality on struct and array values. This meant, among other things, that structs and arrays could not be used as map keys. On the other hand, Go did define equality on function and map values. Function equality was problematic in the presence of closures (when are two closures equal?) while map equality compared pointers, not the maps’ content, which was usually not what the user would want.

Go 1 addressed these issues. First, structs and arrays can be compared for equality and inequality ( == and !=), and therefore be used as map keys, provided they are composed from elements for which equality is also defined, using element-wise comparison.

    type Day struct {
        long  string
        short string
    }
    Christmas := Day{"Christmas", "XMas"}
    Thanksgiving := Day{"Thanksgiving", "Turkey"}
    holiday := map[Day]bool{
        Christmas:    true,
        Thanksgiving: true,
    }
    fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])

Second, Go 1 removes the definition of equality for function values, except for comparison with nil. Finally, map equality is gone too, also except for comparison with nil.

Note that equality is still undefined for slices, for which the calculation is in general infeasible. Also note that the ordered comparison operators (< <= > >=) are still undefined for structs and arrays.

Updating: Struct and array equality is a new feature, so existing code needs no changes. Existing code that depends on function or map equality will be rejected by the compiler and will need to be fixed by hand. Few programs will be affected, but the fix may require some redesign.

The package hierarchy

Go 1 addresses many deficiencies in the old standard library and cleans up a number of packages, making them more internally consistent and portable.

This section describes how the packages have been rearranged in Go 1. Some have moved, some have been renamed, some have been deleted. New packages are described in later sections.

The package hierarchy

Go 1 has a rearranged package hierarchy that groups related items into subdirectories. For instance, utf8 and utf16 now occupy subdirectories of unicode. Also, some packages have moved into subrepositories of code.google.com/p/go while others have been deleted outright.

Old path New path
— —
asn1 encoding/asn1
csv encoding/csv
gob encoding/gob
json encoding/json
xml encoding/xml
— —
exp/template/html html/template
— —
big math/big
cmath math/cmplx
rand math/rand
— —
http net/http
http/cgi net/http/cgi
http/fcgi net/http/fcgi
http/httptest net/http/httptest
http/pprof net/http/pprof
mail net/mail
rpc net/rpc
rpc/jsonrpc net/rpc/jsonrpc
smtp net/smtp
url net/url
— —
exec os/exec
— —
scanner text/scanner
tabwriter text/tabwriter
template text/template
template/parse text/template/parse
— —
utf8 unicode/utf8
utf16 unicode/utf16

Note that the package names for the old cmath and exp/template/html packages have changed to cmplx and template.

Updating: Running go fix will update all imports and package renames for packages that remain inside the standard repository. Programs that import packages that are no longer in the standard repository will need to be edited by hand.

The package tree exp

Because they are not standardized, the packages under the exp directory will not be available in the standard Go 1 release distributions, although they will be available in source code form in the repository for developers who wish to use them.

Several packages have moved under exp at the time of Go 1’s release:

  • ebnf
  • html <sup>†</sup>
  • go/types

( <sup>†</sup> The EscapeString and UnescapeString types remain in package html.)

All these packages are available under the same names, with the prefix exp/: exp/ebnf etc.

Also, the utf8.String type has been moved to its own package, exp/utf8string.

Finally, the gotype command now resides in exp/gotype, while ebnflint is now in exp/ebnflint. If they are installed, they now reside in $GOROOT/bin/tool.

Updating: Code that uses packages in exp will need to be updated by hand, or else compiled from an installation that has exp available. The go fix tool or the compiler will complain about such uses.

The package tree old

Because they are deprecated, the packages under the old directory will not be available in the standard Go 1 release distributions, although they will be available in source code form for developers who wish to use them.

The packages in their new locations are:

  • old/netchan

Updating: Code that uses packages now in old will need to be updated by hand, or else compiled from an installation that has old available. The go fix tool will warn about such uses.

Deleted packages

Go 1 deletes several packages outright:

  • container/vector
  • exp/datafmt
  • go/typechecker
  • old/regexp
  • old/template
  • try

and also the command gotry.

Updating: Code that uses container/vector should be updated to use slices directly. See the Go Language Community Wiki for some suggestions. Code that uses the other packages (there should be almost zero) will need to be rethought.

Packages moving to subrepositories

Go 1 has moved a number of packages into other repositories, usually sub-repositories of the main Go repository. This table lists the old and new import paths:

Old New
— —
crypto/bcrypt code.google.com/p/go.crypto/bcrypt
crypto/blowfish code.google.com/p/go.crypto/blowfish
crypto/cast5 code.google.com/p/go.crypto/cast5
crypto/md4 code.google.com/p/go.crypto/md4
crypto/ocsp code.google.com/p/go.crypto/ocsp
crypto/openpgp code.google.com/p/go.crypto/openpgp
crypto/openpgp/armor code.google.com/p/go.crypto/openpgp/armor
crypto/openpgp/elgamal code.google.com/p/go.crypto/openpgp/elgamal
crypto/openpgp/errors code.google.com/p/go.crypto/openpgp/errors
crypto/openpgp/packet code.google.com/p/go.crypto/openpgp/packet
crypto/openpgp/s2k code.google.com/p/go.crypto/openpgp/s2k
crypto/ripemd160 code.google.com/p/go.crypto/ripemd160
crypto/twofish code.google.com/p/go.crypto/twofish
crypto/xtea code.google.com/p/go.crypto/xtea
exp/ssh code.google.com/p/go.crypto/ssh
— —
image/bmp code.google.com/p/go.image/bmp
image/tiff code.google.com/p/go.image/tiff
— —
net/dict code.google.com/p/go.net/dict
net/websocket code.google.com/p/go.net/websocket
exp/spdy code.google.com/p/go.net/spdy
— —
encoding/git85 code.google.com/p/go.codereview/git85
patch code.google.com/p/go.codereview/patch
— —
exp/wingui code.google.com/p/gowingui

Updating: Running go fix will update imports of these packages to use the new import paths. Installations that depend on these packages will need to install them using a go get command.

Major changes to the library

This section describes significant changes to the core libraries, the ones that affect the most programs.

The error type and errors package

The placement of os.Error in package os is mostly historical: errors first came up when implementing package os, and they seemed system-related at the time. Since then it has become clear that errors are more fundamental than the operating system. For example, it would be nice to use Errors in packages that os depends on, like syscall. Also, having Error in os introduces many dependencies on os that would otherwise not exist.

Go 1 solves these problems by introducing a built-in error interface type and a separate errors package (analogous to bytes and strings) that contains utility functions. It replaces os.NewError with errors.New, giving errors a more central place in the environment.

So the widely-used String method does not cause accidental satisfaction of the error interface, the error interface uses instead the name Error for that method:

    type error interface {
        Error() string
    }

The fmt library automatically invokes Error, as it already does for String, for easy printing of error values.

type SyntaxError struct {
    File    string
    Line    int
    Message string
}

func (se *SyntaxError) Error() string {
    return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message)
}

All standard packages have been updated to use the new interface; the old os.Error is gone.

A new package, errors, contains the function

func New(text string) error

to turn a string into an error. It replaces the old os.NewError.

    var ErrSyntax = errors.New("syntax error")

Updating: Running go fix will update almost all code affected by the change. Code that defines error types with a String method will need to be updated by hand to rename the methods to Error.

System call errors

The old syscall package, which predated os.Error (and just about everything else), returned errors as int values. In turn, the os package forwarded many of these errors, such as EINVAL, but using a different set of errors on each platform. This behavior was unpleasant and unportable.

In Go 1, the syscall package instead returns an error for system call errors. On Unix, the implementation is done by a syscall.Errno type that satisfies error and replaces the old os.Errno.

The changes affecting os.EINVAL and relatives are described elsewhere.

Updating: Running go fix will update almost all code affected by the change. Regardless, most code should use the os package rather than syscall and so will be unaffected.

Time

Time is always a challenge to support well in a programming language. The old Go time package had int64 units, no real type safety, and no distinction between absolute times and durations.

One of the most sweeping changes in the Go 1 library is therefore a complete redesign of the time package. Instead of an integer number of nanoseconds as an int64, and a separate *time.Time type to deal with human units such as hours and years, there are now two fundamental types: time.Time (a value, so the * is gone), which represents a moment in time; and time.Duration, which represents an interval. Both have nanosecond resolution. A Time can represent any time into the ancient past and remote future, while a Duration can span plus or minus only about 290 years. There are methods on these types, plus a number of helpful predefined constant durations such as time.Second.

Among the new methods are things like Time.Add, which adds a Duration to a Time, and Time.Sub, which subtracts two Times to yield a Duration.

The most important semantic change is that the Unix epoch (Jan 1, 1970) is now relevant only for those functions and methods that mention Unix: time.Unix and the Unix and UnixNano methods of the Time type. In particular, time.Now returns a time.Time value rather than, in the old API, an integer nanosecond count since the Unix epoch.

// sleepUntil sleeps until the specified time. It returns immediately if it's too late.
func sleepUntil(wakeup time.Time) {
    now := time.Now() // A Time.
    if !wakeup.After(now) {
        return
    }
    delta := wakeup.Sub(now) // A Duration.
    fmt.Printf("Sleeping for %.3fs\n", delta.Seconds())
    time.Sleep(delta)
}

The new types, methods, and constants have been propagated through all the standard packages that use time, such as os and its representation of file time stamps.

Updating: The go fix tool will update many uses of the old time package to use the new types and methods, although it does not replace values such as 1e9 representing nanoseconds per second. Also, because of type changes in some of the values that arise, some of the expressions rewritten by the fix tool may require further hand editing; in such cases the rewrite will include the correct function or method for the old functionality, but may have the wrong type or require further analysis.

Minor changes to the library

This section describes smaller changes, such as those to less commonly used packages or that affect few programs beyond the need to run go fix. This category includes packages that are new in Go 1. Collectively they improve portability, regularize behavior, and make the interfaces more modern and Go-like.

The archive/zip package

In Go 1, *zip.Writer no longer has a Write method. Its presence was a mistake.

Updating: What little code is affected will be caught by the compiler and must be updated by hand.

The bufio package

In Go 1, bufio.NewReaderSize and bufio.NewWriterSize functions no longer return an error for invalid sizes. If the argument size is too small or invalid, it is adjusted.

Updating: Running go fix will update calls that assign the error to _. Calls that aren’t fixed will be caught by the compiler and must be updated by hand.

The compress/flate, compress/gzip and compress/zlib packages

In Go 1, the NewWriterXxx functions in compress/flate, compress/gzip and compress/zlib all return (*Writer, error) if they take a compression level, and *Writer otherwise. Package gzip ’s Compressor and Decompressor types have been renamed to Writer and Reader. Package flate ’s WrongValueError type has been removed.

Updating Running go fix will update old names and calls that assign the error to _. Calls that aren’t fixed will be caught by the compiler and must be updated by hand.

The crypto/aes and crypto/des packages

In Go 1, the Reset method has been removed. Go does not guarantee that memory is not copied and therefore this method was misleading.

The cipher-specific types *aes.Cipher, *des.Cipher, and *des.TripleDESCipher have been removed in favor of cipher.Block.

Updating: Remove the calls to Reset. Replace uses of the specific cipher types with cipher.Block.

The crypto/elliptic package

In Go 1, elliptic.Curve has been made an interface to permit alternative implementations. The curve parameters have been moved to the elliptic.CurveParams structure.

Updating: Existing users of *elliptic.Curve will need to change to simply elliptic.Curve. Calls to Marshal, Unmarshal and GenerateKey are now functions in crypto/elliptic that take an elliptic.Curve as their first argument.

The crypto/hmac package

In Go 1, the hash-specific functions, such as hmac.NewMD5, have been removed from crypto/hmac. Instead, hmac.New takes a function that returns a hash.Hash, such as md5.New.

Updating: Running go fix will perform the needed changes.

The crypto/x509 package

In Go 1, the CreateCertificate function and CreateCRL method in crypto/x509 have been altered to take an interface{} where they previously took a *rsa.PublicKey or *rsa.PrivateKey. This will allow other public key algorithms to be implemented in the future.

Updating: No changes will be needed.

The encoding/binary package

In Go 1, the binary.TotalSize function has been replaced by Size, which takes an interface{} argument rather than a reflect.Value.

Updating: What little code is affected will be caught by the compiler and must be updated by hand.

The encoding/xml package

In Go 1, the xml package has been brought closer in design to the other marshaling packages such as encoding/gob.

The old Parser type is renamed Decoder and has a new Decode method. An Encoder type was also introduced.

The functions Marshal and Unmarshal work with []byte values now. To work with streams, use the new Encoder and Decoder types.

When marshaling or unmarshaling values, the format of supported flags in field tags has changed to be closer to the json package ( xml:"name,flag"). The matching done between field tags, field names, and the XML attribute and element names is now case-sensitive. The XMLName field tag, if present, must also match the name of the XML element being marshaled.

Updating: Running go fix will update most uses of the package except for some calls to Unmarshal. Special care must be taken with field tags, since the fix tool will not update them and if not fixed by hand they will misbehave silently in some cases. For example, the old "attr" is now written ",attr" while plain "attr" remains valid but with a different meaning.

The expvar package

In Go 1, the RemoveAll function has been removed. The Iter function and Iter method on *Map have been replaced by Do and (*Map).Do.

Updating: Most code using expvar will not need changing. The rare code that used Iter can be updated to pass a closure to Do to achieve the same effect.

The flag package

In Go 1, the interface flag.Value has changed slightly. The Set method now returns an error instead of a bool to indicate success or failure.

There is also a new kind of flag, Duration, to support argument values specifying time intervals. Values for such flags must be given units, just as time.Duration formats them: 10s, 1h30m, etc.

var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")

Updating: Programs that implement their own flags will need minor manual fixes to update their Set methods. The Duration flag is new and affects no existing code.

The go/* packages

Several packages under go have slightly revised APIs.

A concrete Mode type was introduced for configuration mode flags in the packages go/scanner, go/parser, go/printer, and go/doc.

The modes AllowIllegalChars and InsertSemis have been removed from the go/scanner package. They were mostly useful for scanning text other then Go source files. Instead, the text/scanner package should be used for that purpose.

The ErrorHandler provided to the scanner’s Init method is now simply a function rather than an interface. The ErrorVector type has been removed in favor of the (existing) ErrorList type, and the ErrorVector methods have been migrated. Instead of embedding an ErrorVector in a client of the scanner, now a client should maintain an ErrorList.

The set of parse functions provided by the go/parser package has been reduced to the primary parse function ParseFile, and a couple of convenience functions ParseDir and ParseExpr.

The go/printer package supports an additional configuration mode SourcePos; if set, the printer will emit //line comments such that the generated output contains the original source code position information. The new type CommentedNode can be used to provide comments associated with an arbitrary ast.Node (until now only ast.File carried comment information).

The type names of the go/doc package have been streamlined by removing the Doc suffix: PackageDoc is now Package, ValueDoc is Value, etc. Also, all types now consistently have a Name field (or Names, in the case of type Value) and Type.Factories has become Type.Funcs. Instead of calling doc.NewPackageDoc(pkg, importpath), documentation for a package is created with:

    doc.New(pkg, importpath, mode)

where the new mode parameter specifies the operation mode: if set to AllDecls, all declarations (not just exported ones) are considered. The function NewFileDoc was removed, and the function CommentText has become the method Text of ast.CommentGroup.

In package go/token, the token.FileSet method Files (which originally returned a channel of *token.File s) has been replaced with the iterator Iterate that accepts a function argument instead.

In package go/build, the API has been nearly completely replaced. The package still computes Go package information but it does not run the build: the Cmd and Script types are gone. (To build code, use the new go command instead.) The DirInfo type is now named Package. FindTree and ScanDir are replaced by Import and ImportDir.

Updating: Code that uses packages in go will have to be updated by hand; the compiler will reject incorrect uses. Templates used in conjunction with any of the go/doc types may need manual fixes; the renamed fields will lead to run-time errors.

The hash package

In Go 1, the definition of hash.Hash includes a new method, BlockSize. This new method is used primarily in the cryptographic libraries.

The Sum method of the hash.Hash interface now takes a []byte argument, to which the hash value will be appended. The previous behavior can be recreated by adding a nil argument to the call.

Updating: Existing implementations of hash.Hash will need to add a BlockSize method. Hashes that process the input one byte at a time can implement BlockSize to return 1. Running go fix will update calls to the Sum methods of the various implementations of hash.Hash.

Updating: Since the package’s functionality is new, no updating is necessary.

The http package

In Go 1 the http package is refactored, putting some of the utilities into a httputil subdirectory. These pieces are only rarely needed by HTTP clients. The affected items are:

  • ClientConn
  • DumpRequest
  • DumpRequestOut
  • DumpResponse
  • NewChunkedReader
  • NewChunkedWriter
  • NewClientConn
  • NewProxyClientConn
  • NewServerConn
  • NewSingleHostReverseProxy
  • ReverseProxy
  • ServerConn

The Request.RawURL field has been removed; it was a historical artifact.

The Handle and HandleFunc functions, and the similarly-named methods of ServeMux, now panic if an attempt is made to register the same pattern twice.

Updating: Running go fix will update the few programs that are affected except for uses of RawURL, which must be fixed by hand.

The image package

The image package has had a number of minor changes, rearrangements and renamings.

Most of the color handling code has been moved into its own package, image/color. For the elements that moved, a symmetry arises; for instance, each pixel of an image.RGBA is a color.RGBA.

The old image/ycbcr package has been folded, with some renamings, into the image and image/color packages.

The old image.ColorImage type is still in the image package but has been renamed image.Uniform, while image.Tiled has been removed.

This table lists the renamings.

Old New
— —
image.Color color.Color
image.ColorModel color.Model
image.ColorModelFunc color.ModelFunc
image.PalettedColorModel color.Palette
— —
image.RGBAColor color.RGBA
image.RGBA64Color color.RGBA64
image.NRGBAColor color.NRGBA
image.NRGBA64Color color.NRGBA64
image.AlphaColor color.Alpha
image.Alpha16Color color.Alpha16
image.GrayColor color.Gray
image.Gray16Color color.Gray16
— —
image.RGBAColorModel color.RGBAModel
image.RGBA64ColorModel color.RGBA64Model
image.NRGBAColorModel color.NRGBAModel
image.NRGBA64ColorModel color.NRGBA64Model
image.AlphaColorModel color.AlphaModel
image.Alpha16ColorModel color.Alpha16Model
image.GrayColorModel color.GrayModel
image.Gray16ColorModel color.Gray16Model
— —
ycbcr.RGBToYCbCr color.RGBToYCbCr
ycbcr.YCbCrToRGB color.YCbCrToRGB
ycbcr.YCbCrColorModel color.YCbCrModel
ycbcr.YCbCrColor color.YCbCr
ycbcr.YCbCr image.YCbCr
— —
ycbcr.SubsampleRatio444 image.YCbCrSubsampleRatio444
ycbcr.SubsampleRatio422 image.YCbCrSubsampleRatio422
ycbcr.SubsampleRatio420 image.YCbCrSubsampleRatio420
— —
image.ColorImage image.Uniform

The image package’s New functions ( NewRGBA, NewRGBA64, etc.) take an image.Rectangle as an argument instead of four integers.

Finally, there are new predefined color.Color variables color.Black, color.White, color.Opaque and color.Transparent.

Updating: Running go fix will update almost all code affected by the change.

The log/syslog package

In Go 1, the syslog.NewLogger function returns an error as well as a log.Logger.

Updating: What little code is affected will be caught by the compiler and must be updated by hand.

The mime package

In Go 1, the FormatMediaType function of the mime package has been simplified to make it consistent with ParseMediaType. It now takes "text/html" rather than "text" and "html".

Updating: What little code is affected will be caught by the compiler and must be updated by hand.

The net package

In Go 1, the various SetTimeout, SetReadTimeout, and SetWriteTimeout methods have been replaced with SetDeadline, SetReadDeadline, and SetWriteDeadline, respectively. Rather than taking a timeout value in nanoseconds that apply to any activity on the connection, the new methods set an absolute deadline (as a time.Time value) after which reads and writes will time out and no longer block.

There are also new functions net.DialTimeout to simplify timing out dialing a network address and net.ListenMulticastUDP to allow multicast UDP to listen concurrently across multiple listeners. The net.ListenMulticastUDP function replaces the old JoinGroup and LeaveGroup methods.

Updating: Code that uses the old methods will fail to compile and must be updated by hand. The semantic change makes it difficult for the fix tool to update automatically.

The os package

The Time function has been removed; callers should use the Time type from the time package.

The Exec function has been removed; callers should use Exec from the syscall package, where available.

The ShellExpand function has been renamed to ExpandEnv.

The NewFile function now takes a uintptr fd, instead of an int. The Fd method on files now also returns a uintptr.

There are no longer error constants such as EINVAL in the os package, since the set of values varied with the underlying operating system. There are new portable functions like IsPermission to test common error properties, plus a few new error values with more Go-like names, such as ErrPermission and ErrNotExist.

The Getenverror function has been removed. To distinguish between a non-existent environment variable and an empty string, use os.Environ or syscall.Getenv.

The Process.Wait method has dropped its option argument and the associated constants are gone from the package. Also, the function Wait is gone; only the method of the Process type persists.

The Waitmsg type returned by Process.Wait has been replaced with a more portable ProcessState type with accessor methods to recover information about the process. Because of changes to Wait, the ProcessState value always describes an exited process. Portability concerns simplified the interface in other ways, but the values returned by the ProcessState.Sys and ProcessState.SysUsage methods can be type-asserted to underlying system-specific data structures such as syscall.WaitStatus and syscall.Rusage on Unix.

Updating: Running go fix will drop a zero argument to Process.Wait. All other changes will be caught by the compiler and must be updated by hand.

The os.FileInfo type

Go 1 redefines the os.FileInfo type, changing it from a struct to an interface:

    type FileInfo interface {
        Name() string       // base name of the file
        Size() int64        // length in bytes
        Mode() FileMode     // file mode bits
        ModTime() time.Time // modification time
        IsDir() bool        // abbreviation for Mode().IsDir()
        Sys() interface{}   // underlying data source (can return nil)
    }

The file mode information has been moved into a subtype called os.FileMode, a simple integer type with IsDir, Perm, and String methods.

The system-specific details of file modes and properties such as (on Unix) i-number have been removed from FileInfo altogether. Instead, each operating system’s os package provides an implementation of the FileInfo interface, which has a Sys method that returns the system-specific representation of file metadata. For instance, to discover the i-number of a file on a Unix system, unpack the FileInfo like this:

    fi, err := os.Stat("hello.go")
    if err != nil {
        log.Fatal(err)
    }
    // Check that it's a Unix file.
    unixStat, ok := fi.Sys().(*syscall.Stat_t)
    if !ok {
        log.Fatal("hello.go: not a Unix file")
    }
    fmt.Printf("file i-number: %d\n", unixStat.Ino)

Assuming (which is unwise) that "hello.go" is a Unix file, the i-number expression could be contracted to

    fi.Sys().(*syscall.Stat_t).Ino

The vast majority of uses of FileInfo need only the methods of the standard interface.

The os package no longer contains wrappers for the POSIX errors such as ENOENT. For the few programs that need to verify particular error conditions, there are now the boolean functions IsExist, IsNotExist and IsPermission.

    f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
    if os.IsExist(err) {
        log.Printf("%s already exists", name)
    }

Updating: Running go fix will update code that uses the old equivalent of the current os.FileInfo and os.FileMode API. Code that needs system-specific file details will need to be updated by hand. Code that uses the old POSIX error values from the os package will fail to compile and will also need to be updated by hand.

The os/signal package

The os/signal package in Go 1 replaces the Incoming function, which returned a channel that received all incoming signals, with the selective Notify function, which asks for delivery of specific signals on an existing channel.

Updating: Code must be updated by hand. A literal translation of

c := signal.Incoming()

is

c := make(chan os.Signal, 1)
signal.Notify(c) // ask for all signals

but most code should list the specific signals it wants to handle instead:

c := make(chan os.Signal, 1)
signal.Notify(c, syscall.SIGHUP, syscall.SIGQUIT)

The path/filepath package

In Go 1, the Walk function of the path/filepath package has been changed to take a function value of type WalkFunc instead of a Visitor interface value. WalkFunc unifies the handling of both files and directories.

    type WalkFunc func(path string, info os.FileInfo, err error) error

The WalkFunc function will be called even for files or directories that could not be opened; in such cases the error argument will describe the failure. If a directory’s contents are to be skipped, the function should return the value filepath.SkipDir

    markFn := func(path string, info os.FileInfo, err error) error {
        if path == "pictures" { // Will skip walking of directory pictures and its contents.
            return filepath.SkipDir
        }
        if err != nil {
            return err
        }
        log.Println(path)
        return nil
    }
    err := filepath.Walk(".", markFn)
    if err != nil {
        log.Fatal(err)
    }

Updating: The change simplifies most code but has subtle consequences, so affected programs will need to be updated by hand. The compiler will catch code using the old interface.

The regexp package

The regexp package has been rewritten. It has the same interface but the specification of the regular expressions it supports has changed from the old “egrep” form to that of RE2.

Updating: Code that uses the package should have its regular expressions checked by hand.

The runtime package

In Go 1, much of the API exported by package runtime has been removed in favor of functionality provided by other packages. Code using the runtime.Type interface or its specific concrete type implementations should now use package reflect. Code using runtime.Semacquire or runtime.Semrelease should use channels or the abstractions in package sync. The runtime.Alloc, runtime.Free, and runtime.Lookup functions, an unsafe API created for debugging the memory allocator, have no replacement.

Before, runtime.MemStats was a global variable holding statistics about memory allocation, and calls to runtime.UpdateMemStats ensured that it was up to date. In Go 1, runtime.MemStats is a struct type, and code should use runtime.ReadMemStats to obtain the current statistics.

The package adds a new function, runtime.NumCPU, that returns the number of CPUs available for parallel execution, as reported by the operating system kernel. Its value can inform the setting of GOMAXPROCS. The runtime.Cgocalls and runtime.Goroutines functions have been renamed to runtime.NumCgoCall and runtime.NumGoroutine.

Updating: Running go fix will update code for the function renamings. Other code will need to be updated by hand.

The strconv package

In Go 1, the strconv package has been significantly reworked to make it more Go-like and less C-like, although Atoi lives on (it’s similar to int(ParseInt(x, 10, 0)), as does Itoa(x) ( FormatInt(int64(x), 10)). There are also new variants of some of the functions that append to byte slices rather than return strings, to allow control over allocation.

This table summarizes the renamings; see the package documentation for full details.

Old call New call
— —
Atob(x) ParseBool(x)
— —
Atof32(x) ParseFloat(x, 32)§
Atof64(x) ParseFloat(x, 64)
AtofN(x, n) ParseFloat(x, n)
— —
Atoi(x) Atoi(x)
Atoi(x) ParseInt(x, 10, 0)§
Atoi64(x) ParseInt(x, 10, 64)
— —
Atoui(x) ParseUint(x, 10, 0)§
Atoui64(x) ParseUint(x, 10, 64)
— —
Btoi64(x, b) ParseInt(x, b, 64)
Btoui64(x, b) ParseUint(x, b, 64)
— —
Btoa(x) FormatBool(x)
— —
Ftoa32(x, f, p) FormatFloat(float64(x), f, p, 32)
Ftoa64(x, f, p) FormatFloat(x, f, p, 64)
FtoaN(x, f, p, n) FormatFloat(x, f, p, n)
— —
Itoa(x) Itoa(x)
Itoa(x) FormatInt(int64(x), 10)
Itoa64(x) FormatInt(x, 10)
— —
Itob(x, b) FormatInt(int64(x), b)
Itob64(x, b) FormatInt(x, b)
— —
Uitoa(x) FormatUint(uint64(x), 10)
Uitoa64(x) FormatUint(x, 10)
— —
Uitob(x, b) FormatUint(uint64(x), b)
Uitob64(x, b) FormatUint(x, b)

Updating: Running go fix will update almost all code affected by the change.
§ Atoi persists but Atoui and Atof32 do not, so they may require a cast that must be added by hand; the go fix tool will warn about it.

The template packages

The template and exp/template/html packages have moved to text/template and html/template. More significant, the interface to these packages has been simplified. The template language is the same, but the concept of “template set” is gone and the functions and methods of the packages have changed accordingly, often by elimination.

Instead of sets, a Template object may contain multiple named template definitions, in effect constructing name spaces for template invocation. A template can invoke any other template associated with it, but only those templates associated with it. The simplest way to associate templates is to parse them together, something made easier with the new structure of the packages.

Updating: The imports will be updated by fix tool. Single-template uses will be otherwise be largely unaffected. Code that uses multiple templates in concert will need to be updated by hand. The examples in the documentation for text/template can provide guidance.

The testing package

The testing package has a type, B, passed as an argument to benchmark functions. In Go 1, B has new methods, analogous to those of T, enabling logging and failure reporting.

func BenchmarkSprintf(b *testing.B) {
    // Verify correctness before running benchmark.
    b.StopTimer()
    got := fmt.Sprintf("%x", 23)
    const expect = "17"
    if expect != got {
        b.Fatalf("expected %q; got %q", expect, got)
    }
    b.StartTimer()
    for i := 0; i < b.N; i++ {
        fmt.Sprintf("%x", 23)
    }
}

Updating: Existing code is unaffected, although benchmarks that use println or panic should be updated to use the new methods.

The testing/script package

The testing/script package has been deleted. It was a dreg.

Updating: No code is likely to be affected.

The unsafe package

In Go 1, the functions unsafe.Typeof, unsafe.Reflect, unsafe.Unreflect, unsafe.New, and unsafe.NewArray have been removed; they duplicated safer functionality provided by package reflect.

Updating: Code using these functions must be rewritten to use package reflect. The changes to encoding/gob and the protocol buffer library may be helpful as examples.

The url package

In Go 1 several fields from the url.URL type were removed or replaced.

The String method now predictably rebuilds an encoded URL string using all of URL ’s fields as necessary. The resulting string will also no longer have passwords escaped.

The Raw field has been removed. In most cases the String method may be used in its place.

The old RawUserinfo field is replaced by the User field, of type *net.Userinfo. Values of this type may be created using the new net.User and net.UserPassword functions. The EscapeUserinfo and UnescapeUserinfo functions are also gone.

The RawAuthority field has been removed. The same information is available in the Host and User fields.

The RawPath field and the EncodedPath method have been removed. The path information in rooted URLs (with a slash following the schema) is now available only in decoded form in the Path field. Occasionally, the encoded data may be required to obtain information that was lost in the decoding process. These cases must be handled by accessing the data the URL was built from.

URLs with non-rooted paths, such as "mailto:dev@golang.org?subject=Hi", are also handled differently. The OpaquePath boolean field has been removed and a new Opaque string field introduced to hold the encoded path for such URLs. In Go 1, the cited URL parses as:

    URL{
        Scheme: "mailto",
        Opaque: "dev@golang.org",
        RawQuery: "subject=Hi",
    }

A new RequestURI method was added to URL.

The ParseWithReference function has been renamed to ParseWithFragment.

Updating: Code that uses the old fields will fail to compile and must be updated by hand. The semantic changes make it difficult for the fix tool to update automatically.

The go command

Go 1 introduces the go command, a tool for fetching, building, and installing Go packages and commands. The go command does away with makefiles, instead using Go source code to find dependencies and determine build conditions. Most existing Go programs will no longer require makefiles to be built.

See How to Write Go Code for a primer on the go command and the go command documentation for the full details.

Updating: Projects that depend on the Go project’s old makefile-based build infrastructure ( Make.pkg, Make.cmd, and so on) should switch to using the go command for building Go code and, if necessary, rewrite their makefiles to perform any auxiliary build tasks.

The cgo command

In Go 1, the cgo command uses a different _cgo_export.h file, which is generated for packages containing //export lines. The _cgo_export.h file now begins with the C preamble comment, so that exported function definitions can use types defined there. This has the effect of compiling the preamble multiple times, so a package using //export must not put function definitions or variable initializations in the C preamble.

Packaged releases

One of the most significant changes associated with Go 1 is the availability of prepackaged, downloadable distributions. They are available for many combinations of architecture and operating system (including Windows) and the list will grow. Installation details are described on the Getting Started page, while the distributions themselves are listed on the downloads page.

Original source ↗

Update Jun 30, 2026 tracked by Updatify

go1.7.2

go1.7.2 should not be used. It was tagged but not fully released. The release was deferred due to a last minute bug report. Use go1.7.3 instead, and refer to the summary of changes below.

Original source ↗