nvblas_sys/lib.rs
1//! # nvblas-sys
2//!
3//! This package provides linkage to and configuration for [NVBLAS][nvblas].
4//!
5//! ## Why should you use nvblas-sys
6//! It's easy to link to a system library, especially when another package provides
7//! bindings. However, anyone who includes your package down the line will be unable
8//! to override it. Using nvblas-sys means exactly one package will link to
9//! `libnvblas` and those who wish to override it can do so without causing problems
10//! for dependents thanks to the use of the `links` manifest tag.
11//!
12//! ## Setup
13//! Before anything else, [NVBLAS][nvblas] must be installed and exist in cargo
14//! search path. On Linux machines, it should be named `libnvblas.so`. If it is
15//! necessary to override the linkage, it can be [overridden][override] on a per-machine or
16//! per-crate basis by using a [`config.toml` file][configtoml].
17//!
18//! Make sure to invoke the crate to make sure it runs:
19//! ```rust
20//! extern crate nvblas-sys;
21//! ```
22//!
23//! nvblas-sys comes with a default configuration file, but it may not be may not be
24//! acceptable for your usage. To use your own configuration file, include the
25//! following line in your `build.rs` file:
26//! ```rust
27//! println!("cargo:rustc-env=NVBLAS_CONFIG_FILE={}/nvblas.conf",
28//! env::var("CARGO_MANIFEST_DIR").unwrap());
29//! ```
30//! Alternatively, you can set the environment variable `NVBLAS_CONFIG_FILE`
31//! manually.
32//!
33//! Since [NVBLAS][nvblas] is a limited drop-in replacement to traditional CPU BLAS
34//! implementations, nvblas-sys does not provide any declarations; you will also
35//! need to include `blas-sys` as a dependency.
36//!
37//! [configtoml]: https://doc.rust-lang.org/cargo/reference/config.html
38//! [override]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#overriding-build-scripts
39//! [nvblas]: https://docs.nvidia.com/cuda/nvblas/
40
41#![no_std]