fast-gicp-sys 0.3.0

Low-level FFI bindings for fast_gicp C++ library
Documentation

fast-gicp-sys

Low-level FFI bindings for the fast_gicp C++ library.

Build Requirements

Normal Build

  • PCL (Point Cloud Library) >= 1.8
  • Eigen3 >= 3.0
  • C++ compiler with C++17 support
  • CMake

Documentation Build (docs.rs)

No external dependencies required when using the docs-only feature.

Features

  • openmp (default): Enable OpenMP parallelization
  • cuda: Enable CUDA GPU acceleration
  • bindgen: Regenerate bindings from C++ headers (requires all dependencies)
  • docs-only: Skip C++ compilation, use pre-generated bindings only

Pre-generated Bindings

This crate includes pre-generated CXX bindings in src/generated/ to support documentation builds on docs.rs where C++ dependencies are not available.

Updating Pre-generated Bindings

When making changes to the FFI interface, you must regenerate the bindings:

# From the project root
make generate-bindings

# Or manually
cd fast-gicp-sys
cargo build --features bindgen

Important: Always commit the updated files in src/generated/ to ensure docs.rs builds continue to work.

Implementation Details

The binding generation process uses a two-phase approach:

  1. Phase 1: Parse the cxx::bridge definition from src/lib.rs (via ffi_definition module)
  2. Phase 2: Generate two files:
    • src/generated/bindings.rs: Full FFI bindings (used by default)
    • src/generated/stub.rs: Stub implementations with unreachable!() for docs.rs

The build script automatically handles conditional compilation:

  • Default build: Compiles C++ and uses bindings.rs
  • docs-only feature: Skips C++ compilation and uses stub.rs
  • bindgen feature: Regenerates both files from the source definition

Development Workflow

  1. Make changes to the FFI interface in src/lib.rs (in the ffi_definition module)
  2. Test the normal build: cargo build
  3. Regenerate bindings: make generate-bindings
  4. Test docs-only build: cargo build --no-default-features --features docs-only
  5. Run the lint suite: make lint (from project root)
  6. Verify the generated code: cargo expand --lib > expanded.rs
  7. Commit both the source changes and updated src/generated/ files