carla_sys/lib.rs
1//! Low-level FFI bindings to the CARLA C++ client library.
2//!
3//! ⚠️ **Warning:** This crate provides unsafe, low-level FFI bindings.
4//! Most users should use the [`carla`](https://docs.rs/carla) crate instead,
5//! which provides safe, idiomatic Rust wrappers around these bindings.
6//!
7//! # Overview
8//!
9//! `carla-sys` exposes the C++ CARLA client library to Rust using
10//! [autocxx](https://docs.rs/autocxx) for automatic binding generation.
11//! This crate handles:
12//!
13//! - Building and linking the CARLA C++ client library
14//! - Generating Rust FFI bindings to C++ classes and functions
15//! - Providing minimal safe wrappers (e.g., `Send` and `Sync` implementations)
16//!
17//! # Safety
18//!
19//! **This crate is not intended for direct use.** The FFI bindings are largely
20//! `unsafe` and require careful handling of:
21//!
22//! - Raw pointers and null pointer checks
23//! - C++ object lifetimes and ownership
24//! - Memory management across the FFI boundary
25//! - Thread safety of C++ objects
26//!
27//! The [`carla`](https://docs.rs/carla) crate provides safe abstractions over
28//! these unsafe operations.
29//!
30//! # Building
31//!
32//! This crate requires either:
33//! 1. **Prebuilt binaries** - Downloaded automatically for supported platforms
34//! 2. **Building from source** - Requires CARLA source and C++ build tools
35//!
36//! ## Environment Variables
37//!
38//! - `CARLA_DIR` - Path to CARLA installation or source directory
39//! - `TARGET` - Rust target triple (set automatically by cargo)
40//! - `OUT_DIR` - Build output directory (set automatically by cargo)
41//!
42//! ## Features
43//!
44//! - `build-prebuilt` - Build CARLA C++ library from source and save as prebuilt tarball with bindings for distribution
45//! - `docs-only` - Generate documentation without C++ library (for docs.rs)
46//!
47//! # C++ Version Compatibility
48//!
49//! This crate is compatible with **CARLA 0.9.14**. Different CARLA versions
50//! may have incompatible C++ APIs.
51//!
52//! # Thread Safety
53//!
54//! Most C++ types are wrapped with `unsafe impl Send` and `unsafe impl Sync`
55//! in the `impls` module. See `carla-sys/src/impls.rs` for safety documentation
56//! on each implementation.
57//!
58//! # Examples
59//!
60//! **Direct use of this crate is not recommended.** Use the [`carla`] crate instead.
61//!
62//! If you must use `carla-sys` directly (e.g., for custom bindings):
63//!
64//! ```ignore
65//! use carla_sys::carla_rust::client::FfiClient;
66//!
67//! unsafe {
68//! // Create a client - requires manual memory management
69//! let client = FfiClient::new("localhost", 2000, 0);
70//! // ... use client (careful with lifetimes and ownership!)
71//! }
72//! ```
73//!
74//! # Links
75//!
76//! - [CARLA Simulator](https://carla.org/)
77//! - [CARLA C++ Reference](https://carla.readthedocs.io/en/0.9.14/ref_cpp/)
78//! - [`carla` crate](https://docs.rs/carla) - Safe Rust bindings
79//! - [autocxx](https://docs.rs/autocxx) - C++ binding generator
80//!
81//! # See Also
82//!
83//! - [`carla`] - Safe, high-level Rust bindings (use this instead!)
84
85#[cfg(feature = "docs-only")]
86mod ffi_docs_only;
87#[cfg(feature = "docs-only")]
88pub use ffi_docs_only::*;
89
90#[cfg(not(feature = "docs-only"))]
91mod bindings;
92#[cfg(not(feature = "docs-only"))]
93pub use bindings::*;
94
95mod impls;