liqwid-nix

liqwid-nix is a simple library for writing nix flakes in Liqwid Labs projects. The aim of liqwid-nix is to reduce duplication of shared code, while providing a flexible escape for when real changes need to be applied.

Features

  • On-chain project support using Plutarch
  • Off-chain project support using CTL
  • Overridable configuration using flake-parts

debug

Whether to add the attributes debug, allSystems and currentSystem to the flake output. When true, this allows inspection of options via nix repl.

$ nix repl
nix-repl> :lf .
nix-repl> currentSystem._module.args.pkgs.hello
«derivation /nix/store/7vf0d0j7majv1ch1xymdylyql80cn5fp-hello-2.12.1.drv»

Each of debug, allSystems.<system> and currentSystem is an attribute set consisting of the config attributes, plus the extra attributes _module, config, options, extendModules. So note that these are not part of the config parameter, but are merged in for debugging convenience.

  • debug: The top-level options
  • allSystems: The perSystem submodule applied to the configured systems.
  • currentSystem: Shortcut into allSystems. Only available in impure mode. Works for arbitrary system values.

See Expore and debug option values for more examples.

Type: boolean

Default

false

flake

Raw flake output attributes. Any attribute can be set here, but some attributes are represented by options, to provide appropriate configuration merging.

Type: lazy attribute set of raw value

flake.apps

See {option}perSystem.apps for description and examples.

Type: lazy attribute set of lazy attribute set of (submodule)

Default

{}

flake.apps.<name>.<name>.program

A path to an executable or a derivation with meta.mainProgram.

Type: string or package convertible to it

flake.apps.<name>.<name>.type

A type tag for apps consumers.

Type: value "app" (singular enum)

Default

"app"

flake.checks

See {option}perSystem.checks for description and examples.

Type: lazy attribute set of lazy attribute set of package

Default

{}

flake.devShells

See {option}perSystem.devShells for description and examples.

Type: lazy attribute set of lazy attribute set of package

Default

{}

flake.formatter

An attribute set of per system a package used by nix fmt.

Type: lazy attribute set of package

Default

{}

flake.legacyPackages

See {option}perSystem.legacyPackages for description and examples.

Type: lazy attribute set of lazy attribute set of raw value

Default

{}

flake.nixosConfigurations

Instantiated NixOS configurations. Used by nixos-rebuild.

nixosConfigurations is for specific machines. If you want to expose reusable configurations, add them to nixosModules in the form of modules (no lib.nixosSystem), so that you can reference them in this or another flake's nixosConfigurations.

Type: lazy attribute set of raw value

Default

{}

Example

{"_type":"literalExpression","text":"{\n  my-machine = inputs.nixpkgs.lib.nixosSystem {\n    # system is not needed with freshly generated hardware-configuration.nix\n    # system = \"x86_64-linux\";  # or set nixpkgs.hostPlatform in a module.\n    modules = [\n      ./my-machine/nixos-configuration.nix\n      config.nixosModules.my-module\n    ];\n  };\n}\n"}

flake.nixosModules

NixOS modules.

You may use this for reusable pieces of configuration, service modules, etc.

Type: lazy attribute set of unspecified value

Default

{}

flake.overlays

An attribute set of overlays.

Note that the overlays themselves are not mergeable. While overlays can be composed, the order of composition is significant, but the module system does not guarantee sufficiently deterministic definition ordering, across versions and when changing imports.

Type: lazy attribute set of function that evaluates to a(n) function that evaluates to a(n) lazy attribute set of unspecified value

Default

{}

Example

{"_type":"literalExpression","text":"{\n  default = final: prev: {};\n}\n"}

flake.packages

See {option}perSystem.packages for description and examples.

Type: lazy attribute set of lazy attribute set of package

Default

{}

perInput

A function that pre-processes flake inputs.

It is called for users of perSystem such that inputs'.${name} = config.perInput system inputs.${name}.

This is used for inputs' and self'.

The attributes returned by the perInput function definitions are merged into a single namespace (per input), so each module should return an attribute set with usually only one or two predictable attribute names. Otherwise, the inputs' namespace gets polluted.

Type: function that evaluates to a(n) function that evaluates to a(n) lazy attribute set of unspecified value

perSystem

A function from system to flake-like attributes omitting the <system> attribute.

Modules defined here have access to the suboptions and some convenient module arguments.

Type: module

perSystem.apps

Programs runnable with nix run <name>.

