### Customizing ZXC Build with CMake Options

Source: https://context7.com/hellobertrand/zxc/llms.txt

Provides examples of CMake commands to configure the ZXC build process. Options include build type, shared/static libraries, native architecture, disabling components, code coverage, PGO, and installation.

```bash
# Standard release build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# Build shared library instead of static
cmake -B build -DBUILD_SHARED_LIBS=ON

# Portable build (without -march=native)
cmake -B build -DZXC_NATIVE_ARCH=OFF

# Library only (no CLI, no tests)
cmake -B build -DZXC_BUILD_CLI=OFF -DZXC_BUILD_TESTS=OFF

# Enable code coverage
cmake -B build -DZXC_ENABLE_COVERAGE=ON

# Profile-guided optimization (two-pass build)
cmake -B build -DZXC_PGO_MODE=GENERATE
cmake --build build
./build/zxc -b testdata/*  # Generate profile
cmake -B build -DZXC_PGO_MODE=USE
cmake --build build

# Install system-wide
sudo cmake --install build
```

--------------------------------

### Compile ZXC C Example

Source: https://github.com/hellobertrand/zxc/blob/main/docs/EXAMPLES.md

Command-line instruction to compile the ZXC example program linking against the zxc_lib library.

```bash
gcc -o ctx_example ctx_example.c -I include -L build -lzxc_lib
```

--------------------------------

### Install ZXC Node.js bindings from source

Source: https://github.com/hellobertrand/zxc/blob/main/wrappers/nodejs/README.md

Commands to clone the repository and install the native Node.js addon using npm.

```bash
git clone https://github.com/hellobertrand/zxc.git
cd zxc/wrappers/nodejs
npm install
```

--------------------------------

### Install zxc via vcpkg

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Methods for installing the zxc library using the vcpkg package manager in both classic and manifest modes.

```bash
vcpkg install zxc
```

```json
{
  "dependencies": ["zxc"]
}
```

--------------------------------

### Install zxc with Homebrew

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Installs the zxc library using the Homebrew package manager on macOS or Linux.

```bash
brew install zxc
```

--------------------------------

### Install and Integrate zxc Library

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Instructions for installing the zxc binary and integrating the library into projects using CMake or pkg-config. These snippets demonstrate how to link the static library and configure build environments.

```bash
tar -xzf zxc-linux-x86_64.tar.gz -C /usr/local
```

```cmake
find_package(zxc REQUIRED)
target_link_libraries(myapp PRIVATE zxc::zxc_lib)
```

```bash
cc myapp.c $(pkg-config --cflags --libs zxc) -o myapp
```

--------------------------------

### Install zxc with Conan

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Installs the zxc library using the Conan package manager. It can be installed directly via the command line or added to a conanfile.txt.

```bash
conan install -r conancenter --requires="zxc/[*]" --build=missing
```

```ini
[requires]
zxc/[*]
```

--------------------------------

### Compile ZXC Buffer Example

Source: https://github.com/hellobertrand/zxc/blob/main/docs/EXAMPLES.md

Command-line instructions to compile the C source code using GCC, linking against the ZXC library.

```bash
gcc -o buffer_example buffer_example.c -I include -L build -lzxc_lib
```

--------------------------------

### Compile and Execute ZXC Stream Example

Source: https://github.com/hellobertrand/zxc/blob/main/docs/EXAMPLES.md

Commands to compile the C source code using GCC and execute the resulting binary to process files.

```bash
gcc -o stream_example stream_example.c -I include -L build -lzxc_lib -lpthread -lm
./stream_example large_file.bin compressed.xc decompressed.bin
```

--------------------------------

### Manage Reusable Compression Contexts in C

Source: https://github.com/hellobertrand/zxc/blob/main/docs/EXAMPLES.md

Demonstrates the use of zxc_cctx and zxc_dctx to perform allocation-free compression and decompression. It highlights the use of sticky options to maintain configuration across multiple calls.

