| 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 |
## v0.2 changes |
| 7 |
|
| 8 |
If you want to add your changes to v0.2, please submit them to the `libc-0.2` branch. |
| 9 |
If you want to add any breaking changes, it should be submitted to the main branch, |
| 10 |
which has changes for v0.3. |
| 11 |
We will support and make a new release for v0.2 until we make the first release of v0.3. |
| 12 |
|
| 13 |
## Adding an API |
| 14 |
|
| 15 |
Want to use an API which currently isn't bound in `libc`? It's quite easy to add |
| 16 |
one! |
| 17 |
|
| 18 |
The internal structure of this crate is designed to minimize the number of |
| 19 |
`#[cfg]` attributes in order to easily be able to add new items which apply |
| 20 |
to all platforms in the future. As a result, the crate is organized |
| 21 |
hierarchically based on platform. Each module has a number of `#[cfg]`'d |
| 22 |
children, but only one is ever actually compiled. Each module then reexports all |
| 23 |
the contents of its children. |
| 24 |
|
| 25 |
This means that for each platform that libc supports, the path from a |
| 26 |
leaf module to the root will contain all bindings for the platform in question. |
| 27 |
Consequently, this indicates where an API should be added! Adding an API at a |
| 28 |
particular level in the hierarchy means that it is supported on all the child |
| 29 |
platforms of that level. For example, when adding a Unix API it should be added |
| 30 |
to `src/unix/mod.rs`, but when adding a Linux-only API it should be added to |
| 31 |
`src/unix/linux_like/linux/mod.rs`. |
| 32 |
|
| 33 |
If you're not 100% sure at what level of the hierarchy an API should be added |
| 34 |
at, fear not! This crate has CI support which tests any binding against all |
| 35 |
platforms supported, so you'll see failures if an API is added at the wrong |
| 36 |
level or has different signatures across platforms. |
| 37 |
|
| 38 |
New symbol(s) (i.e. functions, constants etc.) should also be added to the |
| 39 |
symbols list(s) found in the `libc-test/semver` directory. These lists keep |
| 40 |
track of what symbols are public in the libc crate and ensures they remain |
| 41 |
available between changes to the crate. If the new symbol(s) are available on |
| 42 |
all supported Unixes it should be added to `unix.txt` list<sup>1</sup>, |
| 43 |
otherwise they should be added to the OS specific list(s). |
| 44 |
|
| 45 |
With that in mind, the steps for adding a new API are: |
| 46 |
|
| 47 |
1. Determine where in the module hierarchy your API should be added. |
| 48 |
2. Add the API, including adding new symbol(s) to the semver lists. |
| 49 |
3. Send a PR to this repo. |
| 50 |
4. Wait for CI to pass, fixing errors. |
| 51 |
5. Wait for a merge! |
| 52 |
|
| 53 |
<sup>1</sup>: Note that this list has nothing to do with any Unix or Posix |
| 54 |
standard, it's just a list shared between all OSs that declare `#[cfg(unix)]`. |
| 55 |
|
| 56 |
## Test before you commit |
| 57 |
|
| 58 |
We have two automated tests running on [GitHub Actions](https://github.com/rust-lang/libc/actions): |
| 59 |
|
| 60 |
1. [`libc-test`](https://github.com/gnzlbg/ctest) |
| 61 |
- `cd libc-test && cargo test` |
| 62 |
- Use the `skip_*()` functions in `build.rs` if you really need a workaround. |
| 63 |
2. Style checker |
| 64 |
- [`sh ci/style.sh`](https://github.com/rust-lang/libc/blob/main/ci/style.sh) |
| 65 |
|
| 66 |
## Breaking change policy |
| 67 |
|
| 68 |
Sometimes an upstream adds a breaking change to their API e.g. removing outdated items, |
| 69 |
changing the type signature, etc. And we probably should follow that change to build the |
| 70 |
`libc` crate successfully. It's annoying to do the equivalent of semver-major versioning |
| 71 |
for each such change. Instead, we mark the item as deprecated and do the actual change |
| 72 |
after a certain period. The steps are: |
| 73 |
|
| 74 |
1. Add `#[deprecated(since = "", note="")]` attribute to the item. |
| 75 |
- The `since` field should have a next version of `libc` |
| 76 |
(e.g., if the current version is `0.2.1`, it should be `0.2.2`). |
| 77 |
- The `note` field should have a reason to deprecate and a tracking issue to call for comments |
| 78 |
(e.g., "We consider removing this as the upstream removed it. |
| 79 |
If you're using it, please comment on #XXX"). |
| 80 |
2. If we don't see any concerns for a while, do the change actually. |
| 81 |
|
| 82 |
## Supported target policy |
| 83 |
|
| 84 |
When Rust removes a support for a target, the libc crate also may remove the support anytime. |
| 85 |
|
| 86 |
## Releasing your change to crates.io |
| 87 |
|
| 88 |
Now that you've done the amazing job of landing your new API or your new |
| 89 |
platform in this crate, the next step is to get that sweet, sweet usage from |
| 90 |
crates.io! The only next step is to bump the version of libc and then publish |
| 91 |
it. If you'd like to get a release out ASAP you can follow these steps: |
| 92 |
|
| 93 |
1. Increment the patch version number in `Cargo.toml` and `libc-test/Cargo.toml`. |
| 94 |
1. Send a PR to this repository. It should [look like this][example-pr], but it'd |
| 95 |
also be nice to fill out the description with a small rationale for the |
| 96 |
release (any rationale is ok though!). |
| 97 |
1. Once merged, the release will be tagged and published by one of the libc crate |
| 98 |
maintainers. |
| 99 |
|
| 100 |
[example-pr]: https://github.com/rust-lang/libc/pull/2120 |