Type: lazy attribute set of (submodule)

Default

{}

Example

{"_type":"literalExpression","text":"{\n  default.program = \"${config.packages.hello}/bin/hello\";\n}\n"}

perSystem.apps.<name>.program

A path to an executable or a derivation with meta.mainProgram.

Type: string or package convertible to it

perSystem.apps.<name>.type

A type tag for apps consumers.

Type: value "app" (singular enum)

Default

"app"

perSystem.checks

Derivations to be built by nix flake check.

Type: lazy attribute set of package

Default

{}

perSystem.debug

Values to return in e.g. allSystems.<system> when debug = true.

Type: lazy attribute set of raw value

perSystem.devShells

An attribute set of packages to be used as shells. nix develop .#<name> will run devShells.<name>.

Type: lazy attribute set of package

Default

{}

perSystem.formatter

A package used by nix fmt.

Type: null or package

Default

null

perSystem.legacyPackages

An attribute set of unmergeable values. This is also used by nix build .#<attrpath>.

Type: lazy attribute set of raw value

Default

{}

perSystem.offchain

A CTL project declaration, with arbitrarily many bundles, a devShell and optional tests.

In order to use this, your repository must provide the cardano-transaction-lib input.

Added in: 2.1.0.

Type: attribute set of (submodule)

Default

{}

perSystem.offchain.<name>.bundles

A map of bundles to be produced for this project.

Added in: 2.1.0.

Type: attribute set of (submodule)

Default

{}

perSystem.offchain.<name>.bundles.<name>.browserRuntime

Whether this bundle is being produced for a browser environment or not.

Added in: 2.1.0.

Type: boolean

Default

true

perSystem.offchain.<name>.bundles.<name>.bundledModuleName

The name of the file containing the bundled JS module that spago bundle-module will produce.

Added in: 2.1.0.

Type: string

Default

"output.js"

perSystem.offchain.<name>.bundles.<name>.enableCheck

Whether to add a flake check testing that the bundle builds correctly.

Added in: 2.1.0.

Type: boolean

Default

false

perSystem.offchain.<name>.bundles.<name>.entrypointJs

Stringified path to the webpack entrypoint file.

Added in: 2.1.0.

Type: string

Default

"index.js"

perSystem.offchain.<name>.bundles.<name>.includeBundledModule

Whether to include the spago bundle-module output in dist in the bundle.

Added in: 2.2.2.

Type: boolean

Default

true

perSystem.offchain.<name>.bundles.<name>.mainModule

The main Purescript module for the bundle (for instance, 'Main').

Added in: 2.1.0.

Type: string matching the pattern [[:upper:]][[:alnum:]](.[[:upper:]][[:alnum:]])*

perSystem.offchain.<name>.bundles.<name>.webpackConfig

Stringified path to the Webpack config file to use.

Added in: 2.1.0.

Type: string

Default

"webpack.config.js"

perSystem.offchain.<name>.compileStrict

Whether to compile the PureScript source with --strict

Added in: 2.8.0.

Type: boolean

Default

true

perSystem.offchain.<name>.enableFormatCheck

Whether to add a flake check verifying that the code (including the flake.nix and any JS files in the project) has been formatted.

Added in: 2.1.0.

Type: boolean

Default

false

perSystem.offchain.<name>.enableJsLintCheck

Whether to add a check verifying that the JS files in the project have been linted.

Added in: 2.1.0.

Type: boolean

Default

false

perSystem.offchain.<name>.ignoredWarningCodes

Warnings from purs to silence during compilation.

Added in: 2.1.0.

Type: list of string

Default

[]

perSystem.offchain.<name>.nodejsPackage

The nodejs package to use.

Type: package

Default

{"_type":"literalExpression","text":"pkgs.nodejs-14_x"}

perSystem.offchain.<name>.packageJson

Path to the project's package.json file.

Added in: 2.6.0.

Type: path

perSystem.offchain.<name>.packageLock

Path to the project's package-lock.json file.

Added in: 2.6.0.

Type: path

perSystem.offchain.<name>.pkgs

Package set to use. If specified, you must also manually apply CTL overlays.

Added in: 2.3.0.

Type: null or raw value

Default

null

perSystem.offchain.<name>.plutip

Options to configure the project's Plutip suite. If defined, a flake check will be created which runs the tests.

Added in: 2.1.0.

Type: null or (submodule)

Default

null

