Skip to content

Commit 62e7b69

Browse files
committed
docs: Improve Justfile with groups and self-documenting targets
Justfile changes: - Organize targets into groups (core, testing, docs, debugging, maintenance) - Add `list-variants` target to show available build variants - Simplify comments to be concise single-line descriptions - Move composefs targets (build-sealed, test-composefs) into core group CONTRIBUTING.md changes: - Reference `just --list` and `just list-variants` instead of duplicating - Remove tables that duplicate Justfile information - Fix broken link to cli.rs The Justfile is now self-documenting via `just --list` (grouped targets) and `just list-variants` (build configuration options). Assisted-by: OpenCode (Claude Sonnet 4) Signed-off-by: Colin Walters <walters@verbum.org>
1 parent 766b534 commit 62e7b69

2 files changed

Lines changed: 240 additions & 184 deletions

File tree

CONTRIBUTING.md

Lines changed: 44 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,20 @@ accepted!
4141
Worth stating: before you start diving into the code you should understand using
4242
the system as a user and how it works. See the user documentation for that.
4343

44-
## Understanding the Justfile
44+
## The Justfile
45+
46+
The [Justfile](Justfile) is the primary interface for building and testing bootc.
47+
48+
```bash
49+
just --list # Show all targets organized by group
50+
just list-variants # Show available build variants and current config
51+
```
52+
53+
### Building from source
4554

4655
Edit the source code; a simple thing to do is add e.g.
47-
`eprintln!("hello world");` into `run_from_opt` in [crates/lib/src/cli.rs](cli.rs).
48-
You can run `make` or `cargo build` to build that locally. However, a key
56+
`eprintln!("hello world");` into `run_from_opt` in [crates/lib/src/cli.rs](crates/lib/src/cli.rs).
57+
You can run `make` or `cargo build` to build that locally. However, a key
4958
next step is to get that binary into a bootc container image.
5059

5160
Running `just` defaults to `just build` which will build a container
@@ -58,14 +67,24 @@ and try running `bootc`.
5867

5968
### Running container-oriented integration tests
6069

61-
`just test-container`
70+
```bash
71+
just test-container
72+
```
6273

6374
### Running (TMT) integration tests
6475

6576
A common cycle here is you'll edit e.g. `deploy.rs` and want to run the
6677
tests that perform an upgrade:
6778

68-
`just test-tmt-one test-20-local-upgrade`
79+
```bash
80+
just test-tmt local-upgrade-reboot
81+
```
82+
83+
To run a specific test:
84+
85+
```bash
86+
just test-tmt readonly
87+
```
6988

7089
### Faster iteration cycles
7190

@@ -96,6 +115,26 @@ then you can `cargo b --release` directly in a Fedora 42 container
96115
or even on your host system, and then directly run e.g. `./target/release/bootc upgrade`
97116
etc.
98117

118+
### Testing with composefs (sealed images)
119+
120+
To build and test with the experimental composefs backend:
121+
122+
```bash
123+
# Build a sealed image with auto-generated test Secure Boot keys
124+
just build-sealed
125+
126+
# Run composefs-specific tests
127+
just test-composefs
128+
129+
# Validate that composefs digests match between build and install views
130+
# (useful for debugging mtime/metadata issues)
131+
just validate-composefs-digest
132+
```
133+
134+
The `build-sealed` target generates test Secure Boot keys in `target/test-secureboot/`
135+
and builds a complete sealed image with UKI. See [experimental-composefs.md](docs/src/experimental-composefs.md)
136+
for more information on sealed images.
137+
99138

100139
### Debugging via lldb
101140

0 commit comments

Comments
 (0)