Skip to content

Latest commit

 

History

History
647 lines (601 loc) · 22 KB

reference.org

File metadata and controls

647 lines (601 loc) · 22 KB
Raw

Reference

spago.nix offers a number of functions providing Nix integration for Spago projects. These are contained in a top-level spago-nix namespace that can be accessed by applying its overlay (overlays.default provided by the spago.nix flake). This document provides an overview of the different library functions and data structures that are made available.

Table of Contents

Top-level attributes

spago-nix.spagoProject

This is the primary interface to working with spago.nix. It takes a src containing a Purescript project and generates several useful flake outputs along with several functions (see below)

Arguments :noexport:

name
(Required) The project name. Used to set the names of derivations generated in spagoProject
Type
string
src
(Required) A Nix store path pointing to the project sources
Type
path
shell
Holds configuration options for the generated devShell. The devShell will always contain a suitable version of purs and spago
Type
attribute set
Default
{
  # Purescript development tools, as made available under
  # `pkgs.purescriptPackages` (this is added by the overlay
  # from `difficult-purescript-nix`, which is automatically
  # applied for you when you apply `spago-nix.overlays.default`)
  #
  # This argument must be an attribute set, where each name
  # is mapped to either an empty attribute set (which implies
  # the latest version of the package), the string `"latest"`,
  # which implies the same, or a specific version, such as
  # `"0.16.6"`. Note that if you specify a version, the
  # `pkgs.purescriptPackages` set must contain the package with
  # the specified version as a suffix, e.g.:
  #
  # `pkgs.purescriptPackages.purescript-language-server-0_16_6`
  #
  # Whatever `tools` you specify here are also returned by
  # `spagoProject`, under the `tools` attribute
  tools = { };
  # Corresponds to `packages` argument of `pkgs.mkShell`
  packages = [ ];
  # If `true`, the Spago packages will be installed in `./.spago` in
  # the `devShell`'s `shellHook`
  install = true;
  # If `true`, `npm install` will only write to `package-lock.json`
  # (and never to `node_modules`)
  packageLockOnly = true;
  # Gets appended to the `shellHook` created for you in the `devShell`
  shellHook = "";
}
Example
{
  packages = {
    psa = { };
    purs-tidy = "latest";
    purescript-language-server = "0.16.6";
  };
  packageLockOnly = false;
  shellHook = ''
    echo 'my shell hook'
  '';
}
extraSources
A mapping from dependency names to their sources. Can be easily converted from flake inputs. Note: The sources provided must match the revisions in your packages.dhall exactly. Otherwise hard-to-debug errors will likely arise
Type
attribute set
Default
{ }
Example
{
  inherit (inputs) foo bar;
}
sha256map
A mapping from dependency names to their sha256 hashes and exact revisions. Can also be converted from flake inputs. Note: It is considerably more convenient and efficient to use extraSources, as the corresponding dependencies will be fetched from the network when using sha256map
Type
attribute set
Default
{ }
Example
{
  foo = {
    inherit (inputs.foo) rev;
    sha256 = inputs.foo.narHash;
  };
}
flags
Contains various flags used for compiling the project sources and installing dependencies
Type
attribute set
Default
{
  # Turns on `--strict` during compilation; corresponds to
  # `psa --strict ...`
  strict = true;
  # List of warnings to silence during compilation. For example
  # `[ "UserDefinedWarning" ]`
  censorCodes = [ ];
  # If set, the generated `node_modules` will also contain all
  # of the `devDependencies` declared in the `package.json`
  development = true;
}
Example
{
  censorCodes = [ "UserDefinedWarning" ];
  development = false;
}
nodejs
The specific version of nodejs to use. Will be used throughout the project components and in the devShell
Type
derivation
Default
pkgs.nodejs-14_x
Example
pkgs.nodejs-18_x
buildConfig
Holds paths to various build configuration files
Type
attribute set
Default
{
  packagesDhall = src + "/packages.dhall";
  spagoDhall = src + "/spago.dhall";
  packageJson = src + "/package.json";
  packageLock = src + "/package-lock.json";
}
Example
{
  spagoDhall = src + "/some/weird/path/spago.dhall";
}
withDocs
If true, spagoProject will build docs using default values for options and add them to the flake attribute that is returned. Even if this is false, you can still use the buildDocs builder to generate documentation
Type
boolean
Default
true
Example
false

spago-nix.utils.apps

This contains utilities for working with flake apps. As these can be applied outside of the context of spagoProject, they are not returned from that function unlike the other functions documented below

fromNodeApp

Turn a NodeJS app (e.g. using nodeApp ) into a flake app. If you pass arguments to the nix run invocation, these will be passed to the provided application.

Note: If you do pass command-line arguments, you should provide the command name as the first argument on the command line (Node’s proces.env.argv always contains the command’s name as its first element). Alternately, the provided app can be created using nodeAppWithArgs with a command argument and an empty list for its arguments (the default value). For example:

