From 13418a50fc55ba3ed5b7bd6ee204ec8fda9f4b2f Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Thu, 29 Oct 2015 11:54:12 -0700 Subject: [PATCH] Improve the README and switch URLs --- README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++------- src/lib.rs | 26 +++++++------- 2 files changed, 99 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index a1c8fdeb..88f62813 100644 --- a/README.md +++ b/README.md @@ -4,21 +4,94 @@ libc A Rust library with native bindings to the types and functions commonly found on various systems, including libc. -[![Build Status](https://travis-ci.org/alexcrichton/libc.svg?branch=master)](https://travis-ci.org/alexcrichton/libc) -[![Build status](https://ci.appveyor.com/api/projects/status/v0414slj8y8nga0p?svg=true)](https://ci.appveyor.com/project/alexcrichton/libc) +[![Build Status](https://travis-ci.org/rust-lang/libc.svg?branch=master)](https://travis-ci.org/rust-lang/libc) +[![Build status](https://ci.appveyor.com/api/projects/status/v0414slj8y8nga0p?svg=true)](https://ci.appveyor.com/project/rust-lang/libc) -[Documentation](http://alexcrichton.com/libc) +[Documentation][#Platforms-and-Documentation] -## Platform Support +## Usage + +First, add the following to your `Cargo.toml`: + +```toml +[dependencies] +libc = "1.0" +``` + +Next, add this to your crate root: + +```rust +extern crate libc; +``` + +## What is libc? + +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`). + +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. + +## Public API + +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. + +## 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. + +## Platforms and Documentation + +The following platforms are currently tested and have documentation available: Tested: - * `{i686,x86_64}-pc-windows-{msvc,gnu}` - * `{i686,x86_64,mips,aarch64}-unknown-linux-gnu` - * `x86_64-unknown-linux-musl` - * `arm-unknown-linux-gnueabihf` - * `arm-linux-androideabi` - * `{i686,x86_64}-apple-{darwin,ios}` + * [`i686-pc-windows-msvc`](https://doc.rust-lang.org/libc/i686-pc-windows-msvc/libc) + * [`x86_64-pc-windows-msvc`](https://doc.rust-lang.org/libc/x86_64-pc-windows-msvc/libc) + * [`i686-pc-windows-gnu`](https://doc.rust-lang.org/libc/i686-pc-windows-gnu/libc) + * [`x86_64-pc-windows-gnu`](https://doc.rust-lang.org/libc/x86_64-pc-windows-gnu/libc) + * [`i686-apple-darwin`](https://doc.rust-lang.org/libc/i686-apple-darwin/libc) + * [`x86_64-apple-darwin`](https://doc.rust-lang.org/libc/x86_64-apple-darwin/libc) + * [`i686-apple-ios`](https://doc.rust-lang.org/libc/i686-apple-ios/libc) + * [`x86_64-apple-ios`](https://doc.rust-lang.org/libc/x86_64-apple-ios/libc) + * [`i686-unknown-linux-gnu`](https://doc.rust-lang.org/libc/i686-unknown-linux-gnu/libc) + * [`x86_64-unknown-linux-gnu`](https://doc.rust-lang.org/libc/x86_64-unknown-linux-gnu/libc) + * [`x86_64-unknown-linux-musl`](https://doc.rust-lang.org/libc/x86_64-unknown-linux-musl/libc) + * [`aarch64-unknown-linux-gnu`](https://doc.rust-lang.org/libc/aarch64-unknown-linux-gnu/libc) + * [`mips-unknown-linux-gnu`](https://doc.rust-lang.org/libc/mips-unknown-linux-gnu/libc) + * [`arm-unknown-linux-gnueabihf`](https://doc.rust-lang.org/libc/arm-unknown-linux-gnueabihf/libc) + * [`arm-linux-androideabi`](https://doc.rust-lang.org/libc/arm-linux-androideabi/libc) -Untested: - * `{i686,x86_64}-unknown-freebsd` - * `x86_64-unknown-{bitrig,dragonfly,openbsd,netbsd}` +The following may be supported, but are not guaranteed to always work: + + * `x86_64-unknown-freebsd` + * `i686-unknown-freebsd` + * `x86_64-unknown-bitrig` + * `x86_64-unknown-dragonfly` + * `x86_64-unknown-openbsd` + * `x86_64-unknown-netbsd` diff --git a/src/lib.rs b/src/lib.rs index 84d89adc..67d7416a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,43 +17,43 @@ html_favicon_url = "https://doc.rust-lang.org/favicon.ico")] #![cfg_attr(all(target_os = "linux", target_arch = "x86_64"), doc( - html_root_url = "http://alexcrichton.com/libc/x86_64-unknown-linux-gnu" + html_root_url = "https://doc.rust-lang.org/libc/x86_64-unknown-linux-gnu" ))] #![cfg_attr(all(target_os = "linux", target_arch = "x86"), doc( - html_root_url = "http://alexcrichton.com/libc/i686-unknown-linux-gnu" + html_root_url = "https://doc.rust-lang.org/libc/i686-unknown-linux-gnu" ))] #![cfg_attr(all(target_os = "linux", target_arch = "arm"), doc( - html_root_url = "http://alexcrichton.com/libc/arm-unknown-linux-gnueabihf" + html_root_url = "https://doc.rust-lang.org/libc/arm-unknown-linux-gnueabihf" ))] #![cfg_attr(all(target_os = "linux", target_arch = "mips"), doc( - html_root_url = "http://alexcrichton.com/libc/mips-unknown-linux-gnu" + html_root_url = "https://doc.rust-lang.org/libc/mips-unknown-linux-gnu" ))] #![cfg_attr(all(target_os = "linux", target_arch = "aarch64"), doc( - html_root_url = "http://alexcrichton.com/libc/aarch64-unknown-linux-gnu" + html_root_url = "https://doc.rust-lang.org/libc/aarch64-unknown-linux-gnu" ))] #![cfg_attr(all(target_os = "linux", target_env = "musl"), doc( - html_root_url = "http://alexcrichton.com/libc/x86_64-unknown-linux-musl" + html_root_url = "https://doc.rust-lang.org/libc/x86_64-unknown-linux-musl" ))] #![cfg_attr(all(target_os = "macos", target_arch = "x86_64"), doc( - html_root_url = "http://alexcrichton.com/libc/x86_64-apple-darwin" + html_root_url = "https://doc.rust-lang.org/libc/x86_64-apple-darwin" ))] #![cfg_attr(all(target_os = "macos", target_arch = "x86"), doc( - html_root_url = "http://alexcrichton.com/libc/i686-apple-darwin" + html_root_url = "https://doc.rust-lang.org/libc/i686-apple-darwin" ))] #![cfg_attr(all(windows, target_arch = "x86_64", target_env = "gnu"), doc( - html_root_url = "http://alexcrichton.com/libc/x86_64-pc-windows-gnu" + html_root_url = "https://doc.rust-lang.org/libc/x86_64-pc-windows-gnu" ))] #![cfg_attr(all(windows, target_arch = "x86", target_env = "gnu"), doc( - html_root_url = "http://alexcrichton.com/libc/i686-pc-windows-gnu" + html_root_url = "https://doc.rust-lang.org/libc/i686-pc-windows-gnu" ))] #![cfg_attr(all(windows, target_arch = "x86_64", target_env = "msvc"), doc( - html_root_url = "http://alexcrichton.com/libc/x86_64-pc-windows-msvc" + html_root_url = "https://doc.rust-lang.org/libc/x86_64-pc-windows-msvc" ))] #![cfg_attr(all(windows, target_arch = "x86", target_env = "msvc"), doc( - html_root_url = "http://alexcrichton.com/libc/i686-pc-windows-msvc" + html_root_url = "https://doc.rust-lang.org/libc/i686-pc-windows-msvc" ))] #![cfg_attr(all(target_os = "android"), doc( - html_root_url = "http://alexcrichton.com/libc/arm-linux-androideabi" + html_root_url = "https://doc.rust-lang.org/libc/arm-linux-androideabi" ))] #[macro_use] mod macros;