docs: update build/devenv docs for thirdparty submodules and auto setup

[dosubot]

Summary

Update documentation for #571

Documentation now reflects that thirdparty C/C++ dependencies are managed as git submodules (tracked via .gitmodules) and built automatically by the build-deps crate/build.rs, rather than using a one-time cargo xtask setup-native step or xtask-managed version constants. The AGENTS guide was updated to describe the new per-library build-scripts/<lib>/ layout, dependency-order source of truth in build-deps/src/versions.rs, and Renovate's git-submodules tracking workflow. The devenv-setup and SKILL pages were revised to remove setup-native from the required workflow, adjust emulator/build-kobo host support (Linux and macOS), and update the listed build modes and prerequisites accordingly.

Follow-up fixes

Cleans up stale references that would error at runtime or mislead developers:

• devenv.nix: Removed deps:native task, cadmus-setup-native script, and --slow flag from build:kobo/cadmus-build-kobo (the setup-native xtask and --slow CLI flag no longer exist)
• thirdparty/AGENTS.md: Fixed build-deps/src/versions.rs → crates/build-deps/src/versions.rs (2 occurrences)
• build-scripts/mupdf/README.md: Replaced stale cargo xtask setup-native reference with build-deps crate's build.rs
• docs/po/messages.pot: Regenerated to reflect English doc source changes
• docs/po/xx.po: Merged against updated .pot to remove stale setup-native msgid

Generated by Dosu

Link to Devin session: https://app.devin.ai/sessions/508d9277efa2403da78a7e04c8020e3b
Requested by: @OGKevin

[OGKevin]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 5200d7df-1712-46aa-9d07-d215ab39c897

📥 Commits

Reviewing files that changed from the base of the PR and between edb3154 and 223ee73.

⛔ Files ignored due to path filters (1)

• docs/po/messages.pot is excluded by !docs/po/messages.pot

📒 Files selected for processing (7)

• .agents/skills/build-cadmus-native/SKILL.md
• .agents/skills/build-kobo/SKILL.md
• build-scripts/mupdf/README.md
• devenv.nix
• docs/po/xx.po
• docs/src/contributing/devenv-setup.md
• thirdparty/AGENTS.md

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (3)

docs/src/**/*.md

📄 CodeRabbit inference engine (docs/AGENTS.md)

docs/src/**/*.md: Use conversational and friendly tone in user-facing documentation
Use active voice in user-facing documentation (e.g., 'Copy the file' instead of 'The file should be copied')
Avoid jargon in user-facing documentation: replace 'artifact' with 'file' or 'package', 'deploy' with 'install' or 'download', 'configure' with 'set up', 'bundle' with 'package', 'on-device' with 'on your Kobo' or 'wirelessly'
Use standardized admonition syntax for documentation: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]

Files:

• docs/src/contributing/devenv-setup.md

docs/src/contributing/**/*.md

📄 CodeRabbit inference engine (docs/AGENTS.md)

docs/src/contributing/**/*.md: Use clear and direct language in contributor documentation with code examples where helpful
Document setup steps precisely in contributor documentation

Files:

• docs/src/contributing/devenv-setup.md

docs/**/*.md

📄 CodeRabbit inference engine (docs/AGENTS.md)

docs/**/*.md: Format Markdown with Prettier
Ensure Markdown passes markdownlint
Use code blocks with language tags in Markdown

Files:

• docs/src/contributing/devenv-setup.md

🧠 Learnings (26)