pkgs.spago-nix.utils.fromNodeApp {
  app = project.nodeAppWithArgs {
    main = "The.Main.Module";
    # or you can leave it empty, a default will be created
    command = "command-name";
    # this is the default
    arguments = [ ];
  };
}

Generally, however, this helper is not useful for nodeAppWithArgs: the resulting node invocation is always executed with the provided arguments

Returns

Flake app

Arguments

app
(Required) A derivation containing an executable in a bin directory and which can be called by Node
Type
derivation

fromDocs

Serve compiled documentation from localhost

Returns

Flake app

Arguments

docs
(Required) A derivation containing the compiled project documentation in the correct directories (generated-docs). Can be obtained from buildDocs
Type
derivation
port
The port on which the local webserver will run
Type
integer
Default
8080
Example
9999

spago-nix.utils.js

Contains Javascript-specific utilities

nodeModulesFor

Generates node_modules. This is called inside spagoProject and made available to users as it may be occasionally desirable to override the nodeModules that are used in different project derivations (e.g. to include/exclude the devDependencies listed in the package.json). Contains lib and bin subdirectories, the former holding the node_modules

Returns

derivation

Arguments

packageJson
(Required) Store path pointint to the package.json
Type
path
packageLock
(Required) Store path pointint to the package-lock.json
Type
path
name
String appended to the store path containing the generated modules
Type
string
Default
""
Example
"my-project" # produces `node-modules-my-project`
nodejs
The specific version of nodejs to use
Type
derivation
Default
pkgs.nodejs-14_x
Example
pkgs.nodejs-18_x
spago
The specific version of spago to use
Type
derivation
Default
pkgs.purescriptPackages.spago
Example
pkgs.purescriptPackages.spago-20_7
development
If true, the nodeModules will contain all devDependencies
Type
boolean
Default
true
Example
false

Library functions

These functions are made available in the attribute set returned by spagoProject . Because Spago has no mechanism for describing different project components (libraries, executables, tests, etc…), spago.nix cannot generate outputs for you automatically (some outputs can be generated and put into the flake attribute). To work around this, the following functions provide a more complete interface for different commands that spago offers

bundleModule

Bundles the project into a CommonJS module using the provided main module to the output filepath indicated by to

Returns

derivation

Arguments

main
The main Purescript module to bundle (the module name, not a filepath), used as the bundled module’s entrypoint
Type
string
Default
"Main"
Example
"Package.Module.Main"
to
The target filepath that the bundled module will be written to
Type
string
Default
"index.js"
Example
"output.js"
name
Overrides the name used for the derivation, which is otherwise derived from the name arg to spagoProject
Type
string
Example
"my-bundled-module"

bundleApp

Bundles the project into an executable that can be run with Node, using the provided main module to the output filepath indicated by to. Note: Although this is bundled into an app, it cannot be run on its own and is mostly useful if you want to use it in another derivation. You will still need to call node to execute it and set the NODE_PATH if necessary. You can also use nodeApp or nodeAppWithArgs , both of which perform these steps for you.

Returns

derivation

Arguments

main
The main Purescript module to bundle (the module name, not a filepath), used as the bundled app’s entrypoint
Type
string
Default
"Main"
Example
"Package.Module.Main"
to
The target filepath that the bundled app will be written to
Type
string
Default
"index.js"
Example
"output.js"
name
Overrides the name used for the derivation, which is otherwise derived from the name arg to spagoProject
Type
string
Example
"my-bundled-app"

runTest

Calls the Purescript entrypoint specified by testMain without writing to $out. Suitable for use as part of your flake checks (if the returns a non-zero exit code, the check will fail)

Returns

derivation

Arguments

testMain
The main Purescript module that acts as an entrypoint
Type
string
Default
"Test.Main"
Example
"Package.Module.Test.Main"
env
Environment or other variables; these are passed directly to runCommand. Can be useful if your test depends on looking up something in the environment
Type
attribute set
Default
{ }
Example
{
  ENV_VAR = "value";
}
nodeModules
Overrides the nodeModules used internally, which default to the project-wide ones
Type
derivation
Example
spago-nix.utils.js.mkNodeModules {
  development = false;
  /* snip */
}
name
Overrides the name used for the derivation, which is otherwise derived from the name arg to spagoProject
Type
string
Example
"my-test"

runTestWithArgs

Calls the Purescript entrypoint (specified by testMain) with Node and without writing to $out. Provides the specified command and arugments to the Node invocation; this is useful if your test requires or parses specific arguments. Also suitable for use as part of your flake checks (if the returns a non-zero exit code, the check will fail to build)

Returns

derivation

Arguments

