kaduceus: High-performance Rust bindings to Kakadu

kaduceus is a Rust binding for the Kakadu library, a powerful and widely-used JPEG 2000 codec. kaduceus is specifically designed for high-performance and low overhead via a carefully crafted set of optimization tricks.

System requirements

• x64 or ARMv8 processor
• Linux kernel 5.1 or later

Key Features

• Asynchronous IO: All IO work submitted during decompression is scheduled to run asynchronously, allowing decoding to overlap with readers/writers and maximize use of system resources.

• Build-time optimization: kaduceus opts into all available build-time optimizations where appropriate. This results in significantly improved performance at the cost of a wide range of platform-specific build targets.

  • LTO (Link-time optimization): Enables whole-program optimization, spanning both Rust and C++ code, resulting in smaller executable sizes and improved runtime efficiency.

  • PGO (Profile-guided optimization): Analyzes code execution patterns from runtime profiling data to identify hot spots and optimize for faster execution.

  • Target-specific features: Automatically selects optimizations based on the target platform's architecture and instruction set (e.g., AVX2, NEON), achieving optimal efficiency for various hardware configurations.

  • Tracing support: kaduceus utilizes the tracing library for structured logging, enabling performance profiling and analysis of interactions between Rust, Kakadu, and other upstream components.

• Minimal footprint: Whole-program LTO and static linkage produces exceptionally compact binaries, making it suitable for resource-constrained environments such as AWS Lambda and packaging in minimal container base images.

Getting Started

1. Install Rust and Cargo: Ensure that you have the Rust toolchain installed, which includes the package manager Cargo. You can download it from https://www.rust-lang.org/tools/install.

2. Install Clang: Ensure you have a working Clang compiler installation. You can find instructions for your platform on the Clang website:

   • Linux/macOS:

     sudo apt-get install clang  # Debian/Ubuntu
     sudo yum install clang     # Fedora/CentOS

3. Install Kakadu: Obtain and install the proprietary Kakadu library from https://www.kakadusoftware.com/. Ensure that the Kakadu library is properly configured and accessible during the build process.

   • Note for Digirati employees: The latest version of Kakadu is included as a submodule within this repository. To access the Kakadu source code, initialize the submodules using the following command:

     git submodule update --init --recursive

4. (Optional) Generate a Clang compile_commands.json file using Bear (Build EAR):

   bear -- cargo build

   This step is optional but recommended for developers working on kaduceus. A compile_commands.json file is required for IDE integration and static analysis. It is generated by the build system, but only if the build.rs script is executed.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.