libdd-libunwind-sys 1.0.2

Rust bindings for using unwind library inside libdatadog
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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# libdatadog-libunwind

Rust bindings for libunwind, targeting Linux on x86_64 and aarch64.

libunwind is **vendored** directly in this repository under `libdd-libunwind-sys/libunwind/`.
Vendoring is intentional: it eliminates the runtime dependency on an external source and protects
against supply chain attacks.

## Crates


| Crate                 | Description                            |
| --------------------- | -------------------------------------- |
| `libdd-libunwind-sys` | Low-level FFI bindings and build logic |


## Bindings

The FFI bindings in `libdd-libunwind-sys/src/` are **hand-written** (not generated by `bindgen`).
Each supported architecture has its own module:

- `libunwind_x86_64.rs` — bindings for x86_64
- `libunwind_aarch64.rs` — bindings for aarch64

The bindings expose a subset of the libunwind API:
`unw_init_local2`, `unw_step`, `unw_get_reg`, `unw_get_proc_name`, and `unw_backtrace2`.

When adding or updating bindings, edit the appropriate architecture file directly.

## Build

### Prerequisites

The build script compiles libunwind from source and requires the following tools on the host:


| Tool             | Purpose                                    | Install (Debian/Ubuntu) |
| ---------------- | ------------------------------------------ | ----------------------- |
| `make`           | Drives the build                           | `apt install make`      |
| `gcc` or `clang` | C/C++ compiler for libunwind               | `apt install gcc`       |


Install all at once:

```sh
apt install make gcc
```

### Building

```sh
cargo build
```

### Supported targets


| Target                      | Status    |
| --------------------------- | --------- |
| `x86_64-unknown-linux-gnu`  | Supported |
| `aarch64-unknown-linux-gnu` | Supported |


All other targets produce an empty crate (the build script and bindings are gated on `target_os = "linux"`).

## How to publish

1. **Bump the version** in `Cargo.toml` and merge the change to `main`.

2. **Tag the release commit** on `main`:

   ```sh
   git checkout main && git pull
   git tag v<version>          # e.g. git tag v1.1.0
   git push origin v<version>
   ```

3. **Wait for CI** — the tag push triggers a pipeline that runs all four
   build+test configurations (CentOS and Alpine, x86\_64 and aarch64).

4. **Trigger the publish job** — once all test jobs are green, a manual
   `publish_crate` job appears in the pipeline.  Click ▶ to publish to
   crates.io.

The publish job validates that the tag version matches `Cargo.toml`, that
the tagged commit is on `main`, and does a `--dry-run` before the real
publish.  If the version is already on crates.io the job exits cleanly
without error.