Merge pull request rust-lang#21 from alexcrichton/master

Implement RFC 1291 changes

Author: alexcrichton

.gitignore

@@ -1,2 +1,2 @@
-/target
-/Cargo.lock
+target
+Cargo.lock

.gitmodules

@@ -1,21 +1,48 @@
 language: rust
-sudo: false
-before_install:
-  - git submodule update --init --recursive
+sudo: required
+rust:
+  - 1.0.0
+  - beta
+  - nightly
+services:
+  - docker
 script:
-  - cargo build --verbose
-  - cargo doc --verbose
-after_success: |
-  [ $TRAVIS_BRANCH = master ] &&
-  [ $TRAVIS_PULL_REQUEST = false ] &&
-  echo '<meta http-equiv=refresh content=0;url=libc/index.html>' > target/doc/index.html &&
-  pip install ghp-import --user $USER &&
-  $HOME/.local/bin/ghp-import -n target/doc &&
-  git push -fq https://${TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages
-
+  - sh ci/run-travis.sh
+os:
+  - linux
+  - osx
 env:
+  matrix:
+    - ARCH=x86_64
+    - ARCH=i686
   global:
-    secure: MZGg+symX6/fcY7TsQ1LkJ28V/CUevNZgs3MiilgvnlgTjqn7BU7gbTvwhLdVZq04/EQ1hTeVzrFGpBfcCUVHYKmP2vooEFJJ+bDGEvyD8ChwCB4nV+NmxF5+NwCi3+Y+0pBgKbt2BasJ+MXkGJpRyFozis6loMWbXTzZzL9jjU=
+    secure: knGy4XLi5DVpZPcBaB8PiGA49NtZLcaWwLIPwSS68CwRJXOeeNPe/+xb7vWCWblJp3k7jK1HkJgHq+muWe1e+gUvXpmvASyuwpIBd4eQn55k4jfQlAVPCpxoIYANnv7bjfDMhuTEUDmvt9vI7BXDlLfi2VRrSrUd9obSwd3QU+ie5V88FTvPIe12zVmcvW8YVkKYsWRM4auIOU7CZSEW4nT+OE6RCpETE12u1qxUhsq03byCL7HQYGJs2S0RsqdyEZV+kAeJxA0ULNXlPs0FEagpqFbxfmZSSWzGp6K9juaRc03OBYiCcxrhYopuU1B1q4xMJk/2xWfPhoNJTU8yKW6fHstJz9Eb7MXH2y3UzDBAbDdwaNH4/aq0fN6O2U2lr7n09oF+pa9Gi5gyUYhKN19skaHMPF+Y7GCkqyCpR2oKTWTp+zSKycvgcsfl9zX2MvZG2NCgLPqRPaCEg/Psa2HvnM4/LgZw5ViDHJDVvNofzKx+2zzUlpsrkXaVDeRqUYVnO/LLiLl1cVT0QDHH1DHLXFY8G7CLfQYA64Np0LURartCmoamC86FavkSPTmnUL7i3RBMJnOUy2Uzf/SzbdRq3Sfp5tAV/miGzWaJFs81wuDKTWq5bnSGNVR18Wori6K8BboRYLmxMpSgQJ/8AnvnXETKwoP2lajJr1A4oPI=
+matrix:
+  include:
+    - os: linux
+      env: TARGET=arm-linux-androideabi
+      rust: nightly
+    - os: linux
+      env: TARGET=x86_64-unknown-linux-musl
+      rust: nightly
+    - os: linux
+      env: TARGET=arm-unknown-linux-gnueabihf
+      rust: nightly
+    - os: linux
+      env: TARGET=mips-unknown-linux-gnu
+      rust: nightly
+    - os: linux
+      env: TARGET=aarch64-unknown-linux-gnu
+      rust: nightly
+    - os: osx
+      env: TARGET=i386-apple-ios
+      rust: nightly-2015-09-08
+    - os: osx
+      env: TARGET=x86_64-apple-ios
+      rust: nightly-2015-09-08
 notifications:
   email:
     on_success: never
+branches:
+  only:
+    - master

.travis.yml

@@ -12,12 +12,6 @@ description = """
 A library for types and bindings to native C functions often found in libc or
 other common platform libraries.
 """
