crate2nix

https://nix-community.github.io/crate2nix/
Admin
crate2nix is a tool that builds Rust cargo-based projects crate-by-crate with Nix, enabling hermetic...
Tokens:12,220
Snippets:178
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Initialize Project Directory

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Start by creating a new directory for your project and navigating into it.

```bash
❯ mkdir ripgrep-example

❯ cd ripgrep-example
```

--------------------------------

### Start Local Dev Server

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Starts a local development server to preview your documentation changes in real-time. The server runs at localhost:4321.

```bash
npm run dev
```

--------------------------------

### Install crate2nix from Tarball (Traditional)

Source: https://nix-community.github.io/crate2nix/10_getting_started/20_installing_crate2nix

Install crate2nix from a tarball of the master branch on GitHub. This method is suitable for traditional Nix setups.

```bash
nix-env -i -f https://github.com/nix-community/crate2nix/tarball/master
```

--------------------------------

### Install NPM Dependencies

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Install the necessary Node.js dependencies for the documentation build process.

```bash
npm install
```

--------------------------------

### Add Sources using crate2nix.json

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Examples of adding sources directly to the `crate2nix.json` configuration file. If the file doesn't exist, it will be created.

```bash
crate2nix source add cratesIo ripgrep 12.0.1
crate2nix source add git https://github.com/kolloch/crate2nix.git --rev 0832e5ac0a2c53a7a99b9b0b2ff2d51828e5cb60
crate2nix source add nix --import ./nix/sources.nix my_crate
```

--------------------------------

### Generate Cargo.nix (Local Install)

Source: https://nix-community.github.io/crate2nix/20_generating/10_generating

Run this command from your project directory containing Cargo.toml if crate2nix is installed locally.

```bash
crate2nix generate
```

--------------------------------

### Install crate2nix from nixpkgs (Flake-enabled)

Source: https://nix-community.github.io/crate2nix/10_getting_started/20_installing_crate2nix

Use this command to install the stable version of crate2nix from nixpkgs if you are using flakes. It also shows how to verify the installation.

```bash
nix profile install nixpkgs#crate2nix
crate2nix help
```

--------------------------------

### Install crate2nix from GitHub (Flake-enabled)

Source: https://nix-community.github.io/crate2nix/10_getting_started/20_installing_crate2nix

Install the latest version of crate2nix directly from its GitHub repository using this command. This is useful for getting the most recent features or fixes.

```bash
nix profile install github:nix-community/crate2nix
crate2nix help
```

--------------------------------

### Install crate2nix using nix-env (Traditional)

Source: https://nix-community.github.io/crate2nix/10_getting_started/20_installing_crate2nix

For traditional Nix environments without flakes, use this command to install crate2nix from nixpkgs. An optional step to update channels is included.

```bash
nix-channel --update # if you wish
nix-env -i -f '<nixpkgs>' -A crate2nix
```

--------------------------------

### Generate Cargo.nix (Elaborate Example)

Source: https://nix-community.github.io/crate2nix/20_generating/10_generating

This command generates Cargo.nix using '<nixos-unstable>' as the default pkgs path, and explicitly sets the Cargo.toml and output file paths.

```bash
crate2nix generate \
    -n '<nixos-unstable>' \
    -f /some/project/dir/Cargo.toml \
    -o /some/project/dir/Cargo.nix
```

--------------------------------

### Dependency with Git Source

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

Example of how to specify a dependency that sources its code directly from a Git repository.

```toml
[dependencies]
"crate2nix" = { git = "https://github.com/kolloch/crate2nix" }
```

--------------------------------

### Get Help with Astro CLI

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Displays help information for the Astro CLI, listing available commands and their usage.

```bash
npm run astro -- --help
```

--------------------------------

### Generate Cargo.nix without Flakes

Source: https://nix-community.github.io/crate2nix/20_generating/20_auto_generating

This example demonstrates how to use crate2nix tools in a non-flake environment. It manually calls `generatedCargoNix` and then `pkgs.callPackage` to build the root crate.

```nix
let
  crate2nix = ...;
  crate2nix-tools = pkgs.callPackage "${crate2nix}/tools.nix" {};
  generated = crate2nix-tools.generatedCargoNix {
    name = "test-rust-project";
    src = ./.;
  };
  called = pkgs.callPackage "${generated}/default.nix" {};
in
  called.rootCrate.build


```

--------------------------------

### Generate Cargo.nix (Nix Run)

Source: https://nix-community.github.io/crate2nix/20_generating/10_generating

Use this command to generate Cargo.nix without a local crate2nix installation, specifying the nixpkgs channel.

```bash
nix run nixpkgs#crate2nix -- generate
```

--------------------------------

### Export tools as flake attribute

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

Example of how to use the `appliedCargoNix` function from the exported `tools` flake attribute to build a root crate.

```nix
# ...
      perSystem = { system, pkgs, lib, inputs', ... }:
        let
          cargoNix = inputs.crate2nix.tools.${system}.appliedCargoNix {
            name = "rustnix";
            src = ./.;
          };
        in
        rec {
          packages.default = cargoNix.rootCrate.build;
        };
# ...
```

--------------------------------

### Generate Cargo.nix with Flakes

Source: https://nix-community.github.io/crate2nix/20_generating/20_auto_generating

This example shows how to integrate crate2nix into a flake-based project using flake-parts to automatically generate Cargo.nix. It configures checks and packages for the Rust project.

```nix
{
  # ...


  inputs = {
    flake-parts = {
      url = "github:hercules-ci/flake-parts";
      inputs.nixpkgs-lib.follows = "nixpkgs";
    };
    crate2nix.url = "github:nix-community/crate2nix";
    # ...
  };


  outputs =
    inputs @ { self
    , nixpkgs
    , flake-parts
    , rust-overlay
    , crate2nix
    , ...
    }: flake-parts.lib.mkFlake { inherit inputs; }
    {
      systems = [
        "x86_64-linux"
        "aarch64-linux"
        "x86_64-linux"
        "aarch64-darwin"
      ];


      perSystem = { system, pkgs, lib, inputs', ... }:
        let
          cargoNix = inputs.crate2nix.tools.${system}.appliedCargoNix {
            name = "rustnix";
            src = ./.;
          };
        in
        rec {
          checks = {
            rustnix = cargoNix.rootCrate.build.override {
              runTests = true;
            };
          };


          packages = {
            rustnix = cargoNix.rootCrate.build;
            default = packages.rustnix;
          };
        };
    };
}


```

--------------------------------

### Define Flake Inputs for External Sources

Source: https://nix-community.github.io/crate2nix/40_external_sources/10_building_fetched_sources

Configure your flake inputs to include external repositories like crate2nix and other project sources. This example shows how to specify URLs for GitHub repositories and whether they are flakes.

```nix
{
  # ...
  inputs = {
    nixpkgs.url = "nixpkgs";
    # ...


    crate2nix_stable = {
      url = "github:nix-community/crate2nix/0.12.0";
    };


    nix-test-runner = {
      url = "github:stoeffel/nix-test-runner";
      flake = false;
    };
  };


  # ...
}

```

--------------------------------

### Preview Production Build

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Locally previews the production-ready documentation site before deploying it.

```bash
npm run preview
```

--------------------------------

### Build Production Site

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Builds the documentation site for production deployment. The output will be placed in the ./dist/ directory.

```bash
npm run build
```

--------------------------------

### Build Docs with Nix

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Builds the documentation site using Nix, ensuring a reproducible build environment.

```bash
nix build .#docs
```

--------------------------------

### Initialize Rust Project with Flake Template

Source: https://nix-community.github.io/crate2nix/10_getting_started/10_flake_template_new

Use this command to create a new Rust project from the crate2nix flake template. Ensure you are in your project directory. If the directory is empty, a hello world stub will be created. For existing projects, remove superfluous files and ensure top-level Cargo.toml/Cargo.lock exist.

```bash
nix flake init --template github:nix-community/crate2nix
```

--------------------------------

### Run Build and Lints with Nix

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Executes both the documentation build process and linting checks using Nix for comprehensive validation.

```bash
nix flake check
```

--------------------------------

### List Configured Sources

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

View all sources that have been added to the project. This command also shows the equivalent `crate2nix source add` commands for easy recreation.

