Skip to content

Latest commit

 

History

History
164 lines (123 loc) · 6.68 KB

README.md

File metadata and controls

164 lines (123 loc) · 6.68 KB
Raw

openblas-src Package Documentation Build

The package provides a source of BLAS and LAPACK via OpenBLAS.

Architecture

Configuration

The following Cargo features are supported:

  • cache to build in a shared directory instead of target (see below),
  • cblas to build CBLAS (enabled by default),
  • lapacke to build LAPACKE (enabled by default),
  • static to link to OpenBLAS statically,
  • system to skip building the bundled OpenBLAS.

Note: On Windows, OpenBLAS can not be built from source. The system feature is supposed to be used.

Dependencies

If you want to build OpenBLAS from source, you need to have the following dependencies installed:

  • HOSTCC compiler (e.g., gcc, clang, or icc),
  • make,
  • CC compiler of the target architecture (e.g., aarch64-linux-gnu-gcc for aarch64),
  • Fortran compiler of the target architecture(e.g., gfortran, flang, or ifort), if there is no Fortran compiler detected, the flag NOFORTRAN should be set to 1 and OpenBLAS will only compile BLAS and f2c-converted LAPACK. For more information, please refer to the Use f2c translations of LAPACK when no Fortran compiler is available.

Caching

The cache feature allows the OpenBLAS build products to be reused between crates that have different target directories. This avoids rebuilding OpenBLAS unnecessarily. However, this also prevents cargo clean from working properly, since the aforementioned build products will not be removed by the command.

The OpenBLAS binary will be placed at ${XDG_DATA_HOME}/openblas_build/[hash of build configure object]. For example, build with LAPACK and build without LAPACK will be placed on different directories. If you build OpenBLAS as a shared library, you need to add the above directory to LD_LIBRARY_PATH (for Linux) or DYLD_LIBRARY_PATH (for macOS). Since build from source is not supported on Windows (see next section), this feature is also not supported.

Windows and vcpkg

On Windows, openblas-src relies on vcpkg to find OpenBLAS. Before building, you must have the correct OpenBLAS installed for your target triplet and kind of linking. For instance, to link dynamically for the x86_64-pc-windows-msvc toolchain, install openblas for the x64-windows triplet:

vcpkg install openblas --triplet x64-windows

To link OpenBLAS statically, install openblas for the x64-windows-static-md triplet:

vcpkg install openblas --triplet x64-windows-static-md

To link OpenBLAS and C Runtime (CRT) statically, install openblas for the x64-windows-static triplet:

vcpkg install openblas --triplet x64-windows-static

and build with +crt-static option

RUSTFLAGS='-C target-feature=+crt-static' cargo build --target x86_64-pc-windows-msvc

Please see the "Static and dynamic C runtimes" in The Rust reference for detail.

ENV variables

Proxy

The openblas-src crate will detect and use proxy settings from your environment variables, such as http_proxy and https_proxy to download necessary dependencies.

Build System through OpenBLAS

According to the OpenbLAS build system, the variables used by OpenBLAS could be passed through environment, such as DYNAMIC_LIST, NUM_THREADS.

HOWEVER, for some of the variables, the openblas-src crate rename them to others to avoid conflicts with the existing envs. The following is the list of the variables that are renamed:

OpenBLAS variable openblas-src variable
TARGET OPENBLAS_TARGET
CC OPENBLAS_CC
FC OPENBLAS_FC
HOSTCC OPENBLAS_HOSTCC
RANLIB OPENBLAS_RANLIB

Cross-compile

Apart from providing the --target option to cargo build, one also has to specify the cross-compilation variables of OpenBLAS. They can be set as environment variables for cargo build using the OPENBLAS_ prefix as follows: OPENBLAS_CC, OPENBLAS_FC, OPENBLAS_HOSTCC, and OPENBLAS_TARGET.

If you do not set these variables, the openblas-build will try to detect them.

For OPENBLAS_TARGET, the basic target that corresponds to the arch of --target will be used.

Rust target OpenBLAS target
aarch64 ARMV8
arm ARMV6
armv5te ARMV5
armv6 ARMV6
armv7 ARMV7
loongarch64 LOONGSONGENERIC
mips64 MIPS64_GENERIC
mips64el MIPS64_GENERIC
riscv64 RISCV64_GENERIC
csky CK860FV
sparc SPARCV7

For OPENBLAS_CC and OPENBLAS_HOSTCC, the cc crate will be used to detect the compiler. Please refer to the cc documentation for more information.

For OPENBLAS_FC, openblas-build will try to detect the compiler through the OPENBLAS_CC set above. It will replace the gcc with gfortran, clang with flang, and icc with ifort and then test if the Fortran compiler exists.

Note: If there is no Fortran compiler detected, the build flag NOFORTRAN will be set to 1 and OpenBLAS will only compile BLAS and f2c-converted LAPACK. For more information, please refer to the Use f2c translations of LAPACK when no Fortran compiler is available.

Contribution

Your contribution is highly appreciated. Do not hesitate to open an issue or a pull request. Note that any contribution submitted for inclusion in the project will be licensed according to the terms given in LICENSE.md.