|
1 | | -# Bashbrew |
2 | | - |
3 | | -The recommended way to use `bashbrew.sh` is to install a symlink in your `PATH` somewhere as `bashbrew`, for example `~/bin/bashbrew -> /path/to/official-images/bashbrew/bashbrew.sh` (assuming `~/bin` is in `PATH`). |
| 1 | +# Bashbrew (`bashbrew`) |
4 | 2 |
|
5 | 3 | ```console |
6 | 4 | $ bashbrew --help |
7 | | - |
8 | | -usage: bashbrew [build|push|list] [options] [repo[:tag] ...] |
9 | | - ie: bashbrew build --all |
10 | | - bashbrew push debian ubuntu:12.04 |
11 | | - bashbrew list --namespaces='_' debian:7 hello-world |
12 | | - |
13 | | -This script processes the specified Docker images using the corresponding |
14 | | -repository manifest files. |
15 | | - |
16 | | -common options: |
17 | | - --all Build all repositories specified in library |
18 | | - --docker="docker" |
19 | | - Use a custom Docker binary |
20 | | - --retries="4" |
21 | | - How many times to try again if the build/push fails before |
22 | | - considering it a lost cause (always attempts a minimum of |
23 | | - one time, but maximum of one plus this number) |
24 | | - --help, -h, -? Print this help message |
25 | | - --library="/home/tianon/docker/stackbrew/library" |
26 | | - Where to find repository manifest files |
27 | | - --logs="/home/tianon/docker/stackbrew/bashbrew/logs" |
28 | | - Where to store the build logs |
29 | | - --namespaces="_" |
30 | | - Space separated list of image namespaces to act upon |
31 | | - |
32 | | - Note that "_" is a special case here for the unprefixed |
33 | | - namespace (ie, "debian" vs "library/debian"), and as such |
34 | | - will be implicitly ignored by the "push" subcommand |
35 | | - |
36 | | - Also note that "build" will always tag to the unprefixed |
37 | | - namespace because it is necessary to do so for dependent |
38 | | - images to use FROM correctly (think "onbuild" variants that |
39 | | - are "FROM base-image:some-version") |
40 | | - --uniq |
41 | | - Only process the first tag of identical images |
42 | | - This is not recommended for build or push |
43 | | - i.e. process python:2.7, but not python:2 |
44 | | - |
45 | | -build options: |
46 | | - --no-build Don't build, print what would build |
47 | | - --no-clone Don't pull/clone Git repositories |
48 | | - --src="/home/tianon/docker/stackbrew/bashbrew/src" |
49 | | - Where to store cloned Git repositories (GOPATH style) |
50 | | - |
51 | | -push options: |
52 | | - --no-push Don't push, print what would push |
| 5 | +NAME: |
| 6 | + bashbrew - canonical build tool for the official images |
| 7 | + |
| 8 | +USAGE: |
| 9 | + bashbrew [global options] command [command options] [arguments...] |
| 10 | + |
| 11 | +COMMANDS: |
| 12 | + list list repo:tag combinations for a given repo |
| 13 | + build build (and tag) repo:tag combinations for a given repo |
| 14 | + tag tag repo:tag into a namespace (especially for pushing) |
| 15 | + push push namespace/repo:tag (see also "tag") |
| 16 | + |
| 17 | + plumbing: |
| 18 | + children print the repos built FROM a given repo or repo:tag |
| 19 | + parents print the repos this repo or repo:tag is FROM |
| 20 | + cat print manifest contents for repo or repo:tag |
| 21 | + from print FROM for repo:tag |
| 22 | + |
| 23 | +GLOBAL OPTIONS: |
| 24 | + --verbose, -v enable more output (esp. "docker build" output) [$BASHBREW_VERBOSE] |
| 25 | + --no-sort do not apply any sorting, even via --build-order |
| 26 | + --constraint value build constraints (see Constraints in Manifest2822Entry) |
| 27 | + --exclusive-constraints skip entries which do not have Constraints |
| 28 | + --library value where the bodies are buried (default: "/home/jsmith/docker/official-images/library") [$BASHBREW_LIBRARY] |
| 29 | + --cache value where the git wizardry is stashed (default: "/home/jsmith/.cache/bashbrew") [$BASHBREW_CACHE] |
| 30 | + --help, -h, -? show help |
53 | 31 |
|
54 | 32 | ``` |
55 | 33 |
|
56 | | -## Subcommands |
57 | | - |
58 | | -### `bashbrew build` |
| 34 | +## Building |
59 | 35 |
|
60 | | -This script reads the library files for the images specified and then clones the required Git repositories into the specified `--src` directory. If the Git repository already exists, the script verifies that the Git ref specified in the library file exists and does `git fetch` as necessary. |
| 36 | +Bashbrew itself is built using `gb` ([github.com/constabulary/gb](https://github.com/constabulary/gb)). |
61 | 37 |
|
62 | | -The next step in the script is to build each image specified. All the `image:tag` combinations are placed into a queue. The processing order is determined by the order of items passed in on the command line (or alphabetical if `--all` is used). When a whole image, like `debian`, is specified the `image:tag` combinations are added to the queue in the order that they appear in the library file. For each `image:tag` to be processed, the system checks out the specified commit and sets mtimes (see [`git-set-mtimes`](#git-set-mtimes)) of all files in the Git repository to take advantage of Docker caching. If the `image:tag` is `FROM` another image that is later in the queue, it is deferred to the end of the queue. |
| 38 | +Once in the `go` subdirectory, `gb build` should produce `go/bin/bashbrew`, ready for use. |
63 | 39 |
|
64 | | -After the image is built, the final step of the script is to tag the image into each of the given `--namespaces`. |
| 40 | +## Usage |
65 | 41 |
|
66 | | -The `--no-clone` option skips the `git clone` step and will cause the script to fail on the build step if the Git repository does not exist or is missing the required Git refs. |
| 42 | +In general, `bashbrew build some-repo` or `bashbrew build ./some-file` should be sufficient for using the tool at a surface level, especially for testing. For more complex usage, please see the built-in help (`bashbrew --help`, `bashbrew build --help`, etc). |
67 | 43 |
|
68 | | -The `--no-build` option skips all the building, including setting the mtimes. |
| 44 | +## Configuration |
69 | 45 |
|
70 | | -**WARNING:** setting `--src` so that it uses a local working copy of your Git directory for a specified build will delete untracked and uncommitted changes, and will disable `gc.auto`. It is not recommended to symlink in your working directories for use during build. |
| 46 | +The default "flags" configuration is in `~/.config/bashbrew/flags`, but the base path can be overridden with `--config` or `BASHBREW_CONFIG` (technically, the full path to the `flags` configuration file is `${BASHBREW_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/bashbrew}/flags`). |
71 | 47 |
|
72 | | -### `bashbrew push` |
| 48 | +To set a default namespace for specific commands only: |
73 | 49 |
|
74 | | -This script takes advantage of `docker login` and does a `docker push` on each `image:tag` specified for the given `--namespaces`. The script will warn if a given `namespace/image:tag` does not exist. |
75 | | - |
76 | | -The `--no-push` option prints out the `docker push` instructions that would have been executed. |
| 50 | +``` |
| 51 | +Commands: tag, push |
| 52 | +Namespace: officialstaging |
| 53 | +``` |
77 | 54 |
|
78 | | -### `bashbrew list` |
| 55 | +To set a default namespace for all commands: |
79 | 56 |
|
80 | | -Takes the same arguments as `bashbrew build` and `bashbrew push`, but prints a list of image names and quits. |
| 57 | +``` |
| 58 | +Namespace: jsmith |
| 59 | +``` |
81 | 60 |
|
82 | | -For example: |
| 61 | +A more complex example: |
83 | 62 |
|
84 | | -```console |
85 | | -$ # count the number of tags in the official library |
86 | | -$ bashbrew list --all | wc -l |
87 | | -802 |
88 | | -$ # count the number of _unique_ tags in the official library |
89 | | -$ bashbrew list --all --uniq | wc -l |
90 | | -296 |
91 | | - |
92 | | -$ # pull all officially supported tags of "debian" |
93 | | -$ bashbrew list debian | xargs -n1 --verbose docker pull |
94 | | -... |
95 | | - |
96 | | -$ # list all unique supported tags of "python" |
97 | | -$ bashbrew list --uniq python |
98 | | -python:2.7.10 |
99 | | -python:2.7.10-onbuild |
100 | | -python:2.7.10-slim |
101 | | -python:2.7.10-wheezy |
102 | | -python:3.2.6 |
103 | | -python:3.2.6-onbuild |
104 | | -python:3.2.6-slim |
105 | | -python:3.2.6-wheezy |
106 | | -python:3.3.6 |
107 | | -python:3.3.6-onbuild |
108 | | -python:3.3.6-slim |
109 | | -python:3.3.6-wheezy |
110 | | -python:3.4.3 |
111 | | -python:3.4.3-onbuild |
112 | | -python:3.4.3-slim |
113 | | -python:3.4.3-wheezy |
114 | 63 | ``` |
| 64 | +# comments are allowed anywhere (and are ignored) |
| 65 | +Library: /mnt/docker/official-images/library |
| 66 | +Cache: /mnt/docker/bashbrew-cache |
| 67 | +Constraints: aufs, docker-1.9, tianon |
| 68 | +ExclusiveConstraints: true |
115 | 69 |
|
116 | | -## Helper Scripts |
| 70 | +# namespace just "tag" and "push" (not "build") |
| 71 | +Commands: tag, push |
| 72 | +Namespace: tianon |
117 | 73 |
|
118 | | -### `git-set-mtimes` |
| 74 | +Commands: list |
| 75 | +ApplyConstraints: true |
| 76 | +
|
| 77 | +Commands: tag |
| 78 | +Verbose: true |
| 79 | +``` |
119 | 80 |
|
120 | | -Since Docker caching of layers is based upon the mtimes of files and folders, this script sets each file's mtime to the time of the commit that most recently modified it and sets each directory's mtime to be the most recent mtime of any file or folder contained within it. This gives a deterministic time for all files and folders in the Git repository. |
| 81 | +In this example, `bashbrew tag` will get both `Namespace` and `Verbose` applied. |
0 commit comments