github.com/buildtool/build-tools@v0.2.29-0.20240322150259-6a1d0a553c23/www/docs/commands/build.md (about)

     1  # build
     2  
     3  Performs a `docker build`, using a `Dockerfile` to build the application and tags the resulting image. By following the
     4  conventions no additional flags are needed, but the following flags are available:
     5  
     6  | Flag                                 | Description                                                                                                                                             |
     7  |:-------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|
     8  | `--file`,`-f` `<path to Dockerfile>` | Used to override the default `Dockerfile` location (which is `$PWD`)                                                                                    |
     9  | `--no-login`                         | Disables login to docker registry (good for local testing)                                                                                              |
    10  | `--no-pull`                          | Disables pulling of remote images if they already exist (good for local testing)                                                                        |
    11  | `--build-arg key=value`              | Additional Docker [build-arg](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg)                         |
    12  | `--platform value`                   | Specify target architecture [architecture](https://docs.docker.com/desktop/multi-arch/). should be a single string for example `--platform linux/amd64` |
    13  
    14  ```sh
    15  $ build --file docker/Dockerfile.build --skip-login --build-arg AUTH_TOKEN=abc
    16  ```
    17  
    18  ## Build-args
    19  
    20  The
    21  following [build-arg](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg)
    22  are automatically made available:
    23  
    24  |      Arg    |                   Value                                |
    25  | :---------- | :----------------------------------------------------- |
    26  | `CI_COMMIT` | The commit being built as exposed by [CI](../ci/ci.md) |
    27  | `CI_BRANCH` | The branch being built as exposed by [CI](../ci/ci.md) |
    28  
    29  they can be used in a `Dockerfile` like:
    30  
    31  ```dockerfile
    32  FROM ubuntu
    33  ARG CI_BRANCH
    34  
    35  RUN echo "Building $CI_BRANCH"
    36  ```
    37  
    38  ## Export content from build
    39  
    40  Buildtools `build` command support exporting content from the actual docker build process,
    41  see [Custom build outputs](https://docs.docker.com/engine/reference/commandline/build/#custom-build-outputs). By
    42  specifying a special stage in the `Dockerfile` and name it `export` you can use the `COPY`
    43  directive to copy files from the build context to the local machine. The copied files will be placed in a
    44  folder `exported`
    45  
    46  ### Example
    47  
    48  Consider a `Dockerfile` like this:
    49  
    50  ```dockerfile
    51  FROM debian as build
    52  RUN echo "text to be copied to localhost" >> /testfile
    53  
    54  # -- export stage
    55  FROM scratch as export
    56  # Copies the file /testfile from `build` stage to localhost
    57  COPY --from=build  /testfile .
    58  
    59  # -- resulting image stage
    60  FROM scratch
    61  # Do other stuff
    62  ```
    63  
    64  Let's try it:
    65  
    66  ```shell
    67  $ ls
    68  Dockerfile
    69  
    70  $ cat Dockerfile
    71  FROM debian as build
    72  RUN echo "text to be copied to localhost" >> /testfile
    73  
    74  # -- export stage
    75  FROM scratch as export
    76  # Copies the file /testfile from `build` stage to localhost
    77  COPY --from=build  /testfile .
    78  
    79  # -- resulting image stage
    80  FROM scratch
    81  # Do other stuff
    82  $ build
    83  ... <build output>
    84  $ ls
    85  Dockerfile  exported
    86  
    87  $ ls exported
    88  testfile
    89  
    90  $ cat exported/testfile
    91  text to be copied to localhost
    92  ```
    93  
    94  [Custom build outputs]: (https://docs.docker.com/engine/reference/commandline/build/#custom-build-outputs)