Building from Source

Minimum Supported Rust Version (MSRV)

All published crates require Rust 1.88 or newer (let-chains; Rust edition 2024), as declared by rust-version = "1.88" in each crate’s Cargo.toml.

Clone

Ensure submodules are also cloned.

git clone --recurse-submodules https://github.com/curtisalexander/readstat-rs.git

The ReadStat repository is included as a git submodule within this repository. In order to build and link, first a readstat-sys crate is created. Then the readstat library and readstat-cli binary crate utilize readstat-sys as a dependency.

Linux

Install developer tools

sudo apt install build-essential

Build

cargo build

iconv: Linked dynamically against the system-provided library. On most distributions it is available by default. No explicit link directives are emitted in the build script — the system linker resolves it automatically.

zlib: Linked via the libz-sys crate, which will use the system-provided zlib if available or compile from source as a fallback.

macOS

Install developer tools

xcode-select --install

Build

cargo build

iconv: Linked dynamically against the system-provided library that ships with macOS (via cargo:rustc-link-lib=iconv in the readstat-sys build script). No additional packages need to be installed.

zlib: Linked via the libz-sys crate, which will use the system-provided zlib that ships with macOS.

Windows

Building on Windows requires Visual Studio C++ Build tools be installed.

Build

cargo build

iconv: Compiled from source using the vendored libiconv-win-build submodule (located at crates/readstat-iconv-sys/vendor/libiconv-win-build/) via the readstat-iconv-sys crate. readstat-iconv-sys is a Windows-only dependency (gated behind [target.'cfg(windows)'.dependencies] in readstat-sys/Cargo.toml).

zlib: Compiled from source via the libz-sys crate (statically linked).

Regenerating bindings (maintainers only)

Default builds consume pre-generated bindings checked into crates/readstat-sys/src/bindings/bindings_<os>_<arch>.rs, so no libclang / LLVM install is required. If you need to regenerate the bindings (e.g. after bumping the vendored ReadStat sources or changing wrapper.h), enable the buildtime_bindgen feature on readstat-sys:

cargo build -p readstat-sys --features buildtime_bindgen

This invokes bindgen, which requires LLVM / libclang to be installed. On Windows specifically, you also need to set LIBCLANG_PATH (e.g. C:\Program Files\LLVM\lib). The build script writes the regenerated file to both OUT_DIR (for the current compile) and src/bindings/bindings_<os>_<arch>.rs (so the diff can be committed). Regeneration must be repeated on each supported target OS — the verify-bindings workflow can do this for you (workflow_dispatch → download artifacts → commit).

wasm32-unknown-emscripten builds require --features buildtime_bindgen because the emsdk sysroot can’t be reproduced from a checked-in file.

Linking Summary