Naersk

Build Rust projects with ease!

Setup
Usage

Setup

Using Flakes

$ nix flake init -t github:nix-community/naersk
$ nix flake lock

Alternatively, store this as flake.nix in your repository:

{
  inputs = {
    flake-utils.url = "github:numtide/flake-utils";
    naersk.url = "github:nix-community/naersk";
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  };

  outputs = { self, flake-utils, naersk, nixpkgs }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = (import nixpkgs) {
          inherit system;
        };

        naersk' = pkgs.callPackage naersk {};
        
      in rec {
        # For `nix build` & `nix run`:
        defaultPackage = naersk'.buildPackage {
          src = ./.;
        };

        # For `nix develop` (optional, can be skipped):
        devShell = pkgs.mkShell {
          nativeBuildInputs = with pkgs; [ rustc cargo ];
        };
      }
    );
}

This assumes flake.nix is created next to Cargo.toml & Cargo.lock - if that's not the case for you, adjust ./. in naersk'.buildPackage.

Note that Naersk by default ignores the rust-toolchain file, using whatever Rust compiler version is present in nixpkgs.

If you have a custom rust-toolchain file, you can make Naersk use it this way:

{
  inputs = {
    flake-utils.url = "github:numtide/flake-utils";
    naersk.url = "github:nix-community/naersk";
    
    nixpkgs-mozilla = {
      url = "github:mozilla/nixpkgs-mozilla";
      flake = false;
    };
  };

  outputs = { self, flake-utils, naersk, nixpkgs, nixpkgs-mozilla }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = (import nixpkgs) {
          inherit system;

          overlays = [
            (import nixpkgs-mozilla)
          ];
        };

        toolchain = (pkgs.rustChannelOf {
          rustToolchain = ./rust-toolchain;
          sha256 = "";
          #        ^ After you run `nix build`, replace this with the actual
          #          hash from the error message
        }).rust;

        naersk' = pkgs.callPackage naersk {
          cargo = toolchain;
          rustc = toolchain;
        };
        
      in rec {
        # For `nix build` & `nix run`:
        defaultPackage = naersk'.buildPackage {
          src = ./.;
        };

        # For `nix develop` (optional, can be skipped):
        devShell = pkgs.mkShell {
          nativeBuildInputs = [ toolchain ];
        };
      }
    );
}

Using Niv

$ niv init
$ niv add nix-community/naersk

... and then create default.nix with:

let
  pkgs = import <nixpkgs> {};
  sources = import ./nix/sources.nix;
  naersk = pkgs.callPackage sources.naersk {};
  
in
  naersk.buildPackage ./.

This assumes default.nix is created next to Cargo.toml & Cargo.lock - if that's not the case for you, adjust ./. in naersk.buildPackage.

Note that Naersk by default ignores the rust-toolchain file, using whatever Rust compiler version is present in nixpkgs.

If you have a custom rust-toolchain file, you can make Naersk use it this way:

$ niv add mozilla/nixpkgs-mozilla

... and then:

let
  sources = import ./nix/sources.nix;
  nixpkgs-mozilla = import sources.nixpkgs-mozilla;
  
  pkgs = import sources.nixpkgs {
    overlays = [
      nixpkgs-mozilla
    ];
  };
  
  toolchain = (pkgs.rustChannelOf {
    rustToolchain = ./rust-toolchain;
    sha256 = "";
    #        ^ After you run `nix-build`, replace this with the actual
    #          hash from the error message
  }).rust;
  
  naersk = pkgs.callPackage sources.naersk {
    cargo = toolchain;
    rustc = toolchain;
  };
  
in
  naersk.buildPackage ./.

Usage

Naersk provides a function called buildPackage that takes an attribute set describing your application's directory, its dependencies etc.; in general, the usage is:

naersk.buildPackage {
  # Assuming there's `Cargo.toml` right in this directory:
  src = ./.; 
  
  someOption = "yass";
  someOtherOption = false;
  CARGO_ENVIRONMENTAL_VARIABLE = "test";
}

Some of the options (described below) are used by Naersk to affect the building process, rest is passed-through into mkDerivation.

`buildPackage`'s parameters

