github.com/docker/app@v0.9.1-beta3.0.20210611140623-a48f773ab002/BUILDING.md (about)

     1  # Building `docker-app` from source
     2  
     3  This guide is useful if you intend to contribute on `docker/app`. Thanks for your
     4  effort. Every contribution is very appreciated.
     5  
     6  This doc includes:
     7  * [Build requirements](#build-requirements)
     8  * [Using Go](#build-using-go)
     9  * [Using Docker](#build-using-docker)
    10  * [Testing](#testing-docker-app)
    11  
    12  ## Build requirements
    13  
    14  To build the `docker-app`, at least one of the following build system
    15  dependencies are required:
    16  
    17  * Docker (17.12 or above)
    18  * Go (1.11.x or above)
    19  
    20  You will also need the following tools:
    21  
    22  * GNU Make
    23  * [`dep`](https://github.com/golang/dep)
    24  * [`gotestsum`](https://github.com/gotestyourself/gotestsum)
    25  
    26  ## Build using Go
    27  
    28  First you need to setup your Go development environment. You can follow this
    29  guideline [How to write go code](https://golang.org/doc/code.html) and at the
    30  end you need to have `GOPATH` set in your environment.
    31  
    32  At this point you can use `go` to checkout `docker-app` in your `GOPATH`:
    33  
    34  ```console
    35  go get github.com/docker/app
    36  ```
    37  
    38  Then use `go` to checkout `gotestsum`:
    39  
    40  ```console
    41  go get gotest.tools/gotestsum
    42  ```
    43  
    44  You are ready to build `docker-app` yourself!
    45  
    46  `docker-app` uses `make` to create a repeatable build flow. It means that you
    47  can run:
    48  
    49  ```console
    50  make
    51  ```
    52  
    53  This is going to build all the project binaries in the `./bin/`
    54  directory, run tests (unit and end-to-end).
    55  
    56  ```console
    57  make bin/docker-app             # builds the docker-app binary
    58  make bin/docker-app-darwin      # builds the docker-app binary for darwin
    59  make bin/docker-app-windows.exe # builds the docker-app binary for windows
    60  
    61  make lint                       # run the linter on the sources
    62  make test-unit                  # run the unit tests
    63  make test-e2e                   # run the end-to-end tests
    64  ```
    65  
    66  Vendoring of external imports uses the [`dep`](https://github.com/golang/dep) tool.
    67  Please refer to its documentation if you need to update a dependency.
    68  
    69  ## Build using Docker
    70  
    71  If you don't have Go installed but Docker is present, you can also use
    72  `docker.Makefile` to build `docker-app` and run tests.
    73  
    74  To use `docker.Makefile` you will need to enable BuildKit.
    75  This is done by setting the environment variable `DOCKER_BUILDKIT=1`
    76  
    77  This `docker.Makefile` is used by our continuous integration too.
    78  
    79  ```sh
    80  make -f docker.Makefile           # builds cross binaries build and tests
    81  make -f docker.Makefile cross     # builds cross binaries (linux, darwin, windows)
    82  make -f docker.Makefile schemas   # update the embedded schemas
    83  
    84  make -f docker.Makefile lint      # run the linter on the sources
    85  make -f docker.Makefile test-unit # run the unit tests
    86  make -f docker.Makefile test-e2e  # run the end-to-end tests
    87  ```
    88  
    89  ## Testing docker-app
    90  
    91  During the automated CI, the unit tests and end-to-end tests are run as
    92  part of the PR validation. As a developer you can run these tests
    93  locally by using any of the following `Makefile` targets:
    94  
    95  - `make test-unit`: run all non-end-to-end tests
    96  - `make test-e2e`: run all end-to-end tests
    97  
    98  To execute a specific test or set of tests you can use the `go test`
    99  capabilities without using the `Makefile` targets. The following
   100  examples show how to specify a test name and also how to use the flag
   101  directly against `go test` to run root-requiring tests.
   102  
   103  ```console
   104  # run the test <TEST_NAME>:
   105  go test -v -run "<TEST_NAME>" .
   106  ```
   107  
   108  **NOTE** if the tests fail with an error message like `"Error: manifest
   109  for docker/cnab-app-base:v0.6.0-68-g3ae57efdb6-dirty not found"`, it means
   110  you forgot to rebuild the base invocation image, simply run
   111  
   112  ```sh
   113  $ make -f docker.Makefile invocation-image
   114  ```
   115  
   116  ### Running specific end-to-end tests
   117  
   118  To execute a specific end-to-end test or set of end-to-end tests you can specify
   119  them with the E2E_TESTS Makefile variable.
   120  
   121  ```console
   122  # run the e2e test <TEST_NAME>:
   123  make E2E_TESTS=<TEST_NAME> test-e2e
   124  ```