```c
#include "zxc.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define BLOCK_SIZE   (64 * 1024)
#define NUM_BLOCKS   32

int main(void) {
    zxc_compress_opts_t create_opts = {
        .level            = 3,
        .checksum_enabled = 0,
        .block_size       = BLOCK_SIZE,
    };
    zxc_cctx* cctx = zxc_create_cctx(&create_opts);
    zxc_dctx* dctx = zxc_create_dctx();

    if (!cctx || !dctx) {
        fprintf(stderr, "Context creation failed\n");
        zxc_free_cctx(cctx);
        zxc_free_dctx(dctx);
        return 1;
    }

    const size_t comp_cap = (size_t)zxc_compress_bound(BLOCK_SIZE);
    uint8_t* comp = malloc(comp_cap);
    uint8_t* src  = malloc(BLOCK_SIZE);
    uint8_t* dec  = malloc(BLOCK_SIZE);

    for (int i = 0; i < NUM_BLOCKS; i++) {
        for (size_t j = 0; j < BLOCK_SIZE; j++) src[j] = (uint8_t)(i ^ j);

        int64_t csz = zxc_compress_cctx(cctx, src, BLOCK_SIZE, comp, comp_cap, NULL);
        if (csz <= 0) { fprintf(stderr, "Block %d: compress error %lld\n", i, (long long)csz); break; }

        int64_t dsz = zxc_decompress_dctx(dctx, comp, (size_t)csz, dec, BLOCK_SIZE, NULL);
        if (dsz != BLOCK_SIZE || memcmp(src, dec, BLOCK_SIZE) != 0) {
            fprintf(stderr, "Block %d: roundtrip mismatch\n", i);
            break;
        }
    }

    zxc_compress_opts_t high_opts = { .level = 5 };
    int64_t csz = zxc_compress_cctx(cctx, src, BLOCK_SIZE, comp, comp_cap, &high_opts);
    printf("Level-5 compressed: %lld bytes\n", (long long)csz);

    zxc_free_cctx(cctx);
    zxc_free_dctx(dctx);
    free(src); free(comp); free(dec);
    return 0;
}
```

--------------------------------

### Build zxc from Source

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Builds the zxc library from its source code using CMake. This process involves cloning the repository, configuring with CMake, building, testing, and optionally installing.

```bash
git clone https://github.com/hellobertrand/zxc.git
cd zxc
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# Run tests
ctest --test-dir build -C Release --output-on-failure

# CLI usage
./build/zxc --help

# Install library, headers, and CMake/pkg-config files
sudo cmake --install build
```

--------------------------------

### zxc Buffer API for In-Memory Compression/Decompression

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Provides C code examples for using the zxc library's buffer API for in-memory compression and decompression. It shows how to set compression options and handle the compressed and decompressed data.

```c
#include "zxc.h"

// Compression
uint64_t bound = zxc_compress_bound(src_size);
zxc_compress_opts_t c_opts = {
    .level            = ZXC_LEVEL_DEFAULT,
    .checksum_enabled = 1,
    /* .block_size = 0 → 256 KB default */
};
int64_t compressed_size = zxc_compress(src, src_size, dst, bound, &c_opts);

// Decompression
zxc_decompress_opts_t d_opts = { .checksum_enabled = 1 };
int64_t decompressed_size = zxc_decompress(src, src_size, dst, dst_capacity, &d_opts);
```

--------------------------------

### Prefix Varint Encoding Example (Text)

Source: https://github.com/hellobertrand/zxc/blob/main/docs/WHITEPAPER.md

Demonstrates the encoding and decoding process for a value using the Prefix Varint format. This format uses the unary prefix of the first byte to indicate the total length of the encoded integer, allowing for efficient decoding.

```text
Value 300 > 127 and < 16383 -> Uses 2-byte format (Prefix '10').

Step 1: Low 6 bits
300 & 0x3F = 44 (0x2C, binary 101100)
Byte 1 = Prefix '10' | 101100 = 10101100 (0xAC)

Step 2: Remaining high bits
300 >> 6 = 4 (0x04, binary 00000100)
Byte 2 = 0x04

Result: 0xAC 0x04

Decoding Verification:
Byte 1 (0xAC) & 0x3F = 44
Byte 2 (0x04) << 6   = 256
Total = 256 + 44 = 300
```

--------------------------------

### Perform In-Memory Compression and Decompression with ZXC

Source: https://github.com/hellobertrand/zxc/blob/main/docs/EXAMPLES.md

Demonstrates the complete lifecycle of compressing and decompressing data using the ZXC Buffer API. It covers memory allocation, setting compression options, performing the operations, and verifying data integrity.

```c
#include "zxc.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(void) {
    const char* original = "Hello, ZXC! This is a sample text for compression.";
    size_t original_size = strlen(original) + 1;

    uint64_t max_compressed_size = zxc_compress_bound(original_size);

    void* compressed   = malloc(max_compressed_size);
    void* decompressed = malloc(original_size);

    if (!compressed || !decompressed) {
        fprintf(stderr, "Memory allocation failed\n");
        free(compressed);
        free(decompressed);
        return 1;
    }

    zxc_compress_opts_t c_opts = {
        .level            = ZXC_LEVEL_DEFAULT,
        .checksum_enabled = 1
    };
    int64_t compressed_size = zxc_compress(
        original,
        original_size,
        compressed,
        max_compressed_size,
        &c_opts
    );

    if (compressed_size <= 0) {
        fprintf(stderr, "Compression failed (error %lld)\n", (long long)compressed_size);
        free(compressed);
        free(decompressed);
        return 1;
    }

    zxc_decompress_opts_t d_opts = { .checksum_enabled = 1 };
    int64_t decompressed_size = zxc_decompress(
        compressed,
        (size_t)compressed_size,
        decompressed,
        original_size,
        &d_opts
    );

    if (decompressed_size <= 0) {
        fprintf(stderr, "Decompression failed (error %lld)\n", (long long)decompressed_size);
        free(compressed);
        free(decompressed);
        return 1;
    }

    if ((size_t)decompressed_size == original_size &&
        memcmp(original, decompressed, original_size) == 0) {
        printf("Success! Data integrity verified.\n");
    }

    free(compressed);
    free(decompressed);
    return 0;
}
```

