toolchain/README.md

124 lines
3.2 KiB
Markdown
Raw Normal View History

2023-01-28 00:05:03 +00:00
# Toolchain #
<https://codeberg.org/distrust/toolchain>
## About ##
A library of opinionated make functions targeting projects that either need
2023-01-28 00:52:14 +00:00
deterministic builds, or a deterministic toolchain shared across all who use a
project.
2023-01-28 00:05:03 +00:00
A dev of a Toolchain enabled project should never need to have anything
on their host system installed but docker, and git. Everything else will be
provided via a Docker container.
Debian currently has the highest reproducibility score of any major Linux
distribution, and as such it is the chosen base for Toolchain.
This was built for Distrust projects, and some of our clients. It is unlikely
to meet the needs of everyone. We suggest including this in your project as
a git subtree, so you can make your own changes, but also pull in changes from
us as desired.
## Uses ##
* Ensure everyone on a team is using the exact same tools
* Ensure all releases and artifacts build hash-for-hash identical every time
* Control supply chain security with only signed/reproducible dependencies
## Features ##
* Can run a shell with all toolchain tooling in the current directory
* Provide make functions for common tasks
* Git clone, apply patches, etc.
* Use a global env file as configuration
* Hash-locking of apt dependencies from a list of top-level required packages
* Provides release.env file with required vars to re-create old releases
## Requirements ##
* docker 18+
* GNU Make 4+
2023-01-28 00:52:14 +00:00
## Setup ##
2023-01-28 00:05:03 +00:00
2023-01-28 00:52:14 +00:00
1. Clone toolchain as a git submodule somewhere in your project
2023-01-28 00:05:03 +00:00
```
git submodule add https://codeberg.org/distrust/toolchain src/toolchain
2023-01-28 00:05:03 +00:00
```
2023-01-28 00:52:14 +00:00
2. Include toolchain Makefile in your root Makefile
2023-01-28 00:05:03 +00:00
```
2023-01-28 00:52:14 +00:00
include src/toolchain/Makefile
2023-01-28 00:05:03 +00:00
```
2023-01-28 00:52:14 +00:00
3. Define any build/dev dependencies for toolchain container
```
echo "libfaketime" >> config/toolchain/packages-base.txt
echo "build-essential" >> config/toolchain/packages-base.txt
```
4. Lock a base Debian container image hash
```
echo "DEBIAN_HASH=48b28b354484a7f0e683e340fa0e6e4c4bce3dc3aa0146fc2f78f443fde2c55d" >> config/global.env
```
5. Generate hashlocks files for all toolchain container dependencies
```
make toolchain-update
```
6. Define your artifact targets
```
$(OUT_DIR)/hello: toolchain \
2023-01-28 00:56:08 +00:00
$(call toolchain,$(USER)," \
2023-01-28 00:52:14 +00:00
cd $(SRC_DIR)/; \
gcc hello.c -o $(OUT_DIR)/hello
2023-01-28 00:56:08 +00:00
")
2023-01-28 00:52:14 +00:00
```
7. Define a release target for your project depending on manifest.txt
2023-01-28 00:05:03 +00:00
```
2023-01-28 00:52:14 +00:00
.PHONY: release
release: $(OUT_DIR)/hello $(OUT_DIR)/manifest.txt
mkdir -p $(RELEASE_DIR)
2023-01-28 00:54:51 +00:00
cp $(OUT_DIR)/hello $(RELEASE_DIR)/hello
2023-01-28 00:52:14 +00:00
cp $(OUT_DIR)/release.env $(RELEASE_DIR)/release.env
cp $(OUT_DIR)/manifest.txt $(RELEASE_DIR)/manifest.txt
2023-01-28 00:05:03 +00:00
```
2023-01-28 00:52:14 +00:00
Note that manifest.txt is optional, but it makes for an ideal single file
to sign if a release will contain more than one artifact.
## Usage ##
### Build a new release
```
make VERSION=1.0.0rc1 release
```
### Reproduce an existing release
```
make VERSION=1.0.0rc1 attest
```
2023-01-28 01:00:24 +00:00
### Add and lock a new container dependency
2023-01-28 00:52:14 +00:00
```
2023-01-28 01:00:24 +00:00
echo "vim-nox" >> config/toolchain/packages-base.txt
make toolchain-update
```
### Run a shell in the toolchain container
```
make toolchain-shell
2023-01-28 00:52:14 +00:00
```