mirror of
https://gitea.com/Lydanne/buildx.git
synced 2025-07-15 07:57:07 +08:00
debug: Add buildx debug command
Signed-off-by: Kohei Tokunaga <ktokunaga.mail@gmail.com>
This commit is contained in:
Kohei Tokunaga
@ -19,11 +19,13 @@ your environment.
|
||||
$ export BUILDX_EXPERIMENTAL=1
|
||||
```
|
||||
|
||||
To start a debug session for a build, you can use the `--invoke` flag with the
|
||||
build command to specify a command to launch in the resulting image.
|
||||
To start a debug session for a build, you can use the `buildx debug` command with `--invoke` flag to specify a command to launch in the resulting image.
|
||||
`buildx debug` command provides `buildx debug build` subcommand that provides the same features as the normal `buildx build` command but allows launching the debugger session after the build.
|
||||
|
||||
Arguments available after `buildx debug build` are the same as the normal `buildx build`.
|
||||
|
||||
```console
|
||||
$ docker buildx build --invoke /bin/sh .
|
||||
$ docker buildx debug --invoke /bin/sh build .
|
||||
[+] Building 4.2s (19/19) FINISHED
|
||||
=> [internal] connecting to local controller 0.0s
|
||||
=> [internal] load build definition from Dockerfile 0.0s
|
||||
@ -56,16 +58,16 @@ Supported keys are `args` (can be JSON array format), `entrypoint` (can be JSON
|
||||
Example:
|
||||
|
||||
```
|
||||
$ docker buildx build --invoke 'entrypoint=["sh"],"args=[""-c"", ""env | grep -e FOO -e AAA""]","env=[""FOO=bar"", ""AAA=bbb""]"' .
|
||||
$ docker buildx debug --invoke 'entrypoint=["sh"],"args=[""-c"", ""env | grep -e FOO -e AAA""]","env=[""FOO=bar"", ""AAA=bbb""]"' build .
|
||||
```
|
||||
|
||||
#### `on-error`
|
||||
#### `on` flag
|
||||
|
||||
If you want to start a debug session when a build fails, you can use
|
||||
`--invoke=on-error` to start a debug session when the build fails.
|
||||
`--on=error` to start a debug session when the build fails.
|
||||
|
||||
```console
|
||||
$ docker buildx build --invoke on-error .
|
||||
$ docker buildx debug --on=error build .
|
||||
[+] Building 4.2s (19/19) FINISHED
|
||||
=> [internal] connecting to local controller 0.0s
|
||||
=> [internal] load build definition from Dockerfile 0.0s
|
||||
@ -85,13 +87,13 @@ Interactive container was restarted with process "edmzor60nrag7rh1mbi4o9lm8". Pr
|
||||
|
||||
This allows you to explore the state of the image when the build failed.
|
||||
|
||||
#### `debug-shell`
|
||||
#### Launch the debug session directly with `buildx debug` subcommand
|
||||
|
||||
If you want to drop into a debug session without first starting the build, you
|
||||
can use `--invoke=debug-shell` to start a debug session.
|
||||
can use `buildx debug` command to start a debug session.
|
||||
|
||||
```
|
||||
$ docker buildx build --invoke debug-shell .
|
||||
$ docker buildx debug
|
||||
[+] Building 4.2s (19/19) FINISHED
|
||||
=> [internal] connecting to local controller 0.0s
|
||||
(buildx)
|
||||
@ -135,15 +137,15 @@ To detach the build process from the CLI, you can use the `--detach=true` flag w
|
||||
the build command.
|
||||
|
||||
```console
|
||||
$ docker buildx build --detach=true --invoke /bin/sh .
|
||||
$ docker buildx debug --invoke /bin/sh build --detach=true .
|
||||
```
|
||||
|
||||
If you start a debugging session using the `--invoke` flag with a detached
|
||||
build, then you can attach to it using the `buildx debug-shell` subcommand to
|
||||
build, then you can attach to it using the `buildx debug` command to
|
||||
immediately enter the monitor mode.
|
||||
|
||||
```console
|
||||
$ docker buildx debug-shell
|
||||
$ docker buildx debug
|
||||
[+] Building 0.0s (1/1) FINISHED
|
||||
=> [internal] connecting to remote controller
|
||||
(buildx) list
|
||||
|
||||
@ -9,21 +9,21 @@ Extended build capabilities with BuildKit
|
||||
|
||||
### Subcommands
|
||||
|
||||
| Name | Description |
|
||||
|:---------------------------------------|:---------------------------------------|
|
||||
| [`bake`](buildx_bake.md) | Build from a file |
|
||||
| [`build`](buildx_build.md) | Start a build |
|
||||
| [`create`](buildx_create.md) | Create a new builder instance |
|
||||
| [`debug-shell`](buildx_debug-shell.md) | Start a monitor |
|
||||
| [`du`](buildx_du.md) | Disk usage |
|
||||
| [`imagetools`](buildx_imagetools.md) | Commands to work on images in registry |
|
||||
| [`inspect`](buildx_inspect.md) | Inspect current builder instance |
|
||||
| [`ls`](buildx_ls.md) | List builder instances |
|
||||
| [`prune`](buildx_prune.md) | Remove build cache |
|
||||
| [`rm`](buildx_rm.md) | Remove a builder instance |
|
||||
| [`stop`](buildx_stop.md) | Stop builder instance |
|
||||
| [`use`](buildx_use.md) | Set the current builder instance |
|
||||
| [`version`](buildx_version.md) | Show buildx version information |
|
||||
| Name | Description |
|
||||
|:-------------------------------------|:---------------------------------------|
|
||||
| [`bake`](buildx_bake.md) | Build from a file |
|
||||
| [`build`](buildx_build.md) | Start a build |
|
||||
| [`create`](buildx_create.md) | Create a new builder instance |
|
||||
| [`debug`](buildx_debug.md) | Start debugger |
|
||||
| [`du`](buildx_du.md) | Disk usage |
|
||||
| [`imagetools`](buildx_imagetools.md) | Commands to work on images in registry |
|
||||
| [`inspect`](buildx_inspect.md) | Inspect current builder instance |
|
||||
| [`ls`](buildx_ls.md) | List builder instances |
|
||||
| [`prune`](buildx_prune.md) | Remove build cache |
|
||||
| [`rm`](buildx_rm.md) | Remove a builder instance |
|
||||
| [`stop`](buildx_stop.md) | Stop builder instance |
|
||||
| [`use`](buildx_use.md) | Set the current builder instance |
|
||||
| [`version`](buildx_version.md) | Show buildx version information |
|
||||
|
||||
|
||||
### Options
|
||||
|
||||
@ -28,7 +28,6 @@ Start a build
|
||||
| `--detach` | | | Detach buildx server (supported only on linux) |
|
||||
| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#file), [`--file`](https://docs.docker.com/engine/reference/commandline/build/#file) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) |
|
||||
| `--iidfile` | `string` | | Write the image ID to the file |
|
||||
| `--invoke` | `string` | | Invoke a command after the build |
|
||||
| `--label` | `stringArray` | | Set metadata for an image |
|
||||
| [`--load`](#load) | | | Shorthand for `--output=type=docker` |
|
||||
| [`--metadata-file`](#metadata-file) | `string` | | Write build result metadata to the file |
|
||||
|
||||
@ -1,18 +0,0 @@
|
||||
# docker buildx debug-shell
|
||||
|
||||
<!---MARKER_GEN_START-->
|
||||
Start a monitor
|
||||
|
||||
### Options
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
|:------------------|:---------|:--------|:-----------------------------------------------------------------------------------------|
|
||||
| `--builder` | `string` | | Override the configured builder instance |
|
||||
| `--detach` | | | Detach buildx server (supported only on linux) |
|
||||
| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output |
|
||||
| `--root` | `string` | | Specify root directory of server to connect |
|
||||
| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) |
|
||||
|
||||
|
||||
<!---MARKER_GEN_END-->
|
||||
|
||||
27
docs/reference/buildx_debug.md
Normal file
27
docs/reference/buildx_debug.md
Normal file
@ -0,0 +1,27 @@
|
||||
# docker buildx debug
|
||||
|
||||
<!---MARKER_GEN_START-->
|
||||
Start debugger
|
||||
|
||||
### Subcommands
|
||||
|
||||
| Name | Description |
|
||||
|:---------------------------------|:--------------|
|
||||
| [`build`](buildx_debug_build.md) | Start a build |
|
||||
|
||||
|
||||
### Options
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
|:------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------|
|
||||
| `--builder` | `string` | | Override the configured builder instance |
|
||||
| `--detach` | | | Detach buildx server for the monitor (supported only on linux) |
|
||||
| `--invoke` | `string` | | Launch a monitor with executing specified command |
|
||||
| `--on` | `string` | | When to launch the monitor ([always, error]) |
|
||||
| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`) for the monitor. Use plain to show container output |
|
||||
| `--root` | `string` | | Specify root directory of server to connect for the monitor |
|
||||
| `--server-config` | `string` | | Specify buildx server config file for the monitor (used only when launching new server) |
|
||||
|
||||
|
||||
<!---MARKER_GEN_END-->
|
||||
|
||||
52
docs/reference/buildx_debug_build.md
Normal file
52
docs/reference/buildx_debug_build.md
Normal file
@ -0,0 +1,52 @@
|
||||
# docker buildx debug build
|
||||
|
||||
<!---MARKER_GEN_START-->
|
||||
Start a build
|
||||
|
||||
### Aliases
|
||||
|
||||
`docker buildx debug build`, `docker buildx debug b`
|
||||
|
||||
### Options
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
|:-------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------------|
|
||||
| [`--add-host`](https://docs.docker.com/engine/reference/commandline/build/#add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) |
|
||||
| `--allow` | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) |
|
||||
| `--attest` | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) |
|
||||
| `--build-arg` | `stringArray` | | Set build-time variables |
|
||||
| `--build-context` | `stringArray` | | Additional build contexts (e.g., name=path) |
|
||||
| `--builder` | `string` | | Override the configured builder instance |
|
||||
| `--cache-from` | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) |
|
||||
| `--cache-to` | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) |
|
||||
| [`--cgroup-parent`](https://docs.docker.com/engine/reference/commandline/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
|
||||
| `--detach` | | | Detach buildx server (supported only on linux) |
|
||||
| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#file), [`--file`](https://docs.docker.com/engine/reference/commandline/build/#file) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) |
|
||||
| `--iidfile` | `string` | | Write the image ID to the file |
|
||||
| `--label` | `stringArray` | | Set metadata for an image |
|
||||
| `--load` | | | Shorthand for `--output=type=docker` |
|
||||
| `--metadata-file` | `string` | | Write build result metadata to the file |
|
||||
| `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build |
|
||||
| `--no-cache` | | | Do not use cache when building the image |
|
||||
| `--no-cache-filter` | `stringArray` | | Do not cache specified stages |
|
||||
| `-o`, `--output` | `stringArray` | | Output destination (format: `type=local,dest=path`) |
|
||||
| `--platform` | `stringArray` | | Set target platform for build |
|
||||
| `--print` | `string` | | Print result of information request (e.g., outline, targets) |
|
||||
| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output |
|
||||
| `--provenance` | `string` | | Shorthand for `--attest=type=provenance` |
|
||||
| `--pull` | | | Always attempt to pull all referenced images |
|
||||
| `--push` | | | Shorthand for `--output=type=registry` |
|
||||
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
|
||||
| `--root` | `string` | | Specify root directory of server to connect |
|
||||
| `--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) |
|
||||
| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
|
||||
| `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
|
||||
| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag), [`--tag`](https://docs.docker.com/engine/reference/commandline/build/#tag) | `stringArray` | | Name and optionally a tag (format: `name:tag`) |
|
||||
| [`--target`](https://docs.docker.com/engine/reference/commandline/build/#target) | `string` | | Set the target build stage to build |
|
||||
| `--ulimit` | `ulimit` | | Ulimit options |
|
||||
|
||||
|
||||
<!---MARKER_GEN_END-->
|
||||
|
||||
Reference in New Issue
Block a user