Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: make buildx build the canonical reference doc #5002

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+390 −667
Open

docs: make buildx build the canonical reference doc #5002

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
12 changes: 8 additions & 4 deletions cli/command/image/build.go
View file
Open in desktop
Expand Up @@ -15,6 +15,7 @@ import (
"strings"

"github.com/distribution/reference"
"github.com/docker/cli-docs-tool/annotation"
"github.com/docker/cli/cli"
"github.com/docker/cli/cli/command"
"github.com/docker/cli/cli/command/image/build"
Expand Down Expand Up @@ -103,10 +104,6 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
options.context = args[0]
return runBuild(cmd.Context(), dockerCli, options)
},
Annotations: map[string]string{
"category-top": "4",
"aliases": "docker image build, docker build, docker buildx build, docker builder build",
},
ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
return nil, cobra.ShellCompDirectiveFilterDirs
},
Expand All @@ -115,9 +112,12 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
flags := cmd.Flags()

flags.VarP(&options.tags, "tag", "t", `Name and optionally a tag in the "name:tag" format`)
flags.SetAnnotation("tag", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#tag"})
flags.Var(&options.buildArgs, "build-arg", "Set build-time variables")
flags.SetAnnotation("build-arg", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg"})
flags.Var(options.ulimits, "ulimit", "Ulimit options")
flags.StringVarP(&options.dockerfileName, "file", "f", "", `Name of the Dockerfile (Default is "PATH/Dockerfile")`)
flags.SetAnnotation("file", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#file"})
flags.VarP(&options.memory, "memory", "m", "Memory limit")
flags.Var(&options.memorySwap, "memory-swap", `Swap limit equal to memory plus swap: -1 to enable unlimited swap`)
flags.Var(&options.shmSize, "shm-size", `Size of "/dev/shm"`)
Expand All @@ -127,6 +127,7 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
flags.StringVar(&options.cpuSetCpus, "cpuset-cpus", "", "CPUs in which to allow execution (0-3, 0,1)")
flags.StringVar(&options.cpuSetMems, "cpuset-mems", "", "MEMs in which to allow execution (0-3, 0,1)")
flags.StringVar(&options.cgroupParent, "cgroup-parent", "", `Set the parent cgroup for the "RUN" instructions during build`)
flags.SetAnnotation("cgroup-parent", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#cgroup-parent"})
flags.StringVar(&options.isolation, "isolation", "", "Container isolation technology")
flags.Var(&options.labels, "label", "Set metadata for an image")
flags.BoolVar(&options.noCache, "no-cache", false, "Do not use cache when building the image")
Expand All @@ -139,8 +140,11 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
flags.StringSliceVar(&options.securityOpt, "security-opt", []string{}, "Security options")
flags.StringVar(&options.networkMode, "network", "default", "Set the networking mode for the RUN instructions during build")
flags.SetAnnotation("network", "version", []string{"1.25"})
flags.SetAnnotation("network", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#network"})
flags.Var(&options.extraHosts, "add-host", `Add a custom host-to-IP mapping ("host:ip")`)
flags.SetAnnotation("add-host", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#add-host"})
flags.StringVar(&options.target, "target", "", "Set the target build stage to build.")
flags.SetAnnotation("target", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#target"})
flags.StringVar(&options.imageIDFile, "iidfile", "", "Write the image ID to the file")

command.AddTrustVerificationFlags(flags, &options.untrusted, dockerCli.ContentTrustEnabled())
Expand Down
68 changes: 32 additions & 36 deletions docs/reference/commandline/build.md
View file
Open in desktop
Expand Up @@ -3,44 +3,40 @@
<!---MARKER_GEN_START-->
Build an image from a Dockerfile

### Aliases

`docker image build`, `docker build`, `docker buildx build`, `docker builder build`

### Options

| Name | Type | Default | Description |
|:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
| `--build-arg` | `list` | | Set build-time variables |
| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build |
| `--compress` | | | Compress the build context using gzip |
| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
| `--disable-content-trust` | `bool` | `true` | Skip image verification |
| `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
| `--force-rm` | | | Always remove intermediate containers |
| `--iidfile` | `string` | | Write the image ID to the file |
| `--isolation` | `string` | | Container isolation technology |
| `--label` | `list` | | Set metadata for an image |
| `-m`, `--memory` | `bytes` | `0` | Memory limit |
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build |
| `--no-cache` | | | Do not use cache when building the image |
| `--platform` | `string` | | Set platform if server is multi-platform capable |
| `--pull` | | | Always attempt to pull a newer version of the image |
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
| `--security-opt` | `stringSlice` | | Security options |
| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
| `--squash` | | | Squash newly built layers into a single new layer |
| `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format |
| `--target` | `string` | | Set the target build stage to build. |
| `--ulimit` | `ulimit` | | Ulimit options |
| Name | Type | Default | Description |
|:-----------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
| [`--add-host`](https://docs.docker.com/reference/cli/docker/buildx/build/#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
| [`--build-arg`](https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg) | `list` | | Set build-time variables |
| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
| [`--cgroup-parent`](https://docs.docker.com/reference/cli/docker/buildx/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
| `--compress` | | | Compress the build context using gzip |
| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
| `--disable-content-trust` | `bool` | `true` | Skip image verification |
| [`-f`](https://docs.docker.com/reference/cli/docker/buildx/build/#file), [`--file`](https://docs.docker.com/reference/cli/docker/buildx/build/#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
| `--force-rm` | | | Always remove intermediate containers |
| `--iidfile` | `string` | | Write the image ID to the file |
| `--isolation` | `string` | | Container isolation technology |
| `--label` | `list` | | Set metadata for an image |
| `-m`, `--memory` | `bytes` | `0` | Memory limit |
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
| [`--network`](https://docs.docker.com/reference/cli/docker/buildx/build/#network) | `string` | `default` | Set the networking mode for the RUN instructions during build |
| `--no-cache` | | | Do not use cache when building the image |
| `--platform` | `string` | | Set platform if server is multi-platform capable |
| `--pull` | | | Always attempt to pull a newer version of the image |
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
| `--security-opt` | `stringSlice` | | Security options |
| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
| `--squash` | | | Squash newly built layers into a single new layer |
| [`-t`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag) | `list` | | Name and optionally a tag in the `name:tag` format |
| [`--target`](https://docs.docker.com/reference/cli/docker/buildx/build/#target) | `string` | | Set the target build stage to build. |
| `--ulimit` | `ulimit` | | Ulimit options |


<!---MARKER_GEN_END-->
Expand Down