Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#12,979 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
73/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
cmake, rust
Domain
build-system, devtools, documentation

Research direction

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.

Written by the indexing model from the issue text.

Description

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.

Dominant language
Rust
Stars
4.9k
Forks
166
Avg merge
1h 20m
Merged PRs (30d)
915

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PerryTS/perry

All issues in PerryTS/perry

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.