JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions 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
`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:
In some instances, it may be necessary to disable testing altogether (with `doCheck = false;`):
* If no tests exist, the `checkPhase` should be explicitly disabled to skip
unnecessary build-steps to speed-up the build.
* 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).
* If tests are highly impure (e.g. due to heavy network usage), it's also fine
disable tests.
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.
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.
However, please check if it's possible to disable a problematic subset of the
test suite and leave a comment explaining your reasoning.
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 `debug` mode
### 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:
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

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

@ -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>