wireapp · fewerner · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
@@ -223,3 +223,10 @@ dist
 
 crypto-ffi/bindings/build
 interop/src/clients/build
+
+# Antora builds
+cc-book/build
+cc-book/**/attachments/doc/*
+
+# Ruby dependencies
+**/.bundle
@@ -69,7 +69,7 @@ WORKSPACE_CARGO_FILES := Cargo.toml Cargo.lock
 CRATE_MANIFESTS := $(addsuffix /Cargo.toml,$(CRATES))
 
 # Enumerate all .rs files in relevant crates
-RUST_RS_FILES := $(shell find $(CRATES) \( -type d -name rust_modules -o -type d -name node_modules \) -prune -o \
+RUST_RS_FILES := $(shell find $(CRATES) \( -type d -name rust_modules -o -type d -name node_modules -o -type d -name autogenerated \) -prune -o \
     -type f -name '*.rs' -print 2>/dev/null | LC_ALL=C sort)
 
 # Files relevant to build interop
@@ -496,7 +496,7 @@ WASM_TARGET_TRIPLE := wasm32-unknown-unknown
 WASM_BUILD_RUSTFLAGS := --cfg getrandom_backend=\"wasm_js\" -Awarnings
 BROWSER_OUT_DIR := $(TS_OUT_DIR)/browser
 TS_NATIVE_OUT_DIR := $(TS_OUT_DIR)/native
-BROWSER_OUT := $(BROWSER_OUT_DIR)/corecrypto.d.ts $(BROWSER_OUT_DIR)/corecrypto.js $(wildcard $(BROWSER_OUT_DIR)/wasm-bindgen/*)
+BROWSER_OUT := $(BROWSER_OUT_DIR)/corecrypto.d.ts $(BROWSER_OUT_DIR)/corecrypto.js
 
 ifeq ($(UNAME_S),Linux)
 TS_NATIVE_TARGET_TRIPLE ?= x86_64-unknown-linux-gnu
@@ -541,7 +541,12 @@ ts-clean: ## Cleanup old TypeScript build outputs
 	&& rm -rf $(JS_DIR)/rust_modules
 
 
-WASM_GEN := $(wildcard $(BROWSER_GEN_DIR)/wasm-bindgen/*) $(BROWSER_GEN_DIR)/core_crypto_ffi.ts
+WASM_GEN := \
+	$(BROWSER_GEN_DIR)/wasm-bindgen/index_bg.wasm \
+	$(BROWSER_GEN_DIR)/wasm-bindgen/index_bg.wasm.d.ts \
+	$(BROWSER_GEN_DIR)/wasm-bindgen/index.d.ts \
+	$(BROWSER_GEN_DIR)/wasm-bindgen/index.js \
+	$(BROWSER_GEN_DIR)/core_crypto_ffi.ts
 
 # As soon as ubrn allows reusage of an existing ffi lib, we need to depend on it here.
 wasm-build-deps := $(RUST_SOURCES) $(BUN_LOCK) $(NODE_MODULES) $(PACKAGE_JSON) $(BUNFIG)
@@ -550,7 +555,7 @@ wasm-build-deps := $(RUST_SOURCES) $(BUN_LOCK) $(NODE_MODULES) $(PACKAGE_JSON) $
 # the shared target outputs used by ios/jvm builds.
 #
 # We are accepting warnings on the generated code when running `cargo check`, this is consistent with the ubrn config.
-$(WASM_GEN): $(wasm-build-deps)
+$(WASM_GEN) &: $(wasm-build-deps)
 	cd $(JS_DIR) && \
 	$(WASM_BUILD_ENV) bun ubrn build web --no-wasm-pack && \
 	cp ../../../Cargo.lock ./rust_modules/wasm/Cargo.lock && \
@@ -567,7 +572,7 @@ wasm-build: $(WASM_GEN)
 
 # generate TypeScript defs only when corecrypto.js changed
 ts-browser-deps := $(TS_BROWSER_SRCS) $(WASM_GEN)
-$(BROWSER_OUT): $(ts-browser-deps)
+$(BROWSER_OUT) &: $(ts-browser-deps)
 	cd $(JS_DIR) && \
 	bun build src/browser/CoreCrypto.ts \
 	  --conditions=cc-browser \
@@ -591,7 +596,7 @@ $(BROWSER_OUT): $(ts-browser-deps)
 ts-browser: $(BROWSER_OUT) ## Build the TypeScript wrapper for the browser
 
 ts-native-deps := $(TS_NATIVE_SRCS) $(RUST_SOURCES) $(BUN_LOCK) $(NODE_MODULES) $(PACKAGE_JSON) $(BUNFIG)
-$(TS_NATIVE_OUT): $(ts-native-deps)
+$(TS_NATIVE_OUT) &: $(ts-native-deps)
 	cd $(JS_DIR) && \
 	rm -rf out/native && \
 	mkdir -p out/native/autogenerated && \
@@ -723,15 +728,15 @@ docs-rust-wasm: $(STAMPS)/docs-rust-wasm ## Generate Rust docs for wasm32-unknow
 # Kotlin docs
 KOTLIN_SOURCES := $(shell find crypto-ffi/bindings/shared/src/commonMain/kotlin \
 	                           -type f -name '*.kt' 2>/dev/null | LC_ALL=C sort)
-DOCS_KOTLIN := target/kotlin/doc/html/index.html
-$(DOCS_KOTLIN): $(JVM_LIB) $(KOTLIN_SOURCES)
+docs-kotlin-deps := $(JVM_LIB) $(jvm-deps) $(KOTLIN_SOURCES)
+$(STAMPS)/docs-kotlin: $(docs-kotlin-deps)
 	cd crypto-ffi/bindings && ./gradlew jvm:dokkaGeneratePublicationHtml
 	mkdir -p target/kotlin/doc
-	cp -R crypto-ffi/bindings/jvm/build/dokka/html/ target/kotlin/doc
+	cp -R crypto-ffi/bindings/jvm/build/dokka/html target/kotlin/doc
+	$(TOUCH_STAMP)
 
 .PHONY: docs-kotlin
-docs-kotlin-deps := $(jvm-deps) $(KOTLIN_SOURCES)
-docs-kotlin: $(DOCS_KOTLIN) ## Generate Kotlin docs
+docs-kotlin: $(STAMPS)/docs-kotlin ## Generate Kotlin docs
 
 # TypeScript docs via Typedoc
 $(STAMPS)/docs-ts: $(BROWSER_OUT) $(TS_NATIVE_OUT)
@@ -769,6 +774,21 @@ docs-swift: $(STAMPS)/docs-swift ## Generate Swift iOS docs (macOS only)
 .PHONY: docs
 docs: docs-rust-generic docs-rust-wasm docs-kotlin docs-ts $(if $(filter Darwin,$(UNAME_S)),docs-swift) ## Generate all docs (excluding Swift on non-Darwin platforms)
 
+$(STAMPS)/cc-book-browser-attachments: $(STAMPS)/docs-ts
+	mkdir -p cc-book/modules/browser/attachments
+	cp -r target/typescript/doc cc-book/modules/browser/attachments/
+	$(TOUCH_STAMP)
+
+$(STAMPS)/cc-book-jvm-attachments: $(STAMPS)/docs-kotlin
+	mkdir -p cc-book/modules/jvm/attachments
+	cp -r target/kotlin/doc cc-book/modules/jvm/attachments/
+	$(TOUCH_STAMP)
+
+# Build the CC book using Antora
+.PHONY: cc-book
+cc-book: $(STAMPS)/cc-book-browser-attachments $(STAMPS)/cc-book-jvm-attachments
+	cd cc-book && \
+	bunx antora antora-playbook.yml
 #-------------------------------------------------------------------------------
 # Aggregate targets
 #-------------------------------------------------------------------------------

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'asciidoctor-pdf'
+gem 'logger'
+gem 'bigdecimal'
+gem 'rouge'
+gem 'asciidoctor-epub3'
@@ -0,0 +1,139 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (2.0.1)
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    afm (1.0.0)
+    asciidoctor (2.0.26)
+    asciidoctor-epub3 (2.3.0)
+      asciidoctor (~> 2.0)
+      gepub (~> 1.0.0)
+      mime-types (~> 3.0)
+      sass
+    asciidoctor-pdf (2.3.24)
+      asciidoctor (~> 2.0)
+      concurrent-ruby (~> 1.3)
+      matrix (~> 0.4)
+      prawn (~> 2.4.0)
+      prawn-icon (~> 3.0.0)
+      prawn-svg (~> 0.34.0)
+      prawn-table (~> 0.2.0)
+      prawn-templates (~> 0.1.0)
+      treetop (~> 1.6.0)
+      ttfunk (~> 1.7.0)
+    bigdecimal (4.0.1)
+    concurrent-ruby (1.3.6)
+    css_parser (1.21.1)
+      addressable
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
+    gepub (1.0.17)
+      nokogiri (>= 1.8.2, < 2.0)
+      rubyzip (> 1.1.1, < 2.4)
+    hashery (2.1.2)
+    logger (1.7.0)
+    matrix (0.4.3)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2026.0317)
+    nokogiri (1.19.2-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.2-x86_64-linux-gnu)
+      racc (~> 1.4)
+    pdf-core (0.9.0)
+    pdf-reader (2.15.1)
+      Ascii85 (>= 1.0, < 3.0, != 2.0.0)
+      afm (>= 0.2.1, < 2)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    polyglot (0.3.5)
+    prawn (2.4.0)
+      pdf-core (~> 0.9.0)
+      ttfunk (~> 1.7)
+    prawn-icon (3.0.0)
+      prawn (>= 1.1.0, < 3.0.0)
+    prawn-svg (0.34.2)
+      css_parser (~> 1.6)
+      matrix (~> 0.4.2)
+      prawn (>= 0.11.1, < 3)
+      rexml (~> 3.2)
+    prawn-table (0.2.2)
+      prawn (>= 1.3.0, < 3.0.0)
+    prawn-templates (0.1.2)
+      pdf-reader (~> 2.0)
+      prawn (~> 2.2)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rexml (3.4.4)
+    rouge (4.7.0)
+    ruby-rc4 (0.1.5)
+    rubyzip (2.3.2)
+    sass (3.7.4)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    treetop (1.6.18)
+      polyglot (~> 0.3)
+    ttfunk (1.7.0)
+
+PLATFORMS
+  arm64-darwin-24
+  x86_64-linux-gnu
+
+DEPENDENCIES
+  asciidoctor-epub3
+  asciidoctor-pdf
+  bigdecimal
+  logger
+  rouge
+
+CHECKSUMS
+  Ascii85 (2.0.1) sha256=15cb5d941808543cbb9e7e6aea3c8ec3877f154c3461e8b3673e97f7ecedbe5a
+  addressable (2.8.9) sha256=cc154fcbe689711808a43601dee7b980238ce54368d23e127421753e46895485
+  afm (1.0.0) sha256=5bd4d6f6241e7014ef090985ec6f4c3e9745f6de0828ddd58bc1efdd138f4545
+  asciidoctor (2.0.26) sha256=16e3accf1fc206bbd6335848649d7fd65f31d2daa60d85af13d47a8ee4b071c1
+  asciidoctor-epub3 (2.3.0) sha256=114cb2759beb4f7a44fbf5b8c890882f29ee0e15f5cfadaf7a67304da33e8c58
+  asciidoctor-pdf (2.3.24) sha256=3076e55132d43b21de93cd7c8149a8c1b2e4afc07e79855fb6b795a0ef20b051
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  css_parser (1.21.1) sha256=6cfd3ffc0a97333b39d2b1b49c95397b05e0e3b684d68f77ec471ba4ec2ef7c7
+  ffi (1.17.3-arm64-darwin) sha256=0c690555d4cee17a7f07c04d59df39b2fba74ec440b19da1f685c6579bb0717f
+  ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
+  gepub (1.0.17) sha256=8c72dd33f47a437bddde1cef6d8d6a9d5cd4721c79bb8d2df70f66bf9fb33c3a
+  hashery (2.1.2) sha256=d239cc2310401903f6b79d458c2bbef5bf74c46f3f974ae9c1061fb74a404862
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  matrix (0.4.3) sha256=a0d5ab7ddcc1973ff690ab361b67f359acbb16958d1dc072b8b956a286564c5b
+  mime-types (3.7.0) sha256=dcebf61c246f08e15a4de34e386ebe8233791e868564a470c3fe77c00eed5e56
+  mime-types-data (3.2026.0317) sha256=77f078a4d8631d52b842ba77099734b06eddb7ad339d792e746d2272b67e511b
+  nokogiri (1.19.2-arm64-darwin) sha256=58d8ea2e31a967b843b70487a44c14c8ba1866daa1b9da9be9dbdf1b43dee205
+  nokogiri (1.19.2-x86_64-linux-gnu) sha256=fa8feca882b73e871a9845f3817a72e9734c8e974bdc4fbad6e4bc6e8076b94f
+  pdf-core (0.9.0) sha256=4f368b2f12b57ec979872d4bf4bd1a67e8648e0c81ab89801431d2fc89f4e0bb
+  pdf-reader (2.15.1) sha256=18c6a986a84a3117fa49f4279fc2de51f5d2399b71833df5d2bccd595c7068ce
+  polyglot (0.3.5) sha256=59d66ef5e3c166431c39cb8b7c1d02af419051352f27912f6a43981b3def16af
+  prawn (2.4.0) sha256=82062744f7126c2d77501da253a154271790254dfa8c309b8e52e79bc5de2abd
+  prawn-icon (3.0.0) sha256=dac8d481dee0f60a769c0cab0fd1baec7351b4806bf9ba959cd6c65f6694b6f5
+  prawn-svg (0.34.2) sha256=afff79d332940f6d59604d0b2810f54d46e9335533a2aa4e892fb7d514777a90
+  prawn-table (0.2.2) sha256=336d46e39e003f77bf973337a958af6a68300b941c85cb22288872dc2b36addb
+  prawn-templates (0.1.2) sha256=117aa03db570147cb86fcd7de4fd896994f702eada1d699848a9529a87cd31f1
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
+  rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rouge (4.7.0) sha256=dba5896715c0325c362e895460a6d350803dbf6427454f49a47500f3193ea739
+  ruby-rc4 (0.1.5) sha256=00cc40a39d20b53f5459e7ea006a92cf584e9bc275e2a6f7aa1515510e896c03
+  rubyzip (2.3.2) sha256=3f57e3935dc2255c414484fbf8d673b4909d8a6a57007ed754dde39342d2373f
+  sass (3.7.4) sha256=808b0d39053aa69068df939e24671fe84fd5a9d3314486e1a1457d0934a4255d
+  sass-listen (4.0.0) sha256=ae9dcb76dd3e234329e5ba6e213f48e532c5a3e7b0b4d8a87f13aaca0cc18377
+  treetop (1.6.18) sha256=a3043f32f1c652aa2abdf3a3848edb2d2f69897257af2675516ac61355c183da
+  ttfunk (1.7.0) sha256=2370ba484b1891c70bdcafd3448cfd82a32dd794802d81d720a64c15d3ef2a96
+
+BUNDLED WITH
+  4.0.8
@@ -0,0 +1,51 @@
+# The CoreCrypto Book
+
+This folder contains the source of the CoreCrypto Book. This book contains both an overview of core CoreCrypto concepts,
+and detailed migration guides for certain major migrations.
+
+## Building the Book
+
+### Prerequisites
+
+- Install the node modules
+
+  ```sh
+  pushd cc-book
+  bun install
+  popd
+  ```
+
+- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/)
+
+- Install bundler
+
+  ```sh
+  pushd cc-book
+  bundler_version="$(grep -A1 'BUNDLED WITH' Gemfile.lock | tail -n1)"
+  sudo gem install bundler -v "$bundler_version"
+  popd
+  ```
+
+- Install Ruby deps
+
+  ```sh
+  pushd cc-book
+  bundle config set --local frozen true
+  bundle config set --local path .bundle
+  bundle install
+  popd
+  ```
+
+### The Build
+
+```sh
+make cc-book
+```
+
+### Serving Locally
+
+It is often handy to serve the book locally. In a separate terminal:
+
+```sh
+miniserve cc-book/build/site --index index.html
+```
@@ -0,0 +1,8 @@
+assembly:
+  xml_ids: true
+  attributes:
+    allow-uri-read: ''
+    source-highlighter: rouge
+    toc: ''
+build:
+  command: bundle exec asciidoctor-epub3
@@ -0,0 +1,7 @@
+assembly:
+  attributes:
+    allow-uri-read: ''
+    source-highlighter: rouge
+    toc: ''
+build:
+  command: bundle exec asciidoctor-pdf --sourcemap --trace
@@ -0,0 +1,18 @@
+site:
+  title: CoreCrypto
+  start_page: core-crypto::index.adoc
+  url: https://docs.example.org # TODO: set this, this is important for printed docs like pdf
+content:
+  sources:
+  - url: ../
+    branches: HEAD
+    start_path: cc-book
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files: ./supplemental-ui
+antora:
+  extensions:
+  - '@antora/pdf-extension'
+  - '@antora/epub-extension'
@@ -0,0 +1,5 @@
+name: core-crypto
+version: 10.0
+title: CoreCrypto
+nav:
+- modules/ROOT/nav.adoc