build: pass BuildOptions around explicitly & fix multi-platform issues

The big change here is to pass around an explicit `*BuildOptions` object
as part of Compose operations like `up` & `run` that may or may not do
builds. If the options object is `nil`, no builds whatsoever will be
attempted.

Motivation is to allow for partial rebuilds in the context of an `up`
for watch. This was broken and tricky to accomplish because various parts
of the Compose APIs mutate the `*Project` for convenience in ways that
make it unusable afterwards. (For example, it might set `service.Build = nil`
because it's not going to build that service right _then_. But we might
still want to build it later!)

NOTE: This commit does not actually touch the watch logic. This is all
      in preparation to make it possible.

As part of this, a bunch of code moved around and I eliminated a bunch
of partially redundant logic, mostly around multi-platform. Several
edge cases have been addressed as part of this:
 * `DOCKER_DEFAULT_PLATFORM` was _overriding_ explicitly set platforms
   in some cases, this is no longer true, and it behaves like the Docker
   CLI now
 * It was possible for Compose to build an image for one platform and
   then try to run it for a different platform (and fail)
 * Errors are no longer returned if a local image exists but for the
   wrong platform - the correct platform will be fetched/built (if
   possible).

Because there's a LOT of subtlety and tricky logic here, I've also tried
to add an excessive amount of explanatory comments.

Signed-off-by: Milas Bowman <[email protected]>

Author: milas

cmd/compose/build.go

