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

### 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.

These new language changes required a large amount of new code that has not had significant testing in production settings. That will only happen as more people write and use generic code. We believe that this feature is well implemented and high quality. However, unlike most aspects of Go, we can't back up that belief with real world experience. Therefore, while we encourage the use of generics where it makes sense, please use appropriate caution when deploying generic code in production.

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 syntax for function and type declarations now accepts type parameters.
- Parameterized functions and types can be instantiated by following them with a list of type arguments in square brackets.
- The new token `~` has been added to the set of operators and punctuation.
- The syntax for Interface types now permits the embedding of arbitrary types (not just type names of interfaces) as well as union and `~T` type elements. Such interfaces may only be used as type constraints. An interface now defines a set of types as well as a set of methods.
- The new predeclared identifier `any` is an alias for the empty interface. It may be used instead of `interface{}`.
- The new predeclared identifier `comparable` is an interface the denotes the set of all types which can be compared using `==` or `!=`. It may only be used as (or embedded in) a type constraint.

The current generics implementation has the following limitations:

- The Go compiler cannot currently handle type declarations inside generic functions or methods. We hope to provide support for this feature in Go 1.19.
- Embedding a type parameter, or a pointer to a type parameter, as an unnamed field in a struct type is not permitted. Similarly embedding a type parameter in an interface type is not permitted. Whether these will ever be permitted is unclear at present.
- A union element with more than one term may not contain an interface type with a non-empty method set. Whether this will ever be permitted is unclear at present.

### 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.

## Ports

### AMD64

Go 1.18 introduces the new `GOAMD64` environment variable, which selects at compile time a mininum target 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 can be found 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

### 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).

### 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`). 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.

The underlying data format of the embedded build information can change with new go releases, so an older version of `go` may not handle the build information produced with a newer version of `go`. To read the version information from a binary built with `go` 1.18, use the `go` `version` command and the `debug/buildinfo` package from `go` 1.18+.

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`).

The `go` `mod` `tidy` command now retains additional checksums in the `go.sum` file for modules whose source code is needed to verify that each imported package is provided by only one module in the build list. Because this condition is rare and failure to apply it results in a build error, this change is not conditioned on the `go` version in the main module's `go.mod` file.

The `go` command now supports a "Workspace" mode. If a `go.work` file is found in the working directory or a parent directory, or one is specified using the `-workfile` flag, it will put the `go` command into workspace mode. In workspace mode, the `go.work` file will be used to determine the set of main modules used as the roots for module resolution, instead of using the normally-found `go.mod` file to specify the single main module. For more information see the `go work` documentation.

The `go` command now supports additional command line options for the new fuzzing support described above:

- `go test` supports `-fuzz`, `-fuzztime`, and `-fuzzminimizetime` options. For documentation on these see `go help testflag`.
- `go clean` supports a `-fuzzcache` option. For documentation see `go help clean`.

### `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.

### `vet`

#### Updates for Generics

The `vet` tool is updated to support generic code. In most cases, it reports an error in generic code whenever it would report an error in the equivalent non-generic code after substituting for type parameters with a type from their type set. For example, `vet` reports a format error in

    func Print[T ~int|~string](t T) {
    	fmt.Printf("%d", t)
    }

because it would report a format error in the non-generic equivalent of `Print[string]`:

    func PrintString(x string) {
    	fmt.Printf("%d", x)
    }

#### Precision improvements for existing checkers

The `cmd/vet` checkers `copylock`, `printf`, `sortslice`, `testinggoroutine`, and `tests` have all had moderate precision improvements to handle additional code patterns. This may lead to newly reported errors in existing packages. For example, the `printf` checker now tracks formatting strings created by concatenating string constants. So `vet` will report an error in:

      // fmt.Printf formatting directive %d is being passed to Println.
      fmt.Println("%d"+` ≡ x (mod 2)`+"\n", x%2)

## 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.

Because of changes in the compiler related to supporting generics, the Go 1.18 compile speed can be roughly 15% slower than the Go 1.17 compile speed. The execution time of the compiled code is not affected. We intend to improve the speed of the compiler in Go 1.19.

## 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 `debug/buildinfo` package

The new `debug/buildinfo` 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.

### 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 package also defines several functions to create and examine these new types: `AddrFrom4`, `AddrFrom16`, `AddrFromSlice`, `AddrPortFrom`, `IPv4Unspecified`, `IPv6LinkLocalAllNodes`, `IPv6Unspecified`, `MustParseAddr`, `MustParseAddrPort`, `MustParsePrefix`, `ParseAddr`, `ParseAddrPort`, `ParsePrefix`, `PrefixFrom`.

