Platform support considerations for RDoc (and other bundled gems) adoption

Context

RDoc is a bundled gem in Ruby, which means:

• docs.ruby-lang.org/en/master is generated using the bundled version
• Ruby CI runs against the bundled version - failures can block Ruby core
• Ruby supports a wide range of platforms, as shown in the rubyci.org matrix. And currently RDoc can be used to generate documentation on all of them as its written in pure Ruby and has no 3rd party dependencies.

If RDoc were to depend on rubydex, platforms that can not build it due to Rust/cargo dependencies support would:

• Not have ri docs available
• Not be able to build Ruby with docs
• Not be able to use RDoc at all (e.g. build gems' docs)

This is different from ZJIT/YJIT, which gracefully disable themselves when Rust is unavailable.

Ruby's platform matrix

Ruby CI tests on the following platforms (rubyci.org, master branch):

Category	Platforms
Linux x86_64	Debian (11, 12, 13, testing), Ubuntu (22.04, 24.04, 26.04), RHEL (8, 9, 10), Fedora 43, Amazon Linux (2, 2023), ArchLinux, OpenSUSE Leap 16.0
Linux aarch64	Ubuntu 26.04, Fedora 42
BSD	OpenBSD 7.7, FreeBSD (13.5, 14.3 x64), FreeBSD 15.0 arm64
macOS	Ventura (M1), Sonoma (M1)
Specialized	ppc64le (Ubuntu), s390x (Ubuntu), riscv64 (Ubuntu 22.04)
Other	WSL2 (Ubuntu 22.04), icc compiler (Ubuntu)

Rust platform support

Rust uses a tiered platform support system:

• Tier 1: Guaranteed to work, official binaries, automated testing
• Tier 2: Guaranteed to build, official binaries, but limited testing
• Tier 3: May or may not work, no official binaries or testing

Mapping Ruby's CI platforms to Rust's tiers:

Platform	Rust Tier	Notes
x86_64, aarch64 (Linux/macOS)	Tier 1	Full support
ppc64le, s390x, riscv64	Tier 2	Builds, but limited testing
FreeBSD x86_64	Tier 2
FreeBSD arm64	Tier 3	May or may not work
OpenBSD	Tier 3	May or may not work

Tier 2/3 platforms may have issues with specific crates or Cargo features. The 70+ transitive dependencies in rubydex increase the risk of encountering platform-specific issues.

YJIT/ZJIT platform support

YJIT/ZJIT only enable themselves on a subset of platforms:

Enabled:

• x86_64 and aarch64/arm64 architectures
• On macOS, Linux, or BSD only

Disabled (Ruby still builds, just without JIT):

• Specialized architectures in Ruby CI: ppc64le, s390x, riscv64
• Windows
• Other unsupported platforms (older ARM variants, etc.)

Current rubydex vs YJIT/ZJIT

Aspect	Rubydex	YJIT	ZJIT
Rust version	1.89.0	1.58.0	1.85.0
Edition	2024	2021	2024
Transitive dependencies	70+ crates	0	0
Build system	Cargo required	Direct rustc works	Direct rustc works
Fallback when Rust unavailable	None	Gracefully disables	Gracefully disables

Recommendations

This issue is NOT intended to block development. However, when making decisions about Rust versions or dependencies, please consider:

1. Rust version: The current requirement of 1.89.0 is recent. Let's consider platform supports when we deciding whether to bump Rust versions in the future too.

2. Dependency auditing: When adding new dependencies, consider their platform support. Some crates may have platform-specific code or dependencies that limit where rubydex can run.

No repository files or tests are named. Start by reviewing the Ruby CI platform matrix and Rust's tiered platform-support documentation, then trace how RDoc and rubydex would affect bundled-gem builds; done means documenting a clear compatibility decision and its platform implications.