Skip to content

Commit c03f108

Browse files
committed
initial documentation and rules
1 parent f43e994 commit c03f108

File tree

3 files changed

+163
-2
lines changed

3 files changed

+163
-2
lines changed

README.md

+50-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,50 @@
1-
# csi-build-rules
2-
common build and test rules for CSI apps
1+
# [csi-build-rules](https://github.com/kubernetes-csi/csi-build-rules)
2+
3+
These build and test rules can be shared between different Go projects
4+
without modifications. Customization for the different projects happen
5+
in the top-level Makefile.
6+
7+
The rules include support for building and pushing Docker images, with
8+
the following features:
9+
- one or more command and image per project
10+
- push canary and/or tagged release images
11+
- automatically derive the image tag(s) from repo tags
12+
- the source code revision is stored in a "revision" image label
13+
- never overwrites an existing release image
14+
15+
Usage
16+
-----
17+
18+
The expected repository layout is:
19+
- `cmd/*/*.go` - source code for each command
20+
- `cmd/*/Dockerfile` - docker file for each command or
21+
Dockerfile in the root when only building a single command
22+
- `Makefile` - includes `build-rules/build.make` and sets
23+
configuration variables
24+
- `.travis.yml` - a symlink to `build-rules/.travis.yml`
25+
26+
To create a release, tag a certain revision with a name that
27+
starts with `v`, for example `v1.0.0`, then `make push`
28+
while that commit is checked out.
29+
30+
It does not matter on which branch that revision exists, i.e. it is
31+
possible to create releases directly from master. A release branch can
32+
still be created for maintenance releases later if needed.
33+
34+
Release branches are expected to be named `release-x.y` for releases
35+
`x.y.z`. Building from such a branch creates `x.y-canary`
36+
images. Building from master creates the main `canary` image.
37+
38+
Sharing and updating
39+
--------------------
40+
41+
[`git subtree`](https://github.com/git/git/blob/master/contrib/subtree/git-subtree.txt)
42+
is the recommended way of maintaining a copy of the rules inside the
43+
`build-rules` directory of a project. This way, it is possible to make
44+
changes also locally, test them and then push them back to the shared
45+
repository at a later time.
46+
47+
Cheat sheet:
48+
49+
- `git subtree pull --prefix=build-rules https://github.com/kubernetes-csi/csi-build-rules.git master` - update local copy to latest upstream
50+
- edit, `git commit`, `git subtree push --prefix=build-rules [email protected]:<user>/csi-build-rules.git <my-new-or-existing-branch>` - push to a new branch before submitting a PR

build.make

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Copyright 2017 The Kubernetes Authors.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
.PHONY: build-% build container-% container push-% push clean test
16+
17+
# A space-separated list of all commands in the repository, must be
18+
# set in main Makefile of a repository.
19+
# CMDS=
20+
21+
# This is the default. It can be overridden in the main Makefile after
22+
# including build.make.
23+
REGISTRY_NAME=quay.io/k8scsi
24+
25+
# Revision that gets built into each binary via the main.version
26+
# string. Uses the `git describe` output based on the most recent
27+
# version tag with a short revision suffix or, if nothing has been
28+
# tagged yet, just the revision.
29+
#
30+
# Beware that tags may also be missing in shallow clones as done by
31+
# some CI systems (like TravisCI, which pulls only 50 commits).
32+
REV=$(shell git describe --long --tags --match='v*' --dirty 2>/dev/null || git rev-list -n1 HEAD)
33+
34+
# A space-separated list of image tags under which the current build is to be pushed.
35+
# Determined dynamically.
36+
IMAGE_TAGS=
37+
38+
# A "canary" image gets built if the current commit is the head of the remote "master" branch.
39+
# That branch does not exist when building some other branch in TravisCI.
40+
IMAGE_TAGS+=$(shell if [ "$$(git rev-list -n1 HEAD)" = "$$(git rev-list -n1 origin/master 2>/dev/null)" ]; then echo "canary"; fi)
41+
42+
# A "X.Y.Z-canary" image gets built if the current commit is the head of a "origin/release-X.Y.Z" branch.
43+
# The actual suffix does not matter, only the "release-" prefix is checked.
44+
IMAGE_TAGS+=$(shell git branch -r --points-at=HEAD | grep 'origin/release-' | grep -v -e ' -> ' | sed -e 's;.*/release-\(.*\);\1-canary;')
45+
46+
# A release image "vX.Y.Z" gets built if there is a tag of that format for the current commit.
47+
# --abbrev=0 suppresses long format, only showing the closest tag.
48+
IMAGE_TAGS+=$(shell tagged="$$(git describe --tags --match='v*' --abbrev=0)"; if [ "$$tagged" ] && [ "$$(git rev-list -n1 HEAD)" = "$$(git rev-list -n1 $$tagged)" ]; then echo $$tagged; fi)
49+
50+
# Images are named after the command contained in them.
51+
IMAGE_NAME=$(REGISTRY_NAME)/$*
52+
53+
ifdef V
54+
TESTARGS = -v -args -alsologtostderr -v 5
55+
else
56+
TESTARGS =
57+
endif
58+
59+
build-%:
60+
mkdir -p bin
61+
CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-X main.version=$(REV) -extldflags "-static"' -o ./bin/$* ./cmd/$*
62+
63+
container-%: build-%
64+
docker build -t $*:latest -f $(shell if [ -e ./cmd/$*/Dockerfile ]; then echo ./cmd/$*/Dockerfile; else echo Dockerfile; fi) --label revision=$(REV) .
65+
66+
push-%: container-%
67+
set -ex; \
68+
push_image () { \
69+
docker tag $*:latest $(IMAGE_NAME):$$tag; \
70+
docker push $(IMAGE_NAME):$$tag; \
71+
}; \
72+
for tag in $(IMAGE_TAGS); do \
73+
if echo $$tag | grep -q -e '-canary$$'; then \
74+
: "creating or overwriting canary image"; \
75+
push_image; \
76+
elif docker pull $(IMAGE_NAME):$$tag 2>&1 | tee /dev/stderr | grep -q "manifest for $(IMAGE_NAME):$$tag not found"; then \
77+
: "creating release image"; \
78+
push_image; \
79+
else \
80+
: "release image $(IMAGE_NAME):$$tag already exists, skipping push"; \
81+
fi; \
82+
done
83+
84+
build: $(CMDS:%=build-%)
85+
container: $(CMDS:%=container-%)
86+
push: $(CMDS:%=push-%)
87+
88+
clean:
89+
-rm -rf bin
90+
91+
test:
92+
go test `go list ./... | grep -v 'vendor'` $(TESTARGS)
93+
go vet `go list ./... | grep -v vendor`
94+
files=$$(find . -name '*.go' | grep -v './vendor'); \
95+
if [ $$(gofmt -d $$files | wc -l) -ne 0 ]; then \
96+
echo "formatting errors:"; \
97+
gofmt -d $$files; \
98+
false; \
99+
fi

travis.yml

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
language: go
2+
sudo: required
3+
services:
4+
- docker
5+
matrix:
6+
include:
7+
- go: 1.11.1
8+
script:
9+
- make all test
10+
after_success:
11+
- if [ "${TRAVIS_PULL_REQUEST}" == "false" ]; then
12+
docker login -u "${DOCKER_USERNAME}" -p "${DOCKER_PASSWORD}" quay.io;
13+
make push;
14+
fi

0 commit comments

Comments
 (0)