diff options
author | figsoda <figsoda@pm.me> | 2021-10-27 09:24:19 -0400 |
---|---|---|
committer | figsoda <figsoda@pm.me> | 2021-10-27 09:24:19 -0400 |
commit | 62d502d7035d79165c8e4588dcae6ff35f296a2f (patch) | |
tree | 4835d03b74fbc315ca4fe7e487441c42e34826c8 /doc | |
parent | d7d45aadf296f2041dc4c0ca4052a662bef0c23e (diff) | |
download | nixpkgs-62d502d7035d79165c8e4588dcae6ff35f296a2f.tar nixpkgs-62d502d7035d79165c8e4588dcae6ff35f296a2f.tar.gz nixpkgs-62d502d7035d79165c8e4588dcae6ff35f296a2f.tar.bz2 nixpkgs-62d502d7035d79165c8e4588dcae6ff35f296a2f.tar.lz nixpkgs-62d502d7035d79165c8e4588dcae6ff35f296a2f.tar.xz nixpkgs-62d502d7035d79165c8e4588dcae6ff35f296a2f.tar.zst nixpkgs-62d502d7035d79165c8e4588dcae6ff35f296a2f.zip |
doc/rust: add documentation for feature options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/languages-frameworks/rust.section.md | 43 |
1 files changed, 36 insertions, 7 deletions
diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index 26eb9e26bd0..19369a5d3f1 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/doc/languages-frameworks/rust.section.md @@ -186,6 +186,33 @@ added. To find the correct hash, you can first use `lib.fakeSha256` or `lib.fakeHash` as a stub hash. Building the package (and thus the vendored dependencies) will then inform you of the correct hash. +### Cargo features {#cargo-features} + +You can disable default features using `buildNoDefaultFeatures`, and +extra features can be added with `buildFeatures`. + +If you want to use different features for check phase, you can use +`checkNoDefaultFeatures` and `checkFeatures`. They are only passed to +`cargo test` and not `cargo build`. If left unset, they default to +`buildNoDefaultFeatures` and `buildFeatures`. + +For example: + +```nix +rustPlatform.buildRustPackage rec { + pname = "myproject"; + version = "1.0.0"; + + buildNoDefaultFeatures = true; + buildFeatures = [ "color" "net" ]; + + # disable network features in tests + checkFeatures = [ "color" ]; + + # ... +} +``` + ### Cross compilation {#cross-compilation} By default, Rust packages are compiled for the host platform, just like any @@ -261,7 +288,7 @@ rustPlatform.buildRustPackage { Please note that the code will be compiled twice here: once in `release` mode for the `buildPhase`, and again in `debug` mode for the `checkPhase`. -Test flags, e.g., `--features xxx/yyy`, can be passed to `cargo test` via the +Test flags, e.g., `--package foo`, can be passed to `cargo test` via the `cargoTestFlags` attribute. Another attribute, called `checkFlags`, is used to pass arguments to the test @@ -421,18 +448,20 @@ you of the correct hash. * `cargoBuildHook`: use Cargo to build a crate. If the crate to be built is a crate in e.g. a Cargo workspace, the relative path to the crate to build can be set through the optional `buildAndTestSubdir` - environment variable. Additional Cargo build flags can be passed - through `cargoBuildFlags`. + environment variable. Features can be specified with + `cargoBuildNoDefaultFeatures` and `cargoBuildFeatures`. Additional + Cargo build flags can be passed through `cargoBuildFlags`. * `maturinBuildHook`: use [Maturin](https://github.com/PyO3/maturin) to build a Python wheel. Similar to `cargoBuildHook`, the optional variable `buildAndTestSubdir` can be used to build a crate in a Cargo workspace. Additional maturin flags can be passed through `maturinBuildFlags`. * `cargoCheckHook`: run tests using Cargo. The build type for checks - can be set using `cargoCheckType`. Additional flags can be passed to - the tests using `checkFlags` and `checkFlagsArray`. By default, - tests are run in parallel. This can be disabled by setting - `dontUseCargoParallelTests`. + can be set using `cargoCheckType`. Features can be specified with + `cargoCheckNoDefaultFeaatures` and `cargoCheckFeatures`. Additional + flags can be passed to the tests using `checkFlags` and + `checkFlagsArray`. By default, tests are run in parallel. This can + be disabled by setting `dontUseCargoParallelTests`. * `cargoInstallHook`: install binaries and static/shared libraries that were built using `cargoBuildHook`. |