```bash
❯ crate2nix source list
ripgrep ripgrep 12.0.1 from crates.io: 1arw9pk1qiih0szd26wq76bc0wwbcmhyyy3d4dnwcflka8kfkikx


        crate2nix source add cratesIo --name 'ripgrep' 'ripgrep' '12.0.1'


ytop    https://github.com/cjbassi/ytop#21cb63f656519b86928fce9522107f78780d6460 via git: 1si5cq18qn819v28vfgbrx3fmfgzj4h0z00ga2p0px42q62vrs7q


        crate2nix source add git --name 'ytop' 'https://github.com/cjbassi/ytop' --rev 21cb63f656519b86928fce9522107f78780d6460
```

--------------------------------

### Run Built Binaries

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Execute the compiled binaries from the `nix build` output. This demonstrates that the binaries were built successfully and can be run.

```bash
❯ ./result-1/bin/ytop --version
ytop 0.5.1
❯ ./result/bin/rg --version
ripgrep 12.0.1
-SIMD -AVX (compiled)
+SIMD +AVX (runtime)
```

--------------------------------

### Import Nixpkgs with Fenix Toolchain Overlay

Source: https://nix-community.github.io/crate2nix/35_toolchains/10_custom_toolchains

This flake configuration demonstrates how to import nixpkgs with a custom Rust toolchain provided by fenix. It sets up an overlay to replace the default rustc and cargo with the fenix toolchain.

```nix
{ 
  description = "containix";


  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/24.05";
    fenix = {
      url = "github:nix-community/fenix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    flake-utils.url = "github:numtide/flake-utils";
    crate2nix.url = "github:nix-community/crate2nix";
  };


  outputs =
    { 
      self, 
      nixpkgs, 
      flake-utils, 
      fenix, 
      crate2nix,
    }:
    flake-utils.lib.eachDefaultSystem (
      system:
      let
        toolchain = fenix.packages.${system}.stable.defaultToolchain;


        pkgs = import nixpkgs {
          inherit system;
          overlays = [ 
            (final: prev: { 
              rustc = toolchain;
              cargo = toolchain;
            })
          ];
        };


        crate2nix' = pkgs.callPackage (import "${crate2nix}/tools.nix") {};
        cargoNix = crate2nix'.appliedCargoNix {
          name = "my-crate";
          src = ./.;
        };
      in
      {
        packages = {
          default = cargoNix.rootCrate.build;
        };
      }
    );
}

```

--------------------------------

### Generate Build File with All Features

Source: https://nix-community.github.io/crate2nix/30_building/20_choosing_features

Use `crate2nix generate --all-features` to create a build file that includes all possible features, providing maximum flexibility.

```bash
crate2nix generate --all-features
```

--------------------------------

### Build Project Binaries

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Use `nix build` with the generated `Cargo.nix` to build the specified workspace members. This command compiles the binaries.

```bash
❯ nix build -f Cargo.nix workspaceMembers.ripgrep workspaceMembers.ytop
[93 built, 0.0 MiB DL]
```

--------------------------------

### Build Rust Project with Nix

Source: https://nix-community.github.io/crate2nix/10_getting_started/10_flake_template_new

Build your Rust project hermetically using Nix. This command verifies your program locally and is suitable for use in CI pipelines.

```bash
nix build
```

--------------------------------

### Version Control Recommendations

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Check `Cargo.nix` and `crate-hashes.json` into version control for reproducible builds. Exclude generated `crate-sources*` files from version control.

```text
For building the binaries, `Cargo.nix` is sufficient. But everyone regenerating it will appreciate if you also check in
  * `crate2nix.json` (the source configuration)
  * `crate-hashes.json` (the hashes for packages not in the lockfile)

The generated `crate-sources*` files should go into `.gitignore` or similar:
`crate-sources*`
  * `crate-sources.nix` is the temporary nix expression to download the sources.
  * `crate-sources` is the temporary result symlink to the downloaded sources.
```

--------------------------------

### Run Individual Integration Test

Source: https://nix-community.github.io/crate2nix/50_contributing/05_code

Execute a specific integration test using `nix-build`. This command builds the project and targets a particular check defined in `tests.nix`.

```bash
nix-build \
  -o ./crate2nix/target/nix-results ./tests.nix -A checks.bin_with_lib_dep

```

--------------------------------

### Run crate2nix from nixpkgs

Source: https://nix-community.github.io/crate2nix/10_getting_started/30_running_crate2nix_without_install

Execute the crate2nix command using the version available in nixpkgs. This is useful for ensuring a stable and managed environment.

```bash
nix run nixpkgs#crate2nix -- help
```

--------------------------------

### Import Nixpkgs from Flake Input

Source: https://nix-community.github.io/crate2nix/40_external_sources/10_building_fetched_sources

This snippet demonstrates how to import a specific version of nixpkgs using a flake input definition. It's useful for ensuring reproducible builds by pinning the exact nixpkgs version.

```nix
let
  flakeInput = import ./flakeInput.nix;
in
import (builtins.fetchTree (flakeInput "nixpkgs"))

```

--------------------------------

### Use import for Cargo.nix files

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

The recommended convention for using Cargo.nix files has changed from `callPackage` to `import`. This change helps prevent issues with cross-compilation.

```nix
let cargo_nix = import ./Cargo.nix { inherit pkgs; };
in cargo_nix.workspaceMembers."${your_crate_name}".build

```

--------------------------------

### Run Rust Project with Nix and Arguments

Source: https://nix-community.github.io/crate2nix/10_getting_started/10_flake_template_new

Run your Rust project with Nix, passing arguments to the application. This is useful for testing different scenarios or configurations.

```bash
nix run -- --arg1 x
```

--------------------------------

### Run crate2nix from GitHub

Source: https://nix-community.github.io/crate2nix/10_getting_started/30_running_crate2nix_without_install

Execute the crate2nix command directly from its GitHub repository. This allows you to use the latest development version or a specific commit.

```bash
nix run github:nix-community/crate2nix -- help
```

--------------------------------

### Run Rust Project with Nix

Source: https://nix-community.github.io/crate2nix/10_getting_started/10_flake_template_new

Execute your Rust project using Nix. This ensures a consistent environment for running your application.

```bash
nix run
```

--------------------------------

### Override Nixpkgs for Build Tests Only

Source: https://nix-community.github.io/crate2nix/50_contributing/05_code

Run `buildTests` using `crate2nix` against a local `nixpkgs` fork without rebuilding `crate2nix` itself. This is efficient for iterating on `buildRustCrate` issues.

```bash
nix-build --arg buildTestNixpkgs ../nixpkgs \
  -o ./crate2nix/target/nix-results ./tests.nix -A checks.bin_with_lib_dep

```

--------------------------------

### Add crates.io Dependency

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Add a dependency from crates.io by specifying the name and version. This command prefetches the source and records it.

```bash
❯ crate2nix source add cratesIo ripgrep 12.0.1
Prefetching https://crates.io/api/v1/crates/ripgrep/12.0.1/download: done.
Added new source: ripgrep 12.0.1 from crates.io: 1arw9pk1qiih0szd26wq76bc0wwbcmhyyy3d4dnwcflka8kfkikx
```

--------------------------------

### Enter Nix Dev Shell

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Use this command to enter a development shell for working on the project, especially if you are not using direnv.

```bash
nix develop
```

--------------------------------

### Generate Cargo.nix and Hashes

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Generate the `Cargo.nix` file, which defines the project's dependencies. This process also fetches indirect dependencies and writes their hashes to `crate-hashes.json`.

```bash
❯ crate2nix generate
Fetching sources.
Generated ./crate2nix-sources.nix successfully.
Fetching sources via ./crate2nix-sources.nix fetchedSources: done.
Prefetching    1/2: https://github.com/rust-psutil/rust-psutil#6abe2de4409672c3f42b69db2b1ba45d73e78ee4
Prefetching    2/2: https://github.com/cjbassi/tui-rs#aff0a4c40aff6e0962a2a935d4b21065298e329c
Wrote hashes to ./crate-hashes.json.
Generated ./Cargo.nix successfully.
```

--------------------------------

### Manage Sources with crate2nix CLI

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Utilize the `crate2nix source` command for various management tasks. Use `--help` for detailed options. `list` shows configured sources, and `remove` deletes a source.

```bash
crate2nix source --help
crate2nix source add --help
crate2nix source list
crate2nix source remove ripgrep
```

--------------------------------

### Build Single Binary Crate

Source: https://nix-community.github.io/crate2nix/30_building/10_building_binaries

Use this command to build a single binary crate generated by Cargo.nix. The resulting binary will be available in the result directory.

```bash
your_crate_name="super_duper"
nix build -f Cargo.nix rootCrate.build
./result/bin/${your_crate_name}
```

--------------------------------

### Access Single Binary Crate Derivation in Nix

Source: https://nix-community.github.io/crate2nix/30_building/10_building_binaries

