Skip to content

Commit 66d96b9

Browse files
borsbors
committed
Auto merge of #1254 - gnzlbg:dox_cleanup, r=gnzlbg
Clean up documentation generation
2 parents a8a817a + 597d612 commit 66d96b9

File tree

53 files changed

+892
-1075
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+892
-1075
lines changed

‎CONTRIBUTING.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
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
24+
`src/unix/notbsd/linux/mod.rs`.
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+
41+
We have two automated tests running on [Travis](https://travis-ci.org/rust-lang/libc):
42+
43+
1. [`libc-test`](https://github.com/alexcrichton/ctest)
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+
56+
1. Update the version number in `Cargo.toml`, you'll just be bumping the patch
57+
version number.
58+
2. Run `cargo update` to regenerate the lockfile to encode your version bump in
59+
the lock file. You may pull in some other updated dependencies, that's ok.
60+
3. Send a PR to this repository. It should [look like this][example], but it'd
61+
also be nice to fill out the description with a small rationale for the
62+
release (any rationale is ok though!)
63+
4. Once merged the release will be tagged and published by one of the libc crate
64+
maintainers.
65+
66+
[example]: https://github.com/rust-lang/libc/pull/583

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "libc"
3-
version = "0.2.48"
3+
version = "0.2.49"
44
authors = ["The Rust Project Developers"]
55
license = "MIT OR Apache-2.0"
66
readme = "README.md"

‎README.md‎

Lines changed: 72 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -1,195 +1,101 @@
1-
libc
2-
====
1+
[![Travis-CI Status]][Travis-CI] [![Appveyor Status]][Appveyor] [![Cirrus-CI Status]][Cirrus-CI] [![Latest Version]][crates.io] [![Documentation]][docs.rs] ![License]
32

4-
Raw FFI bindings to platform libraries like `libc`.
3+
libc - Raw FFI bindings to platforms' system libraries
4+
====
55

6-
[![Build Status](https://travis-ci.org/rust-lang/libc.svg?branch=master)](https://travis-ci.org/rust-lang/libc)
7-
[![Build status](https://ci.appveyor.com/api/projects/status/github/rust-lang/libc?svg=true)](https://ci.appveyor.com/project/rust-lang-libs/libc)
8-
[![Build Status](https://api.cirrus-ci.com/github/rust-lang/libc.svg)](https://cirrus-ci.com/github/rust-lang/libc)
9-
[![Latest version](https://img.shields.io/crates/v/libc.svg)](https://crates.io/crates/libc)
10-
[![Documentation](https://docs.rs/libc/badge.svg)](https://docs.rs/libc)
11-
[![License](https://img.shields.io/crates/l/libc.svg)]
6+
`libc` provides all of the definitions necessary to easily interoperate with C
7+
code (or "C-like" code) on each of the platforms that Rust supports. This
8+
includes type definitions (e.g. `c_int`), constants (e.g. `EINVAL`) as well as
9+
function headers (e.g. `malloc`).
1210

13-
**NOTE:** The minimum supported Rust version is **Rust 1.13.0** . APIs requiring
14-
newer Rust features are only available on newer Rust versions:
11+
This crate exports all underlying platform types, functions, and constants under
12+
the crate root, so all items are accessible as `libc::foo`. The types and values
13+
of all the exported APIs match the platform that libc is compiled for.
1514

16-
| Feature | Version |
17-
|----------------------|---------|
18-
| `union` | 1.19.0 |
19-
| `const mem::size_of` | 1.24.0 |
20-
| `repr(align)` | 1.25.0 |
21-
| `core::ffi::c_void` | 1.30.0 |
15+
More detailed information about the design of this library can be found in its
16+
[associated RFC][rfc].
2217

23-
To use `libc` at its fullest, Rust 1.30.0 is required.
18+
[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1291-promote-libc.md
2419

2520
## Usage
2621

27-
First, add the following to your `Cargo.toml`:
22+
Add the following to your `Cargo.toml`:
2823

2924
```toml
3025
[dependencies]
3126
libc = "0.2"
3227
```
3328

34-
Next, add this to your crate root:
29+
## Features
3530

36-
```rust
37-
extern crate libc;
38-
```
31+
* `use_std`: by default `libc` links to the standard library. Disable this
32+
feature remove this dependency and be able to use `libc` in `#![no_std]`
33+
crates.
3934

40-
Currently libc by default links to the standard library, but if you would
41-
instead like to use libc in a `#![no_std]` situation or crate you can request
42-
this via:
35+
* `extra_traits`: all `struct`s implemented in `libc` are `Copy` and `Clone`.
36+
This feature derives `Debug, `Eq`, `Hash`, and `PartialEq`.
4337

44-
```toml
45-
[dependencies]
46-
libc = { version = "0.2", default-features = false }
47-
```
38+
## Rust version support
4839

49-
By default libc uses private fields in structs in order to enforce a certain
50-
memory alignment on them. These structs can be hard to instantiate outside of
51-
libc. To make libc use `#[repr(align(x))]`, instead of the private fields,
52-
activate the *align* feature. This requires Rust 1.25 or newer:
40+
The minimum supported Rust toolchain version is **Rust 1.13.0** . APIs requiring
41+
newer Rust features are only available on newer Rust toolchains:
5342

54-
```toml
55-
[dependencies]
56-
libc = { version = "0.2", features = ["align"] }
57-
```
43+
| Feature | Version |
44+
|----------------------|---------|
45+
| `union` | 1.19.0 |
46+
| `const mem::size_of` | 1.24.0 |
47+
| `repr(align)` | 1.25.0 |
48+
| `extra_traits` | 1.25.0 |
49+
| `core::ffi::c_void` | 1.30.0 |
50+
| `repr(packed(N))` | 1.33.0 |
5851

59-
All structs implemented by the libc crate have the `Copy` and `Clone` traits
60-
implemented for them. The additional traits of `Debug, `Eq`, `Hash`, and
61-
`PartialEq` can be enabled with the *extra_traits* feature (requires Rust 1.25
62-
or newer):
52+
## Platform support
6353

64-
```toml
65-
[dependencies]
66-
libc = { version = "0.2", features = ["extra_traits"] }
67-
```
54+
[Platform-specific documentation of libc's master branch for all supported platforms][docs.master].
6855

69-
## What is libc?
56+
See [`ci/build.sh`](ci/build.sh) for the platforms on which `libc` is
57+
guaranteed to build for each Rust toolchain. The test-matrix at [Travis-CI],
58+
[Appveyor], and [Cirrus-CI] show the platforms in which `libc` tests are run.
7059

71-
The primary purpose of this crate is to provide all of the definitions necessary
72-
to easily interoperate with C code (or "C-like" code) on each of the platforms
73-
that Rust supports. This includes type definitions (e.g. `c_int`), constants
74-
(e.g. `EINVAL`) as well as function headers (e.g. `malloc`).
60+
<div class="platform_docs"></div>
7561

76-
This crate does not strive to have any form of compatibility across platforms,
77-
but rather it is simply a straight binding to the system libraries on the
78-
platform in question.
62+
## License
7963

80-
## Public API
64+
This project is licensed under either of
8165

82-
This crate exports all underlying platform types, functions, and constants under
83-
the crate root, so all items are accessible as `libc::foo`. The types and values
84-
of all the exported APIs match the platform that libc is compiled for.
66+
* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
67+
([LICENSE-APACHE](LICENSE-APACHE))
8568

86-
More detailed information about the design of this library can be found in its
87-
[associated RFC][rfc].
69+
* [MIT License](http://opensource.org/licenses/MIT)
70+
([LICENSE-MIT](LICENSE-MIT))
8871

89-
[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1291-promote-libc.md
72+
at your option.
73+
74+
## Contributing
75+
76+
We welcome all people who want to contribute. Please see the [contributing
77+
instructions] for more information.
78+
79+
[contributing instructions]: CONTRIBUTING.md
80+
81+
Contributions in any form (issues, pull requests, etc.) to this project
82+
must adhere to Rust's [Code of Conduct].
83+
84+
[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html
85+
86+
Unless you explicitly state otherwise, any contribution intentionally submitted
87+
for inclusion in `libc` by you, as defined in the Apache-2.0 license, shall be
88+
dual licensed as above, without any additional terms or conditions.
9089

91-
## Adding an API
92-
93-
Want to use an API which currently isn't bound in `libc`? It's quite easy to add
94-
one!
95-
96-
The internal structure of this crate is designed to minimize the number of
97-
`#[cfg]` attributes in order to easily be able to add new items which apply
98-
to all platforms in the future. As a result, the crate is organized
99-
hierarchically based on platform. Each module has a number of `#[cfg]`'d
100-
children, but only one is ever actually compiled. Each module then reexports all
101-
the contents of its children.
102-
103-
This means that for each platform that libc supports, the path from a
104-
leaf module to the root will contain all bindings for the platform in question.
105-
Consequently, this indicates where an API should be added! Adding an API at a
106-
particular level in the hierarchy means that it is supported on all the child
107-
platforms of that level. For example, when adding a Unix API it should be added
108-
to `src/unix/mod.rs`, but when adding a Linux-only API it should be added to
109-
`src/unix/notbsd/linux/mod.rs`.
110-
111-
If you're not 100% sure at what level of the hierarchy an API should be added
112-
at, fear not! This crate has CI support which tests any binding against all
113-
platforms supported, so you'll see failures if an API is added at the wrong
114-
level or has different signatures across platforms.
115-
116-
With that in mind, the steps for adding a new API are:
117-
118-
1. Determine where in the module hierarchy your API should be added.
119-
2. Add the API.
120-
3. Send a PR to this repo.
121-
4. Wait for CI to pass, fixing errors.
122-
5. Wait for a merge!
123-
124-
### Test before you commit
125-
126-
We have two automated tests running on [Travis](https://travis-ci.org/rust-lang/libc):
127-
128-
1. [`libc-test`](https://github.com/alexcrichton/ctest)
129-
- `cd libc-test && cargo test`
130-
- Use the `skip_*()` functions in `build.rs` if you really need a workaround.
131-
2. Style checker
132-
- `rustc ci/style.rs && ./style src`
133-
134-
### Releasing your change to crates.io
135-
136-
Now that you've done the amazing job of landing your new API or your new
137-
platform in this crate, the next step is to get that sweet, sweet usage from
138-
crates.io! The only next step is to bump the version of libc and then publish
139-
it. If you'd like to get a release out ASAP you can follow these steps:
140-
141-
1. Update the version number in `Cargo.toml`, you'll just be bumping the patch
142-
version number.
143-
2. Run `cargo update` to regenerate the lockfile to encode your version bump in
144-
the lock file. You may pull in some other updated dependencies, that's ok.
145-
3. Send a PR to this repository. It should [look like this][example], but it'd
146-
also be nice to fill out the description with a small rationale for the
147-
release (any rationale is ok though!)
148-
4. Once merged the release will be tagged and published by one of the libc crate
149-
maintainers.
150-
151-
[example]: https://github.com/rust-lang/libc/pull/583
152-
153-
## Platforms and Documentation
154-
155-
The following platforms are currently tested and have documentation available:
156-
157-
Tested:
158-
* [`i686-pc-windows-msvc`](https://rust-lang.github.io/libc/i686-pc-windows-msvc/libc/)
159-
* [`x86_64-pc-windows-msvc`](https://rust-lang.github.io/libc/x86_64-pc-windows-msvc/libc/)
160-
(Windows)
161-
* [`i686-pc-windows-gnu`](https://rust-lang.github.io/libc/i686-pc-windows-gnu/libc/)
162-
* [`x86_64-pc-windows-gnu`](https://rust-lang.github.io/libc/x86_64-pc-windows-gnu/libc/)
163-
* [`i686-apple-darwin`](https://rust-lang.github.io/libc/i686-apple-darwin/libc/)
164-
* [`x86_64-apple-darwin`](https://rust-lang.github.io/libc/x86_64-apple-darwin/libc/)
165-
(OSX)
166-
* `i386-apple-ios`
167-
* `x86_64-apple-ios`
168-
* [`i686-unknown-linux-gnu`](https://rust-lang.github.io/libc/i686-unknown-linux-gnu/libc/)
169-
* [`x86_64-unknown-linux-gnu`](https://rust-lang.github.io/libc/x86_64-unknown-linux-gnu/libc/)
170-
(Linux)
171-
* [`x86_64-unknown-linux-musl`](https://rust-lang.github.io/libc/x86_64-unknown-linux-musl/libc/)
172-
(Linux MUSL)
173-
* [`aarch64-unknown-linux-gnu`](https://rust-lang.github.io/libc/aarch64-unknown-linux-gnu/libc/)
174-
(Linux)
175-
* `aarch64-unknown-linux-musl`
176-
(Linux MUSL)
177-
* [`sparc64-unknown-linux-gnu`](https://rust-lang.github.io/libc/sparc64-unknown-linux-gnu/libc/)
178-
(Linux)
179-
* [`mips-unknown-linux-gnu`](https://rust-lang.github.io/libc/mips-unknown-linux-gnu/libc/)
180-
* [`arm-unknown-linux-gnueabihf`](https://rust-lang.github.io/libc/arm-unknown-linux-gnueabihf/libc/)
181-
* [`arm-linux-androideabi`](https://rust-lang.github.io/libc/arm-linux-androideabi/libc/)
182-
(Android)
183-
* [`x86_64-unknown-freebsd`](https://rust-lang.github.io/libc/x86_64-unknown-freebsd/libc/)
184-
* [`x86_64-unknown-openbsd`](https://rust-lang.github.io/libc/x86_64-unknown-openbsd/libc/)
185-
* [`x86_64-rumprun-netbsd`](https://rust-lang.github.io/libc/x86_64-unknown-netbsd/libc/)
186-
187-
The following may be supported, but are not guaranteed to always work:
188-
189-
* `i686-unknown-freebsd`
190-
* [`x86_64-unknown-bitrig`](https://rust-lang.github.io/libc/x86_64-unknown-bitrig/libc/)
191-
* [`x86_64-unknown-dragonfly`](https://rust-lang.github.io/libc/x86_64-unknown-dragonfly/libc/)
192-
* `i686-unknown-haiku`
193-
* `x86_64-unknown-haiku`
194-
* [`x86_64-unknown-netbsd`](https://rust-lang.github.io/libc/x86_64-unknown-netbsd/libc/)
195-
* [`x86_64-sun-solaris`](https://rust-lang.github.io/libc/x86_64-sun-solaris/libc/)
90+
[Travis-CI]: https://travis-ci.com/rust-lang/libc
91+
[Travis-CI Status]: https://travis-ci.com/rust-lang/libc.svg?branch=master
92+
[Appveyor]: https://ci.appveyor.com/project/rust-lang-libs/libc
93+
[Appveyor Status]: https://ci.appveyor.com/api/projects/status/github/rust-lang/libc?svg=true
94+
[Cirrus-CI]: https://cirrus-ci.com/github/rust-lang/libc
95+
[Cirrus-CI Status]: https://api.cirrus-ci.com/github/rust-lang/libc.svg
96+
[crates.io]: https://crates.io/crates/libc
97+
[Latest Version]: https://img.shields.io/crates/v/libc.svg
98+
[Documentation]: https://docs.rs/libc/badge.svg
99+
[docs.rs]: https://docs.rs/libc
100+
[License]: https://img.shields.io/crates/l/libc.svg
101+
[docs.master]: https://rust-lang.github.io/libc

‎ci/dox.sh‎

Lines changed: 27 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,43 @@
66

77
set -ex
88

9-
TARGETS=$(grep html_root_url src/lib.rs | sed 's/.*".*\/\(.*\)"/\1/'| sed 's/)//')
9+
TARGET_DOC_DIR=target/doc
10+
README=README.md
11+
PLATFORM_SUPPORT=platform-support.md
1012

11-
rm -rf target/doc
12-
mkdir -p target/doc
13+
rm -rf $TARGET_DOC_DIR
14+
mkdir -p $TARGET_DOC_DIR
1315

14-
cp ci/landing-page-head.html target/doc/index.html
16+
# List all targets that do currently build successfully:
17+
# shellcheck disable=SC1003
18+
grep '[\d|\w|-]* \\' ci/build.sh > targets
19+
sed -i.bak 's/ \\//g' targets
20+
grep '^[_a-zA-Z0-9-]*$' targets > tmp && mv tmp targets
1521

16-
for target in $TARGETS; do
22+
# Create a markdown list of supported platforms in $PLATFORM_SUPPORT
23+
rm $PLATFORM_SUPPORT || true
24+
25+
printf '### Platform-specific documentation\n' >> $PLATFORM_SUPPORT
26+
27+
while read -r target; do
1728
echo "documenting ${target}"
1829

19-
rustdoc -o "target/doc/${target}" --target "${target}" src/lib.rs --cfg cross_platform_docs \
20-
--crate-name libc
30+
#rustdoc -o "$TARGET_DOC_DIR/${target}" --target "${target}" src/lib.rs --cfg cross_platform_docs \
31+
# --crate-name libc
32+
33+
echo "* [${target}](${target}/libc/index.html)" >> $PLATFORM_SUPPORT
34+
done < targets
2135

22-
echo "<li><a href=\"/libc/${target}/libc/index.html\">${target}</a></li>" \
23-
>> target/doc/index.html
24-
done
36+
# Replace <div class="platform_support"></div> with the contents of $PLATFORM_SUPPORT
37+
cp $README $TARGET_DOC_DIR
38+
line=$(grep -n '<div class="platform_docs"></div>' $README | cut -d ":" -f 1)
2539

26-
cat ci/landing-page-footer.html >> target/doc/index.html
40+
set +x
41+
{ head -n "$((line-1))" $README; cat $PLATFORM_SUPPORT; tail -n "+$((line+1))" $README; } > $TARGET_DOC_DIR/$README
2742

2843
# If we're on travis, not a PR, and on the right branch, publish!
2944
if [ "$TRAVIS_PULL_REQUEST" = "false" ] && [ "$TRAVIS_BRANCH" = "master" ]; then
3045
pip install ghp_import --install-option="--prefix=$HOME/.local"
31-
"${HOME}/.local/bin/ghp-import" -n target/doc
46+
"${HOME}/.local/bin/ghp-import" -n $TARGET_DOC_DIR
3247
git push -qf "https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git" gh-pages
3348
fi

0 commit comments

Comments
 (0)