Skip to content

enable experimental commands by default, and remove BUILDX_EXPERIMENTAL env-var #3241

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

Open
thaJeztah wants to merge 7 commits into
base: master
Choose a base branch
from
+9 −83
Open

enable experimental commands by default, and remove BUILDX_EXPERIMENTAL env-var #3241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
164bb43
remove "experimental" hint from help / usage output
thaJeztah Jun 13, 2025
baf1b1e
commands: enable experimental commands by default
thaJeztah Jul 3, 2025
74da0d6
remove uses of BUILDX_EXPERIMENTAL for generating docs
thaJeztah Jul 3, 2025
59525fc
util/confutil: remove IsExperimental() utility
thaJeztah Jul 3, 2025
9691c01
tests: remove redundant cleanup
thaJeztah Jul 3, 2025
5f704ad
remove "experimental" integration tests
thaJeztah Jul 3, 2025
484ab1b
docs: remove use of BUILDX_EXPERIMENTAL as example
thaJeztah Jul 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 0 additions & 24 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,40 +62,19 @@ jobs:
- remote
pkg:
- ./tests
mode:
- ""
- experimental
include:
- worker: docker
pkg: ./tests
- worker: docker+containerd # same as docker, but with containerd snapshotter
pkg: ./tests
- worker: docker
pkg: ./tests
mode: experimental
- worker: docker+containerd # same as docker, but with containerd snapshotter
pkg: ./tests
mode: experimental
- worker: "[email protected]"
pkg: ./tests
- worker: "[email protected]" # same as docker, but with containerd snapshotter
pkg: ./tests
- worker: "[email protected]"
pkg: ./tests
mode: experimental
- worker: "[email protected]" # same as docker, but with containerd snapshotter
pkg: ./tests
mode: experimental
- worker: "[email protected]"
pkg: ./tests
- worker: "[email protected]" # same as docker, but with containerd snapshotter
pkg: ./tests
- worker: "[email protected]"
pkg: ./tests
mode: experimental
- worker: "[email protected]" # same as docker, but with containerd snapshotter
pkg: ./tests
mode: experimental
steps:
-
name: Prepare
Expand All @@ -116,9 +95,6 @@ jobs:
if [[ "${{ matrix.worker }}" == "docker"* ]]; then
echo "TEST_DOCKERD=1" >> $GITHUB_ENV
fi
if [ "${{ matrix.mode }}" = "experimental" ]; then
echo "TEST_BUILDX_EXPERIMENTAL=1" >> $GITHUB_ENV
fi
-
name: Checkout
uses: actions/checkout@v4
Expand Down
15 changes: 5 additions & 10 deletions commands/root.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ import (
historycmd "github.com/docker/buildx/commands/history"
imagetoolscmd "github.com/docker/buildx/commands/imagetools"
"github.com/docker/buildx/util/cobrautil/completion"
"github.com/docker/buildx/util/confutil"
"github.com/docker/buildx/util/logutil"
"github.com/docker/cli-docs-tool/annotation"
"github.com/docker/cli/cli"
Expand Down Expand Up @@ -84,10 +83,6 @@ func NewRootCmd(name string, isPlugin bool, dockerCli *command.DockerCli) *cobra
"using default config store",
))

