Merge pull request #11858 from thaJeztah/compose_native_build

Compose: add documentation on enabling/disabling native build

compose/reference/build.md

@@ -18,8 +18,6 @@ Options:
     --no-rm                 Do not remove intermediate containers after a successful build.
     --parallel              Build images in parallel.
     --progress string       Set type of progress output (`auto`, `plain`, `tty`).
-                            `EXPERIMENTAL` flag for native builder.
-                            To enable, run with `COMPOSE_DOCKER_CLI_BUILD=1`)
     --pull                  Always attempt to pull a newer version of the image.
     -q, --quiet             Don't print anything to `STDOUT`.
 ```
@@ -32,3 +30,15 @@ tagged with that name, substituting any variables beforehand. See
 
 If you change a service's Dockerfile or the contents of its
 build directory, run `docker-compose build` to rebuild it.
+
+## Native build using the docker CLI
+
+Compose by default uses the `docker` CLI to perform builds (also known as "native
+build"). By using the `docker` CLI, Compose can take advantage of features such
+as [BuildKit](../../develop/develop-images/build_enhancements.md), which are not
+supported by Compose itself. BuildKit is enabled by default on Docker Desktop,
+but requires the `DOCKER_BUILDKIT=1` environment variable to be set on other
+platforms.
+
+Refer to the [Compose CLI environment variables](envvars.md#COMPOSE_DOCKER_CLI_BUILD)
+section to learn how to switch between "native build" and "compose build".

compose/reference/envvars.md

@@ -115,6 +115,16 @@ and `exec` operations. This option is not available on Windows where the CLI
 is required for the aforementioned operations.
 Supported: `true` or `1` to enable, `false` or `0` to disable.
 
+## COMPOSE\_DOCKER\_CLI\_BUILD
+
+Configure whether to use the Compose python client for building images or the
+native docker cli. By default, Compose uses the `docker` CLI to perform builds,
+which allows you to use [BuildKit](../../develop/develop-images/build_enhancements.md#to-enable-buildkit-builds)
+to perform builds.
+
+Set `COMPOSE_DOCKER_CLI_BUILD=0` to disable native builds, and to use the built-in
+python client.
+
 ## Related information
 
 - [User guide](../index.md)

go/compose-native-builds.md

@@ -0,0 +1,6 @@
+---
+title: Docker Compose native build through the CLI
+description: Instructions on enabling and disabling Docker Compose native build
+keywords: BuildKit, docker-compose build, configuration
+redirect_to: /compose/reference/build/#native-build-using-the-docker-cli
+---