The `net` package includes new methods that parallel existing methods, but return `netip.AddrPort` instead of the heavier-weight `net.IP` or `*net.UDPAddr` types: `Resolver.LookupNetIP`, `UDPConn.ReadFromUDPAddrPort`, `UDPConn.ReadMsgUDPAddrPort`, `UDPConn.WriteToUDPAddrPort`, `UDPConn.WriteMsgUDPAddrPort`. The new `UDPConn` methods support allocation-free I/O.

The `net` package also now includes functions and methods to convert between the existing `TCPAddr`/`UDPAddr` types and `netip.AddrPort`: `TCPAddrFromAddrPort`, `UDPAddrFromAddrPort`, `TCPAddr.AddrPort`, `UDPAddr.AddrPort`.

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

  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

  The new `Cut` function slices a `[]byte` around a separator. It can replace and simplify many common uses of `Index`, `IndexByte`, `IndexRune`, and `SplitN`.

  `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.

crypto/tls

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

debug/dwarf

  The `StructField` and `BasicType` structs both now have a `DataBitOffset` field, which holds the value of the `DW_AT_data_bit_offset` attribute if present.

debug/elf

  The `R_PPC64_RELATIVE` constant has been added.

debug/plan9obj

  The File.Symbols method now returns the new exported error value ErrNoSymbols if the file has no symbol section.

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

  The new `Config.GoVersion` field sets the accepted Go language version.

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

  - The new type `TypeParam`, factory function `NewTypeParam`, and associated methods are added to represent a type parameter.
  - The new type `TypeParamList` holds a list of type parameters.
  - The new type `TypeList` holds a list of types.
  - The new factory function `NewSignatureType` allocates a `Signature` with (receiver or function) type parameters. To access those type parameters, the `Signature` type has two new methods `Signature.RecvTypeParams` and `Signature.TypeParams`.
  - `Named` types have four new methods: `Named.Origin` to get the original parameterized types of instantiated types, `Named.TypeArgs` and `Named.TypeParams` to get the type arguments or type parameters of an instantiated or parameterized type, and `Named.SetTypeParams` to set the type parameters (for instance, when importing a named type where allocation of the named type and setting of type parameters cannot be done simultaneously due to possible cycles).
  - The `Interface` type has four new methods: `Interface.IsComparable` and `Interface.IsMethodSet` to query properties of the type set defined by the interface, and `Interface.MarkImplicit` and `Interface.IsImplicit` to set and test whether the interface is an implicit interface around a type constraint literal.
  - The new types `Union` and `Term`, factory functions `NewUnion` and `NewTerm`, and associated methods are added to represent type sets in interfaces.
  - The new function `Instantiate` instantiates a parameterized type.
  - The new `Info.Instances` map records function and type instantiations through the new `Instance` type.
  - The new type `ArgumentError` and associated methods are added to represent an error related to a type argument.
  - The new type `Context` and factory function `NewContext` are added to facilitate sharing of identical type instances across type-checked packages, via the new `Config.Context` field.

html/template

  Within a `range` pipeline the new `{{break}}` command will end the loop early and the new `{{continue}}` command will immediately start the next loop iteration.

  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.

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.

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.

  The new `MaxBytesHandler` function creates a `Handler` that wraps its `ResponseWriter` and `Request.Body` with a `MaxBytesReader`.

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

  `regexp` now treats each invalid byte of a UTF-8 string as `U+FFFD`.

runtime/debug

  The `BuildInfo` struct has two new fields, containing additional information about how the binary was built:

  - `GoVersion` holds the version of Go used to build the binary.
  - `Settings` is a slice of `BuildSettings` structs holding key/value pairs describing the build.

strconv

  `strconv.Unquote` now rejects Unicode surrogate halves.

strings

  The new `Cut` function slices a `string` around a separator. It can replace and simplify many common uses of `Index`, `IndexByte`, `IndexRune`, and `SplitN`.

  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.

sync

  The new methods `Mutex.TryLock`, `RWMutex.TryLock`, and `RWMutex.TryRLock`, will acquire the lock if it is not currently held.

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

  `Wrapper` interface has been removed.

testing

  The precedence of `/` in the argument for `-run` and `-bench` has been increased. `A/B|C/D` used to be treated as `A/(B|C)/D` and is now treated as `(A/B)|(C/D)`.

  If the `-run` option does not select any tests, the `-count` option is ignored. This could change the behavior of existing tests in the unlikely case that a test changes the set of subtests that are run each time the test function itself is run.

  The new `testing.F` type is used by the new fuzzing support described above. Tests also now support the command line options `-test.fuzz`, `-test.fuzztime`, and `-test.fuzzminimizetime`.

text/template

  Within a `range` pipeline the new `{{break}}` command will end the loop early and the new `{{continue}}` command will immediately start the next loop iteration.

  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.

text/template/parse

  The package supports the new text/template and html/template `{{break}}` command via the new constant `NodeBreak` and the new type `BreakNode`, and similarly supports the new `{{continue}}` command via the new constant `NodeContinue` and the new type `ContinueNode`.

unicode/utf8

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