--------------------------------

### Perform Multi-threaded Compression and Decompression in C

Source: https://github.com/hellobertrand/zxc/blob/main/docs/EXAMPLES.md

This snippet demonstrates the use of the ZXC stream API to compress and decompress files using multiple threads. It configures the library to auto-detect CPU cores and enables checksum validation to ensure data integrity.

```c
#include "zxc.h"
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char* argv[]) {
    if (argc != 4) {
        fprintf(stderr, "Usage: %s <input_file> <compressed_file> <output_file>\n", argv[0]);
        return 1;
    }

    const char* input_path      = argv[1];
    const char* compressed_path = argv[2];
    const char* output_path     = argv[3];

    FILE* f_in = fopen(input_path, "rb");
    FILE* f_out = fopen(compressed_path, "wb");

    zxc_compress_opts_t c_opts = {
        .n_threads        = 0,
        .level            = ZXC_LEVEL_DEFAULT,
        .checksum_enabled = 1
    };
    int64_t compressed_bytes = zxc_stream_compress(f_in, f_out, &c_opts);

    fclose(f_in);
    fclose(f_out);

    FILE* f_compressed = fopen(compressed_path, "rb");
    FILE* f_decompressed = fopen(output_path, "wb");

    zxc_decompress_opts_t d_opts = { .n_threads = 0, .checksum_enabled = 1 };
    int64_t decompressed_bytes = zxc_stream_decompress(f_compressed, f_decompressed, &d_opts);

    fclose(f_compressed);
    fclose(f_decompressed);

    return 0;
}
```

--------------------------------

### Implement Reusable Compression Contexts in C

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Demonstrates how to initialize and reuse compression and decompression contexts to avoid repeated memory allocation in tight loops. By passing NULL as the options parameter, the library reuses the sticky settings established during context creation.

```c
#include "zxc.h"

zxc_compress_opts_t opts = { .level = 3, .checksum_enabled = 0 };
zxc_cctx* cctx = zxc_create_cctx(&opts);   // allocate once, settings remembered
zxc_dctx* dctx = zxc_create_dctx();        // allocate once

// reuse across many blocks — NULL reuses sticky settings:
int64_t csz = zxc_compress_cctx(cctx, src, src_sz, dst, dst_cap, NULL);
int64_t dsz = zxc_decompress_dctx(dctx, dst, csz, out, src_sz, NULL);

zxc_free_cctx(cctx);
zxc_free_dctx(dctx);
```

--------------------------------

### zxc with tar Command

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Illustrates how to use zxc as an external compressor with the `tar` utility on both GNU/Linux and macOS systems, as well as through pipes.

```bash
# GNU tar (Linux)
tar -I 'zxc -5' -cf archive.tar.zxc data/
tar -I 'zxc -d' -xf archive.tar.zxc

# bsdtar (macOS)
tar --use-compress-program='zxc -5' -cf archive.tar.zxc data/
tar --use-compress-program='zxc -d' -xf archive.tar.zxc

# Pipes (universal)
tar cf - data/ | zxc > archive.tar.zxc
zxc -d < archive.tar.zxc | tar xf -
```

--------------------------------

### CMake Options for zxc Build

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Demonstrates various CMake command-line options to customize the zxc build process, such as building shared libraries, enabling/disabling features like LTO, PGO, CLI, and tests, or enabling code coverage.

```bash
# Build shared library
cmake -B build -DBUILD_SHARED_LIBS=ON

# Portable build (without -march=native)
cmake -B build -DZXC_NATIVE_ARCH=OFF

# Library only (no CLI, no tests)
cmake -B build -DZXC_BUILD_CLI=OFF -DZXC_BUILD_TESTS=OFF

# Code coverage build
cmake -B build -DZXC_ENABLE_COVERAGE=ON
```

--------------------------------

### Basic Compression and Decompression in Rust

Source: https://github.com/hellobertrand/zxc/blob/main/wrappers/rust/zxc/README.md