Attribute	Description
`name`	The name of the derivation.
`version`	The version of the derivation.
`src`	Used by `naersk` as source input to the derivation. When `root` is not set, `src` is also used to discover the `Cargo.toml` and `Cargo.lock`.
`root`	Used by `naersk` to read the `Cargo.toml` and `Cargo.lock` files. May be different from `src`. When `src` is not set, `root` is (indirectly) used as `src`.
`gitAllRefs`	Whether to fetch all refs while fetching Git dependencies. Useful if the wanted revision isn't in the default branch. Requires Nix 2.4+. Default: `false`
`gitSubmodules`	Whether to fetch submodules while fetching Git dependencies. Requires Nix 2.4+. Default: `false`
`cargoBuild`	The command to use for the build. The argument must be a function modifying the default value. Default: `''cargo $cargo_options build $cargo_build_options >> $cargo_build_output_json''`
`cargoBuildOptions`	Options passed to cargo build, i.e. `cargo build <OPTS>`. These options can be accessed during the build through the environment variable `cargo_build_options`. Note: naersk relies on the `--out-dir out` option and the `--message-format` option. The `$cargo_message_format` variable is set based on the cargo version. Note: these values are not (shell) escaped, meaning that you can use environment variables but must be careful when introducing e.g. spaces. The argument must be a function modifying the default value. Default: `[ "$cargo_release" ''-j "$NIX_BUILD_CORES"'' "--message-format=$cargo_message_format" ]`
`remapPathPrefix`	When `true`, rustc remaps the (`/nix/store`) source paths to `/sources` to reduce the number of dependencies in the closure. Default: `true`
`cargoTestCommands`	The commands to run in the `checkPhase`. Do not forget to set `doCheck`. The argument must be a function modifying the default value. Default: `[ ''cargo $cargo_options test $cargo_test_options'' ]`
`cargoTestOptions`	Options passed to cargo test, i.e. `cargo test <OPTS>`. These options can be accessed during the build through the environment variable `cargo_test_options`. Note: these values are not (shell) escaped, meaning that you can use environment variables but must be careful when introducing e.g. spaces. The argument must be a function modifying the default value. Default: `[ "$cargo_release" ''-j "$NIX_BUILD_CORES"'' ]`
`nativeBuildInputs`	Extra `nativeBuildInputs` to all derivations. Default: `[]`
`buildInputs`	Extra `buildInputs` to all derivations. Default: `[]`
`cargoOptions`	Options passed to all cargo commands, i.e. `cargo <OPTS> ...`. These options can be accessed during the build through the environment variable `cargo_options`. Note: these values are not (shell) escaped, meaning that you can use environment variables but must be careful when introducing e.g. spaces. The argument must be a function modifying the default value. Default: `[ ]`
`doDoc`	When true, `cargo doc` is run and a new output `doc` is generated. Default: `false`
`cargoDocCommands`	The commands to run in the `docPhase`. Do not forget to set `doDoc`. The argument must be a function modifying the default value. Default: `[ ''cargo $cargo_options doc $cargo_doc_options'' ]`
`cargoDocOptions`	Options passed to cargo doc, i.e. `cargo doc <OPTS>`. These options can be accessed during the build through the environment variable `cargo_doc_options`. Note: these values are not (shell) escaped, meaning that you can use environment variables but must be careful when introducing e.g. spaces. The argument must be a function modifying the default value. Default: `[ "--offline" "$cargo_release" ''-j "$NIX_BUILD_CORES"'' ]`
`release`	When true, all cargo builds are run with `--release`. The environment variable `cargo_release` is set to `--release` iff this option is set. Default: `true`
`override`	An override for all derivations involved in the build. Default: `(x: x)`
`overrideMain`	An override for the top-level (last, main) derivation. If both `override` and `overrideMain` are specified, both will be applied to the top-level derivation. Default: `(x: x)`
`singleStep`	When true, no intermediary (dependency-only) build is run. Enabling `singleStep` greatly reduces the incrementality of the builds. Default: `false`
`targets`	The targets to build if the `Cargo.toml` is a virtual manifest.
`copyBins`	When true, the resulting binaries are copied to `$out/bin`. Note: this relies on cargo's `--message-format` argument, set in the default `cargoBuildOptions`. Default: `true`
`copyLibs`	When true, the resulting binaries are copied to `$out/lib`. Note: this relies on cargo's `--message-format` argument, set in the default `cargoBuildOptions`. Default: `false`
`copyBinsFilter`	A `jq` filter for selecting which build artifacts to release. This is run on cargo's `--message-format` JSON output. The value is written to the `cargo_bins_jq_filter` variable. Default: `''select(.reason == "compiler-artifact" and .executable != null and .profile.test == false)''`
`copyLibsFilter`	A `jq` filter for selecting which build artifacts to release. This is run on cargo's `--message-format` JSON output. The value is written to the `cargo_libs_jq_filter` variable. Default: `''select(.reason == "compiler-artifact" and ((.target.kind
`copyDocsToSeparateOutput`	When true, the documentation is generated in a different output, `doc`. Default: `true`
`doDocFail`	When true, the build fails if the documentation step fails; otherwise the failure is ignored. Default: `false`
`removeReferencesToSrcFromDocs`	When true, references to the nix store are removed from the generated documentation. Default: `true`
`compressTarget`	When true, the build output of intermediary builds is compressed with `Zstandard`. This reduces the size of closures. Default: `true`
`copyTarget`	When true, the `target/` directory is copied to `$out`. Default: `false`
`postInstall`	Optional hook to run after the compilation is done; inside this script, `$out/bin` contains compiled Rust binaries. Useful if your application needs e.g. custom environment variables, in which case you can simply run `wrapProgram $out/bin/your-app-name` in here. Default: `false`
`usePureFromTOML`	Whether to use the `fromTOML` built-in or not. When set to `false` the python package `remarshal` is used instead (in a derivation) and the JSON output is read with `builtins.fromJSON`. This is a workaround for old versions of Nix. May be used safely from Nix 2.3 onwards where all bugs in `builtins.fromTOML` seem to have been fixed. Default: `true`

Tips & Tricks

Using OpenSSL

If your application uses OpenSSL (making the build process fail), try:

naersk.buildPackage {
  # ...
  
  nativeBuildInputs = with pkgs; [ pkg-config ];
  buildInputs = with pkgs; [ openssl ];
}

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

nix-community / naersk

Programming Languages

Labels

Projects that are alternatives of or similar to naersk

Naersk

Setup

Using Flakes

Using Niv

Usage

`buildPackage`'s parameters

Tips & Tricks

Using OpenSSL

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

nix-community / naersk

Programming Languages

Labels

Projects that are alternatives of or similar to naersk

Naersk

Setup

Using Flakes

Using Niv

Usage

buildPackage's parameters

Tips & Tricks

Using OpenSSL

`buildPackage`'s parameters