diff options
Diffstat (limited to 'libc/README.md')
| -rw-r--r-- | libc/README.md | 226 |
1 files changed, 78 insertions, 148 deletions
diff --git a/libc/README.md b/libc/README.md index 636f10e..a974ccd 100644 --- a/libc/README.md +++ b/libc/README.md @@ -1,173 +1,103 @@ -libc +[![Travis-CI Status]][Travis-CI] [![Appveyor Status]][Appveyor] [![Cirrus-CI Status]][Cirrus-CI] [![Latest Version]][crates.io] [![Documentation]][docs.rs] ![License] + +libc - Raw FFI bindings to platforms' system libraries ==== -Raw FFI bindings to platform libraries like `libc`. +`libc` provides all of the definitions necessary to easily interoperate with C +code (or "C-like" code) on each of the platforms that Rust supports. This +includes type definitions (e.g. `c_int`), constants (e.g. `EINVAL`) as well as +function headers (e.g. `malloc`). + +This crate exports all underlying platform types, functions, and constants under +the crate root, so all items are accessible as `libc::foo`. The types and values +of all the exported APIs match the platform that libc is compiled for. -[](https://travis-ci.org/rust-lang/libc) -[](https://ci.appveyor.com/project/rust-lang-libs/libc) -[](https://cirrus-ci.com/github/rust-lang/libc) -[](https://crates.io/crates/libc) -[](https://docs.rs/libc) - +More detailed information about the design of this library can be found in its +[associated RFC][rfc]. + +[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1291-promote-libc.md ## Usage -First, add the following to your `Cargo.toml`: +Add the following to your `Cargo.toml`: ```toml [dependencies] libc = "0.2" ``` -Next, add this to your crate root: +## Features -```rust -extern crate libc; -``` +* `use_std`: by default `libc` links to the standard library. Disable this + feature remove this dependency and be able to use `libc` in `#![no_std]` + crates. -Currently libc by default links to the standard library, but if you would -instead like to use libc in a `#![no_std]` situation or crate you can request -this via: +* `extra_traits`: all `struct`s implemented in `libc` are `Copy` and `Clone`. + This feature derives `Debug`, `Eq`, `Hash`, and `PartialEq`. -```toml -[dependencies] -libc = { version = "0.2", default-features = false } -``` +## Rust version support -By default libc uses private fields in structs in order to enforce a certain -memory alignment on them. These structs can be hard to instantiate outside of -libc. To make libc use `#[repr(align(x))]`, instead of the private fields, -activate the *align* feature. This requires Rust 1.25 or newer: +The minimum supported Rust toolchain version is **Rust 1.13.0** . APIs requiring +newer Rust features are only available on newer Rust toolchains: -```toml -[dependencies] -libc = { version = "0.2", features = ["align"] } -``` +| Feature | Version | +|----------------------|---------| +| `union` | 1.19.0 | +| `const mem::size_of` | 1.24.0 | +| `repr(align)` | 1.25.0 | +| `extra_traits` | 1.25.0 | +| `core::ffi::c_void` | 1.30.0 | +| `repr(packed(N))` | 1.33.0 | -## What is libc? +## Platform support -The primary purpose of this crate is to provide all of the definitions necessary -to easily interoperate with C code (or "C-like" code) on each of the platforms -that Rust supports. This includes type definitions (e.g. `c_int`), constants -(e.g. `EINVAL`) as well as function headers (e.g. `malloc`). +[Platform-specific documentation (master branch)][docs.master]. -This crate does not strive to have any form of compatibility across platforms, -but rather it is simply a straight binding to the system libraries on the -platform in question. +See +[`ci/build.sh`](https://github.com/rust-lang/libc/blob/master/libc-test/build.rs) +for the platforms on which `libc` is guaranteed to build for each Rust +toolchain. The test-matrix at [Travis-CI], [Appveyor], and [Cirrus-CI] show the +platforms in which `libc` tests are run. -## Public API +<div class="platform_docs"></div> -This crate exports all underlying platform types, functions, and constants under -the crate root, so all items are accessible as `libc::foo`. The types and values -of all the exported APIs match the platform that libc is compiled for. +## License -More detailed information about the design of this library can be found in its -[associated RFC][rfc]. +This project is licensed under either of -[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1291-promote-libc.md +* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) + ([LICENSE-APACHE](LICENSE-APACHE)) + +* [MIT License](http://opensource.org/licenses/MIT) + ([LICENSE-MIT](LICENSE-MIT)) + +at your option. + +## Contributing + +We welcome all people who want to contribute. Please see the [contributing +instructions] for more information. + +[contributing instructions]: CONTRIBUTING.md + +Contributions in any form (issues, pull requests, etc.) to this project +must adhere to Rust's [Code of Conduct]. + +[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in `libc` by you, as defined in the Apache-2.0 license, shall be +dual licensed as above, without any additional terms or conditions. -## Adding an API - -Want to use an API which currently isn't bound in `libc`? It's quite easy to add -one! - -The internal structure of this crate is designed to minimize the number of -`#[cfg]` attributes in order to easily be able to add new items which apply -to all platforms in the future. As a result, the crate is organized -hierarchically based on platform. Each module has a number of `#[cfg]`'d -children, but only one is ever actually compiled. Each module then reexports all -the contents of its children. - -This means that for each platform that libc supports, the path from a -leaf module to the root will contain all bindings for the platform in question. -Consequently, this indicates where an API should be added! Adding an API at a -particular level in the hierarchy means that it is supported on all the child -platforms of that level. For example, when adding a Unix API it should be added -to `src/unix/mod.rs`, but when adding a Linux-only API it should be added to -`src/unix/notbsd/linux/mod.rs`. - -If you're not 100% sure at what level of the hierarchy an API should be added -at, fear not! This crate has CI support which tests any binding against all -platforms supported, so you'll see failures if an API is added at the wrong -level or has different signatures across platforms. - -With that in mind, the steps for adding a new API are: - -1. Determine where in the module hierarchy your API should be added. -2. Add the API. -3. Send a PR to this repo. -4. Wait for CI to pass, fixing errors. -5. Wait for a merge! - -### Test before you commit - -We have two automated tests running on [Travis](https://travis-ci.org/rust-lang/libc): - -1. [`libc-test`](https://github.com/alexcrichton/ctest) - - `cd libc-test && cargo test` - - Use the `skip_*()` functions in `build.rs` if you really need a workaround. -2. Style checker - - `rustc ci/style.rs && ./style src` - -### Releasing your change to crates.io - -Now that you've done the amazing job of landing your new API or your new -platform in this crate, the next step is to get that sweet, sweet usage from -crates.io! The only next step is to bump the version of libc and then publish -it. If you'd like to get a release out ASAP you can follow these steps: - -1. Update the version number in `Cargo.toml`, you'll just be bumping the patch - version number. -2. Run `cargo update` to regenerate the lockfile to encode your version bump in - the lock file. You may pull in some other updated dependencies, that's ok. -3. Send a PR to this repository. It should [look like this][example], but it'd - also be nice to fill out the description with a small rationale for the - release (any rationale is ok though!) -4. Once merged the release will be tagged and published by one of the libc crate - maintainers. - -[example]: https://github.com/rust-lang/libc/pull/583 - -## Platforms and Documentation - -The following platforms are currently tested and have documentation available: - -Tested: - * [`i686-pc-windows-msvc`](https://rust-lang.github.io/libc/i686-pc-windows-msvc/libc/) - * [`x86_64-pc-windows-msvc`](https://rust-lang.github.io/libc/x86_64-pc-windows-msvc/libc/) - (Windows) - * [`i686-pc-windows-gnu`](https://rust-lang.github.io/libc/i686-pc-windows-gnu/libc/) - * [`x86_64-pc-windows-gnu`](https://rust-lang.github.io/libc/x86_64-pc-windows-gnu/libc/) - * [`i686-apple-darwin`](https://rust-lang.github.io/libc/i686-apple-darwin/libc/) - * [`x86_64-apple-darwin`](https://rust-lang.github.io/libc/x86_64-apple-darwin/libc/) - (OSX) - * `i386-apple-ios` - * `x86_64-apple-ios` - * [`i686-unknown-linux-gnu`](https://rust-lang.github.io/libc/i686-unknown-linux-gnu/libc/) - * [`x86_64-unknown-linux-gnu`](https://rust-lang.github.io/libc/x86_64-unknown-linux-gnu/libc/) - (Linux) - * [`x86_64-unknown-linux-musl`](https://rust-lang.github.io/libc/x86_64-unknown-linux-musl/libc/) - (Linux MUSL) - * [`aarch64-unknown-linux-gnu`](https://rust-lang.github.io/libc/aarch64-unknown-linux-gnu/libc/) - (Linux) - * `aarch64-unknown-linux-musl` - (Linux MUSL) - * [`sparc64-unknown-linux-gnu`](https://rust-lang.github.io/libc/sparc64-unknown-linux-gnu/libc/) - (Linux) - * [`mips-unknown-linux-gnu`](https://rust-lang.github.io/libc/mips-unknown-linux-gnu/libc/) - * [`arm-unknown-linux-gnueabihf`](https://rust-lang.github.io/libc/arm-unknown-linux-gnueabihf/libc/) - * [`arm-linux-androideabi`](https://rust-lang.github.io/libc/arm-linux-androideabi/libc/) - (Android) - * [`x86_64-unknown-freebsd`](https://rust-lang.github.io/libc/x86_64-unknown-freebsd/libc/) - * [`x86_64-unknown-openbsd`](https://rust-lang.github.io/libc/x86_64-unknown-openbsd/libc/) - * [`x86_64-rumprun-netbsd`](https://rust-lang.github.io/libc/x86_64-unknown-netbsd/libc/) - -The following may be supported, but are not guaranteed to always work: - - * `i686-unknown-freebsd` - * [`x86_64-unknown-bitrig`](https://rust-lang.github.io/libc/x86_64-unknown-bitrig/libc/) - * [`x86_64-unknown-dragonfly`](https://rust-lang.github.io/libc/x86_64-unknown-dragonfly/libc/) - * `i686-unknown-haiku` - * `x86_64-unknown-haiku` - * [`x86_64-unknown-netbsd`](https://rust-lang.github.io/libc/x86_64-unknown-netbsd/libc/) - * [`x86_64-sun-solaris`](https://rust-lang.github.io/libc/x86_64-sun-solaris/libc/) +[Travis-CI]: https://travis-ci.com/rust-lang/libc +[Travis-CI Status]: https://travis-ci.com/rust-lang/libc.svg?branch=master +[Appveyor]: https://ci.appveyor.com/project/rust-lang-libs/libc +[Appveyor Status]: https://ci.appveyor.com/api/projects/status/github/rust-lang/libc?svg=true +[Cirrus-CI]: https://cirrus-ci.com/github/rust-lang/libc +[Cirrus-CI Status]: https://api.cirrus-ci.com/github/rust-lang/libc.svg +[crates.io]: https://crates.io/crates/libc +[Latest Version]: https://img.shields.io/crates/v/libc.svg +[Documentation]: https://docs.rs/libc/badge.svg +[docs.rs]: https://docs.rs/libc +[License]: https://img.shields.io/crates/l/libc.svg +[docs.master]: https://rust-lang.github.io/libc/#platform-specific-documentation |