Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Contributor docs cannot produce a working from-source build: CONTRIBUTING contradicts rust-toolchain.toml, Dockerfile.dev is at rust:1.75, and the gc-effects sidecar step is undocumented

Aperta
  • Qualcosa non va?
#12,979 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
73/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
cmake, rust
Ambito
build-system, devtools, documentation

Direzione di ricerca

Read CONTRIBUTING.md, rust-toolchain.toml, .cargo/config.toml, and Dockerfile.dev; compare the documented setup with the build sequence and failures described in the issue. Check the repository’s LLVM and gc-effects sidecar requirements, then update the contributor instructions to cover the toolchain, native dependencies, full workspace build, and sidecar generation. Done when a clean Linux x86_64 contributor can follow the docs from setup through a working perry compile.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Building Perry from source on a clean Linux x86_64 host needs four things the contributor docs either omit or actively contradict. Each was hit in order, and each cost a failed build to discover.

1. CONTRIBUTING.md says the workspace pins no toolchain; rust-toolchain.toml pins one

CONTRIBUTING.md:25:

| Rust | stable (≥ 1.94) | Everything. The workspace pins no toolchain, so an older stable fails deep in the dependency graph with a [email protected] requires rustc 1.94.0 MSRV error rather than a clear message — rustup update stable fixes it. |

But rust-toolchain.toml does pin one, channel = "nightly-2026-10-04", and its own comment explains why the file has to exist for exactly the case CONTRIBUTING describes:

Why this file has to exist as well as the workflow inputs: those inputs only govern jobs that go through the action. Nothing else does — a contributor's cargo build, a bisect, a hand-built release artifact, or any script invoking cargo directly.

Following CONTRIBUTING literally and installing stable fails with the option Z is only accepted on the nightly compiler, because .cargo/config.toml passes -Z use-sync-unwind. Suggest the row read "nightly, as pinned by rust-toolchain.toml" and drop the "pins no toolchain" clause.

Related: half of that file's own rationale is now stale. It also justifies the pin with:

perry-runtime uses the float_algebraic methods, so without this file those builds fail with E0658 while CI stays green.

float_algebraic has been stable since 1.98.0. On current nightly the feature gate warns that it "has been stable since 1.98.0 and no longer requires an attribute to enable". Only -Z use-sync-unwind still genuinely requires nightly, so that sentence should be updated or removed before it misleads someone into thinking a recent stable is enough for the opposite reason.

2. Dockerfile.dev cannot build the project

Dockerfile.dev:11 is FROM rust:1.75-bookworm, with rustup component add rustfmt clippy and no LLVM.

  • 1.75 is below even CONTRIBUTING's stated 1.94 minimum, let alone the pinned nightly.
  • No LLVM is installed, so llvm-sys cannot find a suitable version.

As far as I can tell the file cannot produce a working build environment. Either it needs the pinned toolchain plus LLVM 22, or it should say what it is for.

3. LLVM_SYS_221_PREFIX is required and undocumented

With LLVM 22 installed but not in the default search path, the build fails with No suitable version of LLVM was found. It needs LLVM_SYS_221_PREFIX=<llvm-22-prefix> and LIBCLANG_PATH=<prefix>/lib. On a Homebrew host, libffi and zstd also need to be on LIBRARY_PATH, otherwise rust-lld: unable to find library -lffi and -lzstd (the latter while building perry-gc-effects). cmake is required too, for libz-ng-sys.

4. cargo build --release alone is not enough to compile a program

After a successful full workspace build, perry compile fails at link time:

Error: the runtime GC effects sidecar cannot speak for the archives this program links:
  target/release/libperry_runtime.a.gc-effects does not exist

The error message is excellent and names the fix (scripts/gc_call_effects/sidecars.sh target/release), so this is purely a docs gap: nothing in CONTRIBUTING mentions that a from-source build needs that step before the compiler can be used. A "building from source" section listing cargo build --release then sidecars.sh target/release would close it.

Separately, -p perry alone builds a binary that cannot link any program that touches a well-known module — libperry_ext_http.a and friends come from the full workspace build. Worth stating, since -p perry is the natural thing to try.

Working sequence, for reference

asdf install rust nightly          # or rustup; see note below
export LLVM_SYS_221_PREFIX=/home/linuxbrew/.linuxbrew/opt/llvm@22
export LIBCLANG_PATH=$LLVM_SYS_221_PREFIX/lib
export LIBRARY_PATH=/home/linuxbrew/.linuxbrew/opt/libffi/lib:/home/linuxbrew/.linuxbrew/opt/zstd/lib:$LLVM_SYS_221_PREFIX/lib
export PATH=$LLVM_SYS_221_PREFIX/bin:$PATH     # clang, for perry-runtime's build.rs
cargo build --release
scripts/gc_call_effects/sidecars.sh target/release

That produces a working perry 0.5.1662 from 20fde48d in about 10 minutes for the compiler and 10 for the rest of the workspace.

Note on the first line: asdf's rust plugin does not list nightly in asdf list all rust, but asdf install rust nightly works and gives a toolchain that satisfies -Z use-sync-unwind. asdf shims do not read rust-toolchain.toml, so the pinned date is bypassed; current nightly (1.101.0-nightly) builds the workspace fine. Mentioning this would help anyone not using rustup.

Environment

Linux x86_64, Homebrew LLVM 22.1.8, rustc 1.101.0-nightly (19833af72 2026-10-20), Perry main @ 20fde48d. No apt packages were needed.

Lingua principale
Rust
Stelle
4.9k
Fork
166
Merge medio
1h 26m
PR unite (30g)
912

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di PerryTS/perry

Tutte le issue di PerryTS/perry

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.