Skip to content

Commit 3f5c74a

Browse files
committed
Document Alpine Linux build quirk in BUILD.md
On Alpine Linux and other musl-based distributions, the `x86_64-unknown-linux-musl` Rust target statically links musl by default. When the binary dynamically links to Alpine's OpenSSL (which itself links to Alpine's musl), two different musl instances exist in the same process, causing segmentation faults at runtime. This change adds `BUILD.md` documenting the issue and the solution: setting `RUSTFLAGS="-C target-feature=-crt-static"` to dynamically link musl. The document includes the root cause explanation, the fix, and references to the original discussions.
1 parent eb0eab1 commit 3f5c74a

File tree

1 file changed

+32
-0
lines changed

1 file changed

+32
-0
lines changed

BUILD.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Building rabbitmqadmin
2+
3+
## Standard Build
4+
5+
```bash
6+
cargo build --release
7+
```
8+
9+
## Alpine Linux / musl-based Systems
10+
11+
When building on Alpine Linux or other musl-based distributions, you must configure Rust to dynamically link against the system's musl libc to avoid segmentation faults.
12+
13+
### The Problem
14+
15+
The `x86_64-unknown-linux-musl` target statically links musl by default. When your binary dynamically links to Alpine's OpenSSL (which itself links to Alpine's musl), you end up with two different musl instances in the same process, causing segmentation faults at runtime.
16+
17+
### The Solution
18+
19+
Set the `RUSTFLAGS` environment variable to dynamically link musl:
20+
21+
```bash
22+
RUSTFLAGS="-C target-feature=-crt-static" cargo build --release
23+
```
24+
25+
### Alternative: Static Linking
26+
27+
Alternatively, you can statically link OpenSSL by enabling the `vendored` feature in dependencies that use OpenSSL. However, this approach is not currently configured in this project.
28+
29+
### References
30+
31+
- [Rust Users Forum: SIGSEGV with program linked against OpenSSL in an Alpine container](https://users.rust-lang.org/t/sigsegv-with-program-linked-against-openssl-in-an-alpine-container/52172)
32+
- [GitHub Discussion #99](https://github.com/rabbitmq/rabbitmqadmin-ng/discussions/99)

0 commit comments

Comments
 (0)