diff options
-rw-r--r-- | doc/languages-frameworks/rust.section.md | 54 | ||||
-rw-r--r-- | nixos/doc/manual/release-notes/rl-2009.xml | 10 |
2 files changed, 32 insertions, 32 deletions
diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index 066633b53c43..7e5cff8ff607 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/doc/languages-frameworks/rust.section.md @@ -79,11 +79,12 @@ pkgs.rustPlatform.buildRustPackage { 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. +sources twice and to actually test the artifacts that will be used at runtime, +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: +`release` mode. For these situations, the mode for `checkPhase` can be changed like +so: ```nix rustPlatform.buildRustPackage { @@ -92,37 +93,37 @@ rustPlatform.buildRustPackage { } ``` -#### Tests relying on the structure of the `target/`-directory +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`. -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 +#### 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 because we use `cargo --target` during the 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/`. +[are stored in `target/<architecture>/release/`](https://doc.rust-lang.org/cargo/guide/build-cache.html), +rather than in `target/release/`. -This can only be circumvented by patching the affected tests accordingly. +This can only be worked around 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. +In some instances, it may be necessary to disable testing altogether (with `doCheck = false;`): -* If tests are highly impure (e.g. due to heavy network usage), it's also fine - disable tests. +* 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 network usage). -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. +There will obviously be some corner-cases not listed above where it's sensible to disable tests. +The above are just guidelines, and exceptions may be granted on a case-by-case basis. -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. +However, please check if it's possible to disable a problematic subset of the +test suite and leave a comment explaining your reasoning. -### Building a package in the `debug` mode +### Building a package in `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: +By default, `buildRustPackage` will use `release` mode for builds. If a package +should be built in `debug` mode, it can be configured like so: ```nix rustPlatform.buildRustPackage { @@ -131,15 +132,14 @@ rustPlatform.buildRustPackage { } ``` -Obviously, the `checkPhase` will be ran in `debug`-mode as well in this case. +In this scenario, the `checkPhase` will be ran in `debug` mode as well. ### 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`. +In these cases, it's recommended to override the `buildPhase`/`installPhase`/`checkPhase`. -Otherwise, it may be possible that one of the internal steps fails because of the -modified directory structure of `target/`. +Otherwise, some steps may fail because of the modified directory structure of `target/`. ## Compiling Rust crates using Nix instead of Cargo diff --git a/nixos/doc/manual/release-notes/rl-2009.xml b/nixos/doc/manual/release-notes/rl-2009.xml index afd3b5040982..04b0802ad91f 100644 --- a/nixos/doc/manual/release-notes/rl-2009.xml +++ b/nixos/doc/manual/release-notes/rl-2009.xml @@ -360,14 +360,14 @@ php.override { </listitem> <listitem> <para> - Packages built using <literal>buildRustPackage</literal> now use the <literal>release</literal> + Packages built using <literal>buildRustPackage</literal> now use <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. + Please note that Rust packages utilizing a custom build/install procedure + (e.g. by using a <filename>Makefile</filename>) or test suites that rely on the + structure of the <filename>target/</filename> directory may break due to those assumptions. + For further information, please read the Rust section in the Nixpkgs manual. </para> </listitem> </itemizedlist> |