public/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

rust: improve docs

Browse Source 
Co-authored-by: cole-h <cole.e.helbling@outlook.com>
Co-authored-by: asymmetric <lorenzo@mailbox.org>
This commit is contained in:
Maximilian Bosch 2020-05-31 20:47:32 +02:00
parent 6574ba1946
commit 59e8e7a129
No known key found for this signature in database
GPG Key ID: 091DBF4D1FC46B8E
2 changed files with 32 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
doc/languages-frameworks/rust.section.md
View File

@ -79,11 +79,12 @@ pkgs.rustPlatform.buildRustPackage {
When using `buildRustPackage`, the `checkPhase` is enabled by default and runs 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 `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, 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. 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 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 ```nix
rustPlatform.buildRustPackage { 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 #### Tests relying on the structure of the `target/` directory
are likely to fail since we use `cargo --target` during build. This means that
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 the artifacts
[are stored in `target/<architecture>/release/`](https://doc.rust-lang.org/cargo/guide/build-cache.html) [are stored in `target/<architecture>/release/`](https://doc.rust-lang.org/cargo/guide/build-cache.html),
rather than `target/release/`. 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 #### Disabling package-tests
In some cases it's necessary to disable the tests (which can be done by declaring In some instances, it may be necessary to disable testing altogether (with `doCheck = false;`):
`doCheck = false;`) which is fine in the following cases:
* If no tests exist, the `checkPhase` should be explicitly disabled to skip * If no tests exist -- the `checkPhase` should be explicitly disabled to skip
unnecessary build-steps to speed-up the build. unnecessary build steps to speed up the build.
* If tests are highly impure (e.g. due to network usage).
* If tests are highly impure (e.g. due to heavy network usage), it's also fine There will obviously be some corner-cases not listed above where it's sensible to disable tests.
disable tests. The above are just guidelines, and exceptions may be granted on a case-by-case basis.
There are obviously some other corner-cases where it's sensible to disable tests, However, please check if it's possible to disable a problematic subset of the
those aren't hard-rules, in the end this is a case-by-case decision. test suite and leave a comment explaining your reasoning.
Please check however if it's possible to disable a problematic subset of the ### Building a package in `debug` mode
test-suite and leave comment which explains why that's needed.
### Building a package in the `debug` mode By default, `buildRustPackage` will use `release` mode for builds. If a package
should be built in `debug` mode, it can be configured like so:
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 ```nix
rustPlatform.buildRustPackage { 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 ### Custom `build`/`install`-procedures
Some packages may use custom scripts for building/installing, e.g. with a `Makefile`. 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 Otherwise, some steps may fail because of the modified directory structure of `target/`.
modified directory structure of `target/`.
## Compiling Rust crates using Nix instead of Cargo ## Compiling Rust crates using Nix instead of Cargo

10
nixos/doc/manual/release-notes/rl-2009.xml
View File

@ -360,14 +360,14 @@ php.override {
</listitem> </listitem>
<listitem> <listitem>
<para> <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. mode for the <literal>checkPhase</literal> by default.
</para> </para>
<para> <para>
Please note that <literal>rust</literal>-packages utilizing a custom build/install-procedure 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 (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. 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. For further information, please read the Rust section in the Nixpkgs manual.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>