Add a BUILDING document and self described makefile(s)

- `BUILDING.md` holds instruction to help building `docker-app` from
  sources (with or without docker)
- Adds a `help` target to `Makefile` and `docker.Makefile` 👼

Signed-off-by: Vincent Demeester <vincent@sbr.pm>

Author: vdemeester

BUILDING.md

@@ -0,0 +1,94 @@
+# Building `docker-app` from source
+
+This guide is useful if you intend to contribute on `docker/app`. Thanks for your
+effort. Every contribution is very appreciated.
+
+This doc includes:
+* [Build requirements](#build-requirements)
+* [Using Go](#build-using-go)
+* [Using Docker](#build-using-docker)
+* [Testing](#testing-docker-app)
+
+## Build requirements
+
+To build the `docker-app`, at least one of the following build system
+dependencies are required:
+
+* Docker (17.12 or above)
+* Go (1.10.x or above)
+
+You will also need the following tools:
+
+* GNU Make
+* [`dep`](https://github.com/golang/dep)
+
+## Build using Go
+
+First you need to setup your Go development environment. You can follow this
+guideline [How to write go code](https://golang.org/doc/code.html) and at the
+end you need to have `GOPATH` set in your environment.
+
+At this point you can use `go` to checkout `docker-app` in your `GOPATH`:
+
+```sh
+go get github.com/docker/app
+```
+
+You are ready to build `docker-app` yourself!
+
+`docker-app` uses `make` to create a repeatable build flow. It means that you
+can run:
+
+```sh
+make
+```
+
+This is going to build all the project binaries in the `./bin/`
+directory, run tests (unit and end-to-end).
+
+```sh
+make bin/docker-app             # builds the docker-app binary
+make bin/docker-app-darwin      # builds the docker-app binary for darwin
+make bin/docker-app-windows.exe # builds the docker-app binary for windows
+
+make lint                       # run the linter on the sources
+make test-unit                  # run the unit tests
+make test-e2e                   # run the end-to-end tests
+```
+
+Vendoring of external imports uses the [`dep`](https://github.com/golang/dep) tool.
+Please refer to its documentation if you need to update a dependency.
+
+## Build using Docker
+
+If you don't have Go installed but Docker is present, you can also use
+`docker.Makefile` to build `docker-app` and run tests. This
+`docker.Makefile` is used by our continuous integration too.
+
+```sh
+make -f docker.Makefile           # builds cross binaries build and tests
+make -f docker.Makefile cross     # builds cross binaries (linux, darwin, windows)
+
+make -f docker.Makefile lint      # run the linter on the sources
+make -f docker.Makefile test-unit # run the unit tests
+make -f docker.Makefile test-e2e  # run the end-to-end tests
+```
+
+## Testing docker-app
+
+During the automated CI, the unit tests and end-to-end tests are run as
+part of the PR validation. As a developer you can run these tests
+locally by using any of the following `Makefile` targets:
+
+- `make test`: run all non-end-to-end tests
+- `make test-e2e`: run all end-to-end tests
+
+To execute a specific test or set of tests you can use the `go test`
+capabilities without using the `Makefile` targets. The following
+examples show how to specify a test name and also how to use the flag
+directly against `go test` to run root-requiring tests.
+
+```sh
+# run the test <TEST_NAME>:
+go test -v -run "<TEST_NAME>" .
+```

Makefile

@@ -9,7 +9,7 @@ check_go_env:
 	@test $$(go list) = "$(PKG_NAME)" || \
 		(echo "Invalid Go environment" && false)
 
-cross: bin/$(BIN_NAME)-linux bin/$(BIN_NAME)-darwin bin/$(BIN_NAME)-windows.exe
+cross: bin/$(BIN_NAME)-linux bin/$(BIN_NAME)-darwin bin/$(BIN_NAME)-windows.exe ## cross-compile binaries (linux, darwin, windows)
 
 e2e-cross: bin/$(BIN_NAME)-e2e-linux bin/$(BIN_NAME)-e2e-darwin bin/$(BIN_NAME)-e2e-windows.exe
 
@@ -26,17 +26,17 @@ bin/%: cmd/% check_go_env
 
 check: lint test
 
-test: test-unit test-e2e
+test: test-unit test-e2e ## run all tests
 
-lint:
+lint: ## run linter(s)
 	@echo "Linting..."
 	@gometalinter --config=gometalinter.json
 
-test-e2e: bin/$(BIN_NAME)
+test-e2e: bin/$(BIN_NAME) ## run end-to-end tests
 	@echo "Running e2e tests..."
 	$(GO_TEST) ./e2e/
 
-test-unit:
+test-unit: ## run unit tests
 	@echo "Running unit tests..."
 	$(GO_TEST) $(shell go list ./... | grep -vE '/e2e')
 
@@ -53,20 +53,23 @@ coverage-test-e2e: coverage-bin
 	@$(call mkdir,_build/cov)
 	DOCKERAPP_BINARY=../e2e/coverage-bin $(GO_TEST) -v ./e2e
 
-coverage: coverage-test-unit coverage-test-e2e
+coverage: coverage-test-unit coverage-test-e2e ## run tests with coverage
 	go install ./vendor/github.com/wadey/gocovmerge/
 	gocovmerge _build/cov/*.out > _build/cov/all.out
 	go tool cover -func _build/cov/all.out
 	go tool cover -html _build/cov/all.out -o _build/cov/coverage.html
 
-clean:
+clean: ## clean build artifacts
 	$(call rm,bin)
 	$(call rm,_build)
 	$(call rm,docker-app-*.tar.gz)
 
-vendor:
+vendor: ## update vendoring
 	$(call rm,vendor)
 	dep ensure -v
 
-.PHONY: cross e2e-cross test check lint test-unit test-e2e coverage coverage-bin coverage-test-unit coverage-test-e2e clean vendor
+help: ## this help
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
+
+.PHONY: cross e2e-cross test check lint test-unit test-e2e coverage coverage-bin coverage-test-unit coverage-test-e2e clean vendor help
 .DEFAULT: all

docker.Makefile

@@ -23,10 +23,10 @@ create_bin:
 build_dev_image:
 	docker build --target=dev -t $(DEV_IMAGE_NAME) .
 
-shell: build_dev_image
+shell: build_dev_image ## run a shell in the docker build image
 	docker run -ti --rm $(DEV_IMAGE_NAME) bash
 
-cross: create_bin
+cross: create_bin ## cross-compile binaries (linux, darwin, windows)
 	docker build --target=$* -t $(CROSS_IMAGE_NAME)  .
 	docker create --name $(CROSS_CTNR_NAME) $(CROSS_IMAGE_NAME) noop
 	docker cp $(CROSS_CTNR_NAME):$(PKG_PATH)/bin/$(BIN_NAME)-linux bin/$(BIN_NAME)-linux
@@ -56,16 +56,16 @@ tars:
 	tar czf bin/$(BIN_NAME)-windows.tar.gz -C bin $(BIN_NAME)-windows.exe
 	tar czf bin/$(BIN_NAME)-e2e-windows.tar.gz -C bin $(BIN_NAME)-e2e-windows.exe
 
-test: test-unit test-e2e
+test: test-unit test-e2e ## run all tests
 
-test-unit: build_dev_image
+test-unit: build_dev_image ## run unit tests
 	docker run --rm $(DEV_IMAGE_NAME) make test-unit
 
-test-e2e: build_dev_image
+test-e2e: build_dev_image ## run end-to-end tests
 	docker run -v /var/run:/var/run:ro --rm $(DEV_IMAGE_NAME) make bin/$(BIN_NAME) test-e2e
 
 COV_LABEL := com.docker.app.cov-run=$(TAG)
-coverage: build_dev_image
+coverage: build_dev_image ## run tests with coverage
 	@$(call mkdir,_build)
 	docker run -v /var/run:/var/run:ro --name $(COV_CTNR_NAME) -tid $(DEV_IMAGE_NAME) make COMMIT=${COMMIT} TAG=${TAG} coverage
 	docker logs -f $(COV_CTNR_NAME)
@@ -76,7 +76,7 @@ gradle-test:
 	tar cf - Dockerfile.gradle bin/docker-app-linux integrations/gradle | docker build -t $(GRADLE_IMAGE_NAME) -f Dockerfile.gradle -
 	docker run --rm $(GRADLE_IMAGE_NAME) bash -c "./gradlew --stacktrace build && cd example && gradle renderIt"
 
-lint:
+lint: ## run linter(s)
 	$(info Linting...)
 	docker build -t $(LINT_IMAGE_NAME) -f Dockerfile.lint .
 	docker run --rm $(LINT_IMAGE_NAME) make lint
@@ -85,4 +85,7 @@ vendor: build_dev_image
 	$(info Vendoring...)
 	docker run --rm $(DEV_IMAGE_NAME) sh -c "make vendor && hack/check-git-diff vendor"
 
-.PHONY: lint test-e2e test-unit test cross e2e-cross coverage gradle-test shell build_dev_image tars vendor
+help: ## this help
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
+
+.PHONY: lint test-e2e test-unit test cross e2e-cross coverage gradle-test shell build_dev_image tars vendor help