Demonstrates the fundamental usage of the zxc library for compressing and decompressing data. It shows how to use the `compress` and `decompress` functions and verifies the integrity of the decompressed data. No external dependencies are required beyond the 'zxc' crate.

```rust
use zxc::{compress, decompress, Level};

fn main() -> Result<(), zxc::Error> {
    let data = b"Hello, ZXC! This is some data to compress.";
    
    // Compress (no checksum for max speed)
    let compressed = compress(data, Level::Default, None)?;
    println!("Compressed {} -> {} bytes", data.len(), compressed.len());
    
    // Decompress
    let decompressed = decompress(&compressed)?;
    assert_eq!(&decompressed[..], &data[..]);
    
    Ok(())
}
```

--------------------------------

### Get Decompressed Size - zxc_get_decompressed_size (C)

Source: https://context7.com/hellobertrand/zxc/llms.txt

Reads the original uncompressed size from a compressed buffer's footer without decompressing the data. Returns 0 if the buffer is invalid or corrupted. This is useful for pre-allocating the exact buffer size needed for decompression.

```c
#include "zxc.h"

// Read original size before allocating decompression buffer
uint64_t original_size = zxc_get_decompressed_size(compressed_data, compressed_size);

if (original_size == 0) {
    fprintf(stderr, "Invalid or corrupted compressed data\n");
    return 1;
}

// Now allocate exact buffer size needed
void* output = malloc(original_size);
int64_t result = zxc_decompress(compressed_data, compressed_size, output, original_size, NULL);

```

--------------------------------

### zxc CLI Compression and Decompression

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Shows basic command-line usage for zxc, including compressing files with different levels, decompressing files, and benchmarking.

```bash
# Basic Compression (Level 3 is default)
zxc -z input_file output_file

# High Compression (Level 5)
zxc -z -5 input_file output_file

# -z for compression can be omitted
zxc input_file output_file

# as well as output file; it will be automatically assigned to input_file.xc
zxc input_file

# Decompression
zxc -d compressed_file output_file

# Benchmark Mode (Testing speed on your machine)
zxc -b input_file
```

--------------------------------

### Configure Python Extension Module with CMake

Source: https://github.com/hellobertrand/zxc/blob/main/wrappers/python/CMakeLists.txt

This CMake script sets up a Python module build by locating the Python development environment, adding the core project subdirectory, and defining the target library properties. It ensures the module is linked correctly to the zxc_lib and configured for installation.

```cmake
cmake_minimum_required(VERSION 3.20)
project(zxc_python C)

find_package(Python COMPONENTS Development.Module REQUIRED)

# ---- Core ----
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../../
                 ${CMAKE_CURRENT_BINARY_DIR}/zxc_core_build)

# ---- Python extension ----
Python_add_library(_zxc MODULE src/zxc/_zxc.c)

# Without "lib" prefix
set_target_properties(_zxc PROPERTIES PREFIX "")

target_include_directories(_zxc PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/../../include
)

target_link_libraries(_zxc PRIVATE zxc_lib)

install(TARGETS _zxc DESTINATION zxc)
```

--------------------------------

### Manage zero-allocation buffers in Rust

Source: https://context7.com/hellobertrand/zxc/llms.txt

Demonstrates high-performance compression and decompression using pre-allocated buffers. This approach avoids frequent allocations, making it suitable for performance-critical applications.

```rust
use zxc::{compress_to, decompress_to, compress_bound, CompressOptions, DecompressOptions, Level};

fn main() -> Result<(), zxc::Error> {
    let data = b"Hello, ZXC! Reusing buffers for better performance.";
    let mut compressed = vec![0u8; compress_bound(data.len())];
    let mut decompressed = vec![0u8; data.len()];

    let opts = CompressOptions::with_level(Level::Compact).with_checksum();
    let size = compress_to(data, &mut compressed, &opts)?;
    compressed.truncate(size);

    let d_opts = DecompressOptions::verify_checksum();
    decompress_to(&compressed, &mut decompressed, &d_opts)?;
    Ok(())
}
```

--------------------------------

### CLI Usage

Source: https://context7.com/hellobertrand/zxc/llms.txt

The command-line interface provides quick access to compression and decompression operations, supporting file operations, benchmark mode, and integration with tar archives.

```APIDOC
## CLI Usage

The command-line interface provides quick access to compression and decompression operations, supporting file operations, benchmark mode, and integration with tar archives.

### Basic Usage

```bash
# Basic compression (level 3 default)
zxc input_file output_file.xc

# High compression (level 5)
zxc -5 input_file output_file.xc

# Compress with auto-generated output name (input_file.xc)
zxc input_file

