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

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 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:

• 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:

# 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:

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

#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:

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 – 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 and 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 and src/api/Decompressor.cpp – Public class interface for stream decompression.
• src/entropy/ANSRangeEncoder.cpp and src/entropy/ANSRangeDecoder.cpp – Entropy codec implementations compiled into the shared object.
• src/transform/BWT.cpp and src/transform/LZCodec.cpp – Data transformation stages (Burrows-Wheeler Transform, LZ77) that provide high compression ratios.
• src/Global.cpp – Central configuration and error handling utilities.
• 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 and 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.

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

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

• Compressor.hpp for compression operations
• Decompressor.hpp for decompression operations
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}