-- 00-preface.md --
<!--
NOTE: In this document and others in this directory, the convention is to
set fixed-width phrases with non-fixed-width spaces, as in
`hello` `world`.
Do not send CLs removing the interior tags from such phrases.
-->

<style>
  main ul li { margin: 0.5em 0; }
</style>
-- 1-intro.md --
## Introduction to Go 1.21 {#introduction}

The latest Go release, version 1.21, arrives six months after [Go 1.20](/doc/go1.20).

-- 2-language/-heading.md --
## Changes to the language {#language}
-- 2-language/1-built-ins.md --
Go 1.21 adds three new built-ins to the language.

-- 2-language/2-init.md --
<!-- https://go.dev/issue/57411 -->
Package initialization order is now specified more precisely. The
new algorithm is:

- Sort all packages by import path.
- Repeat until the list of packages is empty:
  - Find the first package in the list for which all imports are
    already initialized.
  - Initialize that package and remove it from the list.

-- 2-language/3-inference.md --
Multiple improvements that increase the power and precision of type inference have been made.

-- 2-language/4-loopvar.md --
Go 1.21 includes a preview of a language change we are considering for a future version of Go:
making for loop variables per-iteration instead of per-loop, to avoid accidental sharing bugs.

-- 3-tools/-heading.md --
## Tools {#tools}
-- 3-tools/1-compat.md --
Go 1.21 adds improved support for backwards compatibility and forwards compatibility
in the Go toolchain.

-- 3-tools/2-go-cmd/-heading.md --
### Go command {#go-command}

-- 3-tools/2-go-cmd/c.md --
The `-C` `dir` flag must now be the first
flag on the command-line when used.

-- 3-tools/2-go-cmd/fullpath.md --
<!-- https://go.dev/issue/37708, CL 463837 -->
The new `go` `test` option
`-fullpath` prints full path names in test log messages,
rather than just base names.

-- 3-tools/3-cgo.md --
### Cgo {#cgo}

<!-- CL 490819 -->
In files that `import "C"`, the Go toolchain now
correctly reports errors for attempts to declare Go methods on C types.

-- 4-runtime/-heading.md --
## Runtime {#runtime-changes}
-- 4-runtime/misc.md --
<!-- https://go.dev/issue/7181 -->
When printing very deep stacks, the runtime now prints the first 50
(innermost) frames followed by the bottom 50 (outermost) frames,
rather than just printing the first 100 frames. This makes it easier
to see how deeply recursive stacks started, and is especially
valuable for debugging stack overflows.

-- 5-compiler.md --
## Compiler {#compiler}

Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready
for general use.

-- 6-assembler.md --
## Assembler {#assembler}


<!-- https://go.dev/issue/58378 -->

On amd64, frameless nosplit assembly functions are no longer automatically marked as `NOFRAME`.
Instead, the `NOFRAME` attribute must be explicitly specified if desired,
which is already the behavior on other architectures supporting frame pointers.
With this, the runtime now maintains the frame pointers for stack transitions.

-- 7-stdlib/-heading.md --
## Core library {#library}
-- 7-stdlib/1-slog.md --
### New log/slog package {#slog}

The new [log/slog](/pkg/log/slog) package provides structured logging with levels.

### New testing/slogtest package {#slogtest}