Access the build derivation for a single binary crate within a Nix file. This allows you to use the crate's build output in other Nix derivations.

```nix
let cargo_nix = callPackage ./Cargo.nix {};
in cargo_nix.rootCrate.build
```

--------------------------------

### Build External Rust Project with crate2nix

Source: https://nix-community.github.io/crate2nix/40_external_sources/10_building_fetched_sources

Use this snippet to build an external Rust project by fetching its source and applying crate2nix tools. It requires a flake input definition and specifies pinned versions of crate2nix and nixpkgs for stability.

```nix
let
  flakeInput = import ./flakeInput.nix;
  src = builtins.fetchTree (flakeInput "nix-test-runner");


  # Use last pinned crate2nix packages and corresponding nixpkgs to build the
  # test runner so that it works even if we have broken stuff!
  crate2nix_stable = builtins.fetchTree (flakeInput "crate2nix_stable");
  nixpkgs_stable = builtins.fetchTree (flakeInput "crate2nix_stable.nixpkgs");
in
{ system ? builtins.currentSystem
, pkgs ? import nixpkgs_stable { inherit system; }
, tools ? pkgs.callPackage "${crate2nix_stable}/tools.nix" { }
}:
let
  nixTestRunner = tools.appliedCargoNix {
    name = "nix-test-runner";
    inherit src;
  };
in
nixTestRunner.rootCrate.build

```

--------------------------------

### Generate Build File with Specific Features

Source: https://nix-community.github.io/crate2nix/30_building/20_choosing_features

Use `crate2nix generate --no-default-features --features "feature1 feature2"` to generate a build file with only the specified features enabled, excluding defaults.

```bash
crate2nix generate --no-default-features --features "feature1 feature2"
```

--------------------------------

### Crate2nix Documentation Project Structure

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

This tree structure shows the typical folders and files within an Astro + Starlight project used for crate2nix documentation.

```tree
.\n├── public/\n├── src/\n│   ├── assets/\n│   ├── content/\n│   │   ├── docs/\n│   │   └── config.ts\n│   └── env.d.ts\n├── astro.config.mjs\n├── package.json\n└── tsconfig.json\n
```

--------------------------------

### Override crate build with additional buildInputs for Darwin

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

Demonstrates how to use `overrideCrates` to add specific build inputs for a crate, particularly for macOS. This is useful for conditional dependencies.

```nix
cargo_nix.rootCrate.build.override {
      crateOverrides = defaultCrateOverrides // {
        cssparser-macros = attrs: {
          buildInputs = stdenv.lib.optionals stdenv.isDarwin [darwin.apple_sdk.frameworks.Security]; };
      };
    };
```

--------------------------------

### Conditional dependencies using 'test' configuration

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

Shows how to define conditional dependencies in a Cargo.toml file using the 'test' configuration. These dependencies are ignored when building with crate2nix as test support is not yet available.

```toml
[target.'cfg(test)'.dependencies]
tracing = { version = "0.1.5", features = ["log"] }
```

--------------------------------

### Customize test execution with testPreRun and testPostRun

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

Use `testPreRun` and `testPostRun` attributes to execute bash snippets before and after test commands. This is useful for setting environment variables or controlling test failure behavior.

```nix
# Example usage in Cargo.nix
let
  pkgs = import <nixpkgs> {};
  myCrate = pkgs.rustPlatform.buildRustPackage {
    pname = "my-crate";
    version = "0.1.0";
    src = ./.;

    # Example: Set an environment variable before tests
    testPreRun = ''
      export MY_TEST_VAR="some_value"
    '';

    # Example: Disable exit on error for tests, then re-enable
    testPostRun = ''
      set +e
      # Run actual tests here or other commands
      echo "Tests finished"
      set -e
    '';

    # ... other buildRustPackage arguments
  };
in
myCrate
```

--------------------------------

### Integrate Rust Overlay in Flake with flake-parts

Source: https://nix-community.github.io/crate2nix/35_toolchains/20_using_a_rust_overlay

Configure your flake.nix to use a Rust overlay by adding it to the overlays list in the nixpkgs import. This allows for custom Rust toolchain management.

