README.md 4.49 KB
Newer Older
noplanman's avatar
noplanman committed
1 2 3 4 5 6 7 8
# Borg Binary Builder

Build [BorgBackup] binaries on any platform, for any architecture, using docker.

## Usage

### Build image

9
`./build.sh <arch> [<version>] [<image>]`
noplanman's avatar
noplanman committed
10 11 12 13

See the [list of available architectures] ([on GitHub][available-architectures-github])

*Examples:*
14
- Build version `1.1.14` for `aarch64` with default image name (`borg:1.1.14-aarch64`)
15

16
`./build.sh aarch64 1.1.14`
noplanman's avatar
noplanman committed
17

18
- Build version `1.1.5` for Raspberry Pi 3 with custom image name (`borg:1.1.5-rpi3`)
19

20
`./build.sh raspberrypi3 1.1.5 borg:1.1.5-rpi3`
noplanman's avatar
noplanman committed
21 22 23

### Extract borg binary

24
`./extract.sh <image> <binary_save_location>`
noplanman's avatar
noplanman committed
25
`./extract.sh <arch> [<version>] [<binary_save_location>]`
noplanman's avatar
noplanman committed
26 27 28 29

**Note:** This will overwrite the file at `binary_save_location` if it already exists!

*Examples:*
30
- Extract the borg `1.1.14` binary for `aarch64` to `borg-aarch64` in the current folder
31

32
`./extract.sh aarch64 1.1.14 borg-aarch64`
noplanman's avatar
noplanman committed
33

34
- Extract the borg binary from the `borg:1.1.5-rpi3` image to `/homes/lemoi/borg`
35

36
`./extract.sh borg:1.1.5-rpi3 /homes/lemoi/borg`
noplanman's avatar
noplanman committed
37

38 39 40
### Build base image

To speed up the building process, certain architectures have a prebuilt base image with the development requirements already installed.
41

42 43 44 45
These base images are based on BorgBackup versions:
- 1.1.14 *(for versions 1.1.14 and later)*
- 1.1.10 *(for versions 1.1.10 to 1.1.13)*
- 1.1.0 *(for versions 1.1.0 to 1.1.9)*
46

47
Adding a new architecture (of a specific version) to the base image list and pushing it to docker hub:
48

49
`./build-base.sh <arch> [<version>]`
50 51

*Examples:*
52
- Build base image for `aarch64` set at version 1.1.14:
53

54
`./build-base.sh aarch64 1.1.14`
55

noplanman's avatar
noplanman committed
56 57 58 59
## How this works

### Build

60
The `build.sh` script makes use of the QEMU cross building provided in the used Balena images. For more details, check the [Balena docs].
noplanman's avatar
noplanman committed
61 62 63

Then, the docker image is built for the requested architecture.

64
This is basically done by following the flow of setting up a [BorgBackup development environment] and [creating the standalone binary]. (For more info on this, just have a look at the `Dockerfile` and `docker-setup.sh` files)
noplanman's avatar
noplanman committed
65

66
To use the base images created by `build-base.sh` instead of the normal build image, you can set the `BBB_HOT` environment variable to any value before executing `build.sh`. This starts off the build with the prebuilt base image, speeding up the build tremendously.
67

68
`BBB_HOT=yep ./build.sh ...`
69

70
Builds are based on the Python 3.8 images on Debian Stretch (1.1.14 and later) and the Python 3.5 images on Debian Jessie (1.1.0 to 1.1.13).
71

noplanman's avatar
noplanman committed
72 73 74 75
### Extract

The `extract.sh` script extracts the built binary from the image created using `build.sh`.

76
This basically creates a temporary container from the built image for your selected architecture and version (or custom image name) and writes the binary out to the file path you passed as a parameter.
noplanman's avatar
noplanman committed
77

78 79 80 81 82
## Verify PGP Signature

All automated binary builds can be found on Bintray:
- https://bintray.com/borg-binary-builder/borg-binaries/borg-binaries

83
Using version `1.1.14` for `armv7` as an example:
84

85
1. Simply download the desired binary (`borg-1.1.14-armv7`) and it's corresponding signature file (`borg-1.1.14-armv7.asc`).
86 87 88
2. Next we have to import the official PGP public key needed for verification (which you can find in this repo):
    - `gpg --import borg-binary-builder.public.asc`
3. Then verify the downloaded binary with it's signature file:
89
    - `gpg --verify borg-1.1.14-armv7.asc borg-1.1.14-armv7`
90 91
4. Whoop!

noplanman's avatar
noplanman committed
92 93 94 95
## License

Borg Binary Builder is licensed under the terms of the [WTFPL]. See the [LICENSE] file.

noplanman's avatar
noplanman committed
96 97 98
[BorgBackup]: https://github.com/borgbackup/borg/ "BorgBackup on GitHub"
[BorgBackup development environment]: https://borgbackup.readthedocs.io/en/stable/development.html#building-a-development-environment "BorgBackup development environment"
[creating the standalone binary]: https://borgbackup.readthedocs.io/en/stable/development.html#creating-standalone-binaries "Create standalone binary"
99 100
[list of available architectures]: https://www.balena.io/docs/reference/base-images/base-images/#balena-base-images "List of available Architectures"
[available-architectures-github]: https://github.com/balena-io-library/base-images/tree/master/balena-base-images/python "List of available Architectures on GitHub"
101
[Balena docs]: https://www.balena.io/docs/reference/base-images/base-images/#building-arm-containers-on-x86-machines "Building ARM Containers on x86 Machines"
noplanman's avatar
noplanman committed
102
[WTFPL]: http://www.wtfpl.net/about/ "Do What the Fuck You Want to Public License"
103
[LICENSE]: https://git.feneas.org/borg-binary-builder/borg-binaries/blob/master/LICENSE "View License"