diff --git a/commands/build.go b/commands/build.go index d3f4addb0d8..24d7a97d52f 100644 --- a/commands/build.go +++ b/commands/build.go @@ -599,7 +599,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D flags.StringArrayVar(&options.secrets, "secret", []string{}, `Secret to expose to the build (format: "id=mysecret[,src=/local/secret]")`) - flags.Var(&options.shmSize, "shm-size", `Size of "/dev/shm"`) + flags.Var(&options.shmSize, "shm-size", `Shared memory size for build containers`) flags.StringArrayVar(&options.ssh, "ssh", []string{}, `SSH agent socket or keys to expose to the build (format: "default|[=|[,]]")`) diff --git a/docs/bake-reference.md b/docs/bake-reference.md index 712bb07fe6a..c10e8c13207 100644 --- a/docs/bake-reference.md +++ b/docs/bake-reference.md @@ -836,6 +836,9 @@ RUN --mount=type=secret,id=KUBECONFIG \ ### `target.shm-size` +Sets the size of the shared memory allocated for build containers when using +`RUN` instructions. + The format is ``. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. @@ -848,6 +851,12 @@ target "default" { } ``` +> **Note** +> +> In most cases, it is recommended to let the builder automatically determine +> the appropriate configurations. Manual adjustments should only be considered +> when specific performance tuning is required for complex build scenarios. + ### `target.ssh` Defines SSH agent sockets or keys to expose to the build. @@ -896,7 +905,8 @@ target "default" { ### `target.ulimits` -Ulimits are specified with a soft and hard limit as such: +Ulimits overrides the default ulimits of build's containers when using `RUN` +instructions and are specified with a soft and hard limit as such: `=[:]`, for example: ```hcl @@ -913,6 +923,12 @@ target "app" { > for both values. If no `ulimits` are set, they are inherited from > the default `ulimits` set on the daemon. +> **Note** +> +> In most cases, it is recommended to let the builder automatically determine +> the appropriate configurations. Manual adjustments should only be considered +> when specific performance tuning is required for complex build scenarios. + ## Group Groups allow you to invoke multiple builds (targets) at once. diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index a2cd99fbfb0..bfa75e1e414 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -46,7 +46,7 @@ Start a build | [`--sbom`](#sbom) | `string` | | Shorthand for `--attest=type=sbom` | | [`--secret`](#secret) | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) | | `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) | -| [`--shm-size`](#shm-size) | `bytes` | `0` | Size of `/dev/shm` | +| [`--shm-size`](#shm-size) | `bytes` | `0` | Shared memory size for build containers | | [`--ssh`](#ssh) | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | | [`-t`](https://docs.docker.com/reference/cli/docker/image/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/image/build/#tag) | `stringArray` | | Name and optionally a tag (format: `name:tag`) | | [`--target`](https://docs.docker.com/reference/cli/docker/image/build/#target) | `string` | | Set the target build stage to build | @@ -653,12 +653,21 @@ RUN --mount=type=bind,target=. \ $ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN . ``` -### Size of /dev/shm (--shm-size) +### Shared memory size for build containers (--shm-size) + +Sets the size of the shared memory allocated for build containers when using +`RUN` instructions. The format is ``. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. +> **Note** +> +> In most cases, it is recommended to let the builder automatically determine +> the appropriate configurations. Manual adjustments should only be considered +> when specific performance tuning is required for complex build scenarios. + ### SSH agent socket or keys to expose to the build (--ssh) ```text @@ -692,7 +701,8 @@ $ docker buildx build --ssh default=$SSH_AUTH_SOCK . ### Set ulimits (--ulimit) -`--ulimit` is specified with a soft and hard limit as such: +`--ulimit` overrides the default ulimits of build's containers when using `RUN` +instructions and are specified with a soft and hard limit as such: `=[:]`, for example: ```console @@ -704,3 +714,9 @@ $ docker buildx build --ulimit nofile=1024:1024 . > If you don't provide a `hard limit`, the `soft limit` is used > for both values. If no `ulimits` are set, they're inherited from > the default `ulimits` set on the daemon. + +> **Note** +> +> In most cases, it is recommended to let the builder automatically determine +> the appropriate configurations. Manual adjustments should only be considered +> when specific performance tuning is required for complex build scenarios. diff --git a/docs/reference/buildx_debug_build.md b/docs/reference/buildx_debug_build.md index bec821099e9..23bc018ed18 100644 --- a/docs/reference/buildx_debug_build.md +++ b/docs/reference/buildx_debug_build.md @@ -42,7 +42,7 @@ Start a build | `--sbom` | `string` | | Shorthand for `--attest=type=sbom` | | `--secret` | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) | | `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) | -| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | +| `--shm-size` | `bytes` | `0` | Shared memory size for build containers | | `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | | [`-t`](https://docs.docker.com/reference/cli/docker/image/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/image/build/#tag) | `stringArray` | | Name and optionally a tag (format: `name:tag`) | | [`--target`](https://docs.docker.com/reference/cli/docker/image/build/#target) | `string` | | Set the target build stage to build |