📓 Common learnings

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: docs/AGENTS.md:0-0
Timestamp: 2026-06-04T12:03:49.867Z
Learning: Applies to docs/**/devenv.nix : Update docs/src/contributing/devenv-setup.md when modifying devenv.nix: keep Available Commands table, Platform Support section, Observability Stack, and Troubleshooting in sync

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: In CI, `cargo xtask download-assets` must run before `cargo xtask build-kobo` so the generated asset list stays accurate

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/**/thirdparty/*/{build-kobo.sh,*-kobo.patch} : Prefer using kobo.patch for working around upstream issues rather than modifying build-kobo.sh — patches make the delta explicit and reviewable

Learnt from: CR
Repo: OGKevin/cadmus

Timestamp: 2026-06-08T05:36:29.930Z
Learning: Build libraries in dependency order as defined by `LIBRARY_NAMES` in `crates/build-deps/src/versions.rs`. A library later in the list may link against libraries earlier in the list.

Learnt from: CR
Repo: OGKevin/cadmus

Timestamp: 2026-06-08T05:36:29.930Z
Learning: Apply `kobo.patch` before building patched libraries. Use patches when upstream sources need modification for the cross-compilation environment.

Learnt from: CR
Repo: OGKevin/cadmus

Timestamp: 2026-06-08T05:36:29.930Z
Learning: When upgrading a patched library, verify the patch still applies cleanly against the new source and regenerate it if the patched files changed upstream.

Learnt from: CR
Repo: OGKevin/cadmus

Timestamp: 2026-06-08T05:36:29.930Z
Learning: Never commit built artifacts — only commit source code via submodules and patches in `build-scripts/`.

Learnt from: CR
Repo: OGKevin/cadmus

Timestamp: 2026-06-08T05:36:29.930Z
Learning: Prefer a `kobo.patch` over modifying build logic to work around upstream issues — patches make the delta explicit and reviewable.

📚 Learning: 2026-05-27T00:35:26.129Z

Learnt from: ewired
Repo: OGKevin/cadmus PR: 456
File: thirdparty/mupdf/webp-upstream-697749-kobo.patch:347-352
Timestamp: 2026-05-27T00:35:26.129Z
Learning: In the Cadmus repository, `thirdparty/mupdf/webp-upstream-697749-kobo.patch` is a read-only KOReader upstream patch and must not be modified. Cadmus-specific fixes to `source/fitz/load-webp.c` (including the WebP decoder) belong in `thirdparty/mupdf/webp-load-webp-deviations-kobo.patch` instead.

Applied to files:

• build-scripts/mupdf/README.md
• thirdparty/AGENTS.md

📚 Learning: 2026-05-26T20:10:56.991Z

Learnt from: OGKevin
Repo: OGKevin/cadmus PR: 456
File: crates/core/src/document/mupdf_sys.rs:7-10
Timestamp: 2026-05-26T20:10:56.991Z
Learning: In `crates/core/src/document/mupdf_sys.rs` (OGKevin/cadmus), the project owner prefers safety/soundness documentation for unsafe code to be written as `///` Rust doc comments on the function (so they appear in generated rustdoc), rather than as inline `// SAFETY:` comments inside the unsafe block.

Applied to files:

• build-scripts/mupdf/README.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/**/thirdparty/*/+(build-kobo.sh|kobo.patch|*-kobo.patch|README-kobo.md|README-cadmus.md|Makefile-kobo) : Each library subdirectory may contain build-kobo.sh, kobo.patch, *-kobo.patch files, README-kobo.md, README-cadmus.md, and additional build system files

Applied to files:

• build-scripts/mupdf/README.md
• .agents/skills/build-kobo/SKILL.md
• thirdparty/AGENTS.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/**/thirdparty/*/{build-kobo.sh,*-kobo.patch} : Prefer using kobo.patch for working around upstream issues rather than modifying build-kobo.sh — patches make the delta explicit and reviewable

Applied to files:

• build-scripts/mupdf/README.md
• thirdparty/AGENTS.md
• devenv.nix

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: In CI, `cargo xtask download-assets` must run before `cargo xtask build-kobo` so the generated asset list stays accurate

Applied to files:

• .agents/skills/build-kobo/SKILL.md
• thirdparty/AGENTS.md
• docs/src/contributing/devenv-setup.md
• devenv.nix
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-25T12:43:50.793Z

Learnt from: OGKevin
Repo: OGKevin/cadmus PR: 511
File: crates/core/build.rs:129-131
Timestamp: 2026-05-25T12:43:50.793Z
Learning: In `crates/core/build.rs`, the `generate_bundled_assets()` function intentionally skips missing asset directories (`if !dir.exists() { return; }`) to support emulator/non-Kobo builds where OTA is not used and asset directories may not be present. Any fail-fast guard for missing required directories (e.g., `bin/`, `resources/`, `hyphenation-patterns/`) should be gated on the Kobo target (`TARGET == "arm-unknown-linux-gnueabihf"`) to avoid breaking emulator builds.

Applied to files:

• .agents/skills/build-kobo/SKILL.md
• thirdparty/AGENTS.md
• docs/src/contributing/devenv-setup.md
• devenv.nix
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/**/thirdparty/*/build-kobo.sh : All builds must target arm-linux-gnueabihf with -mcpu=cortex-a9 -mfpu=neon compiler flags

Applied to files:

• .agents/skills/build-kobo/SKILL.md
• thirdparty/AGENTS.md

📚 Learning: 2026-06-06T19:59:31.071Z

Learnt from: OGKevin
Repo: OGKevin/cadmus PR: 571
File: .github/workflows/cargo.yml:162-166
Timestamp: 2026-06-06T19:59:31.071Z
Learning: In `.github/workflows/cargo.yml`, the `cargo xtask download-assets` step in `cache-warmup` is intentionally gated behind the same `if: steps.cache.outputs.cache-hit != 'true'` condition as the warmup build steps. On a warm cache hit, neither assets nor warmup builds run; the `build-kobo` jobs restore from a shared cache that already contains assets from a prior cold run. Running `download-assets` unconditionally in this job is not required.

Applied to files:

• .agents/skills/build-kobo/SKILL.md
• docs/src/contributing/devenv-setup.md
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: After modifying `Cargo.toml`, run `cargo xtask clippy` and `cargo xtask test --features default`

Applied to files:

• .agents/skills/build-kobo/SKILL.md
• docs/src/contributing/devenv-setup.md
• devenv.nix
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: If code generates compile-time metadata from bundled asset directories, ensure `bin/`, `resources/`, and `hyphenation-patterns/` are present before the Kobo build starts

Applied to files:

• .agents/skills/build-kobo/SKILL.md
• thirdparty/AGENTS.md
• docs/src/contributing/devenv-setup.md
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/xtask/src/tasks/util/thirdparty.rs : Library versions must be defined as constants in xtask/src/tasks/util/thirdparty.rs — never hard-code URLs in build scripts

Applied to files:

• .agents/skills/build-kobo/SKILL.md
• thirdparty/AGENTS.md
• docs/src/contributing/devenv-setup.md
• devenv.nix
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/**/thirdparty/** : Build scripts and patches for third-party libraries must be placed in the thirdparty directory, with no downloaded source trees committed — only build scripts and patches

Applied to files:

• thirdparty/AGENTS.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/xtask/src/tasks/util/thirdparty.rs : Respect the build order defined by LIBRARY_NAMES in xtask/src/tasks/util/thirdparty.rs — libraries later in the list may link against earlier ones, and new libraries must be inserted at the correct position

Applied to files:

• thirdparty/AGENTS.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/**/thirdparty/*/*-kobo.patch : When upgrading a patched library, verify the patch still applies cleanly against the new source and regenerate it if the patched files changed upstream

Applied to files:

• thirdparty/AGENTS.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: The `libs/` directory is special: all Cadmus-shipped shared libraries may be cleaned before reboot because the next `KoboRoot.tgz` repopulates that directory

Applied to files:

• thirdparty/AGENTS.md

📚 Learning: 2026-05-27T15:13:37.212Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: thirdparty/AGENTS.md:0-0
Timestamp: 2026-05-27T15:13:37.212Z
Learning: Applies to thirdparty/**/renovate.json : Ensure Renovate regex managers in renovate.json cover new library version constants to enable automated update PRs

