diff options
-rw-r--r-- | doc/languages-frameworks/rust.section.md | 66 | ||||
-rw-r--r-- | nixos/doc/manual/release-notes/rl-2009.xml | 18 |
2 files changed, 81 insertions, 3 deletions
diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index cec3373cbee6..066633b53c43 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/doc/languages-frameworks/rust.section.md @@ -75,6 +75,72 @@ pkgs.rustPlatform.buildRustPackage { } ``` +### Running package tests + +When using `buildRustPackage`, the `checkPhase` is enabled by default and runs +`cargo test` on the package to build. To make sure that we don't compile the +sources twice and to actually test the artifacts that will be used after that, +the tests will be ran in the `release`-mode by default. + +However, in some cases the test-suite of a package doesn't work properly in the +`release` mode. In that case, the mode for `checkPhase` can be changed like this: + +```nix +rustPlatform.buildRustPackage { + /* ... */ + checkType = "debug"; +} +``` + +#### Tests relying on the structure of the `target/`-directory + +Some tests may rely on the structure of the `target/`-directory. Those tests +are likely to fail since we use `cargo --target` during build. This means that +the artifacts +[are stored in `target/<architecture>/release/`](https://doc.rust-lang.org/cargo/guide/build-cache.html) +rather than `target/release/`. + +This can only be circumvented by patching the affected tests accordingly. + +#### Disabling package-tests + +In some cases it's necessary to disable the tests (which can be done by declaring +`doCheck = false;`) which is fine in the following cases: + +* If no tests exist, the `checkPhase` should be explicitly disabled to skip + unnecessary build-steps to speed-up the build. + +* If tests are highly impure (e.g. due to heavy network usage), it's also fine + disable tests. + +There are obviously some other corner-cases where it's sensible to disable tests, +those aren't hard-rules, in the end this is a case-by-case decision. + +Please check however if it's possible to disable a problematic subset of the +test-suite and leave comment which explains why that's needed. + +### Building a package in the `debug` mode + +By default, `buildRustPackage` will use the `release`-mode for building. If a package +should be built in the `debug`-mode however, it can be configured like this: + +```nix +rustPlatform.buildRustPackage { + /* ... */ + buildType = "debug"; +} +``` + +Obviously, the `checkPhase` will be ran in `debug`-mode as well in this case. + +### Custom `build`/`install`-procedures + +Some packages may use custom scripts for building/installing, e.g. with a `Makefile`. +In that case it's recommended to always override the `build-`/`install-`/`checkPhase`. + +Otherwise, it may be possible that one of the internal steps fails because of the +modified directory structure of `target/`. + ## Compiling Rust crates using Nix instead of Cargo ### Simple operation diff --git a/nixos/doc/manual/release-notes/rl-2009.xml b/nixos/doc/manual/release-notes/rl-2009.xml index 744be530be75..afd3b5040982 100644 --- a/nixos/doc/manual/release-notes/rl-2009.xml +++ b/nixos/doc/manual/release-notes/rl-2009.xml @@ -354,9 +354,21 @@ php.override { </para> </listitem> <listitem> - <para> - The default output of <literal>buildGoPackage</literal> is now <literal>$out</literal> instead of <literal>$bin</literal>. - </para> + <para> + The default output of <literal>buildGoPackage</literal> is now <literal>$out</literal> instead of <literal>$bin</literal>. + </para> + </listitem> + <listitem> + <para> + Packages built using <literal>buildRustPackage</literal> now use the <literal>release</literal> + mode for the <literal>checkPhase</literal> by default. + </para> + <para> + Please note that <literal>rust</literal>-packages utilizing a custom build/install-procedure + (e.g. by using a <filename>Makefile</filename>) or test-suites that rely on the + structure in the <filename>target/</filename>-directory may break because of that. + For further information, please read the rust-section in the nixpkgs manual. + </para> </listitem> </itemizedlist> </section> |