# Installation and Linking
## Prerequisites
- Rust toolchain (1.70 or later)
- [cbindgen](https://github.com/mozilla/cbindgen) — for C header generation:
`cargo install cbindgen`
- [cargo-c](https://github.com/lu-zero/cargo-c) — optional, for pkg-config
support: `cargo install cargo-c`
## Building the Library
Build the shared library and regenerate `include/synta.h`:
```bash
cargo build --release -p synta-ffi
```
This places the library in `target/release/` and regenerates `include/synta.h`
via cbindgen (invoked automatically by `build.rs`).
The `openssl` feature is enabled by default and provides AES-CBC content
encryption/decryption (`synta_cms_encrypted_data_create`,
`synta_cms_encrypted_data_decrypt`) and encrypted PKCS#12 bag decryption.
To build with NSS-backed signature verification instead of OpenSSL:
```bash
cargo build --release -p synta-ffi --no-default-features --features nss
```
### With pkg-config Support (cargo-c)
For pkg-config integration, use cargo-c:
```bash
cargo cbuild --release -p synta-ffi
```
This produces a pkg-config-compatible installation with the library at
`target/<host-triple>/release/`.
Install system-wide:
```bash
cargo cinstall --release -p synta-ffi --prefix /usr/local
```
## Linking Against the Library
### Using pkg-config
```bash
gcc myapp.c $(pkg-config --cflags --libs csynta) -o myapp
```
### Using CMake
```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(CSYNTA REQUIRED csynta)
target_link_libraries(myapp ${CSYNTA_LIBRARIES})
target_include_directories(myapp PRIVATE ${CSYNTA_INCLUDE_DIRS})
```
Or with the named target from the generated `CMakeLists.txt`:
```cmake
find_package(Synta REQUIRED)
target_link_libraries(myapp Synta::Synta)
```
### Manual Linking
```bash
gcc myapp.c -I/path/to/include -L/path/to/lib -lcsynta -lpthread -ldl -lm -o myapp
```
Platform-specific link flags:
| Linux / BSD | `-lpthread -ldl -lm` |
| macOS | `-lpthread` |
| Windows | `-lws2_32 -luserenv -lbcrypt` |
## Header File
```c
#include <synta.h>
```
The header is auto-generated by cbindgen from the Rust source. It includes
all type definitions (`SyntaByteArray`, `SyntaDecoder`, `SyntaEncoder`, error
codes, tag classes) and all function prototypes.
## Cargo Features
| `capi` | yes | Exposes the full C API surface; required for all `synta_*` functions |
| `openssl` | no | Links OpenSSL for AES-CBC encryption/decryption and encrypted PKCS#12 support |
## Testing
C integration tests are compiled and executed via the Rust test harness:
```bash
cargo test -p synta-ffi
```
To run under Valgrind:
```bash
./contrib/ci/local-ci.sh --valgrind c-test
```
All tests are verified Valgrind-clean (zero memory leaks).