Skip to content

Commit 371e894

Browse files
garyogaryo
committed
Fixed --exclude to work on dirs, and updated README
1 parent b6cf6cc commit 371e894

File tree

2 files changed

+153
-8
lines changed

2 files changed

+153
-8
lines changed

‎README.md‎

Lines changed: 151 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,164 @@
11
# Build-binary-artifact
22

3-
`build-binary-artifact.py` is a simple binary artifact generator. It creates zip files with specific filename formats, a content signature, and a manifest for trackability.
3+
`build-binary-artifact.py` is a simple binary artifact generator. It
4+
creates zip files with specific filename formats, a content signature,
5+
and a manifest for trackability.
6+
7+
`build-binary-artifact.py` is basically a glorified zip creator. To
8+
use it normally:
9+
10+
```
11+
build-binary-artifact.py --name foo --base-version 1.0 --build-id 1 <FILE_OR_DIR>...
12+
```
13+
14+
That creates a file `foo-1.0-1-2018.10.11-<sha>.zip` where the SHA is
15+
the signature of the dir's contents. `base-version` is the version of
16+
the thing you're packaging. The created zip file just contains the dir
17+
itself, and a `foo-manifest` file for tracking, containing all the
18+
metadata (name, version, build date, build machine, git SHA if
19+
available, etc.)
20+
21+
Why is it better than just using zip? Mainly because it names the
22+
resulting file uniquely, which makes everything totally trackable. And
23+
on the target system you can check the manifest file from where you
24+
unzipped it to see what's actually there, find out when/where/who
25+
built it, etc.
26+
27+
It's scriptable so it's easy to include in any build tool.
28+
29+
To use the resulting binary artifact files: they're just standard Zip
30+
files, so unzip and do whatever you'd normally do.
431

532
## Getting Started
633

7-
Download this repo and copy `build-binary-artifact.py` on your path.
34+
Download this repo and copy `build-binary-artifact.py` somewhere on
35+
your path.
36+
37+
### Usage:
38+
39+
```
40+
usage: build-binary-artifact.py [-h] --base-version BASE_VERSION --name NAME
41+
[--bits BITS] [--build-id BUILD_ID]
42+
[--build-branch BUILD_BRANCH]
43+
[--build-date BUILD_DATE]
44+
[--build-machine BUILD_MACHINE] [--os OS]
45+
[--build-os BUILD_OS] [--note NOTE]
46+
[--author AUTHOR] [--chdir CHDIR]
47+
[--outdir OUTDIR] [--silent] [--tar]
48+
[--name-only] [--hash-only] [--validate]
49+
[--exclude EXCLUDE]
50+
dir [dir ...]
51+
52+
Binary Artifact builder
53+
Make a zip/tarfile called NAME-VER-BUILD-DATE-HASH.tgz from all the files in dirs.
54+
Include a generated manifest, so the result looks like:
55+
filename: NAME-VER-BUILD-DATE-HASH.tgz/.zip
56+
contents:
57+
NAME-VER-BUILD-DATE-HASH/
58+
NAME-manifest.txt
59+
dir1/
60+
dir2/
61+
...
62+
63+
positional arguments:
64+
dir dirs to collect into the binary artifact
65+
66+
optional arguments:
67+
-h, --help show this help message and exit
68+
--base-version BASE_VERSION, -B BASE_VERSION
69+
Base version for manifest (default: None)
70+
--name NAME, -n NAME Artifact name (human readable). E.g. 'libfoo-mac'.
71+
(default: None)
72+
--bits BITS, -b BITS bits (32 or 64) (default: 64)
73+
--build-id BUILD_ID, -i BUILD_ID
74+
Build ID (default: git SHA)
75+
--build-branch BUILD_BRANCH, --branch BUILD_BRANCH
76+
Build branch (default: git branch)
77+
--build-date BUILD_DATE, --date BUILD_DATE, -D BUILD_DATE
78+
Build date (default: now)
79+
--build-machine BUILD_MACHINE, --machine BUILD_MACHINE, -m BUILD_MACHINE
80+
Build machine (default: machine name)
81+
--os OS, -o OS Build machine OS (default: current OS)
82+
--build-os BUILD_OS, -O BUILD_OS
83+
Build machine OS (default: current OS)
84+
--note NOTE, -N NOTE Note to put in manifest (one line) (default: None)
85+
--author AUTHOR, -a AUTHOR
86+
Person (username/email) building the archive (default:
87+
guessed username)
88+
--chdir CHDIR, -C CHDIR
89+
Change to this dir before starting to archive files.
90+
Useful if dir is in a subdir or elsewhere on disk and
91+
you don't want the intervening dir names in the final
92+
archive. (default: None)
93+
--outdir OUTDIR Directory in which to create the output zip/tar file.
94+
(default: .)
95+
--silent, -s Skip printing the manifest file contents on stdout
96+
(default: False)
97+
--tar, -T Create a tar (tgz) file instead of zip (default:
98+
False)
99+
--name-only Don't build the archive; just return the name of the
100+
tar/zip file. (Requires hashing contents.) (default:
101+
False)
102+
--hash-only Don't build the archive; just return the hash of the
103+
given dir. (default: False)
104+
--validate Validate an unpacked archive by checking its hash
105+
against the manifest. (default: False)
106+
--exclude EXCLUDE Exclude this filename from the archive. May be
107+
repeated. (default: None)
108+
```
109+
The following arguments are required: `--base-version`/`-B`, `--name`/`-n`, `dir`.
110+
111+
If `git` is available, the tool tries to inspect the dir and infer
112+
`build-branch` and `build-id` from git. It defaults `build-machine`
113+
from the current machine name, `build-date` defaults to now, and
114+
`build-os` defaults to the current OS.
115+
116+
`build-binary-artifact.py` has three additional modes besides creating
117+
the artifact:
118+
* `validate`: verifies an existing unpacked archive by checking the
119+
content hash against the manifest
120+
* `name-only`: don't build, just return the filename. This is useful
121+
for build systems that want to know the names of targets before
122+
they're created.
123+
* `hash-only`: don't build, just return the content hash.
124+
125+
### Example:
126+
127+
This packages build-binary-artifact itself (the git working dir) as a
128+
binary artifact. It excludes the `.git` folder.
129+
130+
```
131+
% ls
132+
binary-artifact
133+
134+
% python binary-artifact/build-binary-artifact.py --base-version 1.0 \
135+
--build-id 1 --exclude .git --name build-binary-artifact binary-artifact
136+
Created binary artifact ./build-binary-artifact-1.0-1-2018.10.17-99b6130f5a6f51a3.zip
137+
base-version: 1.0
138+
name: build-binary-artifact
139+
os: Windows
140+
bits: 64
141+
author: garyo
142+
build-id: 1
143+
build-branch: None
144+
build-date: Wed Oct 17 10:29:54 2018
145+
build-machine: tower1
146+
build-os: Windows 10 10.0.17134 AMD64
147+
note: None
148+
fullname: build-binary-artifact-1.0-1-2018.10.17-99b6130f5a6f51a3
149+
content-hash: 99b6130f5a6f51a3
150+
Wrote .\build-binary-artifact-1.0-1-2018.10.17-99b6130f5a6f51a3.zip
151+
%
152+
```
8153

