diff --git a/README.md b/README.md index 03000c37..68fe25b0 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,40 @@ # intel-mkl-src -|crate | crate.io | description | -|:-------------|:---------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------| -|intel-mkl-src | [![Crate](http://meritbadge.herokuapp.com/intel-mkl-src)](https://crates.io/crates/intel-mkl-src) | Source crate for Intel-MKL | -|intel-mkl-sys | [![Crate](http://meritbadge.herokuapp.com/intel-mkl-sys)](https://crates.io/crates/intel-mkl-sys) | FFI for Intel-MKL [vector math][VM], and [statistical functions][VSL] | -|intel-mkl-tool| [![Crate](http://meritbadge.herokuapp.com/intel-mkl-tool)](https://crates.io/crates/intel-mkl-tool)| CLI utility for redistributing Intel-MKL | - -Redistribution of Intel MKL as a crate. Tested on Linux, macOS, and Windows (since 0.4.0) +|crate | crate.io | docs.rs | description | +|:-------------|:-------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------|:---------------------------------------------------------------| +|intel-mkl-src | [![crate](https://img.shields.io/crates/v/intel-mkl-src.svg)](https://crates.io/crates/intel-mkl-src) | [![docs.rs](https://docs.rs/intel-mkl-src/badge.svg)](https://docs.rs/intel-mkl-src) | Source crate for Intel-MKL | +|intel-mkl-sys | [![Crate](https://img.shields.io/crates/v/intel-mkl-sys.svg)](https://crates.io/crates/intel-mkl-sys) | [![docs.rs](https://docs.rs/intel-mkl-sys/badge.svg)](https://docs.rs/intel-mkl-sys) |FFI for Intel-MKL [vector math][VM], and [statistical functions][VSL] | +|intel-mkl-tool| [![Crate](https://img.shields.io/crates/v/intel-mkl-tool.svg)](https://crates.io/crates/intel-mkl-tool)| [![docs.rs](https://docs.rs/intel-mkl-tool/badge.svg)](https://docs.rs/intel-mkl-tool)|Seek Intel-MKL libraries from filesystem | [VM]: https://software.intel.com/en-us/mkl-developer-reference-c-vector-mathematical-functions [VSL]: https://software.intel.com/en-us/mkl-developer-reference-c-statistical-functions ## Supported features -- `mkl-*-*-*` features specify which MKL to be linked - - `static` means MKL will be linked statically, and `dynamic` means MKL will be linked dynamically - - `lp64` means 32-bit integer interface, `ilp64` means 64-bit integer interface - - `iomp` means MKL uses Intel OpenMP, `seq` means sequential execution, e.g. no parallelization - - OpenMP is not supported for Windows currently [#46](https://github.com/rust-math/intel-mkl-src/issues/46) - - default is `mkl-static-ilp64-seq`, and you must choose one of them. - - macOS is not supported [#42](https://github.com/rust-math/intel-mkl-src/issues/42) - - | feature name | Linux | macOS | Windows | - |:-----------------------|:------------------:|:------------------:|:------------------:| - | mkl-static-lp64-iomp | :heavy_check_mark: | - | - | - | mkl-static-lp64-seq | :heavy_check_mark: | - | :heavy_check_mark: | - | mkl-static-ilp64-iomp | :heavy_check_mark: | - | - | - | mkl-static-ilp64-seq | :heavy_check_mark: | - | :heavy_check_mark: | - | mkl-dynamic-lp64-iomp | :heavy_check_mark: | :heavy_check_mark: | - | - | mkl-dynamic-lp64-seq | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | mkl-dynamic-ilp64-iomp | :heavy_check_mark: | :heavy_check_mark: | - | - | mkl-dynamic-ilp64-seq | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - -- `download` feature enables downloading MKL archive managed by this project from AWS S3 (default ON) +`mkl-*-*-*` features specify which MKL to be linked as following. +If any feature is set, default to `mkl-static-ilp64-iomp`. + +### Link type (`static` or `dynamic`) +`dynamic` means MKL is linked dynamically, i.e. the executable does not contains MKL libraries +and will seek them from filesystem while execution. +This is better choice when the MKL libraries are managed by the system package manager e.g. `apt`. + +`static` means MKL is linked statically, i.e. the MKL binaries are embedded in the executable file. +This is better choice when creating portable executable, or system-managed MKL library does not exist. + +### Data model (`lp64` or `ilp64`) + +This specify the data model: + +- `ilp64` means `int` (i), `long` (l), and pointers (p) are 64-bit. +- `lp64` means `long` (l) and pointers (p) are 64-bit, `int` is 32-bit. + +### Thread management (`iomp` or `seq`) + +- `iomp` means MKL uses Intel OpenMP runtime +- `seq` means sequential (single thread) execution + +Using GNU OpenMP runtime (`libgomp`) is not supported in this project. ## Usage @@ -46,25 +48,15 @@ fftw-sys = { version = "0.4", features = ["intel-mkl"] } ## How to find system MKL libraries -This crate seeks system MKL libraries, e.g. installed by [apt], [yum], or official manual installer, as following manner: +`intel-mkl-tool` crate seeks system MKL libraries, e.g. installed by various installer as following manner: -- Check `${OUT_DIR}` where previous build has downloaded -- Seek using [pkg-config] crate - - `${PKG_CONFIG_PATH}` has to be set correctly. It may not be set by default in usual install. - - You can confirm it by checking the following command returns error. - ``` - pkg-config --libs mkl-dynamic-lp64-iomp - ``` -- Seek a directory set by `${MKLROOT}` environment variable +- Seek using `pkg-config` command +- Seek `${MKLROOT}` directory - Seek default installation path - `/opt/intel/mkl` for Linux - - `C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows` for Windows - -If not found any MKL library and `download` feature is ON, this crate will download archive from AWS S3 `rust-intel-mkl` bucket. + - `C:/Program Files (x86)/IntelSWTools/` and `C:/Program Files (x86)/Intel/oneAPI` for Windows -[apt]: https://software.intel.com/content/www/us/en/develop/articles/installing-intel-free-libs-and-python-apt-repo.html -[yum]: https://software.intel.com/content/www/us/en/develop/articles/installing-intel-free-libs-and-python-yum-repo.html -[pkg-config]: https://github.com/rust-lang/pkg-config-rs +If `intel-mkl-tool` cannot find system MKL, `intel-mkl-src` try to download MKL binaries from OCI Registry. ## License MKL is distributed under the Intel Simplified Software License for Intel(R) Math Kernel Library, See [License.txt](License.txt).