Skip to content

README quick-start omits Linux system dependencies, causing guaranteed build failure on fresh clone #3087

Description

@newellg

Check for other issues

  • I've checked for other issues, and none exist.

Issue description

Following the README's "Getting Started" quick-start on a fresh Ubuntu machine
leads directly to a build failure, because the documented steps never mention
scripts/setup.sh or any system package installation. That step only exists
in CONTRIBUTING.md, which the README's quick-start doesn't reference or link to.

Steps to reproduce

On a clean Ubuntu install (24.04/25.x, apt-based), with only Rust, Bun, and
just installed (i.e. exactly what the README says is required):

git clone https://github.com/spacedriveapp/spacedrive
cd spacedrive
just setup

just setup runs bun install then cargo xtask setup. Two separate
failures occur in sequence:

1. cargo xtask setup itself fails on a fresh clone with:
error: no such command: 'xtask'
This is because the xtask cargo alias is defined inside .cargo/config.toml,
which is gitignored and only gets generated by cargo xtask setup itself —
a bootstrap chicken-and-egg problem. Workaround: cargo run -p xtask -- setup
(unaliased form) works on the first run.

2. Once past that, building the release daemon (part of xtask setup) fails
building openssl-sys, then ffmpeg-sys-next's bindgen step, then linking
iroh-relay, with errors like:
The system library `openssl` required by crate `openssl-sys` was not found.
...
/usr/include/limits.h:124:16: fatal error: 'limits.h' file not found
Unable to generate bindings: ClangDiagnostic(...)
...
rust-lld: error: unable to find library -lz
rust-lld: error: unable to find library -lzstd

Root cause: none of libssl-dev, clang (only the libclang runtime lib was
present, not the actual clang toolchain — this is what causes the bindgen
limits.h error specifically), zlib1g-dev, or libzstd-dev are installed,
because nothing in the followed instructions said to install them.

scripts/setup.sh (documented only in CONTRIBUTING.md, not linked from the
README) does install most of these (libssl-dev, clang, llvm-dev,
libclang-dev, etc. via its apt branch) — but even that script doesn't
install zlib1g-dev or libzstd-dev, so the -lz/-lzstd linker errors
persist even after running it.


### Platform and versions

Environment

- OS: Ubuntu (apt-based), fresh install
- rustc/cargo: 1.97.1
- Followed only the README's documented prerequisites (Rust, Bun, just, Python)


### Stack trace

```shell

Additional context

Suggested fix

  • Either fold scripts/setup.sh into the README's quick-start (e.g. as a
    step before just setup on Linux), or have the just setup recipe itself
    detect Linux and prompt to run it first.
  • Add zlib1g-dev and libzstd-dev to scripts/setup.sh's apt (and
    equivalent pacman/dnf/apk/eopkg) package lists.
  • Consider having the justfile's setup recipe use cargo run -p xtask -- setup instead of the aliased cargo xtask setup, since the alias
    provably doesn't exist yet on a first-time clone.

Code of Conduct

  • I agree to follow the Code of Conduct.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions