mkLib :: pkgs -> set
Creates a lib
instance bound to the specified (and instantiated) pkgs
set.
This is a convenience escape hatch in case you want to use your own custom
instantiation of nixpkgs with the overlays you may need.
mkLib (import inputs.nixpkgs { system = "armv7l-linux"; })
Note that if you wish to override a particular package without having to overlay
it across all of nixpkgs, consider using overrideScope'
:
(mkLib pkgs).overrideScope' (final: prev: {
cargo-tarpaulin = myCustomCargoTarpaulinVersion;
})
To overlay an entire rust toolchain (e.g. cargo
, rustc
, clippy
, rustfmt
,
etc.) consider using overrideToolchain
.
appendCrateRegistries :: [registry mapping] -> new lib
Creates a new lib
instance which will make additional registries available for
use when downloading crate sources. Each entry can be defined using:
registryFromDownloadUrl
: if you know the exactdl
URL as defined in the registry'sconfig.json
fileregistryFromGitIndex
: if you would like the download URL to be inferred from the index's source directly.
See the documentation on each function for more specifics.
newLib = lib.appendCrateRegistries [
(lib.registryFromDownloadUrl {
indexUrl = "https://github.com/rust-lang/crates.io-index";
dl = "https://crates.io/api/v1/crates";
})
# Or, alternatively
(lib.registryFromGitIndex {
indexUrl = "https://github.com/Hirevo/alexandrie-index";
rev = "90df25daf291d402d1ded8c32c23d5e1498c6725";
})
];
buildDepsOnly :: set -> drv
Create a derivation which will only build all dependencies of a cargo workspace.
Useful for splitting up cargo projects into two derivations: one which only builds dependencies and needs to be rebuilt when a Cargo.lock file changes, and another which inherits the cargo artifacts from the first and (quickly) builds just the application itself.
The exact cargo commands being run (or the arguments passed into it) can be
easily updated to suit your needs. By default all artifacts from running cargo {check,build,test}
will be cached.
In addition to all default and overridden values being set as documented below,
all derivation attributes are delegated to mkCargoDerivation
, and can be used
to influence its behavior.
cargoArtifacts
: set tonull
since this is our entry point for generating cargo artifactsdoInstallCargoArtifacts
: set totrue
pnameSuffix
: set to"-deps"
src
: set to the result ofmkDummySrc
after applying the arguments set. This ensures that we do not need to rebuild the cargo artifacts derivation whenever the application source changes.
buildPhaseCargoCommand
: A command to run during the derivation's build phase. Pre and post build hooks will automatically be run.- Default value:
"${cargoCheckCommand} ${cargoExtraArgs}\n${cargoBuildCommand} ${cargoExtraArgs}"
- Default value:
cargoBuildCommand
: A cargo (build) invocation to run during the derivation's build phase- Default value:
"cargo build --profile release"
CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
- Default value:
cargoCheckCommand
: A cargo (check) invocation to run during the derivation's build phase (in order to cache additional artifacts)- Default value:
"cargo check --profile release --all-targets"
CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
- Default value:
cargoCheckExtraArgs
: additional flags to be passed in thecargoCheckCommand
invocation- Default value:
"--all-targets"
- Default value:
cargoExtraArgs
: additional flags to be passed in the cargo invocation (e.g. enabling specific features)- Default value:
""
- Default value:
cargoTestCommand
: A cargo invocation to run during the derivation's check phase- Default value:
"cargo test --profile release"
CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
- Default value:
cargoTestExtraArgs
: additional flags to be passed in thecargoTestCommand
invocation (e.g. enabling specific tests)- Default value:
""
- Default value:
cargoVendorDir
: A path (or derivation) of vendored cargo sources which can be consumed without network access. Directory structure should basically follow the output ofcargo vendor
.- Default value: the result of
vendorCargoDeps
after applying the arguments set (with the respective default values)
- Default value: the result of
checkPhaseCargoCommand
: A command to run during the derivation's check phase. Pre and post check hooks will automatically be run.- Default value:
"${cargoTestCommand} ${cargoExtraArgs}"
- Default value:
doCheck
: whether the derivation's check phase should be run- Default value:
true
- Default value:
dummySrc
: the "dummy" source to use when building this derivation. Automatically derived if not passed in- Default value:
mkDummySrc args.src
- Default value:
pname
: package name of the derivation- Default value: inherited from calling
crateNameFromCargoToml
- Default value: inherited from calling
version
: version of the derivation- Default value: inherited from calling
crateNameFromCargoToml
- Default value: inherited from calling
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoBuildCommand
cargoCheckCommand
cargoCheckExtraArgs
cargoExtraArgs
cargoTestCommand
cargoTestExtraArgs
dummySrc
buildPackage :: set -> drv
A(n opinionated) version of mkCargoDerivation
which will install to the output
any binaries which were built by cargo in this invocation. All options
understood by mkCargoDerivation
apply here as well, with the only difference
being some additional book keeping necessary to log cargo's results and
subsequently install from that log.
buildPhaseCargoCommand
: A command to run during the derivation's build phase. Pre and post build hooks will automatically be run.- Default value:
cargoBuildCommand
will be invoked along withcargoExtraArgs
passed in, except cargo's build steps will also be captured and written to a log so that it can be used to find the build binaries. - Note that the default install hook assumes that the build phase will create
a log of cargo's build results. If you wish to customize this command
completely, make sure that cargo is run with
--message-format json-render-diagnostics
and the standard output captured and saved to a file. ThecargoBuildLog
shell variable should point to this log.
- Default value:
cargoArtifacts
: A path (or derivation) which contains an existing cargotarget
directory, which will be reused at the start of the derivation. Useful for caching incremental cargo builds.- Default value: the result of
buildDepsOnly
after applying the arguments set (with the respective default values).installCargoArtifactsMode
will be set to"use-zstd"
if not specified.
- Default value: the result of
cargoBuildCommand
: A cargo invocation to run during the derivation's build phase- Default value:
"cargo build --profile release"
CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
- Default value:
cargoExtraArgs
: additional flags to be passed in the cargo invocation (e.g. enabling specific features)- Default value:
""
- Default value:
cargoTestCommand
: A cargo invocation to run during the derivation's check phase- Default value:
"cargo test --profile release"
CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
- Default value:
cargoTestExtraArgs
: additional flags to be passed in thecargoTestCommand
invocation (e.g. enabling specific tests)- Default value:
""
- Default value:
doCheck
: whether the derivation's check phase should be run- Default value:
true
- Default value:
doInstallCargoArtifacts
: controls whether cargo'starget
directory should be copied as an output- Default value:
false
- Default value:
installPhaseCommand
: the command(s) which are expected to install the derivation's outputs.- Default value: will look for a cargo build log and install all binary targets listed there
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoBuildCommand
cargoExtraArgs
cargoTestCommand
cargoTestExtraArgs
The following hooks are automatically added as native build inputs:
installFromCargoBuildLogHook
jq
removeReferencesTo
removeReferencesToVendoredSourcesHook
cargoAudit :: set -> drv
Create a derivation which will run a cargo audit
invocation in a cargo
workspace.
Except where noted below, all derivation attributes are delegated to
mkCargoDerivation
, and can be used to influence its behavior.
buildPhaseCargoCommand
will be set to runcargo audit -n -d ${advisory-db}
in the workspace.cargoArtifacts
will be set tonull
as they are not neededcargoVendorDir
will be set tonull
as it is not neededdoInstallCargoArtifacts
is disabledpnameSuffix
will be set to"-audit"
src
will be filtered to only keepCargo.lock
files
advisory-db
: A path (or derivation) which contains the advisory database- It is possible to track the advisory database as a flake input and avoid having to manually update hashes or specific revisions to check out
src
: The project source to audit, it must contain aCargo.lock
file- Note that the source will internally be filtered to omit any files besides
Cargo.lock
. This avoids having to audit the project again until either the advisory database or the dependencies change.
- Note that the source will internally be filtered to omit any files besides
cargoAuditExtraArgs
: additional flags to be passed in the cargo-audit invocation- Default value:
""
- Default value:
cargoExtraArgs
: additional flags to be passed in the cargo invocation- Default value:
""
- Default value:
pname
: the name of the derivation; will not be introspected from aCargo.toml
file- Default value:
"crate"
- Default value:
version
: the version of the derivation, will not be introspected from aCargo.toml
file- Default value:
"0.0.0"
- Default value:
The cargo-audit
package is automatically appended as a native build input to any
other nativeBuildInputs
specified by the caller.
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoAuditExtraArgs
cargoExtraArgs
cargoBuild :: set -> drv
Create a derivation which will run a cargo build
invocation in a cargo
workspace. Consider using buildPackage
if all you need is to build the
workspace and install the resulting application binaries.
Except where noted below, all derivation attributes are delegated to
mkCargoDerivation
, and can be used to influence its behavior.
buildPhaseCargoCommand
will be set to runcargo build --profile release
for the workspace.CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
pnameSuffix
will be set to"-build"
cargoArtifacts
: A path (or derivation) which contains an existing cargotarget
directory, which will be reused at the start of the derivation. Useful for caching incremental cargo builds.- This can be prepared via
buildDepsOnly
- Alternatively, any cargo-based derivation which was built with
doInstallCargoArtifacts = true
will work as well
- This can be prepared via
cargoExtraArgs
: additional flags to be passed in the cargo invocation (e.g. enabling specific features)- Default value:
""
- Default value:
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoExtraArgs
cargoClippy :: set -> drv
Create a derivation which will run a cargo clippy
invocation in a cargo
workspace.
Except where noted below, all derivation attributes are delegated to
mkCargoDerivation
, and can be used to influence its behavior.
buildPhaseCargoCommand
will be set to runcargo clippy --profile release
for the workspace.CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
pnameSuffix
will be set to"-clippy"
cargoArtifacts
: A path (or derivation) which contains an existing cargotarget
directory, which will be reused at the start of the derivation. Useful for caching incremental cargo builds.- This can be prepared via
buildDepsOnly
- Alternatively, any cargo-based derivation which was built with
doInstallCargoArtifacts = true
will work as well
- This can be prepared via
cargoClippyExtraArgs
: additional flags to be passed in the clippy invocation (e.g. deny specific lints)- Default value:
"--all-targets"
- Default value:
cargoExtraArgs
: additional flags to be passed in the cargo invocation (e.g. enabling specific features)- Default value:
""
- Default value:
The clippy
package is automatically appended as a native build input to any
other nativeBuildInputs
specified by the caller.
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoClippyExtraArgs
cargoExtraArgs
cargoDoc :: set -> drv
Create a derivation which will run a cargo doc
invocation in a cargo
workspace.
Except where noted below, all derivation attributes are delegated to
mkCargoDerivation
, and can be used to influence its behavior.
buildPhaseCargoCommand
will be set to runcargo doc --profile release
for the workspace.CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
pnameSuffix
will be set to"-doc"
cargoArtifacts
: A path (or derivation) which contains an existing cargotarget
directory, which will be reused at the start of the derivation. Useful for caching incremental cargo builds.- This can be prepared via
buildDepsOnly
- Alternatively, any cargo-based derivation which was built with
doInstallCargoArtifacts = true
will work as well
- This can be prepared via
cargoDocExtraArgs
: additional flags to be passed in the rustdoc invocation (e.g. deny specific lints)- Default value:
"--no-deps"
- Default value:
cargoExtraArgs
: additional flags to be passed in the cargo invocation (e.g. enabling specific features)- Default value:
""
- Default value:
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoDocExtraArgs
cargoExtraArgs
cargoFmt :: set -> drv
Create a derivation which will run a cargo fmt
invocation in a cargo
workspace.
Except where noted below, all derivation attributes are delegated to
mkCargoDerivation
, and can be used to influence its behavior.
buildPhaseCargoCommand
will be set to runcargo fmt
(in check mode) in the workspace.cargoArtifacts
is disabled/clearedcargoVendorDir
is disabled/clearedpnameSuffix
will be set to"-fmt"
cargoExtraArgs
: additional flags to be passed in the cargo invocation- Default value:
""
- Default value:
rustFmtExtraArgs
: additional flags to be passed in the rustfmt invocation- Default value:
""
- Default value:
The rustfmt
package is automatically appended as a native build input to any
other nativeBuildInputs
specified by the caller.
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoExtraArgs
rustFmtExtraArgs
cargoNextest :: set -> drv
Create a derivation which will run a cargo nextest
invocation in a cargo
workspace.
Except where noted below, all derivation attributes are delegated to
mkCargoDerivation
, and can be used to influence its behavior.
checkPhaseCargoCommand
will be set to runcargo nextest run --profile release
for the workspace.CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
pnameSuffix
will be set to"-nextest"
and may include partition numbers
cargoArtifacts
: A path (or derivation) which contains an existing cargotarget
directory, which will be reused at the start of the derivation. Useful for caching incremental cargo builds.- This can be prepared via
buildDepsOnly
- Alternatively, any cargo-based derivation which was built with
doInstallCargoArtifacts = true
will work as well
- This can be prepared via
buildPhaseCargoCommand
, unless specified, will be set to print the nextest versioncargoExtraArgs
: additional flags to be passed in the cargo invocation (e.g. enabling specific features)- Default value:
""
- Default value:
cargoNextestExtraArgs
: additional flags to be passed in the clippy invocation (e.g. deny specific lints)- Default value:
""
- Default value:
partitions
: The number of separate nextest partitions to run. Useful if the test suite takes a long time and can be parallelized across multiple build nodes.- Default value:
1
- Default value:
partitionType
: The kind of nextest partition to run (e.g."count"
or"hash"
based).- Default value:
"count"
- Default value:
The cargo-nextest
package is automatically appended as a native build input to any
other nativeBuildInputs
specified by the caller.
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoExtraArgs
cargoNextestExtraArgs
partitions
partitionType
cargoTarpaulin :: set -> drv
Create a derivation which will run a cargo tarpaulin
invocation in a cargo
workspace.
Except where noted below, all derivation attributes are delegated to
mkCargoDerivation
, and can be used to influence its behavior.
buildPhaseCargoCommand
will be set to runcargo tarpaulin --profile release
in the workspace.CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
pnameSuffix
will be set to"-tarpaulin"
cargoArtifacts
: A path (or derivation) which contains an existing cargotarget
directory, which will be reused at the start of the derivation. Useful for caching incremental cargo builds.- This can be prepared via
buildDepsOnly
- Alternatively, any cargo-based derivation which was built with
doInstallCargoArtifacts = true
will work as well
- This can be prepared via
cargoExtraArgs
: additional flags to be passed in the cargo invocation- Default value:
""
- Default value:
cargoTarpaulinExtraArgs
: additional flags to be passed in the cargo tarpaulin invocation- Default value:
"--skip-clean --out Xml --output-dir $out"
- Default value:
The cargo-tarpaulin
package is automatically appended as a native build input to any
other nativeBuildInputs
specified by the caller.
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoExtraArgs
cargoTarpaulinExtraArgs
cargoTest :: set -> drv
Create a derivation which will run a cargo test
invocation in a cargo
workspace.
Except where noted below, all derivation attributes are delegated to
buildPhaseCargoCommand
will be set to runcargo test --profile release
in the workspace.CARGO_PROFILE
can be set on the derivation to alter which cargo profile is selected; setting it to""
will omit specifying a profile altogether.
pnameSuffix
will be set to"-test"
cargoExtraArgs
: additional flags to be passed in the cargo invocation- Default value:
""
- Default value:
cargoTestArgs
: additional flags to be passed in the cargo invocation- Default value:
""
- Default value:
The following attributes will be removed before being lowered to
mkCargoDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
cargoExtraArgs
cargoTestExtraArgs
cleanCargoSource :: path or drv -> drv
Cleans a source tree to omit things like version control directories as well
omit any non-Rust/non-cargo related files. Useful to avoid rebuilding a project
when unrelated files are changed (e.g. flake.nix
or any other nix files).
The final output will be cleaned by both cleanSourcesFilter
(from nixpkgs) and
lib.filterCargoSources
. See each of them for more details on which files are
kept.
If it is necessary to customize which files are kept, a custom filter can be
written (which may want to also call lib.filterCargoSources
) to achieve the
desired behavior.
lib.cleanCargoSource ./.
cleanCargoToml :: set -> set
Cleans all definitions from a Cargo.toml file which are irrelevant for a
minimal build of a package's dependencies. See mkDummySrc
for more information
on how the result is applied.
In general, the following types of attributes are kept from the original input:
- basic package definitions (like name and version)
- dependency definitions
- feature definitions
- workspace definitions
- anything pertaining to project structure (like bin/lib targets, tests, etc.)
lib.cleanCargoToml { cargoToml = ./Cargo.toml; }
# { dependencies = { byteorder = "*"; }; package = { edition = "2021"; name = "simple"; version = "0.1.0"; }; }
cargoToml
: a path to a Cargo.toml filecargoTomlContents
: the contents of a Cargo.toml file as a string
At least one of the above attributes must be specified, or an error will be raised during evaluation.
crateNameFromCargoToml :: set -> set
Extract a crate's name and version from its Cargo.toml file.
The resulting pname
attribute will be populated with the value of the
Cargo.toml's package.name
attribute, if present. Otherwise a placeholder value
will be used.
The resulting version
attribute will be populated with the value of the
Cargo.toml's (top-level) package.version
attribute, if present and if the
value is a string. Otherwise workspace.package.version
will be used if it is
present and the value is a string. Otherwise a placeholder version field will
be used.
lib.crateNameFromCargoToml { cargoToml = ./Cargo.toml; }
# { pname = "simple"; version = "0.1.0"; }
crateRegistries :: set
A set of crate registries made available for use in downloading crate sources. The keys are registry URLs as used in the Cargo.lock file (e.g. "registry+https://...") and the values are the download URL for that registry, including any placeholder values cargo is expected to populate for downloads.
This definition can be updated via appendCrateRegistries
.
src
: a directory which includes a Cargo.toml file at its root.cargoToml
: a path to a Cargo.toml filecargoTomlContents
: the contents of a Cargo.toml file as a string
At least one of the above attributes must be specified, or an error will be raised during evaluation.
pname
: the name of the crate- Default value:
"cargo-package"
if the specified Cargo.toml file did not include a name
- Default value:
version
: the version of the crate- Default value:
"0.0.1"
if the specified Cargo.toml file did not include a version
- Default value:
downloadCargoPackage :: set -> drv
Download a packaged cargo crate (e.g. from crates.io) and prepare it for vendoring.
checksum
: the (sha256) checksum recorded in the Cargo.lock filename
: the name of the cratesource
: the source key recorded in the Cargo.lock fileversion
: the version of the crate
downloadCargoPackageFromGit :: set -> drv
Download a git repository containing a cargo crate or workspace, and prepare it any crates it contains for vendoring.
git
: the URL to the repositoryrev
: the exact revision to check out
ref
: the ref (i.e. branch or tag) to whichrev
belongs to. For branches it should be"refs/head/${branch}"
and for tags it should be"refs/tags/${tag}"
- Default value:
null
- Default value:
allRefs
: whether all git refs should be fetched in order to look for the specifiedrev
- Default value:
true
ifref
is set tonull
,false
otherwise
- Default value:
findCargoFiles :: path -> set of lists
Given a path, recursively search it for any Cargo.toml
, .cargo/config
or
.cargo/config.toml
files.
lib.findCargoFiles ./src
# { cargoTomls = [ "..." ]; cargoConfigs = [ "..." ]; }
filterCargoSources :: path -> string -> bool
A source filter which when used with cleanSourceWith
(from nixpkgs's lib
)
will retain the following files from a given source:
- Cargo files (
Cargo.toml
,Cargo.lock
,.cargo/config.toml
,.cargo/config
) - Rust files (files whose name end with
.rs
) - TOML files (files whose name end with
.toml
)
cleanSourceWith {
src = ./.;
filter = lib.filterCargoSources;
}
Note that it is possible to compose source filters, especially if
filterCargoSources
omits files which are relevant to the build. For example:
let
# Only keeps markdown files
markdownFilter = path: _type: match ".*md$" path;
markdownOrCargo = path: type:
(markdownFilter path type) || (lib.filterCargoSources path type);
in
cleanSourceWith {
src = ./.;
filter = markdownOrCargo;
}
mkCargoDerivation :: set -> drv
A thin wrapper around stdenv.mkDerivation
which includes common hooks for
building a derivation using cargo. Except where noted below, all derivation
attributes are passed straight through, so any common derivation behavior can be
used as expected.
This is a fairly low-level abstraction, so consider using buildPackage
or
cargoBuild
if they fit your needs.
buildPhaseCargoCommand
: A command (likely a cargo invocation) to run during the derivation's build phase. Pre and post build hooks will automatically be run.cargoArtifacts
: A path (or derivation) which contains an existing cargotarget
directory, which will be reused at the start of the derivation. Useful for caching incremental cargo builds.- This can be prepared via
buildDepsOnly
- Alternatively, any cargo-based derivation which was built with
doInstallCargoArtifacts = true
will work as well
- This can be prepared via
buildPhase
: the commands used by the build phase of the derivation- Default value: the build phase will run
preBuild
hooks, print the cargo version, log and evaluatebuildPhaseCargoCommand
, and runpostBuild
hooks
- Default value: the build phase will run
cargoVendorDir
: A path (or derivation) of vendored cargo sources which can be consumed without network access. Directory structure should basically follow the output ofcargo vendor
.- Default value: the result of
vendorCargoDeps
after applying the arguments set (with the respective default values)
- Default value: the result of
checkPhase
: the commands used by the check phase of the derivation- Default value: the check phase will run
preCheck
hooks, log and evaluatecheckPhaseCargoCommand
, and runpostCheck
hooks
- Default value: the check phase will run
checkPhaseCargoCommand
: A command (likely a cargo invocation) to run during the derivation's check phase. Pre and post check hooks will automatically be run.- Default value:
""
- Default value:
configurePhase
: the commands used by the configure phase of the derivation- Default value: the configure phase will run
preConfigureHooks
hooks, then runpostConfigure
hooks
- Default value: the configure phase will run
doInstallCargoArtifacts
: controls whether cargo'starget
directory should be copied as an output- Default value:
true
- Default value:
installPhase
: the commands used by the install phase of the derivation- Default value: the install phase will run
preInstall
hooks, log and evaluateinstallPhaseCommand
, and runpostInstall
hooks
- Default value: the install phase will run
installPhaseCommand
: the command(s) which are expected to install the derivation's outputs.- Default value:
"mkdir -p $out"
- By default an output directory is created such that any other
postInstall
hooks can successfully run. Consider overriding this value with an appropriate installation commands for the package being built.
- Default value:
pname
: the name of the derivation- Default value: the package name listed in
Cargo.toml
- Default value: the package name listed in
pnameSuffix
: a suffix appended topname
- Default value:
""
- Default value:
stdenv
: the standard build environment to use for this derivation- Default value:
pkgs.stdenv
- Default value:
version
: the version of the derivation- Default value: the version listed in
Cargo.toml
- Default value: the version listed in
The following attributes will be removed before being lowered to
stdenv.mkDerivation
. If you absolutely need these attributes present as
environment variables during the build, you can bring them back via
.overrideAttrs
.
buildPhaseCargoCommand
checkPhaseCargoCommand
installPhaseCommand
pnameSuffix
stdenv
The cargo
package is automatically appended as a native build input to any
other nativeBuildInputs
specified by the caller, along with the following
hooks:
cargoHelperFunctionsHook
configureCargoCommonVarsHook
configureCargoVendoredDepsHook
inheritCargoArtifactsHook
installCargoArtifactsHook
zstd
mkDummySrc :: set -> drv
Converts a given source directory of a cargo workspace to the smallest, most trivial form needed to build all dependencies such that their artifacts can be cached.
The actual source files of the project itself are ignored/replaced with empty programs, such that changes to the source files does not invalidate any build caches. More specifically:
- The Cargo.lock file is kept as-is
- Any changes to it will invalidate the build cache
- Any cargo configuration files (i.e. files name
config
orconfig.toml
whose parent directory is named.cargo
) are kept as-is.- Any changes to these files will invalidate the build cache
- Any files named
Cargo.toml
are reduced viacleanCargoToml
and the result is kept. Only the following changes will result in invalidating the build cache:- Any changes to listed dependencies
- Any changes to feature definitions
- Any changes to the workspace member metadata
- Any changes to the
[package]
definition such as name and version - Any changes to the name or path of any target (such as benches, bins, examples, libs, or tests)
src
: a source directory which should be turned into a "dummy" form
cargoLock
: a path to a Cargo.lock file- Default value:
src + /Cargo.lock
- Default value:
extraDummyScript
: additional shell script which will be run inside the builder verbatim. Useful for customizing what the dummy sources include by running any arbitrary commands.- Default value:
""
- Note that this script will run in an environment where the original source is not present as doing so would cause a rebuild if any part of the source changed. Additional files can be copied to the derivation's result, but care must be taken that the derivation only depends on (i.e. is rebuilt if) the smallest subset of the original source as required.
- Here is an example of how to include an entire directory, in this case
.cargo
, but any other directory would work as well:let in mkDummySrc { # The _entire_ source of the project. mkDummySrc will automatically # filter out irrelevant files as described above src = ./.; # Note that here we scope the path to just `./.cargo` and not any other # directories which may exist at the root of the project. Also note that # the entire path is inside of the `${ }` which ensures that the # derivation only consumes that directory. Writing `${./.}/.cargo` would # incorectly consume the entire source root, and therefore rebuild # everything when any file changes, which defeats artifact caching. # # Also note the `--no-target-directory` flag which ensures the results are # copied to `$out/.cargo` instead of something like `$out/HASH-.cargo` extraDummyScript = '' cp -r ${./.cargo} --no-target-directory $out/.cargo ''; }
- Default value:
overrideToolchain :: drv -> set
A convenience method to override and use tools (like cargo
, clippy
,
rustfmt
, rustc
, etc.) from one specific toolchain. The input should be a
single derivation which contains all the tools as binaries. For example, this
can be the output of oxalica/rust-overlay
.
crane.lib.${system}.overrideToolchain myCustomToolchain
registryFromDownloadUrl :: set -> set
Prepares a crate registry into a format that can be passed directly to
appendCrateRegistries
using the registry's download URL.
If the registry in question has a stable download URL (which either never
changes, or it does so very infrequently), then registryFromDownloadUrl
is a
great and lightweight choice for including the registry. To get started, look up
the
config.json
at the registry's root and copy the value of the dl
entry.
If the registry's download endpoint changes more frequently and you would like
to infer the configuration directly from a git revision, consider using
registryFromGitIndex
as an alternative.
dl
: the value of thedl
entry in the registry'sconfig.json
fileindexUrl
: an HTTP URL to the index
lib.registryFromDownloadUrl {
dl = "https://crates.io/api/v1/crates";
indexUrl = "https://github.com/rust-lang/crates.io-index";
}
# { "registry+https://github.com/rust-lang/crates.io-index" = "https://crates.io/api/v1/crates/{crate}/{version}/download"; }
registryFromGitIndex :: set -> set
Prepares a crate registry into a format that can be passed directly to
appendCrateRegistries
using a revision of the registry index to infer the
download URL.
Note that the specified git revision does not need to track updates to the
index itself as long as the pinned revision contains the most recent version of
the config.json
file. In other words, this commit revision only needs to be
updated if the config.json
file changes.
Also note that this approach means that the contents of the entire index at the
specified revision will be added to the Nix store during evaluation time, and
that IFD will need to be enabled. If this is unsatisfactory, consider using
registryFromDownloadUrl
as a simpler alternative.
indexUrl
: an HTTP URL to the indexrev
: any git revision which contains the latestconfig.json
definition
lib.registryFromGitIndex {
url = "https://github.com/Hirevo/alexandrie-index";
rev = "90df25daf291d402d1ded8c32c23d5e1498c6725";
}
# { "registry+https://github.com/Hirevo/alexandrie-index" = "https://crates.polomack.eu/api/v1/crates/{crate}/{version}/download"; }
urlForCargoPackage :: set -> String
Returns the URL for downloading a particular crate. For now, only crates.io is supported.
name
: the name of the cratesource
: the source key recorded in the Cargo.lock fileversion
: the version of the crate
vendorCargoDeps :: set -> drv
Creates a derivation which will download all crates referenced by a Cargo.lock file, and prepare a vendored directory which cargo can use for subsequent builds without needing network access.
Each unique crate index will be vendored as its own subdirectory within the
output of the derivation. A config.toml
file will also be placed at the root
of the output which will contain the necessary configurations to point cargo to
the vendored directories (i.e. this configuration can be appended to the
.cargo/config.toml
definition of the project).
src
: a directory which includes a Cargo.lock file at its root.cargoLock
: a path to a Cargo.lock filecargoLockContents
: the contents of a Cargo.lock file as a string
At least one of the above attributes must be specified, or an error will be raised during evaluation.
vendorCargoRegistries :: set -> set
Creates the derivations necessary to download all crates from all registries
referenced by a Cargo.lock
file, and prepare the vendored directories which
cargo can use for subsequent builds without needing network access.
cargoConfigs
: a list of paths to all.cargo/config.toml
files which may appear in the projectlockPackages
: a list of all[[package]]
entries found in the project'sCargo.lock
file (parsed viabuiltins.fromTOML
)
config
: the configuration entires needed to point cargo to the vendored crates. This is intended to be appended to$CARGO_HOME/config.toml
verbatimsources
: an attribute set of all the newly created cargo sources' names to their location in the Nix store
vendorGitDeps :: set -> set
Creates the derivations necessary to download all crates from all git
dependencies referenced by a Cargo.lock
file, and prepare the vendored
directories which cargo can use for subsequent builds without needing network
access.
lockPackages
: a list of all[[package]]
entries found in the project'sCargo.lock
file (parsed viabuiltins.fromTOML
)
config
: the configuration entires needed to point cargo to the vendored sources. This is intended to be appended to$CARGO_HOME/config.toml
verbatimsources
: an attribute set of all the newly created cargo sources' names to their location in the Nix store
writeTOML :: String -> String -> drv
Takes a file name and an attribute set, converts the set to a TOML document and writes it to a file with the given name.
lib.writeTOML "foo.toml" { foo.bar = "baz"; }
# «derivation /nix/store/...-foo.toml.drv»
Defines helper functions for internal use. It is probably not a great idea to depend on these directly as their behavior can change at any time, but it is worth documenting them just in case:
- Defines a
cargo()
function which will immediately invoke thecargo
command found on the$PATH
after echoing the exact arguments that were passed in. Useful for automatically logging all cargo invocations to the log. - Defines a
cargoWithProfile()
function which will invokecargo
with the provided arguments. If$CARGO_PROFILE
is set, then--profile $CARGO_PROFILE
will be injected into thecargo
invocation- Note: a default value of
$CARGO_PROFILE
is set viaconfigureCargoCommonVarsHook
. You can setCARGO_PROFILE = "something"
in your derivation to change which profile is used, or setCARGO_PROFILE = "";
to omit it altogether.
- Note: a default value of
Defines configureCargoCommonVars()
which will set various common cargo-related
variables, such as honoring the amount of parallelism dictated by Nix, disabling
incremental artifacts, etc. More specifically:
CARGO_BUILD_INCREMENTAL
is set tofalse
if not already definedCARGO_BUILD_JOBS
is set to$NIX_BUILD_CORES
if not already definedCARGO_HOME
is set to$PWD/.cargo-home
if not already defined.- The directory that
CARGO_HOME
points to will be created
- The directory that
CARGO_PROFILE
is set torelease
if not already defined.- Note that this is is used internally specify a cargo profile (e.g.
cargo build --profile release
) and not something natively understood by cargo.
- Note that this is is used internally specify a cargo profile (e.g.
RUST_TEST_THREADS
is set to$NIX_BUILD_CORES
if not already defined
Automatic behavior: runs as a post-patch hook
Defines configureCargoVendoredDeps()
which will prepare cargo to use a
directory of vendored crate sources. It takes two positional arguments:
- a path to the vendored sources
- If not specified, the value of
$cargoVendorDir
will be used - If
cargoVendorDir
is not specified, an error will be raised
- If not specified, the value of
- a path to a cargo config file to modify
- If not specified, the value of
$CARGO_HOME/config.toml
will be used - This cargo config file will be appended with a stanza which will instruct
cargo to use the vendored sources (instead of downloading the sources
directly) as follows:
- If the vendored directory path contains a file named
config.toml
, then its contents will be appended to the specified cargo config path. - Otherwise the entire vendored directory path will be treated as if it only vendors the crates.io index and will be configured as such.
- If the vendored directory path contains a file named
- If not specified, the value of
Automatic behavior: if cargoVendorDir
is set, then
configureCargoVendoredDeps "$cargoVendorDir" "$CARGO_HOME/config.toml"
will be
run as a pre configure hook.
Defines inheritCargoArtifacts()
which will pre-populate cargo's artifact
directory using a previous derivation. It takes two positional arguments:
- a path to the previously prepared artifacts
- If not specified, the value of
$cargoArtifacts
will be used - If
cargoArtifacts
is not specified, an error will be raised - If the specified path is a directory which contains a file called
target.tar.zst
, then that file will be used as specified below - If the specified path is a file (and not a directory) it is assumed that it contains a zstd compressed tarball and will be decompressed and unpacked into the specified cargo artifacts directory
- If the specified path is a directory which contains another directory
called
target
, then that directory will be used as specified below - If the specified path is a directory, its contents will be copied into the specified cargo artifacts directory
- The previously prepared artifacts are expected to be a zstd compressed tarball
- If not specified, the value of
- the path to cargo's artifact directory, where the previously prepared
artifacts should be unpacked
- If not specified, the value of
$CARGO_TARGET_DIR
will be used - If
CARGO_TARGET_DIR
is not set, cargo's default target location (i.e../target
) will be used.
- If not specified, the value of
Automatic behavior: if cargoArtifacts
is set, then
inheritCargoArtifacts "$cargoArtifacts" "$CARGO_TARGET_DIR"
will be run as a
post patch hook.
Required nativeBuildInputs: assumes zstd
is available on the $PATH
Defines compressAndInstallCargoArtifactsDir()
which handles installing
cargo's artifact directory to the derivation's output as a zstd compressed
tarball. It takes two positional arguments:
- the installation directory for the output.
- An error will be raised if not specified
- Cargo's artifact directory will be compressed as a reproducible tarball
with zstd compression. It will be written to this directory and named
target.tar.zstd
- the path to cargo's artifact directory
- An error will be raised if not specified
Defines dedupAndInstallCargoArtifactsDir()
which handles installing
cargo's artifact directory to the derivation's output after deduplicating
identical files against a directory of previously prepared cargo artifacts.
It takes three positional arguments:
- the installation directory for the output.
- An error will be raised if not specified
- If the specified path is a directory which exists then the current cargo artifacts will be compared with the contents of said directory. Any files whose contents and paths match will be symbolically linked together to reduce the size of the data stored in the Nix store.
- the path to cargo's artifact directory
- An error will be raised if not specified
- a path to the previously prepared cargo artifacts
- An error will be raised if not specified
/dev/null
can be specified here if there is no previous directory to deduplicate against
Defines prepareAndInstallCargoArtifactsDir()
which handles installing cargo's
artifact directory to the derivation's output. It takes three positional
arguments:
- the installation directory for the output.
- If not specified, the value of
$out
will be used - Cargo's artifact directory will be installed based on the installation mode selected below
- If not specified, the value of
- the path to cargo's artifact directory
- If not specified, the value of
$CARGO_TARGET_DIR
will be used - If
CARGO_TARGET_DIR
is not set, cargo's default target location (i.e../target
) will be used.
- If not specified, the value of
- the installation mode to apply
- If not specified, the value of
$installCargoArtifactsMode
will be used. If$installCargoArtifactsMode
is not specified, a default value of `"use-symlink" will be used - If set to "use-symlink" then
dedupAndInstallCargoArtifactsDir()
will be used.- If
$cargoArtifacts
is defined and$cargoArtifacts/target
is a valid directory, it will be used during file deduplication
- If
- If set to "use-zstd" then
compressAndInstallCargoArtifactsDir()
will be used. - Otherwise an error will be raised if the mode is not recognized
- If not specified, the value of
Automatic behavior: if doInstallCargoArtifacts
is set to 1
, then
prepareAndInstallCargoArtifactsDir "$out" "$CARGO_TARGET_DIR"
will be run as a
post install hook.
Required nativeBuildInputs: assumes zstd
is available on the $PATH
Defines installFromCargoBuildLog()
which will use a build log produced by
cargo to find and install any binaries and libraries which have been built. It
takes two positional arguments:
- a path to where artifacts should be installed
- If not specified, the value of
$out
will be used - Binaries will be installed in a
bin
subdirectory - Libraries will be installed in a
lib
subdirectory- Note that only library targets with the
staticlib
andcdylib
crate-types will be installed. Library targets with therlib
crate-type will be ignored
- Note that only library targets with the
- If not specified, the value of
- a path to a JSON formatted build log written by cargo
- If not specified, the value of
$cargoBuildLog
will be used - If
cargoBuildLog
is not set, an error will be raised - This log can be captured, for example, via
cargo build --message-format json-render-diagnostics >cargo-build.json
- If not specified, the value of
Automatic behavior: none
Required nativeBuildInputs: assumes cargo
and jq
are available on the $PATH
Defines removeReferencesToVendoredSources()
which handles removing all
references to vendored sources from the installed binaries, which ensures that
nix does not consider the binaries as having a (runtime) dependency on the
sources themselves. It takes two positional arguments:
- the installation directory for the output.
- If not specified, the value of
$out
will be used - If
out
is not specified, an error will be raised
- If not specified, the value of
- a path to the vendored sources
- If not specified, the value of
$cargoVendorDir
will be used - If
cargoVendorDir
is not specified, an error will be raised - Note: it is expected that this directory has the exact structure as would
be produced by
lib.vendorCargoDeps
- If not specified, the value of
Automatic behavior: if cargoVendorDir
is set and
doNotRemoveReferencesToVendorDir
is not set, then
removeReferencesToVendoredSources "$out" "$cargoVendorDir"
will be run as a
post install hook.
Required nativeBuildInputs: assumes remove-references-to
is available on the $PATH