The new [testing/slogtest](/pkg/testing/slogtest) package can help
to validate [slog.Handler](/pkg/log/slog#Handler) implementations.

-- 7-stdlib/2-slices.md --
### New slices package {#slices}

The new [slices](/pkg/slices) package provides many common
operations on slices, using generic functions that work with slices
of any element type.

-- 7-stdlib/99-minor/-heading.md --
### Minor changes to the library {#minor_library_changes}

As always, there are various minor changes and updates to the library,
made with the Go 1 [promise of compatibility](/doc/go1compat)
in mind.
There are also various performance improvements, not enumerated here.

-- 7-stdlib/99-minor/archive/tar/54451.md --

<!-- https://go.dev/issue/54451, CL 491175 -->
The implementation of the
[`io/fs.FileInfo`](/pkg/io/fs/#FileInfo)
interface returned by
[`Header.FileInfo`](/pkg/archive/tar/#Header.FileInfo)
now implements a `String` method that calls
[`io/fs.FormatFileInfo`](/pkg/io/fs/#FormatFileInfo).

-- 7-stdlib/99-minor/archive/zip/54451.md --

<!-- https://go.dev/issue/54451, CL 491175 -->
The implementation of the
[`io/fs.FileInfo`](/pkg/io/fs/#FileInfo)
interface returned by
[`FileHeader.FileInfo`](/pkg/archive/zip/#FileHeader.FileInfo)
now implements a `String` method that calls
[`io/fs.FormatFileInfo`](/pkg/io/fs/#FormatFileInfo).

-- 7-stdlib/99-minor/bytes/53685.md --

<!-- https://go.dev/issue/53685, CL 474635 -->
The [`Buffer`](/pkg/bytes/#Buffer) type
has two new methods:
[`Available`](/pkg/bytes/#Buffer.Available)
and [`AvailableBuffer`](/pkg/bytes/#Buffer.AvailableBuffer).
These may be used along with the
[`Write`](/pkg/bytes/#Buffer.Write)
method to append directly to the `Buffer`.
ways different. 

-- 7-stdlib/99-minor/debug/elf/56887.md --

<!-- https://go.dev/issue/56887, CL 452496 -->
The constant flags permitted in a `DT_FLAGS_1`
dynamic tag are now defined with type
[`DynFlag1`](/pkg/debug/elf/#DynFlag1). These
tags have names starting with `DF_1`.

<!-- CL 473256 -->
The package now defines the constant
[`COMPRESS_ZSTD`](/pkg/debug/elf/#COMPRESS_ZSTD).

-- 7-stdlib/99-minor/debug/elf/56892.md --

<!-- https://go.dev/issue/56892, CL 452617 -->
The new
[`File.DynValue`](/pkg/debug/elf/#File.DynValue)
method may be used to retrieve the numeric values listed with a
given dynamic tag.

-- 7-stdlib/99-minor/debug/elf/60348.md --

<!-- https://go.dev/issue/60348, CL 496918 -->
The package now defines the constant
[`R_PPC64_REL24_P9NOTOC`](/pkg/debug/elf/#R_PPC64_REL24_P9NOTOC).


-- 7-stdlib/99-minor/net/59166.md --

<!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
<!-- CL 471136, CL 471137, CL 471140 -->
On Linux, the [net](/pkg/net/) package can now use
Multipath TCP when the kernel supports it.

-- 7-stdlib/99-minor/net/http/123.md --


<!-- CL 472636 -->
The new [`ResponseController.EnableFullDuplex`](/pkg/net/http#ResponseController.EnableFullDuplex)
method allows server handlers to concurrently read from an HTTP/1
request body while writing the response. Normally, the HTTP/1 server
automatically consumes any remaining request body before starting to
write the response, to avoid deadlocking clients which attempt to
write a complete request before reading the response. The
`EnableFullDuplex` method disables this behavior.

-- 8-ports/-heading.md --
## Ports {#ports}
-- 8-ports/darwin.md --

### Darwin {#darwin}

<!-- https://go.dev/issue/57125 -->
As [announced](go1.20#darwin) in the Go 1.20 release notes,
Go 1.21 requires macOS 10.15 Catalina or later;
support for previous versions has been discontinued.
-- 8-ports/windows.md --
### Windows {#windows}

<!-- https://go.dev/issue/57003, https://go.dev/issue/57004 -->
As [announced](go1.20#windows) in the Go 1.20 release notes,
Go 1.21 requires at least Windows 10 or Windows Server 2016;
support for previous versions has been discontinued.

<!-- CL 470695 -->

<!-- cmd/dist: default to GOARM=7 on all non-arm systems -->
-- 8-ports/wasm.md --
### WebAssembly {#wasm}

<!-- https://go.dev/issue/38248, https://go.dev/issue/59149, CL 489255 -->
The new `go:wasmimport` directive can now be used in Go programs
to import functions from the WebAssembly host.

<!-- https://go.dev/issue/56100 -->

The Go scheduler now interacts much more efficiently with the
JavaScript event loop, especially in applications that block
frequently on asynchronous events.

### WebAssembly System Interface {#wasip1}

<!-- https://go.dev/issue/58141 -->
Go 1.21 adds an experimental port to the [
WebAssembly System Interface (WASI)](https://wasi.dev/), Preview 1
(`GOOS=wasip1`, `GOARCH=wasm`).

As a result of the addition of the new `GOOS` value
"`wasip1`", Go files named `*_wasip1.go`
will now be [ignored
by Go tools](/pkg/go/build/#hdr-Build_Constraints) except when that `GOOS` value is being
used.
If you have existing filenames matching that pattern, you will
need to rename them.
-- want --
<!--
NOTE: In this document and others in this directory, the convention is to
set fixed-width phrases with non-fixed-width spaces, as in
`hello` `world`.
Do not send CLs removing the interior tags from such phrases.
-->

<style>
  main ul li { margin: 0.5em 0; }
</style>

## Introduction to Go 1.21 {#introduction}

The latest Go release, version 1.21, arrives six months after [Go 1.20](/doc/go1.20).

## Changes to the language {#language}

Go 1.21 adds three new built-ins to the language.

<!-- https://go.dev/issue/57411 -->
Package initialization order is now specified more precisely. The
new algorithm is:

- Sort all packages by import path.
- Repeat until the list of packages is empty:
  - Find the first package in the list for which all imports are
    already initialized.
  - Initialize that package and remove it from the list.

Multiple improvements that increase the power and precision of type inference have been made.

Go 1.21 includes a preview of a language change we are considering for a future version of Go:
making for loop variables per-iteration instead of per-loop, to avoid accidental sharing bugs.

## Tools {#tools}

Go 1.21 adds improved support for backwards compatibility and forwards compatibility
in the Go toolchain.

### Go command {#go-command}

The `-C` `dir` flag must now be the first
flag on the command-line when used.

<!-- https://go.dev/issue/37708, CL 463837 -->
The new `go` `test` option
`-fullpath` prints full path names in test log messages,
rather than just base names.

### Cgo {#cgo}

<!-- CL 490819 -->
In files that `import "C"`, the Go toolchain now
correctly reports errors for attempts to declare Go methods on C types.

## Runtime {#runtime-changes}

<!-- https://go.dev/issue/7181 -->
When printing very deep stacks, the runtime now prints the first 50
(innermost) frames followed by the bottom 50 (outermost) frames,
rather than just printing the first 100 frames. This makes it easier
to see how deeply recursive stacks started, and is especially
valuable for debugging stack overflows.

## Compiler {#compiler}

Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready
for general use.

## Assembler {#assembler}


<!-- https://go.dev/issue/58378 -->

On amd64, frameless nosplit assembly functions are no longer automatically marked as `NOFRAME`.
Instead, the `NOFRAME` attribute must be explicitly specified if desired,
which is already the behavior on other architectures supporting frame pointers.
With this, the runtime now maintains the frame pointers for stack transitions.

## Core library {#library}

### New log/slog package {#slog}

The new [log/slog](/pkg/log/slog) package provides structured logging with levels.

### New testing/slogtest package {#slogtest}

The new [testing/slogtest](/pkg/testing/slogtest) package can help
to validate [slog.Handler](/pkg/log/slog#Handler) implementations.

### New slices package {#slices}

The new [slices](/pkg/slices) package provides many common
operations on slices, using generic functions that work with slices
of any element type.

### Minor changes to the library {#minor_library_changes}

As always, there are various minor changes and updates to the library,
made with the Go 1 [promise of compatibility](/doc/go1compat)
in mind.
There are also various performance improvements, not enumerated here.

#### [`archive/tar`](/pkg/archive/tar/)

<!-- https://go.dev/issue/54451, CL 491175 -->
The implementation of the
[`io/fs.FileInfo`](/pkg/io/fs/#FileInfo)
interface returned by
[`Header.FileInfo`](/pkg/archive/tar/#Header.FileInfo)
now implements a `String` method that calls
[`io/fs.FormatFileInfo`](/pkg/io/fs/#FormatFileInfo).

#### [`archive/zip`](/pkg/archive/zip/)

<!-- https://go.dev/issue/54451, CL 491175 -->
The implementation of the
[`io/fs.FileInfo`](/pkg/io/fs/#FileInfo)
interface returned by
[`FileHeader.FileInfo`](/pkg/archive/zip/#FileHeader.FileInfo)
now implements a `String` method that calls
[`io/fs.FormatFileInfo`](/pkg/io/fs/#FormatFileInfo).

#### [`bytes`](/pkg/bytes/)

<!-- https://go.dev/issue/53685, CL 474635 -->
The [`Buffer`](/pkg/bytes/#Buffer) type
has two new methods:
[`Available`](/pkg/bytes/#Buffer.Available)
and [`AvailableBuffer`](/pkg/bytes/#Buffer.AvailableBuffer).
These may be used along with the
[`Write`](/pkg/bytes/#Buffer.Write)
method to append directly to the `Buffer`.
ways different.

#### [`debug/elf`](/pkg/debug/elf/)

<!-- https://go.dev/issue/56887, CL 452496 -->
The constant flags permitted in a `DT_FLAGS_1`
dynamic tag are now defined with type
[`DynFlag1`](/pkg/debug/elf/#DynFlag1). These
tags have names starting with `DF_1`.

<!-- CL 473256 -->
The package now defines the constant
[`COMPRESS_ZSTD`](/pkg/debug/elf/#COMPRESS_ZSTD).

<!-- https://go.dev/issue/56892, CL 452617 -->
The new
[`File.DynValue`](/pkg/debug/elf/#File.DynValue)
method may be used to retrieve the numeric values listed with a
given dynamic tag.

<!-- https://go.dev/issue/60348, CL 496918 -->
The package now defines the constant
[`R_PPC64_REL24_P9NOTOC`](/pkg/debug/elf/#R_PPC64_REL24_P9NOTOC).

#### [`net`](/pkg/net/)

<!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
<!-- CL 471136, CL 471137, CL 471140 -->
On Linux, the [net](/pkg/net/) package can now use
Multipath TCP when the kernel supports it.

#### [`net/http`](/pkg/net/http/)

<!-- CL 472636 -->
The new [`ResponseController.EnableFullDuplex`](/pkg/net/http#ResponseController.EnableFullDuplex)
method allows server handlers to concurrently read from an HTTP/1
request body while writing the response. Normally, the HTTP/1 server
automatically consumes any remaining request body before starting to
write the response, to avoid deadlocking clients which attempt to
write a complete request before reading the response. The
`EnableFullDuplex` method disables this behavior.

## Ports {#ports}

### Darwin {#darwin}

<!-- https://go.dev/issue/57125 -->
As [announced](go1.20#darwin) in the Go 1.20 release notes,
Go 1.21 requires macOS 10.15 Catalina or later;
support for previous versions has been discontinued.

### WebAssembly {#wasm}

<!-- https://go.dev/issue/38248, https://go.dev/issue/59149, CL 489255 -->
The new `go:wasmimport` directive can now be used in Go programs
to import functions from the WebAssembly host.

<!-- https://go.dev/issue/56100 -->

The Go scheduler now interacts much more efficiently with the
JavaScript event loop, especially in applications that block
frequently on asynchronous events.

### WebAssembly System Interface {#wasip1}

<!-- https://go.dev/issue/58141 -->
Go 1.21 adds an experimental port to the [
WebAssembly System Interface (WASI)](https://wasi.dev/), Preview 1
(`GOOS=wasip1`, `GOARCH=wasm`).

As a result of the addition of the new `GOOS` value
"`wasip1`", Go files named `*_wasip1.go`
will now be [ignored
by Go tools](/pkg/go/build/#hdr-Build_Constraints) except when that `GOOS` value is being
used.
If you have existing filenames matching that pattern, you will
need to rename them.

### Windows {#windows}

<!-- https://go.dev/issue/57003, https://go.dev/issue/57004 -->
As [announced](go1.20#windows) in the Go 1.20 release notes,
Go 1.21 requires at least Windows 10 or Windows Server 2016;
support for previous versions has been discontinued.

<!-- CL 470695 -->

<!-- cmd/dist: default to GOARM=7 on all non-arm systems -->