Applied to files:

• thirdparty/AGENTS.md

📚 Learning: 2026-06-04T12:03:49.867Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: docs/AGENTS.md:0-0
Timestamp: 2026-06-04T12:03:49.867Z
Learning: Applies to docs/**/devenv.nix : Update docs/src/contributing/devenv-setup.md when modifying devenv.nix: keep Available Commands table, Platform Support section, Observability Stack, and Troubleshooting in sync

Applied to files:

• docs/src/contributing/devenv-setup.md
• devenv.nix
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-06-04T12:03:49.867Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: docs/AGENTS.md:0-0
Timestamp: 2026-06-04T12:03:49.867Z
Learning: Applies to docs/src/contributing/**/*.md : Document setup steps precisely in contributor documentation

Applied to files:

• docs/src/contributing/devenv-setup.md

📚 Learning: 2026-06-04T12:03:49.867Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: docs/AGENTS.md:0-0
Timestamp: 2026-06-04T12:03:49.867Z
Learning: Applies to docs/src/**/*.md : Avoid jargon in user-facing documentation: replace 'artifact' with 'file' or 'package', 'deploy' with 'install' or 'download', 'configure' with 'set up', 'bundle' with 'package', 'on-device' with 'on your Kobo' or 'wirelessly'

Applied to files:

• docs/src/contributing/devenv-setup.md

📚 Learning: 2026-05-31T07:53:12.579Z