perSystem.offchain.<name>.plutip.buildInputs

Additional packages passed through to the buildInputs of the derivation.

Added in: 2.1.0.

Type: list of package

Default

[]

perSystem.offchain.<name>.plutip.testMain

The name of the main Purescript module containing the test suite.

Added in: 2.1.0.

Type: string matching the pattern [[:upper:]][[:alnum:]](.[[:upper:]][[:alnum:]])*

perSystem.offchain.<name>.runtime

Options to configure CTL's runtime.

Added in: 2.1.0.

Type: submodule

Default

{}

perSystem.offchain.<name>.runtime.enableCtlServer

Whether to enable or disable the CTL server (used to apply arguments to scripts and evaluate UPLC). Enabling this will also add the ctl-server overlay.

Added in: 2.1.0.

Type: boolean

Default

false

perSystem.offchain.<name>.runtime.exposeConfig

Whether to expose the runtime config as an attribute set in packages. Config is not a package so you may want to set it to false.

Added in: 2.3.0.

Type: boolean

Default

false

perSystem.offchain.<name>.runtime.extraConfig

Additional config options to pass to the CTL runtime. See runtime.nix in the CTL flake for a reference of the available options.

By default, the runtime is set to use the preview network and the same node version that CTL uses in its tests.

Added in: 2.1.0.

Type: attribute set of anything

Default

{}

perSystem.offchain.<name>.shell

Options to configure the project's devShell.

Added in: 2.1.0.

Type: submodule

Default

{}

perSystem.offchain.<name>.shell.extraCommandLineTools

List of extra packages to make available to the shell.

Added in: 2.1.0.

Type: list of package

Default

[]

perSystem.offchain.<name>.shell.shellHook

Shell code to run when the shell is started.

Added in: 2.3.0.

Type: strings concatenated with "\n"

Default

""

perSystem.offchain.<name>.spagoOverride

Override packages.dhall and use given flake for spago module.

Added in: 2.3.1.

Type: attribute set of (A flake input of spago module)

Default

{}

perSystem.offchain.<name>.src

Path to the project's source code, including its package.json and package-lock.json files.

Added in: 2.1.0.

Type: path

perSystem.offchain.<name>.tests

Options to configure the project's (non-Plutip) tests. If defined, a flake check will be created which runs the tests.

Added in: 2.1.0.

Type: null or (submodule)

Default

null

perSystem.offchain.<name>.tests.buildInputs

Additional packages passed through to the buildInputs of the derivation.

Added in: 2.1.0.

Type: list of package

Default

[]

perSystem.offchain.<name>.tests.testMain

The name of the main Purescript module containing the test suite.

Added in: 2.1.0.

Type: string matching the pattern [[:upper:]][[:alnum:]](.[[:upper:]][[:alnum:]])*

perSystem.onchain

On-chain project declaration

Type: attribute set of (submodule)

Default

{}

perSystem.onchain.<name>.applyRefact

Apply-refact-related options for the on-chain build.

Added in: 2.2.0

Type: submodule

perSystem.onchain.<name>.applyRefact.package

The apply-refact package to use.

Type: package

Default

{"_type":"literalExpression","text":"pkgs.haskell.packages.ghc924.apply-refact_0_10_0_0"}

perSystem.onchain.<name>.cabalFmt

Cabal-fmt-related options for the on-chain build.

Added in: 2.2.0

Type: submodule

perSystem.onchain.<name>.cabalFmt.package

The cabal-fmt package to use.

Type: package

Default

{"_type":"literalExpression","text":"pkgs.haskellPackages.cabal-fmt"}

perSystem.onchain.<name>.enableBuildChecks

Whether or not to enable adding the package builds to checks.

This is useful if you want to ensure package builds which are not tested by any tests.

Added in: 2.0.0.

Type: boolean

Default

true

perSystem.onchain.<name>.enableCabalFormatCheck

Whether or not to check for Cabal formatting correctness.

Added in: 2.0.0.

Type: boolean

Default

true

perSystem.onchain.<name>.enableHaskellFormatCheck

Whether or not to check for Haskell formatting correctness.

This will use the Haskell extensions configured in ghc.extensions.

Added in: 2.0.0.

Type: boolean

Default

true

perSystem.onchain.<name>.extraHackageDeps

List of packages to add to the hackage provided to haskell.nix.

These are packages that are not available on the public hackage and are manually sourced by your inputs.

Added in: 2.0.0.

