[FEATURE] Generate native Rustdoc JSON from selected sources #197

Open
opened 2026-10-27 17:13:13 +01:00 by erikinkinen · 3 comments
Owner

Problem and motivation

The API converter accepts Rustdoc JSON, but Integration does not produce it from its selected Cargo sources. Native-only interfaces, including the cwd adapters, need matching JSON before their references can be regenerated.

Proposed behavior and scope

Add a Rustdoc JSON stage after source and dependency resolution. Start with Exsh, LibIPC and its syscall crate, LibPosixABI, LibCstd and its POSIX I/O runtime. Use explicit native target and feature profiles, locked offline dependencies, and selected Cargo, compiler, Rustdoc and runtime inputs. Keep the existing converter.

Authority, security and reliability

Reuse the source pipeline and native process owners. Keep sources, tools, locks, children and output files owned through conversion and cleanup. Names and receipts remain descriptive data. Preserve the first failure and partial outputs; uncertain cleanup must prevent reuse. Add no network fallback or inherited tool discovery.

Acceptance criteria

  • Produce JSON for the selected native libraries, including nested packages and native-only exports.
  • Match metadata and Rustdoc target/features, and reject changed or foreign source, lock and tool inputs.
  • Pass an explicitly selected Rustdoc executable and runtime through the existing command runner.
  • Retain original and exported JSON safely across repeated target names; reject missing, replaced, malformed or partial files.
  • Cover success, refusal, cancellation, callback reentry and cleanup failures while preserving original owners and errors.
  • Document the stage and regenerate/check the affected API references from its fresh outputs and matching source selectors.

Alternatives and tradeoffs

Callers can continue supplying JSON themselves, but must coordinate its source, profile and tool provenance separately. Rustdoc JSON also requires a supported toolchain and converter format.

Tracking and rollout

Related: Phase 6, build inventory, documentation, and cwd. Implement the producer, then regenerate the selected references. Whole-manual and in-EriX build acceptance remain separate requirements.

## Problem and motivation The API converter accepts Rustdoc JSON, but Integration does not produce it from its selected Cargo sources. Native-only interfaces, including the cwd adapters, need matching JSON before their references can be regenerated. ## Proposed behavior and scope Add a Rustdoc JSON stage after source and dependency resolution. Start with Exsh, LibIPC and its syscall crate, LibPosixABI, LibCstd and its POSIX I/O runtime. Use explicit native target and feature profiles, locked offline dependencies, and selected Cargo, compiler, Rustdoc and runtime inputs. Keep the existing converter. ## Authority, security and reliability Reuse the source pipeline and native process owners. Keep sources, tools, locks, children and output files owned through conversion and cleanup. Names and receipts remain descriptive data. Preserve the first failure and partial outputs; uncertain cleanup must prevent reuse. Add no network fallback or inherited tool discovery. ## Acceptance criteria - [ ] Produce JSON for the selected native libraries, including nested packages and native-only exports. - [ ] Match metadata and Rustdoc target/features, and reject changed or foreign source, lock and tool inputs. - [x] Pass an explicitly selected Rustdoc executable and runtime through the existing command runner. - [ ] Retain original and exported JSON safely across repeated target names; reject missing, replaced, malformed or partial files. - [ ] Cover success, refusal, cancellation, callback reentry and cleanup failures while preserving original owners and errors. - [ ] Document the stage and regenerate/check the affected API references from its fresh outputs and matching source selectors. ## Alternatives and tradeoffs Callers can continue supplying JSON themselves, but must coordinate its source, profile and tool provenance separately. Rustdoc JSON also requires a supported toolchain and converter format. ## Tracking and rollout Related: [Phase 6](https://git.erikinkinen.fi/erix/integration/issues/65), [build inventory](https://git.erikinkinen.fi/erix/integration/issues/1), [documentation](https://git.erikinkinen.fi/erix/docs/issues/1), and [cwd](https://git.erikinkinen.fi/erix/posixd/issues/44). Implement the producer, then regenerate the selected references. Whole-manual and in-EriX build acceptance remain separate requirements.
Author
Owner

The producer is implemented in Integration. It uses the completed Cargo graph and explicit package, target, feature and tool inputs, then retains the original and exported files through conversion and retirement. Fresh Rustdoc generation and the affected API references remain open.

The producer is implemented in [Integration](https://git.erikinkinen.fi/erix/integration/commit/acdeaf70b2b83143e9e4bb911ec67be45582a11c). It uses the completed Cargo graph and explicit package, target, feature and tool inputs, then retains the original and exported files through conversion and retirement. Fresh Rustdoc generation and the affected API references remain open.
Author
Owner

The producer has completed a fresh original-source fixture using the selected Cargo, compiler, Rustdoc and runtime. Paired metadata and JSON generation used x86_64-unknown-none with native-fixture: the native and feature-gated APIs were present, and the host-only API was absent. Sources, outputs and process owners remained held through the checks and completed cleanup. The six selected library packages and their converter/manual adoption remain next.

The producer has completed a fresh original-source fixture using the selected Cargo, compiler, Rustdoc and runtime. Paired metadata and JSON generation used `x86_64-unknown-none` with `native-fixture`: the native and feature-gated APIs were present, and the host-only API was absent. Sources, outputs and process owners remained held through the checks and completed cleanup. The six selected library packages and their converter/manual adoption remain next.
Author
Owner

The six regenerated API references now include the C file, pipe and readiness interfaces. Generation and an independent second conversion completed while the original producers retained their sources and JSON outputs.

The native command owner also retains failed status publication on its original invocation and handles cancellation after completed retirement. The C runtime and documentation builds now select these fixes through the coordinated consumers. Guest C execution and the complete build inside EriX remain outstanding.

The six [regenerated API references](https://git.erikinkinen.fi/erix/docs/commit/91374fb0a139cee1d4f346ce2d25fd08eae8e8f3) now include the C file, pipe and readiness interfaces. Generation and an independent second conversion completed while the original producers retained their sources and JSON outputs. The [native command owner](https://git.erikinkinen.fi/erix/integration/commit/7bf80c35d2b5a950d6525418a7e0487bffad95ba) also retains failed status publication on its original invocation and handles cancellation after completed retirement. The C runtime and documentation builds now select these fixes through the [coordinated consumers](https://git.erikinkinen.fi/erix/integration/commit/fbe198a23ea9adc65df0ca01042daadfc4f84422). Guest C execution and the complete build inside EriX remain outstanding.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:34:22 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/integration#197
No description provided.