Go 1.18 Release Notes

DRAFT RELEASE NOTES — Introduction to Go 1.18

Go 1.18 is not yet released. These are work-in-progress release notes. Go 1.18 is expected to be released in February 2022.

Changes to the language

TODO: complete this section

Generics

Go 1.18 includes an implementation of generic features as described by the Type Parameters Proposal. This includes major - but fully backward-compatible - changes to the language. The following is a list of the most visible changes. For a more comprehensive overview, see the proposal. For details see the language spec.

The current generics implementation has the following limitations:

Bug fixes

The Go 1.18 compiler now correctly reports declared but not used errors for variables that are set inside a function literal but are never used. Before Go 1.18, the compiler did not report an error in such cases. This fixes long-outstanding compiler issue #8560. As a result of this change, (possibly incorrect) programs may not compile anymore. The necessary fix is straightforward: fix the program if it was in fact incorrect, or use the offending variable, for instance by assigning it to the blank identifier _. Since go vet always pointed out this error, the number of affected programs is likely very small.

The Go 1.18 compiler now reports an overflow when passing a rune constant expression such as '1' << 32 as an argument to the predeclared functions print and println, consistent with the behavior of user-defined functions. Before Go 1.18, the compiler did not report an error in such cases but silently accepted such constant arguments if they fit into an int64. As a result of this change, (possibly incorrect) programs may not compile anymore. The necessary fix is straightforward: fix the program if it was in fact incorrect, or explicitly convert the offending argument to the correct type. Since go vet always pointed out this error, the number of affected programs is likely very small.

Fuzzing

Go 1.18 includes an implementation of fuzzing as described by the fuzzing proposal.

See the fuzzing landing page to get started.

Please be aware that fuzzing can consume a lot of memory and may impact your machine’s performance while it runs. Also be aware that the fuzzing engine writes values that expand test coverage to a fuzz cache directory within $GOCACHE/fuzz while it runs. There is currently no limit to the number of files or total bytes that may be written to the fuzz cache, so it may occupy a large amount of storage (possibly several GBs).

Ports

AMD64

Go 1.18 introduces the new GOAMD64 environment variable which selects a version of the AMD64 architecture. Allowed values are v1, v2, v3, or v4. Each higher level requires, and takes advantage of, additional processor features. A detailed description of the versions is here.

The GOAMD64 environment variable defaults to v1.

RISC-V

The 64-bit RISC-V architecture on Linux (the linux/riscv64 port) now supports the c-archive and c-shared build modes.

Windows

The windows/arm and windows/arm64 ports now support non-cooperative preemption, bringing that capability to all four Windows ports, which should hopefully address subtle bugs encountered when calling into Win32 functions that block for extended periods of time.

iOS

On iOS (the ios/arm64 port) and iOS simulator running on AMD64-based macOS (the ios/amd64 port), Go 1.18 now requires iOS 12 or later; support for previous versions has been discontinued.

FreeBSD

Go 1.18 is the last release that is supported on FreeBSD 11.x, which has already reached end-of-life. Go 1.19 will require FreeBSD 12.2+ or FreeBSD 13.0+. FreeBSD 13.0+ will require a kernel with the COMPAT_FREEBSD12 option set (this is the default).

Tools

Go command

go get no longer builds or installs packages in module-aware mode. go get is now dedicated to adjusting dependencies in go.mod. Effectively, the -d flag is always enabled. To install the latest version of an executable outside the context of the current module, use go install example.com/cmd@latest. Any version query may be used instead of latest. This form of go install was added in Go 1.16, so projects supporting older versions may need to provide install instructions for both go install and go get. go get now reports an error when used outside a module, since there is no go.mod file to update. In GOPATH mode (with GO111MODULE=off), go get still builds and installs packages, as before.

The go command now embeds version control information in binaries including the currently checked-out revision, commit time, and a flag indicating whether edited or untracked files are present. Version control information is embedded if the go command is invoked in a directory within a Git, Mercurial, Fossil, or Bazaar repository, and the main package and its containing main module are in the same repository. This information may be omitted using the flag -buildvcs=false.

