You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
110 lines
3.4 KiB
110 lines
3.4 KiB
# Rust bindings to *nix APIs
|
|
|
|
[](https://cirrus-ci.com/github/nix-rust/nix)
|
|
[](https://crates.io/crates/nix)
|
|
|
|
[Documentation (Releases)](https://docs.rs/nix/)
|
|
|
|
Nix seeks to provide friendly bindings to various *nix platform APIs (Linux, Darwin,
|
|
...). The goal is to not provide a 100% unified interface, but to unify
|
|
what can be while still providing platform specific APIs.
|
|
|
|
For many system APIs, Nix provides a safe alternative to the unsafe APIs
|
|
exposed by the [libc crate](https://github.com/rust-lang/libc). This is done by
|
|
wrapping the libc functionality with types/abstractions that enforce legal/safe
|
|
usage.
|
|
|
|
|
|
As an example of what Nix provides, examine the differences between what is
|
|
exposed by libc and nix for the
|
|
[gethostname](http://man7.org/linux/man-pages/man2/gethostname.2.html) system
|
|
call:
|
|
|
|
```rust,ignore
|
|
// libc api (unsafe, requires handling return code/errno)
|
|
pub unsafe extern fn gethostname(name: *mut c_char, len: size_t) -> c_int;
|
|
|
|
// nix api (returns a nix::Result<CStr>)
|
|
pub fn gethostname<'a>(buffer: &'a mut [u8]) -> Result<&'a CStr>;
|
|
```
|
|
|
|
## Supported Platforms
|
|
|
|
nix target support consists of two tiers. While nix attempts to support all
|
|
platforms supported by [libc](https://github.com/rust-lang/libc), only some
|
|
platforms are actively supported due to either technical or manpower
|
|
limitations. Support for platforms is split into three tiers:
|
|
|
|
* Tier 1 - Builds and tests for this target are run in CI. Failures of either
|
|
block the inclusion of new code.
|
|
* Tier 2 - Builds for this target are run in CI. Failures during the build
|
|
blocks the inclusion of new code. Tests may be run, but failures
|
|
in tests don't block the inclusion of new code.
|
|
* Tier 3 - Builds for this target are run in CI. Failures during the build
|
|
*do not* block the inclusion of new code. Testing may be run, but
|
|
failures in tests don't block the inclusion of new code.
|
|
|
|
The following targets are supported by `nix`:
|
|
|
|
Tier 1:
|
|
* aarch64-unknown-linux-gnu
|
|
* arm-unknown-linux-gnueabi
|
|
* armv7-unknown-linux-gnueabihf
|
|
* i686-unknown-freebsd
|
|
* i686-unknown-linux-gnu
|
|
* i686-unknown-linux-musl
|
|
* mips-unknown-linux-gnu
|
|
* mips64-unknown-linux-gnuabi64
|
|
* mips64el-unknown-linux-gnuabi64
|
|
* mipsel-unknown-linux-gnu
|
|
* powerpc64le-unknown-linux-gnu
|
|
* x86_64-apple-darwin
|
|
* x86_64-unknown-freebsd
|
|
* x86_64-unknown-linux-gnu
|
|
* x86_64-unknown-linux-musl
|
|
|
|
Tier 2:
|
|
* aarch64-apple-ios
|
|
* aarch64-linux-android
|
|
* arm-linux-androideabi
|
|
* arm-unknown-linux-musleabi
|
|
* armv7-apple-ios
|
|
* armv7-linux-androideabi
|
|
* armv7s-apple-ios
|
|
* i386-apple-ios
|
|
* i686-apple-darwin
|
|
* i686-linux-android
|
|
* powerpc-unknown-linux-gnu
|
|
* s390x-unknown-linux-gnu
|
|
* x86_64-apple-ios
|
|
* x86_64-linux-android
|
|
* x86_64-unknown-netbsd
|
|
|
|
Tier 3:
|
|
* x86_64-fuchsia
|
|
* x86_64-unknown-redox
|
|
* x86_64-unknown-linux-gnux32
|
|
|
|
## Usage
|
|
|
|
`nix` requires Rust 1.40.0 or newer.
|
|
|
|
To use `nix`, add this to your `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
nix = "0.20.0"
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are very welcome. Please See [CONTRIBUTING](CONTRIBUTING.md) for
|
|
additional details.
|
|
|
|
Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
|
|
discuss `nix` development.
|
|
|
|
## License
|
|
|
|
Nix is licensed under the MIT license. See [LICENSE](LICENSE) for more details.
|