diff --git a/commands/build.go b/commands/build.go index f290de67..2cbf8fb6 100644 --- a/commands/build.go +++ b/commands/build.go @@ -27,6 +27,7 @@ import ( "github.com/docker/buildx/store" "github.com/docker/buildx/store/storeutil" "github.com/docker/buildx/util/buildflags" + "github.com/docker/buildx/util/cobrautil" "github.com/docker/buildx/util/desktop" "github.com/docker/buildx/util/ioset" "github.com/docker/buildx/util/metrics" @@ -537,7 +538,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D if isExperimental() { flags.StringVar(&options.printFunc, "print", "", "Print result of information request (e.g., outline, targets)") - flags.SetAnnotation("print", "experimentalCLI", nil) + cobrautil.MarkFlagsExperimental(flags, "print") } flags.BoolVar(&options.exportPush, "push", false, `Shorthand for "--output=type=registry"`) @@ -566,11 +567,9 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D if isExperimental() { // TODO: move this to debug command if needed flags.StringVar(&options.Root, "root", "", "Specify root directory of server to connect") - flags.SetAnnotation("root", "experimentalCLI", nil) flags.BoolVar(&options.Detach, "detach", false, "Detach buildx server (supported only on linux)") - flags.SetAnnotation("detach", "experimentalCLI", nil) flags.StringVar(&options.ServerConfig, "server-config", "", "Specify buildx server config file (used only when launching new server)") - flags.SetAnnotation("server-config", "experimentalCLI", nil) + cobrautil.MarkFlagsExperimental(flags, "root", "detach", "server-config") } // hidden flags @@ -593,7 +592,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D flags.BoolVar(&ignoreBool, "squash", false, "Squash newly built layers into a single new layer") flags.MarkHidden("squash") flags.SetAnnotation("squash", "flag-warn", []string{"experimental flag squash is removed with BuildKit. You should squash inside build using a multi-stage Dockerfile for efficiency."}) - flags.SetAnnotation("squash", "experimentalCLI", nil) + cobrautil.MarkFlagsExperimental(flags, "squash") flags.StringVarP(&ignore, "memory", "m", "", "Memory limit") flags.MarkHidden("memory") diff --git a/commands/debug/root.go b/commands/debug/root.go index 4d803c10..b16c75e4 100644 --- a/commands/debug/root.go +++ b/commands/debug/root.go @@ -10,6 +10,7 @@ import ( "github.com/docker/buildx/controller/control" controllerapi "github.com/docker/buildx/controller/pb" "github.com/docker/buildx/monitor" + "github.com/docker/buildx/util/cobrautil" "github.com/docker/buildx/util/progress" "github.com/docker/cli/cli/command" "github.com/moby/buildkit/util/progress/progressui" @@ -42,9 +43,6 @@ func RootCmd(dockerCli command.Cli, children ...DebuggableCmd) *cobra.Command { Use: "debug", Short: "Start debugger", Args: cobra.NoArgs, - Annotations: map[string]string{ - "experimentalCLI": "", - }, RunE: func(cmd *cobra.Command, args []string) error { printer, err := progress.NewPrinter(context.TODO(), os.Stderr, progressui.DisplayMode(progressMode)) if err != nil { @@ -73,21 +71,19 @@ func RootCmd(dockerCli command.Cli, children ...DebuggableCmd) *cobra.Command { return err }, } + cobrautil.MarkCommandExperimental(cmd) flags := cmd.Flags() flags.StringVar(&options.InvokeFlag, "invoke", "", "Launch a monitor with executing specified command") - flags.SetAnnotation("invoke", "experimentalCLI", nil) flags.StringVar(&options.OnFlag, "on", "error", "When to launch the monitor ([always, error])") - flags.SetAnnotation("on", "experimentalCLI", nil) flags.StringVar(&controlOptions.Root, "root", "", "Specify root directory of server to connect for the monitor") - flags.SetAnnotation("root", "experimentalCLI", nil) flags.BoolVar(&controlOptions.Detach, "detach", runtime.GOOS == "linux", "Detach buildx server for the monitor (supported only on linux)") - flags.SetAnnotation("detach", "experimentalCLI", nil) flags.StringVar(&controlOptions.ServerConfig, "server-config", "", "Specify buildx server config file for the monitor (used only when launching new server)") - flags.SetAnnotation("server-config", "experimentalCLI", nil) flags.StringVar(&progressMode, "progress", "auto", `Set type of progress output ("auto", "plain", "tty") for the monitor. Use plain to show container output`) + cobrautil.MarkFlagsExperimental(flags, "invoke", "on", "root", "detach", "server-config") + for _, c := range children { cmd.AddCommand(c.NewDebugger(&options)) } diff --git a/commands/root.go b/commands/root.go index 43a43a4c..780b689d 100644 --- a/commands/root.go +++ b/commands/root.go @@ -59,6 +59,10 @@ func NewRootCmd(name string, isPlugin bool, dockerCli command.Cli) *cobra.Comman "using default config store", )) + if !isExperimental() { + cmd.SetHelpTemplate(cmd.HelpTemplate() + "\nExperimental commands and flags are hidden. Set BUILDX_EXPERIMENTAL=1 to show them.\n") + } + addCommands(cmd, dockerCli) return cmd } diff --git a/docs/generate.go b/docs/generate.go index f48a3cc2..0cd0033e 100644 --- a/docs/generate.go +++ b/docs/generate.go @@ -3,6 +3,7 @@ package main import ( "log" "os" + "strings" "github.com/docker/buildx/commands" clidocstool "github.com/docker/cli-docs-tool" @@ -26,6 +27,28 @@ type options struct { formats []string } +// fixUpExperimentalCLI trims the " (EXPERIMENTAL)" suffix from the CLI output, +// as docs.docker.com already displays "experimental (CLI)", +// +// https://github.com/docker/buildx/pull/2188#issuecomment-1889487022 +func fixUpExperimentalCLI(cmd *cobra.Command) { + const ( + annotationExperimentalCLI = "experimentalCLI" + suffixExperimental = " (EXPERIMENTAL)" + ) + if _, ok := cmd.Annotations[annotationExperimentalCLI]; ok { + cmd.Short = strings.TrimSuffix(cmd.Short, suffixExperimental) + } + cmd.Flags().VisitAll(func(f *pflag.Flag) { + if _, ok := f.Annotations[annotationExperimentalCLI]; ok { + f.Usage = strings.TrimSuffix(f.Usage, suffixExperimental) + } + }) + for _, c := range cmd.Commands() { + fixUpExperimentalCLI(c) + } +} + func gen(opts *options) error { log.SetFlags(0) @@ -57,6 +80,8 @@ func gen(opts *options) error { return err } case "yaml": + // fix up is needed only for yaml (used for generating docs.docker.com contents) + fixUpExperimentalCLI(cmd) if err = c.GenYamlTree(cmd); err != nil { return err } diff --git a/docs/reference/buildx.md b/docs/reference/buildx.md index 0cd8b755..1ca845ba 100644 --- a/docs/reference/buildx.md +++ b/docs/reference/buildx.md @@ -14,7 +14,7 @@ Extended build capabilities with BuildKit | [`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 | +| [`debug`](buildx_debug.md) | Start debugger (EXPERIMENTAL) | | [`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 | diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index 2df9e8dc..5d4e916e 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -25,7 +25,7 @@ Start a build | [`--cache-from`](#cache-from) | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) | | [`--cache-to`](#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) | +| `--detach` | | | Detach buildx server (supported only on linux) (EXPERIMENTAL) | | [`-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 | @@ -36,16 +36,16 @@ Start a build | [`--no-cache-filter`](#no-cache-filter) | `stringArray` | | Do not cache specified stages | | [`-o`](#output), [`--output`](#output) | `stringArray` | | Output destination (format: `type=local,dest=path`) | | [`--platform`](#platform) | `stringArray` | | Set target platform for build | -| `--print` | `string` | | Print result of information request (e.g., outline, targets) | +| `--print` | `string` | | Print result of information request (e.g., outline, targets) (EXPERIMENTAL) | | [`--progress`](#progress) | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output | | [`--provenance`](#provenance) | `string` | | Shorthand for `--attest=type=provenance` | | `--pull` | | | Always attempt to pull all referenced images | | [`--push`](#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 | +| `--root` | `string` | | Specify root directory of server to connect (EXPERIMENTAL) | | [`--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) | +| `--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` | | [`--ssh`](#ssh) | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | | [`-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`) | diff --git a/docs/reference/buildx_debug.md b/docs/reference/buildx_debug.md index c9a85629..565ab0ab 100644 --- a/docs/reference/buildx_debug.md +++ b/docs/reference/buildx_debug.md @@ -1,7 +1,7 @@ # docker buildx debug -Start debugger +Start debugger (EXPERIMENTAL) ### Subcommands @@ -15,12 +15,12 @@ Start debugger | 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` | `error` | When to launch the monitor ([always, error]) | +| `--detach` | | | Detach buildx server for the monitor (supported only on linux) (EXPERIMENTAL) | +| `--invoke` | `string` | | Launch a monitor with executing specified command (EXPERIMENTAL) | +| `--on` | `string` | `error` | When to launch the monitor ([always, error]) (EXPERIMENTAL) | | `--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) | +| `--root` | `string` | | Specify root directory of server to connect for the monitor (EXPERIMENTAL) | +| `--server-config` | `string` | | Specify buildx server config file for the monitor (used only when launching new server) (EXPERIMENTAL) | diff --git a/docs/reference/buildx_debug_build.md b/docs/reference/buildx_debug_build.md index 1aa69eb8..78633d92 100644 --- a/docs/reference/buildx_debug_build.md +++ b/docs/reference/buildx_debug_build.md @@ -21,7 +21,7 @@ Start a build | `--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) | +| `--detach` | | | Detach buildx server (supported only on linux) (EXPERIMENTAL) | | [`-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 | @@ -32,16 +32,16 @@ Start a build | `--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) | +| `--print` | `string` | | Print result of information request (e.g., outline, targets) (EXPERIMENTAL) | | `--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 | +| `--root` | `string` | | Specify root directory of server to connect (EXPERIMENTAL) | | `--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) | +| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) | | `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | | `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | | [`-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`) | diff --git a/util/cobrautil/cobrautil.go b/util/cobrautil/cobrautil.go index 9b53dffe..71633bb1 100644 --- a/util/cobrautil/cobrautil.go +++ b/util/cobrautil/cobrautil.go @@ -1,6 +1,10 @@ package cobrautil -import "github.com/spf13/cobra" +import ( + "github.com/sirupsen/logrus" + "github.com/spf13/cobra" + "github.com/spf13/pflag" +) // HideInheritedFlags hides inherited flags func HideInheritedFlags(cmd *cobra.Command, hidden ...string) { @@ -12,3 +16,38 @@ func HideInheritedFlags(cmd *cobra.Command, hidden ...string) { _ = cmd.Flags().MarkHidden(h) } } + +const annotationExperimentalCLI = "experimentalCLI" + +func MarkFlagExperimental(f *pflag.Flag) { + if _, ok := f.Annotations[annotationExperimentalCLI]; ok { + return + } + if f.Annotations == nil { + f.Annotations = make(map[string][]string) + } + f.Annotations[annotationExperimentalCLI] = nil + f.Usage += " (EXPERIMENTAL)" +} + +func MarkFlagsExperimental(fs *pflag.FlagSet, names ...string) { + for _, name := range names { + f := fs.Lookup(name) + if f == nil { + logrus.Warningf("Unknown flag name %q", name) + continue + } + MarkFlagExperimental(f) + } +} + +func MarkCommandExperimental(c *cobra.Command) { + if _, ok := c.Annotations[annotationExperimentalCLI]; ok { + return + } + if c.Annotations == nil { + c.Annotations = make(map[string]string) + } + c.Annotations[annotationExperimentalCLI] = "" + c.Short += " (EXPERIMENTAL)" +}