```nix
{
  # ...


  inputs = {
    flake-parts = {
      url = "github:hercules-ci/flake-parts";
      inputs.nixpkgs-lib.follows = "nixpkgs";
    };
    crate2nix.url = "github:nix-community/crate2nix";
    # ...
  };


  outputs =
    inputs @ { self
    , nixpkgs
    , flake-parts
    , rust-overlay
    , crate2nix
    , ...
    }:
    flake-parts.lib.mkFlake { inherit inputs; } {
      systems = [
        "x86_64-linux"
        "aarch64-linux"
        "x86_64-linux"
        "aarch64-darwin"
      ];


      perSystem = { system, lib, inputs', ... }:
        let
          pkgs = import nixpkgs {
            inherit system;


            overlays = [ rust-overlay.overlays.default ];
          };


          buildRustCrateForPkgs =
            crate:
            pkgs.buildRustCrate.override {
              rustc = pkgs.rust-bin.stable.latest.default;
              cargo = pkgs.rust-bin.stable.latest.default;
            };


          generatedCargoNix = inputs.crate2nix.tools.${system}.generatedCargoNix {
            name = "rustnix";
            src = ./.;
          };


          cargoNix = import generatedCargoNix {
            inherit pkgs buildRustCrateForPkgs;
          };
        in
          rec {
            checks = {
              rustnix = cargoNix.rootCrate.build.override {
                runTests = true;
              };
            };


            packages = {
              rustnix = cargoNix.rootCrate.build;
              default = packages.rustnix;
            };
          };
    };
}

```

--------------------------------

### Override Nixpkgs for All Tests

Source: https://nix-community.github.io/crate2nix/50_contributing/05_code

Run integration tests for `crate2nix` against a local fork of `nixpkgs`. This is useful for testing changes in `crate2nix` that interact with `nixpkgs`.

```bash
nix-build --arg nixpkgs ../nixpkgs -o ./crate2nix/target/nix-results ./tests.nix checks

```

--------------------------------

### Run Astro CLI Commands

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Execute various commands provided by the Astro CLI for managing the documentation project, such as adding integrations or checking for errors.

```bash
npm run astro ...
```

--------------------------------

### Override Nixpkgs for Individual Test

Source: https://nix-community.github.io/crate2nix/50_contributing/05_code

Execute a single integration test while overriding `nixpkgs` with a local fork. This allows testing specific scenarios against your modified `nixpkgs`.

```bash
nix-build --arg nixpkgs ../nixpkgs \
  -o ./crate2nix/target/nix-results ./tests.nix -A checks.bin_with_lib_dep

```

--------------------------------

### Run Skipped Integration Test

Source: https://nix-community.github.io/crate2nix/50_contributing/05_code

Force the execution of a test that is currently marked as skipped. Use the `.forceSkipped` attribute to override the skip status.

```bash
nix-build \
    -o ./crate2nix/target/nix-results ./tests.nix -A checks.empty_cross.forceSkipped

```

--------------------------------

### Build Workspace Member Crate

Source: https://nix-community.github.io/crate2nix/30_building/10_building_binaries

Build a specific crate from a Cargo workspace generated by Cargo.nix. The resulting binary is placed in the result directory.

```bash
your_crate_name="super_duper"
nix build -f Cargo.nix workspaceMembers.${your_crate_name}.build
./result/bin/${your_crate_name}
```

--------------------------------

### Add OpenSSL dependency to a crate

Source: https://nix-community.github.io/crate2nix/30_building/30_crateoverrides

Use `crateOverride` to add `pkgs.openssl` to the `buildInputs` for the `funky-things` crate. This is useful for crates with native dependencies not covered by default overrides.

```nix
let
  customBuildRustCrateForPkgs = pkgs: pkgs.buildRustCrate.override {
    defaultCrateOverrides = pkgs.defaultCrateOverrides // {
      funky-things = attrs: {
        buildInputs = [ pkgs.openssl ];
      };
    };
  };
  generatedBuild = callPackage ./crate2nix/Cargo.nix {
    buildRustCrateForPkgs = customBuildRustCrateForPkgs;
  };
in generatedBuild.rootCrate.build

```

--------------------------------

### Enable Rust Test Execution

Source: https://nix-community.github.io/crate2nix/30_building/40_tests

Enable test execution for Rust crates by setting `runTests = true;`. Optionally, provide `testInputs` to make specific packages available during the test run. This setting is ignored if `runTests` is false.

