|
| 1 | +# Libdatadog - shared repository for Datadog rust |
| 2 | + |
| 3 | +**libdatadog** is a Rust workspace of shared libraries and utilities for Datadog's instrumentation tooling (continuous profilers, crash tracking, APM tracing). It exposes C/C++ FFI bindings consumed by Datadog SDKs in other languages. |
| 4 | + |
| 5 | +## Development Workflow |
| 6 | + |
| 7 | +### Validating after changes |
| 8 | + |
| 9 | +Iterate fastest with `cargo check -p <crate>` while editing; the full validation steps below are what should be green before declaring work done. |
| 10 | + |
| 11 | +1. **Compile** — use `cargo check -p <crate>` for fast iteration on a single crate; run the full workspace build only when changes are repo-wide: |
| 12 | + ```bash |
| 13 | + cargo check -p <crate> # fast iteration on a single crate |
| 14 | + cargo build --workspace --exclude builder # full build (repo-wide changes only) |
| 15 | + ``` |
| 16 | + |
| 17 | +2. **Format and lint** — always run on every crate that was touched, before finishing: |
| 18 | + ```bash |
| 19 | + cargo +nightly-2026-02-08 fmt --all -- --check |
| 20 | + cargo +stable clippy --workspace --all-targets --all-features -- -D warnings |
| 21 | + ``` |
| 22 | + |
| 23 | +3. **Run tests** with nextest plus doc tests: |
| 24 | + ```bash |
| 25 | + cargo nextest run --workspace --no-fail-fast |
| 26 | + cargo nextest run --workspace --all-features --exclude builder --exclude test_spawn_from_lib |
| 27 | + cargo test --doc |
| 28 | + ``` |
| 29 | + Run a single test by substring: `cargo nextest run -p <crate-name> <test-name>`. |
| 30 | + |
| 31 | +4. **If FFI crates were touched**, build and run the C/C++ FFI examples: |
| 32 | + ```bash |
| 33 | + cargo ffi-test |
| 34 | + ``` |
| 35 | + |
| 36 | +5. **If `tracing_integration_tests::` tests fail**, they require Docker. Prompt the user to start Docker and retry; to skip them locally use: |
| 37 | + ```bash |
| 38 | + cargo nextest run -E '!test(tracing_integration_tests::)' |
| 39 | + ``` |
| 40 | + |
| 41 | +6. **If `Cargo.lock` was touched**, regenerate the third-party license CSV so `cargo deny` and the CI guard stay green: |
| 42 | + ```bash |
| 43 | + ./scripts/update_license_3rdparty.sh |
| 44 | + cargo deny check |
| 45 | + ``` |
| 46 | + |
| 47 | +### Per-crate test notes |
| 48 | + |
| 49 | +- **crashtracker**: needs `--features libdd-crashtracker/generate-unit-test-files` for unit tests. |
| 50 | +- **http-client**: ships two alternative backend features (`reqwest-backend` is the default, `hyper-backend` is the alternative). Cargo does not enforce exclusivity, but each backend must be exercised independently when this crate is touched: |
| 51 | + ```bash |
| 52 | + # Default (reqwest) backend — covered by the workspace test run |
| 53 | + cargo nextest run -p libdd-http-client |
| 54 | + # Hyper backend |
| 55 | + cargo nextest run -p libdd-http-client --no-default-features --features hyper-backend,https |
| 56 | + ``` |
| 57 | +- **test_spawn_from_lib**: `cargo nextest run --package test_spawn_from_lib --features prefer-dynamic`. |
| 58 | + |
| 59 | + |
| 60 | +## Key Conventions |
| 61 | + |
| 62 | +### Reliability & integrability |
| 63 | +libdatadog is integrated into many runtimes and languages via FFI, and runs in Datadog customers' environments. Code should be as reliable and integrable as possible: |
| 64 | +- Avoid `unwrap`/`panic!` outside of tests; bubble errors up instead. |
| 65 | +- Bubble errors up to the library caller with detail — prefer structured error enums (e.g. `thiserror`) over opaque strings. |
| 66 | +- Stay free of global effects unless a feature requires them: no spawning threads, no globals, no reading environment variables behind the caller's back. |
| 67 | +- Care about performance, especially memory allocations on hot paths. |
| 68 | +- Panics across FFI boundaries are undefined behavior. FFI entry points must catch unwinds (e.g. `std::panic::catch_unwind`) and convert them into error returns rather than letting them propagate into the caller's runtime. |
| 69 | +- The C FFI does **not** offer C ABI backward-compatibility guarantees: callers (Datadog SDKs) pin to specific libdatadog versions, so `#[repr(C)]` layouts, function signatures, and enum variants may change between releases. |
| 70 | + |
| 71 | +### Cryptography |
| 72 | +- Default build: ring as TLS crypto provider |
| 73 | +- FIPS (US government cloud) builds: aws-lc-rs via `fips` feature flag |
| 74 | +- Windows FIPS requires env var: `AWS_LC_FIPS_SYS_NO_ASM=1` |
| 75 | + |
| 76 | +### Commit Messages |
| 77 | +PR titles and commits must follow **Conventional Commits**: `<type>([scope]): <description>` |
| 78 | +Common types: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore` |
| 79 | +Breaking changes: append `!` — e.g. `feat!: remove deprecated API` |
| 80 | + |
| 81 | +### Licenses |
| 82 | +All source files must have Apache 2.0 license headers (except `symbolizer-ffi`). Use `./scripts/reformat_copyright.sh` to add or fix headers automatically. The third-party license CSV (`LICENSE-3rdparty.csv`) is validated in CI. To regenerate: |
| 83 | +```bash |
| 84 | +./scripts/update_license_3rdparty.sh |
| 85 | +``` |
| 86 | + |
| 87 | +### Build Tooling |
| 88 | +- **builder** — generates release artifacts (C libraries, headers, pkg-config). Run with: |
| 89 | + ```bash |
| 90 | + cargo run --bin release -- --out output-folder |
| 91 | + ``` |
| 92 | + Feature flags control what's built: `crashtracker`, `profiling`, `telemetry`, `data-pipeline`, `symbolizer`, `library-config`, `log`, `ddsketch`, `ffe` |
| 93 | +- **tools** — dev binaries: header dedup, FFI test runner, JUnit attribute injection |
0 commit comments