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 ```