9154
### Prerequisites
10155

11156
Python 2.7 or 3.6+
12157

13158
### Installing
14159

15-
Eventually this tool should be installable via `pip install build-binary-artifact` but for now, just download the repo.
160+
Eventually this tool will be installable via `pip install build-binary-artifact`
161+
but for now, just download the repo.
16162

17163
## Running the tests
18164

@@ -25,10 +171,8 @@ Pull requests and issues gratefully accepted!
25171

26172
## Authors
27173

28-
* **Gary Oberbrunner** at Boris FX, Inc.
29-
174+
* **Gary Oberbrunner** at Boris FX, Inc. (current maintainer)
30175

31176
## License
32177

33-
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details
34-
178+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

‎build-binary-artifact.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,7 @@ def make_zipfile(dirs, manifest, manifest_name, top_level_name, outdir, exclude=
145145
for dir in dirs:
146146
f.write(dir, '%s/%s' % (top_level_name, dir))
147147
for root, dirs, files in os.walk(dir):
148+
dirs[:] = [d for d in dirs if d not in exclude]
148149
for file in files:
149150
if exclude is None or file not in exclude:
150151
name = os.path.join(root, file)
@@ -262,7 +263,7 @@ class CustomFormatter(argparse.ArgumentDefaultsHelpFormatter,
262263
parser.add_argument('--base-version', '-B', required=True,
263264
help="""Base version for manifest""")
264265
parser.add_argument('--name', '-n', required=True,
265-
help="""Artifact name (human readable). E.g. 'mocha-bcc-mac'.""")
266+
help="""Artifact name (human readable). E.g. 'libfoo-mac'.""")
266267
parser.add_argument('--bits', '-b', type=int, default=64,
267268
help="""bits (32 or 64)""")
268269
parser.add_argument('--build-id', '-i',

0 commit comments

Comments
 (0)