-include = ["Cargo.toml", "rust/src/liblibc/*"]
 
 [features]
-default = ["cargo-build"]
-cargo-build = []
-
-[lib]
-name = "libc"
-path = "rust/src/liblibc/lib.rs"
+default = []

Cargo.toml

@@ -5,21 +5,112 @@ A Rust library with native bindings to the types and functions commonly found on
 various systems, including 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/alexcrichton/libc)
 
-[Documentation](http://doc.rust-lang.org/libc)
+[Documentation](#platforms-and-documentation)
 
 ## Usage
 
-Add this to your `Cargo.toml`:
+First, add the following to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-
-libc = "0.1"
+libc = "1.0"
 ```
 
-and this to your crate root:
+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.
+
+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
+
+## 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!
+
+## Platforms and Documentation
+
+The following platforms are currently tested and have documentation available:
+
+Tested:
+  * [`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)
+    (Windows)
+  * [`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)
+    (OSX)
+  * [`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)
+    (iOS)
+  * [`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)
+    (Linux)
+  * [`x86_64-unknown-linux-musl`](https://doc.rust-lang.org/libc/x86_64-unknown-linux-musl/libc)
+    (Linux MUSL)
+  * [`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)
+    (Android)
+
+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`

README.md

@@ -0,0 +1,25 @@
+environment:
+  matrix:
+  - TARGET: x86_64-pc-windows-gnu
+    MSYS2_BITS: 64
+  - TARGET: i686-pc-windows-gnu
+    MSYS2_BITS: 32
+  - TARGET: x86_64-pc-windows-msvc
+  - TARGET: i686-pc-windows-msvc
+install:
+  - ps: Start-FileDownload "https://static.rust-lang.org/dist/rust-nightly-${env:TARGET}.exe"
+  - rust-nightly-%TARGET%.exe /VERYSILENT /NORESTART /DIR="C:\Program Files (x86)\Rust"
+  - SET PATH=%PATH%;C:\Program Files (x86)\Rust\bin
+  - if defined MSYS2_BITS set PATH=%PATH%;C:\msys64\mingw%MSYS2_BITS%\bin
+  - rustc -V
+  - cargo -V
+
+build: false
+
+test_script:
+  - cargo test
+  - cargo run --manifest-path libc-test/Cargo.toml
+
+branches:
+  only:
+    - master

appveyor.yml

@@ -0,0 +1,68 @@
+The goal of the libc crate is to have CI running everywhere to have the
+strongest guarantees about the definitions that this library contains, and as a
+result the CI is pretty complicated and also pretty large! Hopefully this can
+serve as a guide through the sea of scripts in this directory and elsewhere in
+this project.
+
+# Files
+
+First up, let's talk about the files in this directory:
+
+* `msys2.ps1` - a PowerShell script which is used to install MSYS2 on the
+  AppVeyor bots. As of this writing MSYS2 isn't installed by default, and this
+  script will install the right version/arch of msys2 in preparation of using
+  the contained C compiler to compile C shims.
+
+* `run-travis.sh` - a shell script run by all Travis builders, this is
+  responsible for setting up the rest of the environment such as installing new
+  packages, downloading Rust target libraries, etc.
+
+* `run.sh` - the actual script which runs tests for a particular architecture.
+  Called from the `run-travis.sh` script this will run all tests for the target
+  specified.
+
+* `cargo-config` - Cargo configuration of linkers to use copied into place by
+  the `run-travis.sh` script before builds are run.
+
+* `dox.sh` - script called from `run-travis.sh` on only the linux 64-bit nightly
+  Travis bots to build documentation for this crate.
+
+* `landing-page-*.html` - used by `dox.sh` to generate a landing page for all
+  architectures' documentation.
+
+# CI Systems
+
+Currently this repository leverages a combination of Travis CI and AppVeyor for
+running tests. The triples tested are:
+
+* AppVeyor
+  * `{i686,x86_64}-pc-windows-{msvc,gnu}`
+* Travis
+  *  `{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}`
+
+The Windows triples are all pretty standard, they just set up their environment
+then run tests, no need for downloading any extra target libs (we just download
+the right installer). The Intel Linux/OSX builds are similar in that we just
+download the right target libs and run tests. Note that the Intel Linux/OSX
+builds are run on stable/beta/nightly, but are the only ones that do so.
+
+The remaining architectures look like:
+
+* Android runs in a [docker image][android-docker] with an emulator, the NDK,
+  and the SDK already set up. The entire build happens within the docker image.
+* The MIPS, ARM, and AArch64 builds all use QEMU to run the generated binary to
+  actually verify the tests pass.
+* The MUSL build just has to download a MUSL compiler and target libraries and
+  then otherwise runs tests normally.
+* iOS builds need an extra linker flag currently, but beyond that they're built
+  as standard as everything else.
+
+[android-docker]: https://github.com/rust-lang/rust-buildbot/blob/master/slaves/android/Dockerfile
+
+Hopefully that's at least somewhat of an introduction to everything going on
+here, and feel free to ping @alexcrichton with questions!
+

ci/README.md

@@ -0,0 +1,38 @@
+# A vagrant configuration file for running tests on BSD-like machines
+#
+# Note that this was originally intended to later be used to run tests on
+# Travis, but it didn't work out. Regardless this has stuck around! You can run
+# tests in FreeBSD via:
+#
+#     git clone https://github.com/alexcrichton/libc
+#     cd libc/ci
+#     vagrant up freebsd
+#     vagrant ssh freebsd
+#     ...
+#     cd /vagrant/libc-test
+#     cargo run
+#
+# And "that's it"! You look up instructions on Vagrant's website for how to
+# install vagrant.
+
+Vagrant.configure(2) do |config|
+  # For a complete reference, please see the online documentation at
+  # https://docs.vagrantup.com.
+
+  config.vm.synced_folder "..", "/vagrant"
+
+  config.vm.define :freebsd do |bsd|
+    bsd.vm.box = "arkadi/freebsd-10.1-amd64"
+    bsd.vm.provision :shell, inline: 'yes | sudo pkg install rust cargo'
+    bsd.vm.provider "virtualbox" do |vb|
+      vb.memory = "2048"
+    end
+  end
+
+  config.vm.define :openbsd do |bsd|
+    bsd.vm.box = "bodgit/openbsd-5.7-amd64"
+    bsd.vm.provider "virtualbox" do |vb|
+      vb.memory = "2048"
+    end
+  end
+end

ci/Vagrantfile

@@ -0,0 +1,13 @@
+# Configuration of which linkers to call on Travis for various architectures
+
+[target.arm-linux-androideabi]
+linker = "arm-linux-androideabi-gcc"
+
+[target.arm-unknown-linux-gnueabihf]
+linker = "arm-linux-gnueabihf-gcc-4.7"
+
+[target.mips-unknown-linux-gnu]
+linker = "mips-linux-gnu-gcc"
+
+[target.aarch64-unknown-linux-gnu]
+linker = "aarch64-linux-gnu-gcc"

ci/cargo-config

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# Builds documentation for all target triples that we have a registered URL for
+# in liblibc. This scrapes the list of triples to document from `src/lib.rs`
+# which has a bunch of `html_root_url` directives we pick up.
+
+set -e
+
+TARGETS=`grep html_root_url src/lib.rs | sed 's/.*".*\/\(.*\)"/\1/'`
+
+rm -rf target/doc
+mkdir -p target/doc
+
+cp ci/landing-page-head.html target/doc/index.html
+
+for target in $TARGETS; do
+  echo documenting $target
+
+  rustdoc -o target/doc/$target --target $target src/lib.rs --cfg dox \
+    --crate-name libc
+
+  echo "<li><a href="$target/libc/index.html">$target</a></li>" \
+    >> target/doc/index.html
+done
+
+cat ci/landing-page-footer.html >> target/doc/index.html
+
+# If we're on travis, not a PR, and on the right branch, publish!
+if [ "$TRAVIS_PULL_REQUEST" = "false" ] && [ "$TRAVIS_BRANCH" = "master" ]; then
+  pip install ghp-import --user $USER
+  $HOME/.local/bin/ghp-import -n target/doc
+  git push -qf https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages
+fi

ci/dox.sh

@@ -0,0 +1,7 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+  </head>
+  <body>
+    <ul>

ci/landing-page-footer.html

@@ -0,0 +1,4 @@
+    </ul>
+  </body>
+</html>
+