testMain
The main Purescript module that acts as an entrypoint
Type
string
Default
"Test.Main"
Example
"Package.Module.Test.Main"
command
The command-line name. Node’s process.env.argv includes this as the first argument, so if we didn’t include it then the first argument would become the command name (an undesirable result)
Type
string
Default
builtins.replaceStrings [ "." ] [ "-" ]
  (lib.strings.toLower testMain)
Example
"my-test"
arguments
The arguments to provide to the command. These are joined into a single space-separated string and passed to the Node invocation
Type
list
Default
[ ]
Example
[ "--arg1" "val1" "--arg2" "val2" ]
env
Environment or other variables; these are passed directly to runCommand. Can be useful if your test depends on looking up something in the environment
Type
attribute set
Default
{ }
Example
{
  ENV_VAR = "value";
}
nodeModules
Overrides the nodeModules used internally, which default to the project-wide ones
Type
derivation
Example
spago-nix.utils.js.mkNodeModules {
  development = false;
  /* snip */
}
name
Overrides the name used for the derivation, which is otherwise derived from the name arg to spagoProject
Type
string
Example
"my-test"

nodeApp

Creates an executable from the Purescript entrypoint (specified by main) that calls Node, installing it to $out/bin/name. This is similar to bundleApp above, but calls node for you and also sets the correct NODE_PATH using the nodeModules that have been generated for the project (unless overridden)

Returns

derivation

Arguments

main
The main Purescript module that acts as an entrypoint
Type
string
Default
"Main"
Example
"Package.Module.Main"
env
Environment or other variables. These are export ed in a script that is provided to writeShellApplication, so you may want to use escapeShellArg as this is not done for you automatically. Can be useful if your test depends on looking up something in the environment
Type
attribute set
Default
{ }
Example
{
  ENV_VAR = "value";
}
nodeModules
Overrides the nodeModules used internally, which default to the project-wide ones
Type
derivation
Example
spago-nix.utils.js.mkNodeModules {
  development = false;
  /* snip */
}
name
Overrides the name used for the derivation, which is otherwise derived from the name arg to spagoProject
Type
string
Example
"my-node-app"

nodeAppWithArgs

Similar to nodeApp above, but also allows for passing a command name and list of arguments. Note: This is useful if you want to call an application with the same set of arguments each time – specifically, those passed with the provided list of arguments will always be used

Returns

derivation

Arguments

main
The main Purescript module that acts as an entrypoint
Type
string
Default
"Main"
Example
"Package.Module.Main"
env
Environment or other variables. These are export ed in a script that is provided to writeShellApplication, so you may want to use escapeShellArg as this is not done for you automatically. Can be useful if your test depends on looking up something in the environment
Type
attribute set
Default
{ }
Example
{
  ENV_VAR = "value";
}
nodeModules
Overrides the nodeModules used internally, which default to the project-wide ones
Type
derivation
Example
spago-nix.utils.js.mkNodeModules {
  development = false;
  /* snip */
}
name
Overrides the name used for the derivation, which is otherwise derived from the name arg to spagoProject
Type
string
Example
"my-node-app"

buildDocs

Compiles the project documentation, either solely for dependencies if depsOnly is enabled, or for all modules including the project sources (the default behavior). Note: If you set the withDocs argument to true (the default value) in spagoProject , a docs attribute will be built and added to flake.packages.

Returns

derivation

Arguments

format
The format for the resulting compiled documentation
Type
one of ”html” or ”markdown”
Default
"html"
Example
"markdown"
depsOnly
If true, documentation will only be compiled for the project’s dependencies
Type
boolean
Default
false
Example
true

Other

flake

This is a set returned from the spagoProject function and contains the following attributes. Its structure mirrors the outputs of a flake.nix:

devShells

default
Contains a development environment corresponding to the options provided to spagoProject’s shell argument. Irrespective of the selected options, it will always contain a version of purs that corresponds to your upstream package set as well as spago. Also aliased to the devShell attribute

packages

output
This holds the output directory that is created by purs when compiling the project’s sources. It can be used in subsequent derivations. It copies the src as well: if you read from a file from a relative path in your Purescript code, purs doesn’t copy it into the output directory. This behavior may change in the future.
docs
This is only added to the flake if withDocs is enabled (the default). It contains the generated-docs and output directory produced by spago docs. It uses the default format (html) and includes the project’s sources as well. If you set withDocs to false, you can still build documentation with more customization options using buildDocs (but it will not be automatically added to the flake of course)

apps

docs
As with packages.docs, this is only added to the flake if withDocs is enabled. It builds uses that derivation to serve documentation on localhost:8080. If you do not enable withDocs, then you can use spago-nix.utils.apps.fromDocs to create a local documentation server with more options

tools

This is a set containing the Purescript packages used to build the project. It will always contain the version of purs selected for your project as well as spago. If you provide a list of tools in the shell argument to spagoProject, it will also contain those (e.g. purs-tidy).