Skip to main content

Requirements

This page details the requirements and dependencies needed to use SingleRust effectively.

Rust and Cargo​

SingleRust requires a recent version of Rust and Cargo:

  • Rust: Version 1.70.0 or higher
  • Cargo: Comes with Rust installation

Installing Rust and Cargo​

If you don't have Rust installed, we recommend using rustup, the Rust toolchain installer:

For Linux and macOS:​

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the on-screen instructions, then reload your shell or run:

source $HOME/.cargo/env

For Windows:​

  1. Download the rustup-init.exe installer from https://win.rustup.rs/
  2. Run the installer and follow the on-screen instructions

Verifying Rust Installation​

Verify your Rust installation by running:

rustc --version
cargo --version

System Dependencies​

SingleRust relies on several system libraries for its functionality:

Essential Dependencies​

  • pkg-config: Used for locating system libraries
  • HDF5: Required for reading and writing H5AD files
  • zlib: Compression library, needed for HDF5
  • fontconfig: Required for plotting functionality

Optional Dependencies​

  • BLAS/LAPACK: Required when using the lapack feature
  • OpenMP: For parallel computation when using certain features

Installing System Dependencies​

For Ubuntu/Debian:​

sudo apt update
sudo apt install pkg-config libhdf5-dev zlib1g-dev libfontconfig-dev
# For optional LAPACK support
sudo apt install libopenblas-dev liblapack-dev

For Fedora/RHEL/CentOS:​

sudo dnf install pkgconfig hdf5-devel zlib-devel fontconfig-devel
# For optional LAPACK support
sudo dnf install openblas-devel lapack-devel

For macOS:​

Using Homebrew:

brew install pkg-config hdf5 fontconfig
# For optional LAPACK support
brew install openblas lapack

For Windows:​

Using MSYS2/MinGW:

pacman -S mingw-w64-x86_64-pkg-config mingw-w64-x86_64-hdf5 mingw-w64-x86_64-fontconfig
# For optional LAPACK support
pacman -S mingw-w64-x86_64-openblas

Alternatively, you can use vcpkg:

vcpkg install hdf5:x64-windows zlib:x64-windows fontconfig:x64-windows

Environment Variables​

Some libraries may require specific environment variables to be set:

For HDF5:​

If HDF5 is installed in a non-standard location, you may need to set:

# Linux/macOS
export HDF5_DIR=/path/to/hdf5

# Windows PowerShell
$env:HDF5_DIR = "C:\path\to\hdf5"

For LAPACK/BLAS:​

When using the lapack feature, you may need to specify library paths:

# Linux/macOS
export OPENBLAS_LIB_DIR=/path/to/openblas/lib
export LAPACK_LIB_DIR=/path/to/lapack/lib

# Windows PowerShell
$env:OPENBLAS_LIB_DIR = "C:\path\to\openblas\lib"
$env:LAPACK_LIB_DIR = "C:\path\to\lapack\lib"

Hardware Requirements​

SingleRust is designed to handle large datasets efficiently. Recommended hardware specifications:

  • RAM: 8GB minimum, 16GB+ recommended for most single-cell datasets
  • CPU: Multi-core processor recommended (4+ cores for optimal parallel processing)
  • Disk: SSD recommended for faster I/O operations
  • GPU: Not required, but can be utilized with specific features for accelerated computation

Development Requirements​

If you plan to contribute to SingleRust or build from source:

  • git: For repository management
  • rust-analyzer: Recommended for IDE integration
  • rustfmt and clippy: For code formatting and linting (installed by default with rustup)

Install development tools:

rustup component add rustfmt clippy

Troubleshooting Common Issues​

HDF5 Not Found​

If you encounter an error about HDF5 not being found:

  1. Ensure HDF5 is installed
  2. Verify that pkg-config can find HDF5: 
    pkg-config --libs hdf5
  3. Set the HDF5_DIR environment variable if necessary

Linking Errors​

If you encounter linking errors related to BLAS or LAPACK:

  1. Make sure you have installed the appropriate libraries
  2. Set the environment variables mentioned in the Environment Variables section
  3. Consider building with different features based on your system capability: 
    cargo build --no-default-features --features="native-blas"

Other Build Issues​

For other build issues, consult the project's GitHub Issues or create a new issue with details about your system and the exact error messages.