# Decompress
zxc -d compressed_file.xc output_file
```

### Benchmark Mode

```bash
# Benchmark mode (test speed on your machine)
zxc -b input_file
```

### Integration with tar

```bash
# Integration with GNU tar
tar -I 'zxc -5' -cf archive.tar.zxc data/
tar -I 'zxc -d' -xf archive.tar.zxc

# Integration with bsdtar (macOS)
tar --use-compress-program='zxc -5' -cf archive.tar.zxc data/
tar --use-compress-program='zxc -d' -xf archive.tar.zxc

# Pipe-based compression
tar cf - data/ | zxc > archive.tar.zxc
zxc -d < archive.tar.zxc | tar xf -
```
```

--------------------------------

### Run ZXC test suite

Source: https://github.com/hellobertrand/zxc/blob/main/wrappers/nodejs/README.md

Executes the defined test scripts for the ZXC Node.js package.

```bash
npm test
```

--------------------------------

### zxc Stream API for File Compression/Decompression

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Demonstrates the C code for using zxc's stream API for compressing and decompressing data from files, potentially in a multi-threaded manner. It covers setting stream options like thread count and checksums.

```c
#include "zxc.h"

// Compression (auto-detect threads, level 3, checksum on)
zxc_compress_opts_t c_opts = {
    .n_threads        = 0,               // 0 = auto
    .level            = ZXC_LEVEL_DEFAULT,
    .checksum_enabled = 1,
    /* .block_size = 0 → 256 KB default */
};
int64_t bytes_written = zxc_stream_compress(f_in, f_out, &c_opts);

// Decompression
zxc_decompress_opts_t d_opts = { .n_threads = 0, .checksum_enabled = 1 };
int64_t bytes_out = zxc_stream_decompress(f_in, f_out, &d_opts);
```

--------------------------------

### C API: Reusable Contexts

Source: https://github.com/hellobertrand/zxc/blob/main/README.md

Endpoints for managing compression and decompression contexts to avoid per-call memory allocation overhead.

```APIDOC
## C API: Reusable Context Management

### Description
Provides functions to create and manage persistent compression (cctx) and decompression (dctx) contexts. Reusing contexts allows for significant performance gains in tight loops by avoiding repeated heap allocations.

### Methods
- `zxc_create_cctx(zxc_compress_opts_t* opts)`: Initializes a compression context.
- `zxc_create_dctx()`: Initializes a decompression context.
- `zxc_compress_cctx(...)`: Performs compression using a reusable context.
- `zxc_decompress_dctx(...)`: Performs decompression using a reusable context.

### Parameters
#### Request Body (zxc_compress_opts_t)
- **level** (int) - Required - Compression level.
- **checksum_enabled** (int) - Required - Boolean flag for checksum validation.

### Request Example
```c
zxc_compress_opts_t opts = { .level = 3, .checksum_enabled = 0 };
zxc_cctx* cctx = zxc_create_cctx(&opts);
```

### Response
#### Success Response (int64_t)
- **result** (int64_t) - Returns the size of the processed data in bytes.

#### Response Example
```c
int64_t csz = zxc_compress_cctx(cctx, src, src_sz, dst, dst_cap, NULL);
```
```

--------------------------------

### Execute compression and decompression in Node.js

Source: https://context7.com/hellobertrand/zxc/llms.txt

Uses the native Node.js N-API addon to perform compression tasks. Includes support for checksums, buffer size calculations, and metadata retrieval.

```javascript
const zxc = require('zxc-compress');
const data = Buffer.from('Hello, ZXC! '.repeat(1000));

const compressed = zxc.compress(data, {
    level: zxc.LEVEL_DEFAULT,
    checksum: true
});

const decompressed = zxc.decompress(compressed, {
    checksum: true
});

const originalSize = zxc.getDecompressedSize(compressed);
const maxSize = zxc.compressBound(1024 * 1024);
```

--------------------------------

### Using Pre-allocated Buffers for Compression/Decompression in Rust

Source: https://github.com/hellobertrand/zxc/blob/main/wrappers/rust/zxc/README.md

Illustrates how to use pre-allocated buffers with `compress_to` and `decompress_to` for zero-allocation compression and decompression. This is useful for performance-critical applications or when managing memory explicitly. It requires the 'zxc' crate and involves calculating buffer bounds.

```rust
use zxc::{compress_to, decompress_to, compress_bound, CompressOptions, DecompressOptions};

let data = b"Hello, world!";

// Compression
let mut output = vec![0u8; compress_bound(data.len())];
let size = compress_to(data, &mut output, &CompressOptions::default())?;
output.truncate(size);

// Decompression
let mut decompressed = vec![0u8; data.len()];
decompress_to(&output, &mut decompressed, &DecompressOptions::default())?;
```

--------------------------------

### Compress and decompress data using ZXC