Additionally, the go command embeds information about the build including build and tool tags (set with -tags), compiler, assembler, and linker flags (like -gcflags), whether cgo was enabled, and if it was, the values of the cgo environment variables (like CGO_CFLAGS). This information may be omitted using the flag -buildinfo=false. Both VCS and build information may be read together with module information using go version -m file or runtime/debug.ReadBuildInfo (for the currently running binary) or the new debug/buildinfo package.

If the main module's go.mod file specifies go 1.17 or higher, go mod download without arguments now downloads source code for only the modules explicitly required in the main module's go.mod file. (In a go 1.17 or higher module, that set already includes all dependencies needed to build the packages and tests in the main module.) To also download source code for transitive dependencies, use go mod download all.

The go mod vendor subcommand now supports a -o flag to set the output directory. (Other go commands still read from the vendor directory at the module root when loading packages with -mod=vendor, so the main use for this flag is for third-party tools that need to collect package source code.)

The go build command and related commands now support an -asan flag that enables interoperation with C (or C++) code compiled with the address sanitizer (C compiler option -fsanitize=address).

gofmt

gofmt now reads and formats input files concurrently, with a memory limit proportional to GOMAXPROCS. On a machine with multiple CPUs, gofmt should now be significantly faster.

Runtime

The garbage collector now includes non-heap sources of garbage collector work (e.g., stack scanning) when determining how frequently to run. As a result, garbage collector overhead is more predictable when these sources are significant. For most applications these changes will be negligible; however, some Go applications may now use less memory and spend more time on garbage collection, or vice versa, than before. The intended workaround is to tweak GOGC where necessary.

The runtime now returns memory to the operating system more efficiently and has been tuned to work more aggressively as a result.

Go 1.17 generally improved the formatting of arguments in stack traces, but could print inaccurate values for arguments passed in registers. This is improved in Go 1.18 by printing a question mark (?) after each value that may be inaccurate.

Compiler

Go 1.17 implemented a new way of passing function arguments and results using registers instead of the stack on 64-bit x86 architecture on selected operating systems. Go 1.18 expands the supported platforms to include 64-bit ARM (GOARCH=arm64), big- and little-endian 64-bit PowerPC (GOARCH=ppc64, ppc64le), as well as 64-bit x86 architecture (GOARCH=amd64) on all operating systems. On 64-bit ARM and 64-bit PowerPC systems, benchmarking shows typical performance improvements of 10% or more.

As mentioned in the Go 1.17 release notes, this change does not affect the functionality of any safe Go code and is designed to have no impact on most assembly code. See the Go 1.17 release notes for more details.

The compiler now can inline functions that contain range loops or labeled for loops.

The new compiler -asan option supports the new go command -asan option.

TODO: Mention build speed impact.

Linker

The new linker -asan option supports the new go command -asan option.

Core library

New constraints package

The new constraints package defines a set of useful constraints that can be used with type parameters of generic functions.

New net/netip package

The new net/netip package defines a new IP address type, Addr. Compared to the existing net.IP type, the netip.Addr type takes less memory, is immutable, and is comparable so it supports == and can be used as a map key.

In addition to Addr, the package defines AddrPort, representing an IP and port, and Prefix, representing a network CIDR prefix.

The net package now has methods to send and receive UDP packets using netip.Addr values instead of the relatively heavy *net.UDPAddr values.

TODO

TODO: complete this section

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.

TODO: complete this section

bufio

The new Writer.AvailableBuffer method returns an empty buffer with a possibly non-empty capacity for use with append-like APIs. After appending, the buffer can be provided to a succeeding Write call and possibly avoid any copying.

The methods Reader.Reset and Writer.Reset now use the default buffer size when called on objects with a nil buffer.

bytes

Trim, TrimLeft, and TrimRight are now allocation free and, especially for small ASCII cutsets, up to 10 times faster.

The Title function is now deprecated. It doesn't handle Unicode punctuation and language-specific capitalization rules, and is superseded by the golang.org/x/text/cases package.

TODO: bytes.Cut.

crypto/tls

The new Conn.NetConn method allows access to the underlying net.Conn.

debug/buildinfo