@@ -35,7 +35,6 @@ import (
 
 type buildOptions struct {
 	*ProjectOptions
-	composeOptions
 	quiet   bool
 	pull    bool
 	push    bool
@@ -73,7 +72,7 @@ func (opts buildOptions) toAPIBuildOptions(services []string) (api.BuildOptions,
 	}, nil
 }
 
-func buildCommand(p *ProjectOptions, progress *string, backend api.Service) *cobra.Command {
+func buildCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	opts := buildOptions{
 		ProjectOptions: p,
 	}
@@ -118,7 +117,7 @@ func buildCommand(p *ProjectOptions, progress *string, backend api.Service) *cob
 	cmd.Flags().Bool("no-rm", false, "Do not remove intermediate containers after a successful build. DEPRECATED")
 	cmd.Flags().MarkHidden("no-rm") //nolint:errcheck
 	cmd.Flags().VarP(&opts.memory, "memory", "m", "Set memory limit for the build container. Not supported by BuildKit.")
-	cmd.Flags().StringVar(progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of ui output (%s)`, strings.Join(printerModes, ", ")))
+	cmd.Flags().StringVar(&p.Progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of ui output (%s)`, strings.Join(printerModes, ", ")))
 	cmd.Flags().MarkHidden("progress") //nolint:errcheck
 
 	return cmd
@@ -130,6 +129,10 @@ func runBuild(ctx context.Context, backend api.Service, opts buildOptions, servi
 		return err
 	}
 
+	if err := applyPlatforms(project, false); err != nil {
+		return err
+	}
+
 	apiBuildOptions, err := opts.toAPIBuildOptions(services)
 	if err != nil {
 		return err

cmd/compose/compose.go

@@ -26,8 +26,9 @@ import (
 	"strings"
 	"syscall"
 
-	"github.com/compose-spec/compose-go/dotenv"
 	buildx "github.com/docker/buildx/util/progress"
+
+	"github.com/compose-spec/compose-go/dotenv"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/remote"
 
@@ -117,6 +118,7 @@ type ProjectOptions struct {
 	ProjectDir    string
 	EnvFiles      []string
 	Compatibility bool
+	Progress      string
 }
 
 // ProjectFunc does stuff within a types.Project
@@ -170,6 +172,7 @@ func (o *ProjectOptions) addProjectFlags(f *pflag.FlagSet) {
 	f.StringVar(&o.ProjectDir, "project-directory", "", "Specify an alternate working directory\n(default: the path of the, first specified, Compose file)")
 	f.StringVar(&o.WorkDir, "workdir", "", "DEPRECATED! USE --project-directory INSTEAD.\nSpecify an alternate working directory\n(default: the path of the, first specified, Compose file)")
 	f.BoolVar(&o.Compatibility, "compatibility", false, "Run compose in backward compatibility mode")
+	f.StringVar(&o.Progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of progress output (%s)`, strings.Join(printerModes, ", ")))
 	_ = f.MarkHidden("workdir")
 }
 
@@ -294,7 +297,6 @@ func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //
 		version  bool
 		parallel int
 		dryRun   bool
-		progress string
 	)
 	c := &cobra.Command{
 		Short:            "Docker Compose",
@@ -359,7 +361,7 @@ func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //
 				ui.Mode = ui.ModeTTY
 			}
 
-			switch progress {
+			switch opts.Progress {
 			case ui.ModeAuto:
 				ui.Mode = ui.ModeAuto
 			case ui.ModeTTY:
@@ -375,7 +377,7 @@ func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //
 			case ui.ModeQuiet, "none":
 				ui.Mode = ui.ModeQuiet
 			default:
-				return fmt.Errorf("unsupported --progress value %q", progress)
+				return fmt.Errorf("unsupported --progress value %q", opts.Progress)
 			}
 
 			if opts.WorkDir != "" {
@@ -446,7 +448,7 @@ func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //
 		portCommand(&opts, dockerCli, backend),
 		imagesCommand(&opts, dockerCli, backend),
 		versionCommand(dockerCli),
-		buildCommand(&opts, &progress, backend),
+		buildCommand(&opts, backend),
 		pushCommand(&opts, backend),
 		pullCommand(&opts, backend),
 		createCommand(&opts, backend),
@@ -478,8 +480,6 @@ func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //
 		completeProfileNames(&opts),
 	)
 
-	c.Flags().StringVar(&progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of progress output (%s)`, strings.Join(printerModes, ", ")))
-
 	c.Flags().StringVar(&ansi, "ansi", "auto", `Control when to print ANSI control characters ("never"|"always"|"auto")`)
 	c.Flags().IntVar(&parallel, "parallel", -1, `Control max parallelism, -1 for unlimited`)
 	c.Flags().BoolVarP(&version, "version", "v", false, "Show the Docker Compose version information")

cmd/compose/create.go

@@ -123,6 +123,9 @@ func (opts createOptions) Apply(project *types.Project) error {
 			project.Services[i] = service
 		}
 	}
+	// N.B. opts.Build means "force build all", but images can still be built
+	// when this is false
+	// e.g. if a service has pull_policy: build or its local image is missing
 	if opts.Build {
 		for i, service := range project.Services {
 			if service.Build == nil {
@@ -132,6 +135,7 @@ func (opts createOptions) Apply(project *types.Project) error {
 			project.Services[i] = service
 		}
 	}
+	// opts.noBuild, however, means do not perform ANY builds
 	if opts.noBuild {
 		for i, service := range project.Services {
 			service.Build = nil
@@ -141,6 +145,11 @@ func (opts createOptions) Apply(project *types.Project) error {
 			project.Services[i] = service
 		}
 	}
+
+	if err := applyPlatforms(project, true); err != nil {
+		return err
+	}
+
 	for _, scale := range opts.scale {
 		split := strings.Split(scale, "=")
 		if len(split) != 2 {

cmd/compose/options.go

@@ -0,0 +1,76 @@
+/*
+   Copyright 2023 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package compose
+
+import (
+	"fmt"
+
+	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/compose/v2/pkg/utils"
+)
+
+func applyPlatforms(project *types.Project, buildForSinglePlatform bool) error {
+	defaultPlatform := project.Environment["DOCKER_DEFAULT_PLATFORM"]
+	for i := range project.Services {
+		// mutable reference so platform fields can be updated
+		service := &project.Services[i]
+
+		if service.Build == nil {
+			continue
+		}
+
+		// default platform only applies if the service doesn't specify
+		if defaultPlatform != "" && service.Platform == "" {
+			if len(service.Build.Platforms) > 0 && !utils.StringContains(service.Build.Platforms, defaultPlatform) {
+				return fmt.Errorf("service %q build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: %s", service.Name, defaultPlatform)
+			}
+			service.Platform = defaultPlatform
+		}
+
+		if service.Platform != "" {
+			if len(service.Build.Platforms) > 0 {
+				if !utils.StringContains(service.Build.Platforms, service.Platform) {
+					return fmt.Errorf("service %q build configuration does not support platform: %s", service.Name, service.Platform)
+				}
+			}
+
+			if buildForSinglePlatform || len(service.Build.Platforms) == 0 {
+				// if we're building for a single platform, we want to build for the platform we'll use to run the image
+				// similarly, if no build platforms were explicitly specified, it makes sense to build for the platform
+				// the image is designed for rather than allowing the builder to infer the platform
+				service.Build.Platforms = []string{service.Platform}
+			}
+		}
+
+		// services can specify that they should be built for multiple platforms, which can be used
+		// with `docker compose build` to produce a multi-arch image
+		// other cases, such as `up` and `run`, need a single architecture to actually run
+		// if there is only a single platform present (which might have been inferred
+		// from service.Platform above), it will be used, even if it requires emulation.
+		// if there's more than one platform, then the list is cleared so that the builder
+		// can decide.
+		// TODO(milas): there's no validation that the platform the builder will pick is actually one
+		// 	of the supported platforms from the build definition
+		// 	e.g. `build.platforms: [linux/arm64, linux/amd64]` on a `linux/ppc64` machine would build
+		// 	for `linux/ppc64` instead of returning an error that it's not a valid platform for the service.
+		if buildForSinglePlatform && len(service.Build.Platforms) > 1 {
+			// empty indicates that the builder gets to decide
+			service.Build.Platforms = nil
+		}
+	}
+	return nil
+}

cmd/compose/options_test.go

@@ -0,0 +1,130 @@
+/*
+   Copyright 2023 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package compose
+
+import (
+	"testing"
+
+	"github.com/compose-spec/compose-go/types"
+	"github.com/stretchr/testify/require"
+)
+
+func TestApplyPlatforms_InferFromRuntime(t *testing.T) {
+	makeProject := func() *types.Project {
+		return &types.Project{
+			Services: []types.ServiceConfig{
+				{
+					Name:  "test",
+					Image: "foo",
+					Build: &types.BuildConfig{
+						Context: ".",
+						Platforms: []string{
+							"linux/amd64",
+							"linux/arm64",
+							"alice/32",
+						},
+					},
+					Platform: "alice/32",
+				},
+			},
+		}
+	}
+
+	t.Run("SinglePlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, true))
+		require.EqualValues(t, []string{"alice/32"}, project.Services[0].Build.Platforms)
+	})
+
+	t.Run("MultiPlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, false))
+		require.EqualValues(t, []string{"linux/amd64", "linux/arm64", "alice/32"},
+			project.Services[0].Build.Platforms)
+	})
+}
+
+func TestApplyPlatforms_DockerDefaultPlatform(t *testing.T) {
+	makeProject := func() *types.Project {
+		return &types.Project{
+			Environment: map[string]string{
+				"DOCKER_DEFAULT_PLATFORM": "linux/amd64",
+			},
+			Services: []types.ServiceConfig{
+				{
+					Name:  "test",
+					Image: "foo",
+					Build: &types.BuildConfig{
+						Context: ".",
+						Platforms: []string{
+							"linux/amd64",
+							"linux/arm64",
+						},
+					},
+				},
+			},
+		}
+	}
+
+	t.Run("SinglePlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, true))
+		require.EqualValues(t, []string{"linux/amd64"}, project.Services[0].Build.Platforms)
+	})
+
+	t.Run("MultiPlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, false))
+		require.EqualValues(t, []string{"linux/amd64", "linux/arm64"},
+			project.Services[0].Build.Platforms)
+	})
+}
+
+func TestApplyPlatforms_UnsupportedPlatform(t *testing.T) {
+	makeProject := func() *types.Project {
+		return &types.Project{
+			Environment: map[string]string{
+				"DOCKER_DEFAULT_PLATFORM": "commodore/64",
+			},
+			Services: []types.ServiceConfig{
+				{
+					Name:  "test",
+					Image: "foo",
+					Build: &types.BuildConfig{
+						Context: ".",
+						Platforms: []string{
+							"linux/amd64",
+							"linux/arm64",
+						},
+					},
+				},
+			},
+		}
+	}
+
+	t.Run("SinglePlatform", func(t *testing.T) {
+		project := makeProject()
+		require.EqualError(t, applyPlatforms(project, true),
+			`service "test" build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: commodore/64`)
+	})
+
+	t.Run("MultiPlatform", func(t *testing.T) {
+		project := makeProject()
+		require.EqualError(t, applyPlatforms(project, false),
+			`service "test" build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: commodore/64`)
+	})
+}