github.com/simonferquel/app@v0.6.1-0.20181012141724-68b7cccf26ac/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.10.x or above)
    19  
    20  You will also need the following tools:
    21  
    22  * GNU Make
    23  * [`dep`](https://github.com/golang/dep)
    24  
    25  ## Build using Go
    26  
    27  First you need to setup your Go development environment. You can follow this
    28  guideline [How to write go code](https://golang.org/doc/code.html) and at the
    29  end you need to have `GOPATH` set in your environment.
    30  
    31  At this point you can use `go` to checkout `docker-app` in your `GOPATH`:
    32  
    33  ```sh
    34  go get github.com/docker/app
    35  ```
    36  
    37  You are ready to build `docker-app` yourself!
    38  
    39  `docker-app` uses `make` to create a repeatable build flow. It means that you
    40  can run:
    41  
    42  ```sh
    43  make
    44  ```
    45  
    46  This is going to build all the project binaries in the `./bin/`
    47  directory, run tests (unit and end-to-end).
    48  
    49  ```sh
    50  make bin/docker-app             # builds the docker-app binary
    51  make bin/docker-app-darwin      # builds the docker-app binary for darwin
    52  make bin/docker-app-windows.exe # builds the docker-app binary for windows
    53  
    54  make lint                       # run the linter on the sources
    55  make test-unit                  # run the unit tests
    56  make test-e2e                   # run the end-to-end tests
    57  ```
    58  
    59  Vendoring of external imports uses the [`dep`](https://github.com/golang/dep) tool.
    60  Please refer to its documentation if you need to update a dependency.
    61  
    62  ## Build using Docker
    63  
    64  If you don't have Go installed but Docker is present, you can also use
    65  `docker.Makefile` to build `docker-app` and run tests. This
    66  `docker.Makefile` is used by our continuous integration too.
    67  
    68  ```sh
    69  make -f docker.Makefile           # builds cross binaries build and tests
    70  make -f docker.Makefile cross     # builds cross binaries (linux, darwin, windows)
    71  make -f docker.Makefile schemas   # update the embedded schemas
    72  
    73  make -f docker.Makefile lint      # run the linter on the sources
    74  make -f docker.Makefile test-unit # run the unit tests
    75  make -f docker.Makefile test-e2e  # run the end-to-end tests
    76  ```
    77  
    78  ## Testing docker-app
    79  
    80  During the automated CI, the unit tests and end-to-end tests are run as
    81  part of the PR validation. As a developer you can run these tests
    82  locally by using any of the following `Makefile` targets:
    83  
    84  - `make test`: run all non-end-to-end tests
    85  - `make test-e2e`: run all end-to-end tests
    86  
    87  To execute a specific test or set of tests you can use the `go test`
    88  capabilities without using the `Makefile` targets. The following
    89  examples show how to specify a test name and also how to use the flag
    90  directly against `go test` to run root-requiring tests.
    91  
    92  ```sh
    93  # run the test <TEST_NAME>:
    94  go test -v -run "<TEST_NAME>" .
    95  ```