Installation Guide (Developer)

AI capabilities are already quite strong nowadays. If you encounter problems during development, you can usually resolve them by having an inexpensive AI model (such as Deepseek-flash or ChatGPT-luna) scan through the project.

This page only covers some necessary, or rather personalized, notes.

1. Development Environment

• Operating System: Linux is recommended; macOS is also acceptable. Although RSTSR has been verified to run on Windows, developing on Windows is not recommended.
• Rust Toolchain: Nightly is recommended (and is also specified in each project's rust-toolchain.toml). Note that the purpose of using nightly is to provide better support for rustfmt and clippy; for the RSTSR project as a whole, Rust edition 2021 and MSRV 1.82 are currently required.

2. Common Test Commands

The following commands are taken from rstsr's GitHub Actions workflows (.github/workflows/), and developers can use them directly.

2.1 Core Library Tests (without BLAS)

# core library unit tests
cargo test -p rstsr-core --lib --release
cargo test -p rstsr-common --lib --release

# core library tests under column-major configuration
# (col_major and row_major are mutually exclusive features)
cargo test -p rstsr-core --lib --release \
  --no-default-features \
  --features="std backtrace faer rayon col_major faer_as_default"

# integration tests
cargo test -p rstsr-core --test "*" --release

2.2 OpenBLAS Backend Tests

OpenBLAS tests require additional preparation (installing the library and generating test data):

# 1. install OpenBLAS (with OpenMP support)
sudo apt-get install -y libopenblas-openmp-dev

# 2. prepare the conda environment and test data
#    (tests depend on .npy data generated by numpy/scipy)
conda install -y numpy scipy
cd rstsr-test-manifest/resources && python gen_rand_vec.py

# 3. run the tests (note the --test-threads=1, see the explanation below)
RSTSR_DEV=1 cargo test -p rstsr-openblas --release --features="openmp linalg" -- --test-threads=1

2.3 Linalg (faer backend) Tests

cargo test -p rstsr-linalg-traits --test "*" --release --features="faer"

2.4 Code Style Checks

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

2.5 Notes on cargo test Options

In general, for the parts that do not involve a BLAS backend, a plain cargo test is often sufficient (it has been verified that cargo test -p rstsr-core --lib can run in parallel normally).

However, for the parts that involve a BLAS backend, cargo test by default runs each test function in parallel with multiple threads within the same test binary, and each test function may spawn its own rayon thread pool and BLAS thread pool, which can lead to thread scheduling contention or thread stack overflow. Please use cargo test -- --test-threads=1 when testing BLAS backends (especially the matmul and linalg parts) to avoid running tests in parallel.

RSTSR can generally only guarantee safety on the main thread and on child threads spawned from the main thread (i.e., the scenario of embedding the RSTSR library in a binary for execution). The parallel test threads of cargo test and their child threads are not the working environment that RSTSR's design takes into account.

For convenience and safety, please generally include the --test-threads=1 argument.

3. AI Coding Assistance

RSTSR can be used as a standalone project, but if you want to use AI for assisted development, it is best to put the entire project family together:

• rstsr: https://github.com/RESTGroup/rstsr
  • The core RSTSR project, where all the important code is developed; the API documentation for docs.rs is also written in the corresponding programs.
• rstsr-book: https://github.com/RESTGroup/rstsr-book
  • The documentation project of RSTSR, which contains user documentation, developer documentation, technical documentation, and a blog, distinct from the API documentation.
• rstsr-agents: https://github.com/RESTGroup/rstsr-agents
  • The code agent project of RSTSR. This project is still under development and will include standard components needed for AI-assisted development, such as AGENTS.md and .agents.
• rstsr-ffi: https://github.com/RESTGroup/rstsr-ffi
  • The FFI project of RSTSR, which contains binding code for C/C++ libraries.

If you need to use AI for assisted development, please refer to the AGENTS.md file in the rstsr-agents project. Our application of AI to RSTSR is still in an exploratory stage; the general stance is permissive but cautious, and parts other than integration tests and FFI generally require explicit review.

The entire RSTSR project (except rstsr-agents) adds the common AI-assisted development file paths to .gitignore. Developers can configure their local AI agent settings according to their own needs without affecting other developers.

4. BLAS Backends and Using OpenBLAS

For ordinary RSTSR users, using faer as the parallel computation and linear algebra backend is sufficient. Most ordinary users do not need additional configuration.

But for users with high-performance computing development needs, a BLAS-supporting backend is generally required. RSTSR supports many mainstream BLAS backends, such as OpenBLAS, MKL, AOCL, KML, and BLIS/FLAME.

Different BLAS backends may have slightly different implementations (or may introduce differentiated implementations in the future), especially in handling parallel thread count control and GEMM calls. But in the vast majority of cases, different BLAS backends share the same implementation. Therefore, if a developer notices a problem with one BLAS backend's implementation, or needs to introduce a new feature, it is recommended to make the same change to all BLAS backends.

OpenBLAS is currently the BLAS backend that supports the most operating systems and microarchitectures. We recommend that general developers prioritize OpenBLAS as the BLAS development backend, and OpenMP support should be enabled. Other BLAS backends are used only for adaptation purposes, or in real applications as higher-performance BLAS backends replacing OpenBLAS.

To use the OpenBLAS backend in development,

• Set the environment variable RSTSR_DEV=1. This will link openblas and gomp when compiling the library rstsr-openblas.
• Set the environment variable LD_LIBRARY_PATH, adding the path to the OpenBLAS library (there must be a libopenblas.so/dylib file, not libopenblas.a or libopenblas.so.0).
• Make sure that OpenBLAS is linked with OpenMP. The crate rstsr-openblas treats OpenBLAS differently depending on whether OpenMP is linked; on Linux, please confirm with ldd libopenblas.so whether libgomp.so or libomp.so is linked to OpenBLAS.
• Make sure that libgomp.so or libomp.so is in the system library path or in LD_LIBRARY_PATH.
• Enable the feature openmp for the crate rstsr-openblas. With this option enabled, RSTSR's OpenBLAS backend can properly recognize and use the OpenMP thread pool.
• Or enable the feature dynamic_loading as an alternative. This option dynamically loads libopenblas at runtime and detects its parallel mode, without needing to link the OpenMP library at compile time; it is suitable for environments where configuring RSTSR_DEV and the libgomp linking is inconvenient. But after enabling it, the path to libopenblas.so/dylib must be provided at runtime. Note that dynamic_loading may introduce too much debug information, causing the build artifacts to be too large or the first compilation to take too long.

info

The crate rstsr-openblas does not enable the feature openmp by default; this is because in distributions such as conda or apt, the default OpenBLAS version is sometimes serial or pthreads-parallel.

However, we believe that, whether in terms of thread scheduling convenience or performance, OpenMP is a better choice than pthreads. RSTSR's OpenBLAS backend can control the number of OpenMP threads at runtime, thus achieving the ability to run BLAS functions serially. Therefore, after setting device.set_num_threads(1), RSTSR API users can ask the BLAS backend to run BLAS functions in single-threaded mode, without the need to specifically link a serial BLAS library.

We may change the default feature settings of the crate rstsr-openblas in the future; the openmp feature may be enabled by default later.

Other backends can also be configured in a similar way. The environment variable RSTSR_DEV=1 is designed as a development backdoor. As a library rather than a binary program, we generally do not provide build.rs, but require users to do the linking in their own binary projects. However, for development convenience, some libraries have build.rs that ordinary users would not enable, but which can be adjusted through the RSTSR_DEV=1 backdoor option; in that case, RSTSR_DEV=1 enables a linking process specifically for development mode.

5. VS Code Setup

Our programs are developed in VS Code. Developers can open all RSTSR projects through a workspace, or open only a single RSTSR project. We exclude the .vscode configuration files via .gitignore in all projects, so developers can configure their own VS Code working environment.

Below is an example workspace configuration file, which developers can refer to when setting up their own VS Code working environment.

Note that

• Please install the rust-analyzer extension in VS Code.
• Please put rstsr, rstsr-book, rstsr-ffi, and rstsr-agents in the same folder (e.g., rstsr-pack), save the json configuration file below as rstsr-pack.code-workspace, and then open this workspace file in VS Code.
• For developers using AI code agents, depending on the code agent you use (OpenCode-based or Claude-based), please symlink the folder rstsr-agents to .agents or .claude in the workspace directory, and symlink the key prompt file rstsr-agents/AGENTS.md to AGENTS.md or CLAUDE.md in the workspace directory.

Notes on the configuration file below:

• RAYON_NUM_THREADS is set to the number of physical cores (rather than logical cores), to avoid thread scheduling contention.
• CARGO_TARGET_DIR is set to debug. Since the environment variables in VS Code are likely to be different from those you set in the terminal, to avoid the situation where different compilation settings between VS Code and the terminal frequently break incremental compilation, we suggest that VS Code and the terminal use different cargo target directories; the terminal uses the usual target directory, while VS Code uses the debug directory. Both are excluded via .gitignore and will not affect other developers.
• RSTSR_DEV is set to 1. This environment variable is used to link the appropriate libraries in development mode (developers need to manually specify environment variables such as LD_LIBRARY_PATH to provide the locations of these libraries).
• We have added a large number of --exclude options to check.extraArgs. Most of the time, we only need to ensure the correctness of the OpenBLAS backend; the other BLAS backends only need to be adapted in the end. If these libraries are not excluded, rust-analyzer will spend a lot of time checking the code of these BLAS backends, making rust-analyzer slower to respond. We suggest running clippy checks on the code of these BLAS backends only when finally adapting them.
• The --no-deps option is passed to cargo metadata, so that rust-analyzer does not fetch the metadata of dependency packages. This can avoid errors in rust-analyzer caused by feature conflicts among dependency packages. For example, the Cargo.toml of rstsr-book does not declare the features mentioned in the configuration below (backtrace, openmp, faer); without this option, rust-analyzer would fail to work because it cannot resolve these features.
• This project requires code to be formatted with rustfmt.

{
  "folders": [
    {"path": "rstsr"},
    {"path": "rstsr-book"},
    {"path": "rstsr-ffi"},
    {"path": "rstsr-agents"}
  ],
  "settings": {
    "rust-analyzer.server.extraEnv": {
      "RAYON_NUM_THREADS": "16", // set to physical core count
      "CARGO_TARGET_DIR": "debug",
      "RSTSR_DEV": "1"
    },
    "rust-analyzer.cargo.extraEnv": {
      "RAYON_NUM_THREADS": "16", // set to physical core count
      "CARGO_TARGET_DIR": "debug",
      "RSTSR_DEV": "1"
    },
    "rust-analyzer.runnables.extraEnv": {
      "RAYON_NUM_THREADS": "16", // set to physical core count
      "CARGO_TARGET_DIR": "debug",
      "RSTSR_DEV": "1"
    },
    "rust-analyzer.cargo.targetDir": "debug",
    "rust-analyzer.check.command": "clippy",
    "rust-analyzer.check.overrideCommand": [
      "cargo",
      "clippy",
      "--workspace",
      "--message-format=json",
      "--all-targets",
    ],
    "rust-analyzer.check.extraArgs": [
      // leave openblas to still be clippy checked
      "--exclude", "rstsr-mkl",
      "--exclude", "rstsr-aocl",
      "--exclude", "rstsr-kml",
      "--exclude", "rstsr-blis",
      "--exclude", "rstsr-tblis",
    ],
    "rust-analyzer.cargo.features": [
      "backtrace", // better debugging in rstsr
      "openmp",    // enable OpenMP in rstsr-openblas
      "faer"       // enable faer for multi-threading device tests
    ],
    "rust-analyzer.cargo.metadataExtraArgs": [
      "--no-deps"
    ],
    "[rust]": {
      "editor.defaultFormatter": "rust-lang.rust-analyzer",
      "editor.formatOnSave": true
    },
  }
}