dev: build using plain-ish build.rs

.devin/wiki.json

@@ -86,7 +86,7 @@
     },
     {
       "title": "Crate Structure",
-      "purpose": "Document the Rust workspace layout: each crate (cadmus-core, cadmus, emulator, importer, fetcher, xtask), their roles, the binaries they produce, and the inter-crate dependency graph. Cover shared workspace dependencies such as rustls and the release-minsized build profile.",
+      "purpose": "Document the Rust workspace layout: each crate (cadmus-core, cadmus, emulator, importer, fetcher, xtask, build-deps), their roles, the binaries they produce, and the inter-crate dependency graph. Cover shared workspace dependencies such as rustls and the release-minsized build profile. The build-deps crate is shared between cadmus-core's build.rs and xtask, and owns all thirdparty C/C++ build orchestration (native and Kobo recipes, MuPDF source preparation, mupdf_wrapper compilation).",
       "parent": "Contributor Guide",
       "page_notes": [
         {
@@ -96,7 +96,7 @@
     },
     {
       "title": "Development Environment",
-      "purpose": "Document the devenv and Nix-based reproducible development environment: entering the shell, available cargo xtask commands (setup-native, run-emulator, build-kobo, dist, bundle, test, docs), devenv tasks (deps:native, docs:build, build:kobo), the integrated observability stack (OTel Collector, Prometheus, Tempo, Loki, Grafana), platform support (Linux full, macOS native-only), and local override via devenv.local.nix.",
+      "purpose": "Document the devenv and Nix-based reproducible development environment: entering the shell, available cargo xtask commands (run-emulator, build-kobo, dist, bundle, test, docs, download-assets), devenv tasks (docs:build, build:kobo), the integrated observability stack (OTel Collector, Prometheus, Tempo, Loki, Grafana), platform support (Linux full, macOS full including Kobo cross-compilation), and local override via devenv.local.nix. Thirdparty native dependencies are built lazily by the cadmus-core build.rs (via the build-deps crate) the first time `cargo build` runs, so no explicit setup step is required.",
       "parent": "Contributor Guide",
       "page_notes": [
         {
@@ -176,7 +176,7 @@
     },
     {
       "title": "Building for Device",
-      "purpose": "Explain the end-to-end process for cross-compiling and packaging Cadmus for a target device: the ARM cross-compilation toolchain, cargo xtask build-kobo (fast vs slow modes, mupdf_wrapper compilation), cargo xtask dist assembly, cargo xtask bundle packaging, NickelMenu integration, and the device management shell scripts (wifi-enable.sh, wifi-disable.sh, usb-enable.sh, usb-disable.sh). Currently Kobo-specific; the build system is expected to generalise as additional devices are supported.",
+      "purpose": "Explain the end-to-end process for cross-compiling and packaging Cadmus for a target device: the ARM cross-compilation toolchain, cargo xtask build-kobo (a thin wrapper over `cargo build --release --target arm-unknown-linux-gnueabihf` whose thirdparty native artifacts are produced lazily by the cadmus-core build.rs via the build-deps crate), cargo xtask dist assembly, cargo xtask bundle packaging, NickelMenu integration, and the device management shell scripts (wifi-enable.sh, wifi-disable.sh, usb-enable.sh, usb-disable.sh). Currently Kobo-specific; the build system is expected to generalise as additional devices are supported.",
       "parent": "Contributor Guide",
       "page_notes": [
         {
@@ -186,7 +186,7 @@
     },
     {
       "title": "Third-Party Dependencies",
-      "purpose": "Document the thirdparty/ directory: its role in the cross-compilation pipeline, how library sources are downloaded at build time (not vendored), the dependency-ordered build process via build-kobo.sh scripts, which libraries carry Kobo-specific patches and the rationale behind each patch (e.g. bypassing pkg-config for cross-compilation, stripping unnecessary build targets, adding a device-specific cross-compile target), the relationship between version constants in xtask and Renovate-managed automated updates, and guidance on adding or upgrading a library.",
+      "purpose": "Document the thirdparty/ directory: its role in the cross-compilation pipeline, how library sources are vendored as git submodules and built from source by the build-deps crate (invoked from the cadmus-core build.rs and from xtask), the dependency-ordered build process via per-library recipes in build-deps (build/kobo/recipes.rs for ARM, build/native.rs for the host), which libraries carry Kobo-specific patches under build-scripts/ and the rationale behind each patch (e.g. bypassing pkg-config for cross-compilation, stripping unnecessary build targets, adding a device-specific cross-compile target), the relationship between version constants in build-deps (versions.rs) and Renovate-managed automated updates (including the git-submodules manager for submodule SHAs), and guidance on adding or upgrading a library.",
       "parent": "Contributor Guide",
       "page_notes": [
         {

.github/actions/build-kobo/action.yml

@@ -23,18 +23,6 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Cache Cargo registry
-      id: rust-toolchain-cache
-      uses: actions/cache@v5
-      with:
-        path: |
-          ~/.cargo/bin/
-          ~/.cargo/registry/index/
-          ~/.cargo/registry/cache/
-          ~/.cargo/git/db/
-          target/
-        key: ${{ runner.os }}-cargo-build-kobo-${{ hashFiles('**/Cargo.lock') }}
-
     - name: Cache Linaro toolchain
       id: cache-linaro
       uses: actions/cache@v5
@@ -52,11 +40,6 @@ runs:
         tar xf gcc-linaro-4.9.4-2017.01-x86_64_arm-linux-gnueabihf.tar.xz --strip-components=1
         rm gcc-linaro-4.9.4-2017.01-x86_64_arm-linux-gnueabihf.tar.xz
 
-    - name: Cache thirdparty libraries
-      uses: ./.github/actions/cache-thirdparty
-      with:
-        kind: kobo-build
-
     - name: Cache NickelMenu downloads
       uses: actions/cache@v5
       with:
@@ -88,9 +71,9 @@ runs:
         GH_OAUTH_CLIENT_ID: ${{ inputs.gh-oauth-client-id }}
       run: |
         if [ "${{ inputs.test }}" = "true" ]; then
-          cargo xtask build-kobo --slow --features test
+          cargo xtask build-kobo --features test
         else
-          cargo xtask build-kobo --slow
+          cargo xtask build-kobo
         fi
 
     - name: Create distribution

.github/actions/cargo-cache/action.yml

@@ -0,0 +1,67 @@
+name: Cargo shared cache
+description: >
+  Restore or save the shared Cargo cache. The cache key incorporates the
+  Rust toolchain fingerprint, the Cargo lockfile, build scripts, the
+  mupdf_wrapper C glue, and the gitlink SHAs of every thirdparty
+  submodule so that the key changes when any submodule pointer moves.
+
+  Defaults to restore-only. Pass `mode: save` in the cache-warmup job to
+  write a fresh cache.
+
+inputs:
+  cachekey:
+    description: "The dtolnay/rust-toolchain cachekey output"
+    required: true
+  mode:
+    description: "`restore` (default) or `save` (read-write)"
+    required: false
+    default: restore
+
+outputs:
+  cache-hit:
+    description: "Whether a matching cache entry was found"
+    value: ${{ steps.save.outputs.cache-hit || steps.restore.outputs.cache-hit }}
+
+runs:
+  using: composite
+  steps:
+    - name: Compute submodule hash
+      id: submodules
+      shell: bash
+      run: |
+        # Hash all thirdparty submodule gitlink SHAs so the cache key
+        # changes when any submodule pointer moves.
+        sha=$(git ls-tree HEAD thirdparty/ | sha256sum | cut -c1-12)
+        echo "hash=$sha" >> "$GITHUB_OUTPUT"
+
+    - name: Restore shared cargo cache
+      if: inputs.mode == 'restore'
+      id: restore
+      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae
+      with:
+        path: |
+          ~/.cargo/bin/
+          ~/.cargo/registry/index/
+          ~/.cargo/registry/cache/
+          ~/.cargo/git/db/
+          target/
+          libs/
+        key: ${{ runner.os }}-cargo-shared-${{ inputs.cachekey }}-${{ hashFiles('**/Cargo.lock', 'crates/build-deps/**', 'build-scripts/**', '.gitmodules', 'mupdf_wrapper/mupdf_wrapper.c', 'crates/core/build.rs') }}-${{ steps.submodules.outputs.hash }}
+        restore-keys: |
+          ${{ runner.os }}-cargo-shared-${{ inputs.cachekey }}-
+
+    - name: Save shared cargo cache
+      if: inputs.mode == 'save'
+      id: save
+      uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae
+      with:
+        path: |
+          ~/.cargo/bin/
+          ~/.cargo/registry/index/
+          ~/.cargo/registry/cache/
+          ~/.cargo/git/db/
+          target/
+          libs/
+        key: ${{ runner.os }}-cargo-shared-${{ inputs.cachekey }}-${{ hashFiles('**/Cargo.lock', 'crates/build-deps/**', 'build-scripts/**', '.gitmodules', 'mupdf_wrapper/mupdf_wrapper.c', 'crates/core/build.rs') }}-${{ steps.submodules.outputs.hash }}
+        restore-keys: |
+          ${{ runner.os }}-cargo-shared-${{ inputs.cachekey }}-

.github/workflows/build-release-candidate.yml

@@ -43,9 +43,15 @@ jobs:
           ref: ${{ steps.pr.outputs.branch }}
 
       - uses: dtolnay/rust-toolchain@stable
+        id: rust-toolchain
         with:
           targets: arm-unknown-linux-gnueabihf
 
+      - uses: ./.github/actions/cargo-cache
+        with:
+          cachekey: ${{ steps.rust-toolchain.outputs.cachekey }}
+          mode: restore
+
       - name: Build Kobo artifacts
         uses: ./.github/actions/build-kobo
         with:

.github/workflows/cadmus-docs.yml

@@ -47,6 +47,7 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
       - uses: dtolnay/rust-toolchain@stable
+        id: rust-toolchain
 
       - name: Setup Python
         uses: actions/setup-python@v6
@@ -71,17 +72,15 @@ jobs:
         with:
           node-version: ${{ env.NODE_VERSION }}
 
-      - name: Cache cargo doc
-        uses: actions/cache@v5
+      - uses: ./.github/actions/cargo-cache
         with:
-          path: target/doc
-          key: ${{ runner.os }}-cargo-doc-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-doc-
+          cachekey: ${{ steps.rust-toolchain.outputs.cachekey }}
+          mode: restore
 
       - name: Build documentation portal
         env:
           RUSTDOCFLAGS: -D warnings
+          CADMUS_SKIP_THIRDPARTY_DEPS: "1"
         run: cargo xtask docs --base-url "$ZOLA_BASE_URL"
 
       - name: Upload build artifact