pkgconf 0.1.0

Parse pkg-config output with proper --whole-archive and static library support
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

# pkgconf

A Rust build helper for parsing pkg-config output with proper `--whole-archive` and static library support.

## Problem

The standard [`pkg-config`](https://crates.io/crates/pkg-config) crate has limitations:

1. **Flag reordering** — It doesn't preserve the ordering of `-Wl,--whole-archive` and `-l` flags, breaking linking for libraries with constructor functions (like DPDK's `RTE_INIT` macros)
2. **Static detection** — It doesn't properly distinguish between static and dynamic libraries based on `.a` file availability

## Solution

This crate parses pkg-config output directly and:

- **Tracks `--whole-archive` regions** from the pkg-config output
- **Auto-detects static library availability** by checking if `lib<name>.a` exists
- **Excludes system directories** (default: `/usr`) so system libs link dynamically
- **Emits correct cargo link directives** with proper modifiers (`static:`, `+whole-archive`, `-bundle`)

## Usage

```rust
use pkgconf::PkgConfigParser;

// In build.rs
fn main() {
    PkgConfigParser::new()
        .probe_and_emit(
            ["openssl", "libfoo"],
            None,  // or Some("/custom/pkgconfig/path")
        )
        .expect("pkg-config failed");
}
```

### Force Whole-Archive

For libraries with constructor functions that need `--whole-archive`:

```rust
use pkgconf::PkgConfigParser;

PkgConfigParser::new()
    .force_whole_archive([
        "mylib_with_constructors",
    ])
    .probe_and_emit(["mylib"], None)
    .expect("pkg-config failed");
```

### Custom System Roots

Libraries under system roots link dynamically (even if `.a` exists):

```rust
use pkgconf::PkgConfigParser;

PkgConfigParser::new()
    .system_roots(["/usr", "/usr/local", "/opt/homebrew"])
    .probe_and_emit(["openssl"], None)
    .expect("pkg-config failed");
```

## Link Kinds

Libraries are emitted with one of three link kinds:

| Condition | Link Kind | Cargo Directive |
|-----------|-----------|-----------------|
| No `.a` found (or in system dir) | `Default` | `rustc-link-lib=name` |
| `.a` exists, outside whole-archive region | `Static` | `rustc-link-lib=static:-bundle=name` |
| `.a` exists, inside whole-archive region | `WholeArchive` | `rustc-link-lib=static:+whole-archive,-bundle=name` |

## Why Constructor Functions Need Whole-Archive

Libraries using `__attribute__((constructor))` or macros like DPDK's `RTE_INIT` register functionality at load time. Without `--whole-archive`, the linker discards these "unused" symbols, causing registration to fail silently.

## License

MIT