if !confutil.IsExperimental() {
Copy link
Member Author

@thaJeztah thaJeztah Jun 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also considering if we should just (as we did for the CLI) always enable the debug command;

buildx/commands/root.go

Lines 121 to 123 in 08dd378

if confutil.IsExperimental() {
cmd.AddCommand(debugCmd(dockerCli, opts))
}

The output already shows it's experimental;

BUILDX_EXPERIMENTAL=1 docker buildx debug --help
Usage:  docker buildx debug [OPTIONS] COMMAND

Start debugger (EXPERIMENTAL)

EXPERIMENTAL:
  docker buildx debug is an experimental feature.
  Experimental features provide early access to product functionality. These
  features may change between releases without warning, or can be removed from a
  future release. Learn more about experimental features in our documentation:
  https://docs.docker.com/go/experimental/

Copy link
Member

@crazy-max crazy-max Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also considering if we should just (as we did for the CLI) always enable the debug command

With on-going work with debug command related to new DAP implementation I think we should keep it experimental for now:

Copy link
Member Author

@thaJeztah thaJeztah Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I was considering that we would have it visible, but call out that it's experimental? It may help getting more people to try it if we don't require config changes, as long as we explicitly call out that it's experimental?

Copy link
Member

@crazy-max crazy-max Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the future I agree that we should deprecate BUILDX_EXPERIMENTAL as the CLI already marks commands as experimental anyway.

Copy link
Collaborator

@jsternberg jsternberg Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For what it's worth, the debug adapter stuff is going under another command in dap. Right now, debug controls the monitor. We do potentially have plans to completely remove the debug command and integrate it directly with build.

Copy link
Member

@crazy-max crazy-max Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed with @tonistiigi, we would need to always enable the debug command if we are removing this hint from help so users are aware of it.

cmd.SetHelpTemplate(cmd.HelpTemplate() + "\nExperimental commands and flags are hidden. Set BUILDX_EXPERIMENTAL=1 to show them.\n")
}

addCommands(cmd, &opt, dockerCli)
return cmd
}
Expand Down Expand Up @@ -117,13 +112,13 @@ func addCommands(cmd *cobra.Command, opts *rootOptions, dockerCli command.Cli) {
duCmd(dockerCli, opts),
imagetoolscmd.RootCmd(cmd, dockerCli, imagetoolscmd.RootOptions{Builder: &opts.builder}),
historycmd.RootCmd(cmd, dockerCli, historycmd.RootOptions{Builder: &opts.builder}),

// experimental commands
debugCmd(dockerCli, opts),
dapCmd(dockerCli, opts),
)
if confutil.IsExperimental() {
cmd.AddCommand(debugCmd(dockerCli, opts))
cmd.AddCommand(dapCmd(dockerCli, opts))
}