Source: https://github.com/hellobertrand/zxc/blob/main/wrappers/nodejs/README.md

Demonstrates how to import the zxc-compress module, compress a Node.js Buffer, and decompress it back to its original state.

```javascript
const zxc = require('zxc-compress');

// Compress
const data = Buffer.from('Hello, World!'.repeat(1_000));
const compressed = zxc.compress(data, { level: zxc.LEVEL_DEFAULT });

// Decompress (auto-detects size)
const decompressed = zxc.decompress(compressed);

console.log(`Original: ${data.length} bytes`);
console.log(`Compressed: ${compressed.length} bytes`);
console.log(`Ratio: ${(compressed.length / data.length * 100).toFixed(1)}%`);
```

--------------------------------

### Configure Profile-Guided Optimization (PGO)

Source: https://github.com/hellobertrand/zxc/blob/main/CMakeLists.txt

Manages PGO workflows by toggling between generation and usage modes. Requires the binary directory to contain profile data when in USE mode.

```cmake
if(ZXC_PGO_MODE STREQUAL "GENERATE")
    target_compile_options(zxc_lib PRIVATE -fprofile-generate=${CMAKE_BINARY_DIR}/pgo)
    target_link_options(zxc_lib PRIVATE -fprofile-generate=${CMAKE_BINARY_DIR}/pgo)
elseif(ZXC_PGO_MODE STREQUAL "USE")
    if(EXISTS "${CMAKE_BINARY_DIR}/pgo")
        target_compile_options(zxc_lib PRIVATE -fprofile-use=${CMAKE_BINARY_DIR}/pgo -fprofile-correction)
        target_link_options(zxc_lib PRIVATE -fprofile-use=${CMAKE_BINARY_DIR}/pgo)
    endif()
endif()
```

--------------------------------

### Context API - Compression

Source: https://context7.com/hellobertrand/zxc/llms.txt

Reusable compression context for high-frequency call sites to eliminate allocation overhead.

```APIDOC
## FUNCTION zxc_create_cctx / zxc_compress_cctx

### Description
Creates a reusable compression context (cctx) that stores sticky options, ideal for batch processing or filesystem plug-ins.

### Parameters
- **create_opts** (zxc_compress_opts_t*) - Required - Initial configuration for the context.
- **cctx** (zxc_cctx*) - Required - The context handle for compression operations.

### Response
- **int64_t** - Compressed size of the block. Returns a negative value on failure.
```

--------------------------------

### Rust API - Compression and Decompression

Source: https://context7.com/hellobertrand/zxc/llms.txt

High-level Rust bindings providing safe, idiomatic compression and decompression with automatic memory management.

```APIDOC
## FUNCTION compress / decompress

### Description
Standard compression and decompression functions for Rust, returning Result types for idiomatic error handling.

### Parameters
- **data** (&[u8]) - Required - Input byte slice.
- **level** (Level) - Required - Compression intensity level.
- **options** (Option<T>) - Optional - Additional configuration.

### Response
- **Result<Vec<u8>, Error>** - The compressed or decompressed data buffer.

### Request Example
```rust
let compressed = compress(data, Level::Default, None)?;
let decompressed = decompress(&compressed)?;
```
```

--------------------------------

### Locate Dependency with Vendored Fallback

Source: https://github.com/hellobertrand/zxc/blob/main/CMakeLists.txt

Attempts to find a system-installed version of the rapidhash library. If not found, it defaults to a local vendored directory.

```cmake
find_path(RAPIDHASH_INCLUDE_DIR rapidhash.h)
if(NOT RAPIDHASH_INCLUDE_DIR)
    set(RAPIDHASH_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src/lib/vendors")
    message(STATUS "Using vendored rapidhash from ${RAPIDHASH_INCLUDE_DIR}")
else()
    message(STATUS "Found system rapidhash in ${RAPIDHASH_INCLUDE_DIR}")
endif()
```

--------------------------------

### Sans-IO API

Source: https://github.com/hellobertrand/zxc/blob/main/docs/API.md

Low-level primitives for building custom compression drivers. This API provides manual control over context initialization and memory management, allowing for specialized integration patterns.

```c
ZXC_EXPORT int zxc_cctx_init(zxc_cctx_t* ctx, size_t chunk_size, int mode, int level, int checksum_enabled);
ZXC_EXPORT void zxc_cctx_free(zxc_cctx_t* ctx);
```

--------------------------------

### CMake Integration for ZXC Library

Source: https://context7.com/hellobertrand/zxc/llms.txt

Shows how to integrate the ZXC library into a CMake project using `find_package` or `pkg-config`. This enables linking the ZXC library to your executable.

