diff options
author | John Ericson <John.Ericson@Obsidian.Systems> | 2017-12-13 16:14:47 -0500 |
---|---|---|
committer | John Ericson <John.Ericson@Obsidian.Systems> | 2017-12-13 16:14:47 -0500 |
commit | a0b1ebeee965c03e670af7bb6807e213997ebbb4 (patch) | |
tree | 449dfbb80891d79eea9ce021a1408fce9d73fc48 /doc | |
parent | 84fb59e0be30504e16ed428c34f1b321f6187fbe (diff) | |
parent | 105d9519c128a8954e5dd1616f71311ddde20cbc (diff) |
Merge remote-tracking branch 'upstream/staging' into binutils-wrapper
Diffstat (limited to 'doc')
-rw-r--r-- | doc/languages-frameworks/python.md | 2 | ||||
-rw-r--r-- | doc/languages-frameworks/rust.md | 163 | ||||
-rw-r--r-- | doc/package-notes.xml | 10 | ||||
-rw-r--r-- | doc/stdenv.xml | 15 |
4 files changed, 180 insertions, 10 deletions
diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.md index 9172d71221394..3700d2e57d476 100644 --- a/doc/languages-frameworks/python.md +++ b/doc/languages-frameworks/python.md @@ -134,7 +134,7 @@ with ```nix with import <nixpkgs> {}; -python35.withPackages (ps: [ps.numpy ps.toolz]) +(python35.withPackages (ps: [ps.numpy ps.toolz])).env ``` Executing `nix-shell` gives you again a Nix shell from which you can run Python. diff --git a/doc/languages-frameworks/rust.md b/doc/languages-frameworks/rust.md index bedda76a30665..aa6a7d654108a 100644 --- a/doc/languages-frameworks/rust.md +++ b/doc/languages-frameworks/rust.md @@ -20,7 +20,7 @@ For daily builds (beta and nightly) use either rustup from nixpkgs or use the [Rust nightlies overlay](#using-the-rust-nightlies-overlay). -## Packaging Rust applications +## Compiling Rust applications with Cargo Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`: @@ -56,6 +56,167 @@ checksum can be then take from the failed build. To install crates with nix there is also an experimental project called [nixcrates](https://github.com/fractalide/nixcrates). +## Compiling Rust crates using Nix instead of Cargo + +When run, `cargo build` produces a file called `Cargo.lock`, +containing pinned versions of all dependencies. Nixpkgs contains a +tool called `carnix` (`nix-env -iA nixos.carnix`), which can be used +to turn a `Cargo.lock` into a Nix expression. + +That Nix expression calls `rustc` directly (hence bypassing Cargo), +and can be used to compile a crate and all its dependencies. Here is +an example for a minimal `hello` crate: + + + $ cargo new hello + $ cd hello + $ cargo build + Compiling hello v0.1.0 (file:///tmp/hello) + Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs + $ carnix -o hello.nix --src ./. Cargo.lock --standalone + $ nix-build hello.nix + +Now, the file produced by the call to `carnix`, called `hello.nix`, looks like: + +``` +with import <nixpkgs> {}; +let kernel = buildPlatform.parsed.kernel.name; + # ... (content skipped) + hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate { + crateName = "hello"; + version = "0.1.0"; + authors = [ "Authorname <user@example.com>" ]; + src = ./.; + inherit dependencies buildDependencies features; + }; +in +rec { + hello_0_1_0 = hello_0_1_0_ rec {}; +} +``` + +In particular, note that the argument given as `--src` is copied +verbatim to the source. If we look at a more complicated +dependencies, for instance by adding a single line `libc="*"` to our +`Cargo.toml`, we first need to run `cargo build` to update the +`Cargo.lock`. Then, `carnix` needs to be run again, and produces the +following nix file: + +``` +with import <nixpkgs> {}; +let kernel = buildPlatform.parsed.kernel.name; + # ... (content skipped) + hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate { + crateName = "hello"; + version = "0.1.0"; + authors = [ "Jörg Thalheim <joerg@thalheim.io>" ]; + src = ./.; + inherit dependencies buildDependencies features; + }; + libc_0_2_34_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate { + crateName = "libc"; + version = "0.2.34"; + authors = [ "The Rust Project Developers" ]; + sha256 = "11jmqdxmv0ka10ay0l8nzx0nl7s2lc3dbrnh1mgbr2grzwdyxi2s"; + inherit dependencies buildDependencies features; + }; +in +rec { + hello_0_1_0 = hello_0_1_0_ rec { + dependencies = [ libc_0_2_34 ]; + }; + libc_0_2_34_features."default".from_hello_0_1_0__default = true; + libc_0_2_34 = libc_0_2_34_ rec { + features = mkFeatures libc_0_2_34_features; + }; + libc_0_2_34_features."use_std".self_default = hasDefault libc_0_2_34_features; +} +``` + +Here, the `libc` crate has no `src` attribute, so `buildRustCrate` +will fetch it from [crates.io](https://crates.io). A `sha256` +attribute is still needed for Nix purity. + +Some crates require external libraries. For crates from +[crates.io](https://crates.io), such libraries can be specified in +`defaultCrateOverrides` package in nixpkgs itself. + +Starting from that file, one can add more overrides, to add features +or build inputs by overriding the hello crate in a seperate file. + +``` +with import <nixpkgs> {}; +(import ./hello.nix).hello_0_1_0.override { + crateOverrides = defaultCrateOverrides // { + hello = attrs: { buildInputs = [ openssl ]; }; + }; +} +``` + +Here, `crateOverrides` is expected to be a attribute set, where the +key is the crate name without version number and the value a function. +The function gets all attributes passed to `buildRustCrate` as first +argument and returns a set that contains all attribute that should be +overwritten. + +For more complicated cases, such as when parts of the crate's +derivation depend on the the crate's version, the `attrs` argument of +the override above can be read, as in the following example, which +patches the derivation: + +``` +with import <nixpkgs> {}; +(import ./hello.nix).hello_0_1_0.override { + crateOverrides = defaultCrateOverrides // { + hello = attrs: lib.optionalAttrs (lib.versionAtLeast attrs.version "1.0") { + postPatch = '' + substituteInPlace lib/zoneinfo.rs \ + --replace "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo" + ''; + }; + }; +} +``` + +Another situation is when we want to override a nested +dependency. This actually works in the exact same way, since the +`crateOverrides` parameter is forwarded to the crate's +dependencies. For instance, to override the build inputs for crate +`libc` in the example above, where `libc` is a dependency of the main +crate, we could do: + +``` +with import <nixpkgs> {}; +(import hello.nix).hello_0_1_0.override { + crateOverrides = defaultCrateOverrides // { + libc = attrs: { buildInputs = []; }; + }; +} +``` + +Three more parameters can be overridden: + +- The version of rustc used to compile the crate: + + ``` + hello_0_1_0.override { rust = pkgs.rust; }; + ``` + +- Whether to build in release mode or debug mode (release mode by + default): + + ``` + hello_0_1_0.override { release = false; }; + ``` + +- Whether to print the commands sent to rustc when building + (equivalent to `--verbose` in cargo: + + ``` + hello_0_1_0.override { verbose = false; }; + ``` + + ## Using the Rust nightlies overlay Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope. diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 184bee089ae36..b657f5809db96 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -667,11 +667,13 @@ cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el <section xml:id="sec-weechat"> <title>Weechat</title> <para> -Weechat can currently be configured to include your choice of plugins. -To make use of this functionality, install an expression that overrides its configuration such as +Weechat can be configured to include your choice of plugins, reducing its +closure size from the default configuration which includes all available +plugins. To make use of this functionality, install an expression that +overrides its configuration such as <programlisting>weechat.override {configure = {availablePlugins, ...}: { - plugins = with availablePlugins; [ python perl ]; - } + plugins = with availablePlugins; [ python perl ]; + } }</programlisting> </para> <para> diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 544f89ae4bde0..91c659408c4bb 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -251,10 +251,17 @@ genericBuild <varlistentry> <term><varname>enableParallelBuilding</varname></term> - <listitem><para>If set, <literal>stdenv</literal> will pass specific - flags to <literal>make</literal> and other build tools to enable - parallel building with up to <literal>build-cores</literal> - workers.</para></listitem> + <listitem> + <para>If set to <literal>true</literal>, <literal>stdenv</literal> will + pass specific flags to <literal>make</literal> and other build tools to + enable parallel building with up to <literal>build-cores</literal> + workers.</para> + + <para>Unless set to <literal>false</literal>, some build systems with good + support for parallel building including <literal>cmake</literal>, + <literal>meson</literal>, and <literal>qmake</literal> will set it to + <literal>true</literal>.</para> + </listitem> </varlistentry> <varlistentry> |