# Installation

> NumKong for Rust

Minimal:

```toml
[dependencies]
numkong = "8"
```

With host-side parallel helpers:

```toml
[dependencies]
numkong = { version = "8", features = ["parallel", "std"] }
```

### Compilation and Backend Selection

The crate builds the C library through CMake, which probes the compiler for every backend of the target architecture, so the build machine needs CMake 3.28 or newer.
All supported backends are compiled into a single binary and selected at runtime.
Setting `NUMKONG_LIBRARY_DIR` to the exact directory holding a `numkong_static` archive CMake already built skips the build and links that archive. For Visual Studio build trees, include the configuration directory, such as `build_msvc2022_x64/Release`. Cargo-managed builds use CMake's install target and link from its installed `lib` directory.

The two CPU features are `std`, which enables standard library support, and `parallel`, which adds host-side orchestration via ForkUnion and implies `std`.

The `cuda` and `rocm` features add the NVIDIA and AMD GPU kernels, and may be combined.
They need `nvcc` or `hipcc` on the build machine, and the binary then links `libcudart` or `libamdhip64` from the toolkit CMake found.

```toml
[dependencies]
numkong = { version = "8", features = ["cuda"] }
```

Backend selection follows the target architecture.
ARM gets NEON, SVE, and SME, with SME available on Linux, FreeBSD, and macOS.
x86-64 gets Haswell (AVX2), Skylake/Ice Lake/Sapphire Rapids AVX-512 variants, and AMX on Linux and Windows only.
RISC-V gets RVV backends on Linux and FreeBSD.
WebAssembly gets the one SIMD capability the Rust target declares, as the next section shows.
A backend the compiler cannot build is left out, and `NUMKONG_MARCH=native` tunes the scaffolding for the build host, as described in [CONTRIBUTING.md](https://github.com/ashvardanian/NumKong/blob/main/CONTRIBUTING.md#target-baseline-policy).

#### WebAssembly

An engine validates a WebAssembly module whole, so the crate compiles one SIMD capability, the one the Rust target declares: `v128relaxed` under `-C target-feature=+relaxed-simd`, `v128` under `+simd128`, and the serial kernels alone without either, for engines that lack SIMD.
A target declaring neither fails the build, rather than quietly falling back to the serial kernels.
`build.rs` passes that capability to CMake as `NUMKONG_MARCH`, beside the toolchain the target needs:

| Rust target                                        | CMake toolchain                             | Needs                            |
| :------------------------------------------------- | :------------------------------------------ | :------------------------------- |
| `wasm32-wasip1`, `wasm32-wasip2`                   | `cmake/toolchain-wasm32-wasi.cmake`         | `WASI_SDK_PATH`, or `~/wasi-sdk` |
| `wasm32-wasip1-threads`                            | `cmake/toolchain-wasm32-wasi-threads.cmake` | `WASI_SDK_PATH`, or `~/wasi-sdk` |
| `wasm32-unknown-emscripten`                        | `cmake/toolchain-wasm32-emscripten.cmake`   | `EMSDK`                          |
| `wasm32-unknown-unknown`, `wasm64-unknown-unknown` | none, as the library needs no libc          | a Clang with WebAssembly         |

```sh
RUSTFLAGS="-C target-feature=+relaxed-simd" cargo build --target wasm32-wasip1
```