This new package provides access to module versions, version control information, and build flags embedded in executable files built by the go command. The same information is also available via runtime/debug.ReadBuildInfo for the currently running binary and via go version -m on the command line.

go/ast

Per the proposal Additions to go/ast and go/token to support parameterized functions and types the following additions are made to the go/ast package:

  • the FuncType and TypeSpec nodes have a new field TypeParams to hold type parameters, if any.
  • The new expression node IndexListExpr represents index expressions with multiple indices, used for function and type instantiations with more than one explicit type argument.

go/constant

The new Kind.String method returns a human-readable name for the receiver kind.

go/token

The new constant TILDE represents the ~ token per the proposal Additions to go/ast and go/token to support parameterized functions and types .

go/types

Per the proposal Additions to go/types to support type parameters the following additions are made to the go/types package:

image/draw

The Draw and DrawMask fallback implementations (used when the arguments are not the most common image types) are now faster when those arguments implement the optional draw.RGBA64Image and image.RGBA64Image interfaces that were added in Go 1.17.

net

net.Error.Temporary has been deprecated.

TODO: Several new net APIs.

net/http

On WebAssembly targets, the Dial, DialContext, DialTLS and DialTLSContext method fields in Transport will now be correctly used, if specified, for making HTTP requests.

The new Cookie.Valid method reports whether the cookie is valid.

os/user

User.GroupIds. now uses a Go native implementation when cgo is not available.

reflect

The new Value.SetIterKey and Value.SetIterValue methods set a Value using a map iterator as the source. They are equivalent to Value.Set(iter.Key()) and Value.Set(iter.Value()) but do fewer allocations.

The new Value.UnsafePointer method returns the Value's value as an unsafe.Pointer. This allows callers to migrate from Value.UnsafeAddr and Value.Pointer to eliminate the need to perform uintptr to unsafe.Pointer conversions at the callsite (as unsafe.Pointer rules require).

The new MapIter.Reset method changes its receiver to iterate over a different map. The use of MapIter.Reset allows allocation-free iteration over many maps.

A number of methods ( Value.CanInt, Value.CanUint, Value.CanFloat, Value.CanComplex ) have been added to Value to test if a conversion is safe.

Value.FieldByIndexErr has been added to avoid the panic that occurs in Value.FieldByIndex when stepping through a nil pointer to an embedded struct.

reflect.Ptr and reflect.PtrTo have been renamed to reflect.Pointer and reflect.PointerTo, respectively, for consistency with the rest of the reflect package. The old names will continue to work, but will be deprecated in a future Go release.

regexp

TODO: https://golang.org/cl/354569: document and implement that invalid UTF-8 bytes are the same as U+FFFD

strconv

TODO: https://golang.org/cl/343877: reject surrogate halves in Unquote

strings

The new Clone function copies the input string without the returned cloned string referencing the input string's memory.

Trim, TrimLeft, and TrimRight are now allocation free and, especially for small ASCII cutsets, up to 10 times faster.

The Title function is now deprecated. It doesn't handle Unicode punctuation and language-specific capitalization rules, and is superseded by the golang.org/x/text/cases package.

TODO: strings.Cut.

sync

TODO: https://golang.org/cl/319769: add Mutex.TryLock, RWMutex.TryLock, RWMutex.TryRLock

syscall

The new function SyscallN has been introduced for Windows, allowing for calls with arbitrary number of arguments. As a result, Syscall, Syscall6, Syscall9, Syscall12, Syscall15, and Syscall18 are deprecated in favor of SyscallN.

SysProcAttr.Pdeathsig. is now supported in FreeBSD.

syscall/js

TODO: https://golang.org/cl/356430: remove Wrapper interface

testing

TODO: https://golang.org/cl/343883: increase alternation precedence

TODO: https://golang.org/cl/356669: skip extra -count iterations if there are no tests

text/template

The and function no longer always evaluates all arguments; it stops evaluating arguments after the first argument that evaluates to false. Similarly, the or function now stops evaluating arguments after the first argument that evaluates to true. This makes a difference if any of the arguments is a function call.

unicode/utf8

The AppendRune function appends the UTF-8 new encoding of a rune to a []byte.