Type: list of string

Default

[]

perSystem.onchain.<name>.fourmolu

Fourmolu-related options for the on-chain build.

Added in: 2.2.0

Type: submodule

perSystem.onchain.<name>.fourmolu.package

The fourmolu package to use.

Type: package

Default

{"_type":"literalExpression","text":"pkgs.haskell.packages.ghc924.fourmolu_0_9_0_0"}

perSystem.onchain.<name>.ghc

GHC-related options for the on-chain build.

Added in: 2.0.0.

Type: submodule

perSystem.onchain.<name>.ghc.extensions

The list of extensions to use with the project. List them out without the '-X' prefix.

Example: [ "TypeApplications" "QualifiedDo" ]

Added in: 2.0.0.

Type: list of string

Default

["QuasiQuotes","TemplateHaskell","TypeApplications","ImportQualifiedPost","PatternSynonyms","OverloadedRecordDot"]

perSystem.onchain.<name>.ghc.version

The version name of GHC to use.

Examples: ghc923, ghc925, ghc8107.

Added in: 2.0.0.

Type: string

Default

"ghc925"

perSystem.onchain.<name>.hasktags

Hasktags-related options for the on-chain build.

Added in: 2.2.0

Type: submodule

perSystem.onchain.<name>.hasktags.package

The hasktags package to use.

Type: package

Default

{"_type":"literalExpression","text":"pkgs.haskell.packages.ghc924.hasktags"}

perSystem.onchain.<name>.hlint

HLint-related options for the on-chain build.

Added in: 2.2.0

Type: submodule

perSystem.onchain.<name>.hlint.package

The hlint package to use.

Type: package

Default

{"_type":"literalExpression","text":"pkgs.haskell.packages.ghc924.hlint"}

perSystem.onchain.<name>.hoogleImage

Options for the hoogle image.

Added in: 2.5.0.

Type: submodule

perSystem.onchain.<name>.hoogleImage.enable

Whether or not to expose a docker image bundling the hoogle server with the packages available.

Added in: 2.5.0.

Type: boolean

Default

false

perSystem.onchain.<name>.hoogleImage.hoogleDirectory

Path to copy hoogle data dir from.

Added in: 2.5.0.

Type: null or path

Default

null

perSystem.onchain.<name>.shell

Options for the dev shell.

Added in: 2.0.0.

Type: submodule

perSystem.onchain.<name>.shell.extraCommandLineTools

List of extra packages to make available to the shell.

Added in: 2.0.0.

Type: list of package

Default

[]

perSystem.onchain.<name>.src

The source code of the project

Added in: 2.0.0.

Type: path

perSystem.packages

An attribute set of packages to be built by nix build.

nix build .#<name> will build packages.<name>.

Type: lazy attribute set of package

Default

{}

perSystem.run

Scripts that can be run using nix run.

These are intended to replace makefiles.

Added in: 2.0.0.

Type: attribute set of (submodule)

Default

{}

perSystem.run.<name>.dependencies

The dependencies to include in the script's environment.

Added in: 2.0.0.

Type: list of package

Default

[]

perSystem.run.<name>.doCheck

Whether this script should also be a check.

Added in: 2.0.0.

Type: boolean

Default

false

perSystem.run.<name>.groups

Setting group allows running multiple run scripts all at once.

These groups will be aliases to all of the scripts that tagged them.

Added in: 2.0.0.

Type: list of string

Default

[]

perSystem.run.<name>.help

Help message to provide when using nix run .#help -- <name>.

Added in: 2.0.0.

Type: string

Default

"No help provided."

perSystem.run.<name>.script

The script to run.

Added in: 2.0.0.

Type: string

systems

All the system types to enumerate in the flake output subattributes.

In other words, all valid values for system in e.g. packages.<system>.foo.

Type: list of string

transposition

A helper that defines transposed attributes in the flake outputs.

Transposition is the operation that swaps the indices of a data structure. Here it refers specifically to the transposition between

perSystem: .${system}.${attribute}
outputs:   .${attribute}.${system}

It also defines the reverse operation in {option}perInput.

Type: lazy attribute set of (submodule)

transposition.<name>.adHoc

Whether to provide a stub option declaration for {option}perSystem.<name>.

The stub option declaration does not support merging and lacks documentation, so you are recommended to declare the {option}perSystem.<name> option yourself and avoid {option}adHoc.

Type: boolean

Default

false