Learnt from: OGKevin
Repo: OGKevin/cadmus PR: 553
File: docs/src/installation/migration.md:87-88
Timestamp: 2026-05-31T07:53:12.579Z
Learning: For markdown files under docs/src/ in the cadmus (OGKevin/cadmus) repo, validate mdBook admonition syntax using the allowed types: NOTE, TIP, WARNING, IMPORTANT, and CAUTION. The correct format is a blockquote prefix like `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`, or `> [!CAUTION]`. Do not flag `[!CAUTION]` or `[!IMPORTANT]` as non-standard in this repo.

Applied to files:

• docs/src/contributing/devenv-setup.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: Applies to .github/workflows/cargo.yml : The `clippy` and `test` jobs in `.github/workflows/cargo.yml` use a matrix to check every feature flag individually and in combination

Applied to files:

• devenv.nix
• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: Applies to .github/workflows/cargo.yml : For workspace-wide feature flags in CI, use `--workspace --all-targets --features <name>` in `.github/workflows/cargo.yml`

Applied to files:

• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: Applies to .github/workflows/cargo.yml : For crate-specific feature flags in CI, use `-p <crate> --all-targets --features <name>` in `.github/workflows/cargo.yml`

Applied to files:

• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: Applies to .github/workflows/cargo.yml : Only `default` and `test` features should produce build artifacts in `.github/workflows/cargo.yml`

Applied to files:

• .agents/skills/build-cadmus-native/SKILL.md

📚 Learning: 2026-05-28T14:01:38.823Z

Learnt from: CR
Repo: OGKevin/cadmus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-05-28T14:01:38.823Z
Learning: Applies to .github/workflows/cargo.yml : All feature flag combinations should run on `ubuntu-latest` in `.github/workflows/cargo.yml`

Applied to files:

• .agents/skills/build-cadmus-native/SKILL.md

🪛 LanguageTool

thirdparty/AGENTS.md

[style] ~61-~61: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ild-deps/src/build/kobo/recipes.rs. 3. Add the library name to LIBRARY_NAMES` in ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (6)

.agents/skills/build-cadmus-native/SKILL.md (1)

32-32: LGTM!

Also applies to: 41-43, 82-84, 96-98

.agents/skills/build-kobo/SKILL.md (1)

7-7: LGTM!

Also applies to: 12-12, 22-24, 33-35

devenv.nix (1)

681-681: LGTM!

Also applies to: 704-704

docs/src/contributing/devenv-setup.md (1)

21-21: LGTM!

Also applies to: 32-37, 73-77, 193-194

build-scripts/mupdf/README.md (1)

4-5: LGTM!

thirdparty/AGENTS.md (1)

5-7: LGTM!

Also applies to: 12-13, 17-19, 29-30, 34-35, 51-56, 58-65, 69-70, 72-72, 75-76

---

Walkthrough

This PR consolidates native dependency building into build-deps's build.rs, removing the separate cargo xtask setup-native step. Skill documentation is updated to clarify automatic MuPDF/libwebp compilation, build-kobo support is broadened from Linux-only to Linux and macOS with Linaro toolchain support on both, and the development environment (devenv.nix) is updated to drop setup-native references while adding Linaro toolchain PATH setup. Documentation for commands, tasks, and third-party dependency workflows is refreshed to reflect git-submodule-based tracking, build-deps-driven orchestration, and Renovate's git-submodules manager.

Sequence Diagram(s)

The changes are primarily documentation and configuration updates reflecting an internal implementation shift—no new feature interactions or multi-component flows are introduced that would warrant a sequence diagram. The architectural change (moving build logic from xtask setup-native to build-deps's build.rs) is already embedded in the codebase; this PR communicates that change to users and contributors.

Possibly related PRs

• OGKevin/cadmus#520: Updates docs for Kobo build support on macOS and changes build-kobo framing from "Linux-only" to cross-platform.
• OGKevin/cadmus#518: Modifies devenv.nix task configuration for cargo xtask build-kobo and aligns documentation toward macOS cross-compilation support.

Suggested reviewers

• OGKevin

---

🏗️ No more setup dance—just cargo build and watch the native deps flow,
From build-deps to Kobo, on Linux and macOS we go.
Docs rewritten clean, the workflow's now clear,
Submodules and Renovate—the future is here! ✨

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: update build/devenv docs for thirdparty submodules and auto setup' follows the Conventional Commits format with a clear 'docs' type prefix and accurately describes the main changes across documentation and configuration files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}