fast-gicp-sys 0.3.0

Low-level FFI bindings for fast_gicp C++ library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

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

```bash
# 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