```cmake
# CMakeLists.txt
cmake_minimum_required(VERSION 3.14)
project(myapp)

# Method 1: find_package (after installing ZXC)
find_package(zxc REQUIRED)
add_executable(myapp main.c)
target_link_libraries(myapp PRIVATE zxc::zxc_lib)

# Method 2: vcpkg integration
# In vcpkg.json: { "dependencies": ["zxc"] }
find_package(zxc CONFIG REQUIRED)
target_link_libraries(myapp PRIVATE zxc::zxc_lib)
```

--------------------------------

### CLI Compression and Decompression Operations

Source: https://context7.com/hellobertrand/zxc/llms.txt

The ZXC command-line interface supports file compression, decompression, benchmarking, and integration with archive tools like tar. It allows for configurable compression levels and pipe-based workflows.

```bash
# Basic compression (level 3 default)
zxc input_file output_file.xc

# High compression (level 5)
zxc -5 input_file output_file.xc

# Decompress
zxc -d compressed_file.xc output_file

# Integration with GNU tar
tar -I 'zxc -5' -cf archive.tar.zxc data/
tar -I 'zxc -d' -xf archive.tar.zxc

# Pipe-based compression
tar cf - data/ | zxc > archive.tar.zxc
zxc -d < archive.tar.zxc | tar xf -
```

--------------------------------

### Define Opaque Contexts and Internal Types

Source: https://github.com/hellobertrand/zxc/blob/main/docs/API.md

Definitions for opaque library contexts and internal data structures like block headers and compression state buffers.

```c
typedef struct zxc_cctx_s zxc_cctx;  // Opaque compression context
typedef struct zxc_dctx_s zxc_dctx;  // Opaque decompression context

typedef struct {
    uint32_t* hash_table;     // LZ77 hash table
    uint16_t* chain_table;    // Collision chain table
    void*     memory_block;   // Single allocation owner
    uint32_t  epoch;          // Lazy hash invalidation counter
    uint32_t* buf_sequences;  // Packed sequence records
    uint8_t*  buf_tokens;     // Token buffer
    uint16_t* buf_offsets;    // Offset buffer
    uint8_t*  buf_extras;     // Extra-length buffer
    uint8_t*  literals;       // Literal bytes
    uint8_t*  lit_buffer;     // Scratch buffer for RLE
    size_t    lit_buffer_cap;
    uint8_t*  work_buf;       // Padded scratch for buffer-API decompression
    size_t    work_buf_cap;
    int       checksum_enabled;
    int       compression_level;
    size_t    chunk_size;     // Effective block size
    uint32_t  offset_bits;    // log2(chunk_size)
    uint32_t  offset_mask;    // (1 << offset_bits) - 1
    uint32_t  max_epoch;      // 1 << (32 - offset_bits)
} zxc_cctx_t;

typedef struct {
    uint8_t  block_type;   // See FORMAT.md §4
    uint8_t  block_flags;
    uint8_t  reserved;
    uint8_t  header_crc;   // 1-byte header CRC
    uint32_t comp_size;    // Compressed payload size (excl. header)
} zxc_block_header_t;
```

--------------------------------

### Define Configuration Structs

Source: https://github.com/hellobertrand/zxc/blob/main/docs/API.md

Configuration structures for compression and decompression streams. These structs support thread counts, checksum toggles, and optional progress callbacks.

```c
typedef struct {
    int    n_threads;         // Worker thread count (0 = auto-detect).
    int    level;             // Compression level 1–5 (0 = default).
    size_t block_size;        // Block size in bytes (0 = 256 KB default).
    int    checksum_enabled;  // 1 = enable checksums, 0 = disable.
    zxc_progress_callback_t progress_cb;  // Optional callback (NULL to disable).
    void*  user_data;                     // Passed through to progress_cb.
} zxc_compress_opts_t;

typedef struct {
    int    n_threads;         // Worker thread count (0 = auto-detect).
    int    checksum_enabled;  // 1 = verify checksums, 0 = skip.
    zxc_progress_callback_t progress_cb;  // Optional callback.
    void*  user_data;                     // Passed through to progress_cb.
} zxc_decompress_opts_t;
```

--------------------------------

### Python Compression and Decompression with ZXC

Source: https://context7.com/hellobertrand/zxc/llms.txt

Demonstrates basic and advanced compression/decompression using ZXC's Python bindings. Supports buffer protocol for seamless integration with libraries like NumPy. GIL is released for true parallelism.