```nix
      let cargo_nix = callPackage ./Cargo.nix {};
          crate2nix = cargo_nix.rootCrate.build.override {
     runTests = true;
     testInputs = [ pkgs.cowsay ];
   };
      in ...
```

--------------------------------

### Conditionally add macOS Security framework

Source: https://nix-community.github.io/crate2nix/30_building/30_crateoverrides

Conditionally add the macOS Security framework to the `buildInputs` for `cssparser-macros` only when building on Darwin. This demonstrates using Nix's `lib.optionals` for platform-specific dependencies.

```nix
let
  customBuildRustCrateForPkgs = pkgs: pkgs.buildRustCrate.override {
    defaultCrateOverrides = pkgs.defaultCrateOverrides // {
      cssparser-macros = attrs: {
        buildInputs =
          lib.optionals
            pkgs.stdenv.isDarwin
            [ pkgs.darwin.apple_sdk.frameworks.Security ];
      };
    };
  };
  generatedBuild = callPackage ./crate2nix/Cargo.nix {
    buildRustCrateForPkgs = customBuildRustCrateForPkgs;
  };
in generatedBuild.rootCrate.build

```

--------------------------------

### Run Pre-commit Lints

Source: https://nix-community.github.io/crate2nix/50_contributing/10_docs

Executes pre-commit hooks for linting the project files without committing changes. This is useful for checking code quality before committing.

```bash
pre-commit
```

--------------------------------

### Override Features with override Function

Source: https://nix-community.github.io/crate2nix/30_building/20_choosing_features

The `override` function on `rootCrate.build` allows for granular control over features for a specific crate.

```nix
let cargo_nix = callPackage ./Cargo.nix {};
    crate2nix = cargo_nix.rootCrate.build.override { features = ["default" "other"]; };
in ...
```

--------------------------------

### Access Workspace Member Crate Derivation in Nix

Source: https://nix-community.github.io/crate2nix/30_building/10_building_binaries

Access the build derivation for a specific crate within a Cargo workspace in a Nix file. This is useful for integrating workspace members into larger Nix projects.

```nix
let cargo_nix = callPackage ./Cargo.nix {};
in cargo_nix.workspaceMembers."${your_crate_name}".build
```

--------------------------------

### Add Git Dependency

Source: https://nix-community.github.io/crate2nix/40_external_sources/20_generating_for_fetched_sources

Add a dependency from a git repository by providing the URL and a specific revision hash. This ensures reproducible builds from a specific commit.

```bash
❯ crate2nix source add git https://github.com/cjbassi/ytop --rev 21cb63f656519b86928fce9522107f78780d6460
Prefetching https://github.com/cjbassi/ytop#21cb63f656519b86928fce9522107f78780d6460: done.
Added new source: https://github.com/cjbassi/ytop#21cb63f656519b86928fce9522107f78780d6460 via git: 1si5cq18qn819v28vfgbrx3fmfgzj4h0z00ga2p0px42q62vrs7q
```

--------------------------------

### Override Features with callPackage

Source: https://nix-community.github.io/crate2nix/30_building/20_choosing_features

When importing a build file using `callPackage`, you can set the `rootFeatures` attribute to control the enabled features.

```nix
let cargo_nix = callPackage ./Cargo.nix { rootFeatures = ["default" "other"]; };
    crate2nix = cargo_nix.rootCrate.build;
in ...
```

--------------------------------

### Override Features via Command Line Argument

Source: https://nix-community.github.io/crate2nix/30_building/20_choosing_features

Use the `rootFeatures` argument when calling the generated build file from the command line to specify desired features.

```bash
nix build -f ....nix --arg rootFeatures '["default" "other"]' rootCrate.build
```

--------------------------------

### Override rootFeatures on rootCrate.build

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

Features can be overridden directly on the rootCrate.build derivation using the override function.

```nix
let cargo_nix = callPackage ./Cargo.nix {};
    crate2nix = cargo_nix.rootCrate.build.override { features = ["default" "other"]; };
in ...;
```

--------------------------------

### Override rootFeatures when calling with callPackage

Source: https://nix-community.github.io/crate2nix/90_reference/90_changelog

When importing the build file with callPackage, you can specify rootFeatures in the arguments.

```nix
let cargo_nix = callPackage ./Cargo.nix { rootFeatures = ["default" "other"]; };
    crate2nix = cargo_nix.rootCrate.build;
in ...;
```
Tokens:
Raw