cmd.RegisterFlagCompletionFunc( //nolint:errcheck
_ = cmd.RegisterFlagCompletionFunc(
"builder",
completion.BuilderNames(dockerCli),
)
Expand Down
2 changes: 0 additions & 2 deletions docker-bake.hcl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,6 @@ target "validate-docs" {
inherits = ["_common"]
args = {
FORMATS = DOCS_FORMATS
BUILDX_EXPERIMENTAL = 1 // enables experimental cmds/flags for docs generation
}
dockerfile = "./hack/dockerfiles/docs.Dockerfile"
target = "validate"
Expand All @@ -116,7 +115,6 @@ target "update-docs" {
inherits = ["_common"]
args = {
FORMATS = DOCS_FORMATS
BUILDX_EXPERIMENTAL = 1 // enables experimental cmds/flags for docs generation
}
dockerfile = "./hack/dockerfiles/docs.Dockerfile"
target = "update"
Expand Down
8 changes: 4 additions & 4 deletions docs/bake-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -632,7 +632,7 @@ from both the `app-dev` and `_release` targets.
target "app-dev" {
args = {
GO_VERSION = "1.20"
BUILDX_EXPERIMENTAL = 1
ENABLE_DEBUG = 1
}
tags = ["docker.io/username/myapp"]
dockerfile = "app.Dockerfile"
Expand All @@ -644,7 +644,7 @@ target "app-dev" {
target "_release" {
args = {
BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
BUILDX_EXPERIMENTAL = 0
ENABLE_DEBUG = 0
}
}

Expand All @@ -656,7 +656,7 @@ target "app-release" {

When inheriting attributes from multiple targets and there's a conflict,
the target that appears last in the `inherits` list takes precedence.
The previous example defines the `BUILDX_EXPERIMENTAL` argument twice for the `app-release` target.
The previous example defines the `ENABLE_DEBUG` argument twice for the `app-release` target.
It resolves to `0` because the `_release` target appears last in the inheritance chain:

```console
Expand All @@ -676,7 +676,7 @@ $ docker buildx bake --print app-release
"dockerfile": "app.Dockerfile",
"args": {
"BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1",
"BUILDX_EXPERIMENTAL": "0",
"ENABLE_DEBUG": "0",
"GO_VERSION": "1.20"
},
"labels": {
Expand Down
7 changes: 0 additions & 7 deletions docs/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,6 @@ state of the build environment at any point.

## Starting the debugger

To start the debugger, first, ensure that `BUILDX_EXPERIMENTAL=1` is set in
your environment.

```console
$ export BUILDX_EXPERIMENTAL=1
```

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.

Expand Down
3 changes: 0 additions & 3 deletions docs/reference/buildx_build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,6 @@ Start a build

<!---MARKER_GEN_END-->

Flags marked with `[experimental]` need to be explicitly enabled by setting the
`BUILDX_EXPERIMENTAL=1` environment variable.

## Description

The `docker buildx build` command starts a build using BuildKit.
Expand Down
1 change: 0 additions & 1 deletion hack/dockerfiles/docs.Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ RUN apk add --no-cache rsync git
WORKDIR /src
COPY --from=docsgen /out/docsgen /usr/bin
ARG FORMATS
ARG BUILDX_EXPERIMENTAL
RUN --mount=target=/context \
--mount=target=.,type=tmpfs <<EOT
set -e
Expand Down
2 changes: 0 additions & 2 deletions hack/test
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ set -eu -o pipefail
: "${TEST_DOCKERD=}"
: "${TEST_BUILDKIT_TAG=}"
: "${TEST_BUILDKIT_IMAGE=}"
: "${TEST_BUILDX_EXPERIMENTAL=}"

if [ "$TEST_IMAGE_BUILD" = "1" ]; then
${BUILDX_CMD} bake integration-test --set "*.output=type=docker,name=$TEST_IMAGE_ID"
Expand Down Expand Up @@ -54,7 +53,6 @@ cid=$(docker create --rm --privileged $dockerConfigMount \
-e TEST_DOCKERD \
-e TEST_BUILDKIT_IMAGE \
-e TEST_BUILDKIT_TAG \
-e TEST_BUILDX_EXPERIMENTAL \
-e SKIP_INTEGRATION_TESTS \
-e GOTESTSUM_FORMAT \
-e GO_TEST_COVERPROFILE \
Expand Down
15 changes: 0 additions & 15 deletions tests/integration.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ import (
"os/exec"
"path/filepath"
"reflect"
"strconv"
"strings"
"sync"
"testing"
Expand Down Expand Up @@ -64,9 +63,6 @@ func buildxCmd(sb integration.Sandbox, opts ...cmdOpt) *exec.Cmd {
if context := sb.DockerAddress(); context != "" {
cmd.Env = append(cmd.Env, "DOCKER_CONTEXT="+context)
}
if isExperimental() {
cmd.Env = append(cmd.Env, "BUILDX_EXPERIMENTAL=1")
}
if v := os.Getenv("GO_TEST_COVERPROFILE"); v != "" {
coverDir := filepath.Join(filepath.Dir(v), "helpers")
cmd.Env = append(cmd.Env, "GOCOVERDIR="+coverDir)
Expand Down Expand Up @@ -128,14 +124,6 @@ func driverName(sbName string) (string, bool, bool) {
return name, hasVersion, hasFeature
}

func isExperimental() bool {
if v, ok := os.LookupEnv("TEST_BUILDX_EXPERIMENTAL"); ok {
vv, _ := strconv.ParseBool(v)
return vv
}
return false
}

func buildkitTag() string {
if v := os.Getenv("TEST_BUILDKIT_TAG"); v != "" {
return v
Expand Down Expand Up @@ -172,9 +160,6 @@ func buildkitVersion(t *testing.T, sb integration.Sandbox) string {
require.NoError(t, err, "undock not found")

destDir := t.TempDir()
t.Cleanup(func() {
os.RemoveAll(destDir)
})
Comment on lines -175 to -177
Copy link
Member Author

@thaJeztah thaJeztah Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really related, but my IDE was complaining about the unhandled error, and it was redundant, so added a commit to remove it 😂


cmd := exec.Command(undockBin, "--cachedir", "/root/.cache/undock", "--include", "/usr/bin/buildkitd", "--rm-dist", buildkitImage, destDir)
require.NoErrorf(t, cmd.Run(), "failed to extract buildkitd binary from %q", buildkitImage)
Expand Down
15 changes: 0 additions & 15 deletions util/confutil/exp.go
View file
Open in desktop

This file was deleted.