2014-08-16 18:45:34 -07:00
|
|
|
# Rust bindings to *nix APIs
|
2014-08-07 13:02:28 -07:00
|
|
|
|
2020-10-12 08:06:18 -07:00
|
|
|
[](https://cirrus-ci.com/github/nix-rust/nix)
|
2021-08-13 23:10:42 -07:00
|
|
|
[](https://crates.io/crates/nix)
|
2016-07-10 01:27:13 -05:00
|
|
|
|
2016-12-03 14:36:47 +01:00
|
|
|
[Documentation (Releases)](https://docs.rs/nix/)
|
|
|
|
|
|
2016-07-10 01:27:13 -05:00
|
|
|
Nix seeks to provide friendly bindings to various *nix platform APIs (Linux, Darwin,
|
2015-02-20 16:24:42 -08:00
|
|
|
...). The goal is to not provide a 100% unified interface, but to unify
|
|
|
|
|
what can be while still providing platform specific APIs.
|
2014-08-16 18:45:34 -07:00
|
|
|
|
2016-07-10 01:27:13 -05:00
|
|
|
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.
|
2015-05-28 15:17:49 -07:00
|
|
|
|
|
|
|
|
|
2016-07-10 01:27:13 -05:00
|
|
|
As an example of what Nix provides, examine the differences between what is
|
|
|
|
|
exposed by libc and nix for the
|
2021-05-13 23:37:16 -05:00
|
|
|
[gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html) system
|
2016-07-10 01:27:13 -05:00
|
|
|
call:
|
2015-05-28 15:17:49 -07:00
|
|
|
|
2016-07-10 01:27:13 -05:00
|
|
|
```rust,ignore
|
|
|
|
|
// libc api (unsafe, requires handling return code/errno)
|
|
|
|
|
pub unsafe extern fn gethostname(name: *mut c_char, len: size_t) -> c_int;
|
|
|
|
|
|
2017-03-20 21:24:02 +01:00
|
|
|
// nix api (returns a nix::Result<CStr>)
|
|
|
|
|
pub fn gethostname<'a>(buffer: &'a mut [u8]) -> Result<&'a CStr>;
|
2016-07-10 01:27:13 -05:00
|
|
|
```
|
2014-08-07 13:02:28 -07:00
|
|
|
|
2017-04-15 12:12:33 -07:00
|
|
|
## Supported Platforms
|
|
|
|
|
|
2017-04-17 15:16:22 -07:00
|
|
|
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
|
2017-12-24 14:54:34 -05:00
|
|
|
limitations. Support for platforms is split into three tiers:
|
2017-04-15 12:12:33 -07:00
|
|
|
|
2017-04-17 15:16:22 -07:00
|
|
|
* 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.
|
2017-06-30 10:25:57 -07:00
|
|
|
* 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.
|
2017-04-15 12:12:33 -07:00
|
|
|
|
2019-03-10 08:23:52 -07:00
|
|
|
The following targets are supported by `nix`:
|
2017-04-15 12:12:33 -07:00
|
|
|
|
|
|
|
|
Tier 1:
|
|
|
|
|
* aarch64-unknown-linux-gnu
|
|
|
|
|
* arm-unknown-linux-gnueabi
|
2017-07-09 11:28:34 -07:00
|
|
|
* armv7-unknown-linux-gnueabihf
|
2017-10-14 17:57:59 -06:00
|
|
|
* i686-unknown-freebsd
|
2017-07-09 11:28:34 -07:00
|
|
|
* i686-unknown-linux-gnu
|
|
|
|
|
* i686-unknown-linux-musl
|
|
|
|
|
* mips-unknown-linux-gnu
|
2017-07-09 13:19:41 -07:00
|
|
|
* mips64-unknown-linux-gnuabi64
|
|
|
|
|
* mips64el-unknown-linux-gnuabi64
|
2017-07-09 11:28:34 -07:00
|
|
|
* mipsel-unknown-linux-gnu
|
2017-06-20 00:02:12 +02:00
|
|
|
* powerpc64le-unknown-linux-gnu
|
2017-07-09 11:28:34 -07:00
|
|
|
* x86_64-apple-darwin
|
|
|
|
|
* x86_64-unknown-freebsd
|
|
|
|
|
* x86_64-unknown-linux-gnu
|
2017-04-17 17:34:02 -07:00
|
|
|
* x86_64-unknown-linux-musl
|
2017-04-15 12:12:33 -07:00
|
|
|
|
|
|
|
|
Tier 2:
|
2017-07-04 10:40:23 -07:00
|
|
|
* aarch64-apple-ios
|
2017-07-04 01:07:21 +02:00
|
|
|
* aarch64-linux-android
|
|
|
|
|
* arm-linux-androideabi
|
2017-11-21 22:27:15 -08:00
|
|
|
* arm-unknown-linux-musleabi
|
2017-07-04 01:07:21 +02:00
|
|
|
* armv7-linux-androideabi
|
2017-11-21 22:27:15 -08:00
|
|
|
* i686-linux-android
|
2017-07-18 20:24:48 -07:00
|
|
|
* powerpc-unknown-linux-gnu
|
2017-07-09 12:13:32 -07:00
|
|
|
* s390x-unknown-linux-gnu
|
2017-07-04 10:40:23 -07:00
|
|
|
* x86_64-apple-ios
|
2017-11-21 22:27:15 -08:00
|
|
|
* x86_64-linux-android
|
2017-07-04 10:40:23 -07:00
|
|
|
* x86_64-unknown-netbsd
|
2017-02-24 11:09:38 -08:00
|
|
|
|
2020-05-19 22:48:11 -04:00
|
|
|
Tier 3:
|
2020-08-05 13:25:03 -04:00
|
|
|
* x86_64-fuchsia
|
2020-05-19 22:48:11 -04:00
|
|
|
* x86_64-unknown-redox
|
2021-02-13 09:30:39 +01:00
|
|
|
* x86_64-unknown-linux-gnux32
|
2020-05-19 22:48:11 -04:00
|
|
|
|
2015-02-20 16:24:42 -08:00
|
|
|
## Usage
|
|
|
|
|
|
2021-08-13 17:37:00 -06:00
|
|
|
`nix` requires Rust 1.46.0 or newer.
|
2019-03-10 08:23:52 -07:00
|
|
|
|
2020-05-31 15:17:16 -06:00
|
|
|
To use `nix`, add this to your `Cargo.toml`:
|
2015-02-20 16:24:42 -08:00
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[dependencies]
|
2021-07-09 08:07:41 -06:00
|
|
|
nix = "0.22.0"
|
2015-02-20 16:24:42 -08:00
|
|
|
```
|
|
|
|
|
|
2016-02-27 13:02:25 +01:00
|
|
|
## Contributing
|
|
|
|
|
|
2016-07-10 01:27:13 -05:00
|
|
|
Contributions are very welcome. Please See [CONTRIBUTING](CONTRIBUTING.md) for
|
|
|
|
|
additional details.
|
|
|
|
|
|
2017-06-03 12:17:19 -07:00
|
|
|
Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
|
|
|
|
|
discuss `nix` development.
|
|
|
|
|
|
2016-07-10 01:27:13 -05:00
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
Nix is licensed under the MIT license. See [LICENSE](LICENSE) for more details.
|