```python
import zxc

# Basic compression/decompression
data = b"Hello, ZXC! " * 1000

# Compress with default settings
compressed = zxc.compress(data)
print(f"Compressed: {len(data)} -> {len(compressed)} bytes")

# Compress with options
compressed = zxc.compress(data, level=5, checksum=True)
print(f"Level 5: {len(compressed)} bytes ({len(compressed)/len(data)*100:.1f}%)")

# Decompress
decompressed = zxc.decompress(compressed)
assert decompressed == data

# Works with numpy arrays (buffer protocol)
import numpy as np
arr = np.random.bytes(1024 * 1024)  # 1 MB
compressed_arr = zxc.compress(arr)
print(f"NumPy array: {len(arr)} -> {len(compressed_arr)} bytes")
```

--------------------------------

### Query original size from compressed data in Rust

Source: https://context7.com/hellobertrand/zxc/llms.txt

Shows how to retrieve the original uncompressed size from a compressed payload without performing a full decompression operation.

```rust
use zxc::{compress, decompressed_size, Level};

fn main() -> Result<(), zxc::Error> {
    let data = b"Sample data for size query demonstration.";
    let compressed = compress(data, Level::Default, None)?;

    if let Some(size) = decompressed_size(&compressed) {
        println!("Original size: {} bytes", size);
    }
    Ok(())
}
```

--------------------------------

### Reusable Compression Context - zxc_create_cctx / zxc_compress_cctx (C)

Source: https://context7.com/hellobertrand/zxc/llms.txt

Creates and utilizes a reusable compression context to avoid per-call memory allocations, making it suitable for high-frequency operations like filesystem plugins or batch processing. Options set during context creation are sticky for subsequent compressions.

```c
#include "zxc.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define BLOCK_SIZE   (64 * 1024)  // 64 KB
#define NUM_BLOCKS   100

int main(void) {
    // Create context with sticky options (remembered for future calls)
    zxc_compress_opts_t create_opts = {
        .level            = 3,
        .checksum_enabled = 0,
        .block_size       = BLOCK_SIZE,
    };
    zxc_cctx* cctx = zxc_create_cctx(&create_opts);

    if (!cctx) {
        fprintf(stderr, "Context creation failed\n");
        return 1;
    }

    const size_t comp_cap = zxc_compress_bound(BLOCK_SIZE);
    uint8_t* src = malloc(BLOCK_SIZE);
    uint8_t* comp = malloc(comp_cap);

    // Process many blocks without per-call allocation
    for (int i = 0; i < NUM_BLOCKS; i++) {
        // Fill with test data
        memset(src, i, BLOCK_SIZE);

        // Compress - pass NULL to reuse sticky settings
        int64_t csz = zxc_compress_cctx(cctx, src, BLOCK_SIZE, comp, comp_cap, NULL);

        if (csz < 0) {
            fprintf(stderr, "Block %d failed: %s\n", i, zxc_error_name((int)csz));
            break;
        }
    }

    printf("Processed %d blocks with zero per-block allocation\n", NUM_BLOCKS);

    zxc_free_cctx(cctx);
    free(src);
    free(comp);
    return 0;
}

```

--------------------------------

### Perform standard compression and decompression in Rust

Source: https://context7.com/hellobertrand/zxc/llms.txt

Provides a safe, idiomatic Rust API for compressing and decompressing data. Uses the Result type for error propagation and handles memory management automatically.

```rust
use zxc::{compress, decompress, Level, Error};

fn main() -> Result<(), Error> {
    let data = b"Hello, ZXC! This is sample data for compression.";
    let compressed = compress(data, Level::Default, None)?;
    let decompressed = decompress(&compressed)?;
    assert_eq!(&decompressed[..], &data[..]);
    Ok(())
}
```

--------------------------------

### Configure Build Options and Optimization

Source: https://github.com/hellobertrand/zxc/blob/main/CMakeLists.txt

Defines project-wide build options including LTO, PGO, and native architecture optimization. It includes logic to check for LTO support and disables conflicting features like code coverage.

```cmake
option(ZXC_NATIVE_ARCH "Enable -march=native for maximum performance" ON)
option(ZXC_ENABLE_LTO "Enable Interprocedural Optimization (LTO)" ON)
if(ZXC_ENABLE_LTO AND NOT ZXC_ENABLE_COVERAGE)
    include(CheckIPOSupported)
    check_ipo_supported(RESULT result OUTPUT output)
    if(result)
        message(STATUS "LTO/IPO is supported and enabled.")
    endif()
endif()
```

--------------------------------

### Querying Decompressed Size in Rust

Source: https://github.com/hellobertrand/zxc/blob/main/wrappers/rust/zxc/README.md

Demonstrates how to determine the size of the decompressed data before allocating a buffer using the `decompressed_size` function. This is useful for optimizing memory allocation when the original data size is unknown. It requires the 'zxc' crate.

```rust
use zxc::decompressed_size;

if let Some(size) = decompressed_size(&compressed) {
    let mut buffer = vec![0u8; size];
    // ...
}
```