# How to Build Kanzi as a Shared Library (.so/.dll) for Dynamic Linking

> Build Kanzi as a shared library (.so/.dll) for dynamic linking. Learn how to create libkanzi_shared using CMake and link your application efficiently.

- Repository: [flanglet/kanzi-cpp](https://github.com/flanglet/kanzi-cpp)
- Tags: how-to-guide
- Published: 2026-03-02

---

**Build the `libkanzi_shared` target using CMake to generate `libkanzi.so` on Linux/macOS or `kanzi.dll` on Windows, then link your application against `-lkanzi` or `kanzi.lib` and include the public headers from `src/api/`.**

The [flanglet/kanzi-cpp](https://github.com/flanglet/kanzi-cpp) repository provides a high-performance lossless compression engine written in modern C++. To integrate Kanzi into existing projects without static linking, you can compile it as a shared library that exposes the `Compressor` and `Decompressor` classes for dynamic linking.

## Understanding the Library Structure

Kanzi’s source tree is organized into three logical compilation units defined in the top-level [`CMakeLists.txt`](https://github.com/flanglet/kanzi-cpp/blob/main/CMakeLists.txt):

- **Common core** – Utilities, timers, global state, and the BWT/transform framework.
- **Compression code** – The `Compressor` class, entropy encoders (ANS, Huffman, FPAQ), and bit-stream writers.
- **Decompression code** – The `Decompressor` class, matching entropy decoders, and bit-stream readers.

CMake aggregates these into a single target named **`libkanzi_shared`** (output filename **`kanzi`**) that combines `LIB_COMMON_SOURCES`, `LIB_COMP_SOURCES`, and `LIB_DECOMP_SOURCES`【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L1-L30】【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L100-L104】. This unified target ensures the resulting `.so` or `.dll` contains the complete compress-and-decompress stack, eliminating the need to manage multiple library files.

## CMake Build Steps for the Shared Library

To generate the shared library from the flanglet/kanzi-cpp source code:

```bash

# 1. Clone the repository

git clone https://github.com/flanglet/kanzi-cpp.git
cd kanzi-cpp

# 2. Create a separate build directory

mkdir build && cd build

# 3. Generate build files (detects compiler and enables threading support)

cmake ..

# 4. Compile the shared library target

make lib               # Alias for libkanzi_shared

# Alternatively: make shared_lib

```

After compilation:

- On **Linux/macOS**, find **`libkanzi.so`** inside `build/lib/`.
- On **Windows**, find **`kanzi.dll`** inside `build\bin\Release\` (or the appropriate configuration folder).

The build system automatically links against `Threads::Threads` for multi-threading support【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L15-L17】.

To install the library and headers system-wide, run:

```bash
make install

```

This copies the binary to `$(CMAKE_INSTALL_PREFIX)/lib` and public headers to `$(CMAKE_INSTALL_PREFIX)/include/kanzi` according to the `install(TARGETS …)` stanza【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L44-L50】.

## Linking Against Kanzi in Your Application

Once built, link your C++ application against the shared library and include the public API headers installed by CMake.

### C++ Usage Example

```cpp
#include <kanzi/Compressor.hpp>
#include <kanzi/Decompressor.hpp>
#include <kanzi/BitStreamException.hpp>
#include <fstream>

int main() {
    // Compression
    std::ifstream fin("input.txt", std::ios::binary);
    std::ofstream fout("output.kanzi", std::ios::binary);
    kanzi::Compressor compressor(fin, fout, nullptr); // nullptr = default options
    compressor.process();

    // Decompression
    std::ifstream cfin("output.kanzi", std::ios::binary);
    std::ofstream cout("recovered.txt", std::ios::binary);
    kanzi::Decompressor decompressor(cfin, cout, nullptr);
    decompressor.process();
}

```

### Linux and macOS Linking

Compile your program with:

```bash
g++ -std=c++17 my_program.cpp -L/path/to/kanzi/lib -lkanzi -pthread -o my_program

```

Ensure `libkanzi.so` is in your linker path or `LD_LIBRARY_PATH` at runtime.

### Windows Linking with MSVC

1. Add the directory containing **`kanzi.dll`** to **Additional Library Directories**.
2. Link against the import library **`kanzi.lib`** (generated alongside the DLL).
3. Ensure **`kanzi.dll`** is in your executable’s directory or system `PATH` at runtime.

## Key Source Files in the Shared Build

The following files constitute the complete shared-library implementation in flanglet/kanzi-cpp:

- **[`CMakeLists.txt`](https://github.com/flanglet/kanzi-cpp/blob/main/CMakeLists.txt)** – Declares `libkanzi_shared`, sets compiler flags (including `-fPIC`), and manages the install rules【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L1-L30】【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L44-L50】.
- **[`src/api/Compressor.hpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/api/Compressor.hpp)** and **[`src/api/Compressor.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/api/Compressor.cpp)** – Public class interface for stream compression【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L50-L53】.
- **[`src/api/Decompressor.hpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/api/Decompressor.hpp)** and **[`src/api/Decompressor.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/api/Decompressor.cpp)** – Public class interface for stream decompression.
- **[`src/entropy/ANSRangeEncoder.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/entropy/ANSRangeEncoder.cpp)** and **[`src/entropy/ANSRangeDecoder.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/entropy/ANSRangeDecoder.cpp)** – Entropy codec implementations compiled into the shared object.
- **[`src/transform/BWT.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/transform/BWT.cpp)** and **[`src/transform/LZCodec.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/transform/LZCodec.cpp)** – Data transformation stages (Burrows-Wheeler Transform, LZ77) that provide high compression ratios.
- **[`src/Global.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/Global.cpp)** – Central configuration and error handling utilities.
- **[`src/util/WallTimer.cpp`](https://github.com/flanglet/kanzi-cpp/blob/main/src/util/WallTimer.cpp)** – Timing utilities compiled with position-independent code for shared library safety.

## Summary

- **CMake target**: Build `libkanzi_shared` (output name `kanzi`) to obtain a single shared library containing compression, decompression, and utility code.
- **Output files**: `libkanzi.so` on Unix-like systems and `kanzi.dll` on Windows, located in `build/lib/` or `build\bin\Release\` respectively.
- **Installation**: `make install` places headers in `include/kanzi/` and the library in `lib/` under your `CMAKE_INSTALL_PREFIX`.
- **Headers**: Include [`kanzi/Compressor.hpp`](https://github.com/flanglet/kanzi-cpp/blob/main/kanzi/Compressor.hpp) and [`kanzi/Decompressor.hpp`](https://github.com/flanglet/kanzi-cpp/blob/main/kanzi/Decompressor.hpp) to use the API.
- **Link flags**: Use `-lkanzi -pthread` on Linux/macOS; link against `kanzi.lib` on Windows while ensuring the DLL is in the runtime path.

## Frequently Asked Questions

### What is the exact output filename of the Kanzi shared library?

On Linux and macOS, CMake produces **`libkanzi.so`**. On Windows, the build generates **`kanzi.dll`** with an accompanying **`kanzi.lib`** import library. These filenames are controlled by the `libkanzi_shared` target properties defined in the root [`CMakeLists.txt`](https://github.com/flanglet/kanzi-cpp/blob/main/CMakeLists.txt).

### Which headers must I include to use the Kanzi shared library?

You need the public API headers installed to `include/kanzi/`:

- **[`Compressor.hpp`](https://github.com/flanglet/kanzi-cpp/blob/main/Compressor.hpp)** for compression operations
- **[`Decompressor.hpp`](https://github.com/flanglet/kanzi-cpp/blob/main/Decompressor.hpp)** for decompression operations
- **[`BitStreamException.hpp`](https://github.com/flanglet/kanzi-cpp/blob/main/BitStreamException.hpp)** for error handling during I/O

These headers declare the `kanzi::Compressor` and `kanzi::Decompressor` classes that interface with the shared library code.

### How do I install Kanzi system-wide after building?

Run `make install` from your build directory. CMake copies the shared library to `$(CMAKE_INSTALL_PREFIX)/lib` and headers to `$(CMAKE_INSTALL_PREFIX)/include/kanzi`【/cache/repos/github.com/flanglet/kanzi-cpp/master/CMakeLists.txt†L44-L50】. You can customize the prefix by running `cmake -DCMAKE_INSTALL_PREFIX=/your/path ..` before building.

### Can I use the shared library from C code instead of C++?

Yes. The repository provides a thin C wrapper that exposes the compression and decompression functionality through C-compatible functions. Link against `libkanzi` (or `kanzi.dll`) and include the appropriate C headers to call the library from non-C++ projects.