diff --git a/README.md b/README.md index e4595caff..2ed57c849 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Go Report Card](https://goreportcard.com/badge/github.com/docker/buildx?style=flat-square)](https://goreportcard.com/report/github.com/docker/buildx) [![codecov](https://img.shields.io/codecov/c/github/docker/buildx?logo=codecov&style=flat-square)](https://codecov.io/gh/docker/buildx) -`buildx` is a Docker CLI plugin for extended build capabilities with +Buildx is a Docker CLI plugin for extended build capabilities with [BuildKit](https://github.com/moby/buildkit). Key features: @@ -16,7 +16,7 @@ Key features: - Multiple builder instance support - Multi-node builds for cross-platform images - Compose build support -- High-level build constructs (`bake`) +- High-level build options (`bake`) - In-container driver support (both Docker and Kubernetes) # Table of Contents @@ -26,10 +26,9 @@ Key features: - [Linux packages](#linux-packages) - [Manual download](#manual-download) - [Dockerfile](#dockerfile) -- [Set buildx as the default builder](#set-buildx-as-the-default-builder) - [Building](#building) - [Getting started](#getting-started) - - [Building with buildx](#building-with-buildx) + - [Building with Buildx](#building-with-buildx) - [Working with builder instances](#working-with-builder-instances) - [Building multi-platform images](#building-multi-platform-images) - [Reference](docs/reference/buildx.md) @@ -49,12 +48,9 @@ Key features: - [`buildx version`](docs/reference/buildx_version.md) - [Contributing](#contributing) -For more information on how to use Buildx, see -[Docker Build docs](https://docs.docker.com/build/). - # Installing -Using `buildx` with Docker requires Docker engine 19.03 or newer. +Using Buildx with Docker requires Docker engine 19.03 or newer. > [!WARNING] > Using an incompatible version of Docker may result in unexpected behavior, @@ -75,9 +71,9 @@ Docker Engine package repositories contain Docker Buildx packages when installed ## Manual download > [!IMPORTANT] -> This section is for unattended installation of the buildx component. These +> This section is for unattended installation of the Buildx component. These > instructions are mostly suitable for testing purposes. We do not recommend -> installing buildx using manual download in production environments as they +> installing Buildx using manual download in production environments as they > will not be updated automatically with security updates. > > On Windows and macOS, we recommend that you install [Docker Desktop](https://docs.docker.com/desktop/) @@ -87,11 +83,11 @@ You can also download the latest binary from the [GitHub releases page](https:// Rename the relevant binary and copy it to the destination matching your OS: -| OS | Binary name | Destination folder | -| -------- | -------------------- | -----------------------------------------| -| Linux | `docker-buildx` | `$HOME/.docker/cli-plugins` | -| macOS | `docker-buildx` | `$HOME/.docker/cli-plugins` | -| Windows | `docker-buildx.exe` | `%USERPROFILE%\.docker\cli-plugins` | +| OS | Binary name | Destination folder | +|---------|---------------------|-------------------------------------| +| Linux | `docker-buildx` | `$HOME/.docker/cli-plugins` | +| macOS | `docker-buildx` | `$HOME/.docker/cli-plugins` | +| Windows | `docker-buildx.exe` | `%USERPROFILE%\.docker\cli-plugins` | Or copy it into one of these folders for installing it system-wide. @@ -123,14 +119,6 @@ COPY --from=docker/buildx-bin /buildx /usr/libexec/docker/cli-plugins/docker-bui RUN docker buildx version ``` -# Set buildx as the default builder - -Running the command [`docker buildx install`](docs/reference/buildx_install.md) -sets up docker builder command as an alias to `docker buildx build`. This -results in the ability to have `docker build` use the current buildx builder. - -To remove this alias, run [`docker buildx uninstall`](docs/reference/buildx_uninstall.md). - # Building ```console @@ -151,17 +139,17 @@ $ make install # Getting started -## Building with buildx +## Building with Buildx Buildx is a Docker CLI plugin that extends the `docker build` command with the -full support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit) +full support of the features provided by [Moby BuildKit](https://docs.docker.com/build/buildkit/) builder toolkit. It provides the same user experience as `docker build` with many new features like creating scoped builder instances and building against multiple nodes concurrently. -After installation, buildx can be accessed through the `docker buildx` command -with Docker 19.03. `docker buildx build` is the command for starting a new -build. With Docker versions older than 19.03 buildx binary can be called +After installation, Buildx can be accessed through the `docker buildx` command +with Docker 19.03. `docker buildx build` is the command for starting a new +build. With Docker versions older than 19.03 Buildx binary can be called directly to access the `docker buildx` subcommands. ```console @@ -180,20 +168,25 @@ are not yet available for regular `docker build` like building manifest lists, distributed caching, and exporting build results to OCI image tarballs. Buildx is flexible and can be run in different configurations that are exposed -through various "drivers". Each driver defines how and where a build should -run, and have different feature sets. +through various [drivers](https://docs.docker.com/build/builders/drivers/). +Each driver defines how and where a build should run, and have different +feature sets. We currently support the following drivers: -- The `docker` driver ([guide](https://docs.docker.com/build/drivers/docker/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) -- The `docker-container` driver ([guide](https://docs.docker.com/build/drivers/docker-container/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) -- The `kubernetes` driver ([guide](https://docs.docker.com/build/drivers/kubernetes/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) -- The `remote` driver ([guide](https://docs.docker.com/build/drivers/remote/)) +- The `docker` driver ([manual](https://docs.docker.com/build/builders/drivers/docker/)) +- The `docker-container` driver ([manual](https://docs.docker.com/build/builders/drivers/docker-container/)) +- The `kubernetes` driver ([manual](https://docs.docker.com/build/drivers/kubernetes/)) +- The `remote` driver ([manual](https://docs.docker.com/build/builders/drivers/remote/)) -For more information on drivers, see the [drivers guide](https://docs.docker.com/build/drivers/). +For more information, see the [builders](https://docs.docker.com/build/builders/) +and [drivers](https://docs.docker.com/build/builders/drivers/) guide. + +> [!NOTE] +> For more information, see [Docker Build docs](https://docs.docker.com/build/concepts/overview/). ## Working with builder instances -By default, buildx will initially use the `docker` driver if it is supported, +By default, Buildx will initially use the `docker` driver if it is supported, providing a very similar user experience to the native `docker build`. Note that you must use a local shared daemon to build your applications. @@ -212,7 +205,7 @@ while creating the new builder. After creating a new instance, you can manage it lifecycle using the [`docker buildx inspect`](docs/reference/buildx_inspect.md), [`docker buildx stop`](docs/reference/buildx_stop.md), and [`docker buildx rm`](docs/reference/buildx_rm.md) commands. To list all -available builders, use [`buildx ls`](docs/reference/buildx_ls.md). After +available builders, use [`docker buildx ls`](docs/reference/buildx_ls.md). After creating a new builder you can also append new nodes to it. To switch between different builders, use [`docker buildx use `](docs/reference/buildx_use.md). @@ -223,9 +216,12 @@ Docker also features a [`docker context`](https://docs.docker.com/engine/referen command that can be used for giving names for remote Docker API endpoints. Buildx integrates with `docker context` so that all of your contexts automatically get a default builder instance. While creating a new builder -instance or when adding a node to it you can also set the context name as the +instance or when adding a node to it, you can also set the context name as the target. +> [!NOTE] +> For more information, see [Builders docs](https://docs.docker.com/build/builders/). + ## Building multi-platform images BuildKit is designed to work well for building for multiple platforms and not @@ -239,8 +235,8 @@ platform for the build output, (for example, `linux/amd64`, `linux/arm64`, or When the current builder instance is backed by the `docker-container` or `kubernetes` driver, you can specify multiple platforms together. In this case, it builds a manifest list which contains images for all specified architectures. -When you use this image in [`docker run`](https://docs.docker.com/engine/reference/commandline/run/) -or [`docker service`](https://docs.docker.com/engine/reference/commandline/service/), +When you use this image in [`docker run`](https://docs.docker.com/reference/cli/docker/container/run/) +or [`docker service`](https://docs.docker.com/reference/cli/docker/service/), Docker picks the correct image based on the node's platform. You can build multi-platform images using three different strategies that are @@ -304,6 +300,9 @@ COPY --from=build /log /log You can also use [`tonistiigi/xx`](https://github.com/tonistiigi/xx) Dockerfile cross-compilation helpers for more advanced use-cases. +> [!NOTE] +> For more information, see [Multi-platform builds docs](https://docs.docker.com/build/building/multi-platform/). + ## High-level build options See [High-level builds with Bake](https://docs.docker.com/build/bake/) for more details.