Introduction

This library provides a set of Nix functions to make creating flakes for languages such as Haskell, PureScript, Rust, and TypeScript easier.

perSystem.lib.haskellData

Makes a derivation containing a Haskell Cabal package with data modules (using Cabal data stanzas)

Type: function that evaluates to a(n) (attribute set) (read only)

Default: <function, args: {cabalDataPatterns, cabalPackageName, cabalPackageVersion?, srcs}>

Example:

''
  ```haskell
    haskellData {
      srcs = [ ./. ];
      cabalDataPatterns = [ "**/*.json" ];
      cabalPackageName = "golden-json-data";
    };
  ```
''

Declared by:

perSystem.lib.haskellFlake

TODO(jaredponn): write down documentation here

Type: function that evaluates to a(n) (attribute set) (read only)

Default: <function>

Example:

''
  TODO(jaredponn): write down an example here
''

Declared by:

perSystem.lib.haskellPlutusFlake

TODO(jaredponn): write down documentation here

Type: function that evaluates to a(n) (attribute set) (read only)

Default: <function>

Example:

''
  TODO(jaredponn): write down an example here
''

Declared by:

perSystem.lib.purescriptFlake

TODO(jaredponn): write down documentation here

Type: function that evaluates to a(n) (attribute set) (read only)

Default: <function>

Example:

''
  TODO(jaredponn): write down an example here
''

Declared by:

perSystem.lib.rustFlake

Creates a flake for a Rust project.

Arguments:

  • src: Source folder (unfiltered)
  • extraSourceFilters(optional): Extra filters to add non-rust related files to the derivation
  • crane(optional): Crane version to be used
  • crateName: Name of the project
  • version: Major version of the project
  • rustChannel(default=stable): Rust profile (stable, nightly, etc.)
  • rustVersion(default=latest): Rust version
  • nativeBuildInputs(optional): Additional native build inputs
  • buildInputs(optional): Additional build inputs
  • extraSources(optional): Extra sources, allowing to use other rustFlake components to be used as dependencies
  • extraSourcesDir(default=.extras): Folder to store extra source libraries
  • data(optional): Data dependencies
  • dataDir(default=data): Folder to store the data dependencies
  • devShellHook(optional): Shell script executed after entering the dev shell
  • devShellTools(optional): Packages made available in the dev shell
  • testTools(optional): Packages made available in checks and the dev shell
  • cargoNextestExtraArgs(optional): Extra cargo nextest arguments
  • doInstallCargoArtifacts(optional): Controls whether cargo’s target directory should be copied as an output
  • target (optional): Main Rust compilation target (Rust will figure out by default)
  • extraTargets(optional): Extra Rust compilation targets
  • extraRustcFlags(optional): Extra rustc flags
  • extraCargoArgs(optional): Extra cargo arguments
  • extraEnvVars(optional): Extra environment variables
  • generateDocs(default=true): Generate Rustdoc
  • runTests(default=true): Run testsuite using cargo-nextest
  • runClippy(default=true): Run clippy linter
  • exportTests(default=false): Build testsuite as standalone executables

Returns:

Returns an attribute set of the form

{
  devShells."dev-${name}-rust" = derivation { ... };
  packages."${name}-rust" = derivation { ... };
  packages."${name}-rust-src" = derivation { ... };
  packages."${name}-rust-build-env" = derivation { ... };
  packages."${name}-rust-doc" = derivation { ... };
  checks."${name}-rust-test" = derivation { ... };
  checks."${name}-rust-clippy" = derivation { ... };
}

where

  • packages."${name}-rust" contains the binary executable of the project.
  • packages."${name}-rust-src" contains the source folder, to be used as a dependency of other application in extraSources
  • packages."${name}-rust-build-env" contains the source folder, to be used as a standalone library (not is extraSources)
  • packages."${name}-rust-doc" contains the API references document
  • checks."${name}-rust-test" runs tests using cargo nextest
  • checks."${name}-rust-clippy" runs clippy

Type: function that evaluates to a(n) (attribute set) (read only)

Default: <function, args: {buildInputs?, cargoNextestExtraArgs?, crane?, crateName, data?, dataDir?, devShellHook?, devShellTools?, doInstallCargoArtifacts?, exportTests?, extraCargoArgs?, extraEnvVars?, extraRustcFlags?, extraSourceFilters?, extraSources?, extraSourcesDir?, extraTargets?, generateDocs?, nativeBuildInputs?, runClippy?, runTests?, rustChannel?, rustProfile?, rustVersion?, src, target?, testTools?, version?}>

Example:

''
  { ... }:
  {
    perSystem =
      { config, ... }:
  
      let
        rustFlake = config.lib.rustFlake {
          src = ./.;
          crateName = "rust-flake-project";
  
          devShellHook = config.settings.shell.hook;
          exportTests = true;
        };
      in
      {
  
        inherit (rustFlake) packages checks devShells;
  
      };
  }
''

Declared by:

perSystem.lib.typescriptFlake

Creates a flake for a TypeScript project.

Returns an attribute set of the form

{
  devShells."${name}-typescript" = derivation { ... };
  packages."${name}-typescript" = derivation { ... };
  packages."${name}-typescript-exe" = derivation { ... };
  packages."${name}-typescript-lib" = derivation { ... };
  packages."${name}-typescript-tgz" = derivation { ... };
  packages."${name}-typescript-node2nix" = derivation { ... };
  checks."${name}-typescript-test" = derivation { ... };
}

where

  • packages."${name}-typescript" contains the project with a node_modules/ provided by Nix (in the configurePhase), and its buildPhase runs npm run "$npmBuildScript" (where npmBuildScript is build by default). Indeed, one can overlay the entire derivation (which contains all its dependencies) to postprocess their project as they see fit. For example, one may want to generate documentation instead of building the project, by running:

    packages."${name}-typescript".overrideAttrs (_self: _super: {
  npmBuildScript = "docs";
  installPhase = 
     ''
         mv ./docs "$out"
     '';
 });

    where we assume that the package.json contains scripts.docs = <some-script> which produces documentation in the ./docs folder.

  • devShells."${name}-typescript" provides a developer shell with the environment variable NODE_PATH as the path to the node_modules/ produced by Nix, and the command ${name}-npm-extra-dependencies which copies the transitive closure of npmExtraDependencies to the folder ./.extra-dependencies.

    Moreover, the shellHook will:

    • create a symbolic link named node_modules pointing to $NODE_PATH; and
    • execute ${name}-npm-extra-dependencies.

    As such, one should enter the development shell in the folder that the project exists in, so npm may use the provided dependencies from nix.

  • packages."${name}-typescript-exe" is packages."${name}-typescript" except runs npm install --global --prefix="$out" for the installPhase and copies some of the symbolic links so that the output makes sense.

  • packages."${name}-typescript-tgz" is packages."${name}-typescript" except runs npm pack after the buildPhase to create a tarball of the project in the directory $out/tarballs/.

  • packages."${name}-typescript-lib" is packages."${name}-typescript-tgz" except that it unpacks the tarball to $out/lib/node_modules/<package-name>

  • packages."${name}-typescript-test" is packages."${name}-typescript" except it runs npm test after the buildPhase succeeding only if npm test succeeds.

Type: function that evaluates to a(n) (attribute set) (read only)

Default: <function, args: {data?, dataDir?, devShellHook?, devShellTools?, name, nodejs?, npmBuildScript?, npmExtraDependencies?, src, testTools?}>

Example: "TODO(jaredponn)"

Declared by: