]>
Commit | Line | Data |
---|---|---|
532ac7d7 XL |
1 | # Contributing to `libc` |
2 | ||
3 | Welcome! If you are reading this document, it means you are interested in contributing | |
4 | to the `libc` crate. | |
5 | ||
6 | ## Adding an API | |
7 | ||
8 | Want to use an API which currently isn't bound in `libc`? It's quite easy to add | |
9 | one! | |
10 | ||
11 | The internal structure of this crate is designed to minimize the number of | |
12 | `#[cfg]` attributes in order to easily be able to add new items which apply | |
13 | to all platforms in the future. As a result, the crate is organized | |
14 | hierarchically based on platform. Each module has a number of `#[cfg]`'d | |
15 | children, but only one is ever actually compiled. Each module then reexports all | |
16 | the contents of its children. | |
17 | ||
18 | This means that for each platform that libc supports, the path from a | |
19 | leaf module to the root will contain all bindings for the platform in question. | |
20 | Consequently, this indicates where an API should be added! Adding an API at a | |
21 | particular level in the hierarchy means that it is supported on all the child | |
22 | platforms of that level. For example, when adding a Unix API it should be added | |
23 | to `src/unix/mod.rs`, but when adding a Linux-only API it should be added to | |
e74abb32 | 24 | `src/unix/linux_like/linux/mod.rs`. |
532ac7d7 XL |
25 | |
26 | If you're not 100% sure at what level of the hierarchy an API should be added | |
27 | at, fear not! This crate has CI support which tests any binding against all | |
28 | platforms supported, so you'll see failures if an API is added at the wrong | |
29 | level or has different signatures across platforms. | |
30 | ||
31 | With that in mind, the steps for adding a new API are: | |
32 | ||
33 | 1. Determine where in the module hierarchy your API should be added. | |
34 | 2. Add the API. | |
35 | 3. Send a PR to this repo. | |
36 | 4. Wait for CI to pass, fixing errors. | |
37 | 5. Wait for a merge! | |
38 | ||
39 | ### Test before you commit | |
40 | ||
e1599b0c | 41 | We have two automated tests running on [Azure Pipelines](https://dev.azure.com/rust-lang2/libc/_build?definitionId=1&_a=summary): |
532ac7d7 | 42 | |
e1599b0c | 43 | 1. [`libc-test`](https://github.com/gnzlbg/ctest) |
532ac7d7 XL |
44 | - `cd libc-test && cargo test` |
45 | - Use the `skip_*()` functions in `build.rs` if you really need a workaround. | |
46 | 2. Style checker | |
47 | - `rustc ci/style.rs && ./style src` | |
48 | ||
49 | ### Releasing your change to crates.io | |
50 | ||
51 | Now that you've done the amazing job of landing your new API or your new | |
52 | platform in this crate, the next step is to get that sweet, sweet usage from | |
53 | crates.io! The only next step is to bump the version of libc and then publish | |
54 | it. If you'd like to get a release out ASAP you can follow these steps: | |
55 | ||
3dfed10e XL |
56 | 1. Increment the patch version number in `Cargo.toml`. |
57 | 1. Send a PR to this repository. It should [look like this][example], but it'd | |
532ac7d7 XL |
58 | also be nice to fill out the description with a small rationale for the |
59 | release (any rationale is ok though!) | |
3dfed10e | 60 | 1. Once merged, the release will be tagged and published by one of the libc crate |
532ac7d7 XL |
61 | maintainers. |
62 | ||
63 | [example]: https://github.com/rust-lang/libc/pull/583 |