~thatonelutenist/idr2nix

clone

read-only
https://git.sr.ht/~thatonelutenist/idr2nix
read/write
git@git.sr.ht:~thatonelutenist/idr2nix

You can also use your local clone with git send-email.

#idr2nix

idr2nix is a work in progress utility for adapting Idris 2 projects to Nix flakes, using the idris2-pack database.

#idr2nix CLI Usage

#Installation

Addition of this repository to your nix flakes registry and utilization of nix run is recommended:

nix registry add idr2nix 'git+https://git.sr.ht/~thatonelutenist/idr2nix?ref=trunk'
nix run idr2nix -- --help

The remainder of this readme will assume that you have this registry entry

#Initialization and Updating

The state directory (.idr2nix by default) must first be initialized, this is recommend in the root directory of the project, but can be anywhere on the system:

nix run idr2nix -- init

This will automatically pull down a copy of the pack database, and set the collection to latest nightly.

The pack database can be updated with the update-pack subcommand, and the -u/--update-collection flag can be used to change the collection in use to the current latest nightly:

# Just update the pack database
nix run idr2nix -- update-pack
# Also update the collection in use to latest nightly
nix run idr2nix -- update-pack -u

#Generating a sources.json

The gen-sources subcommand is used to generate the sources.json file used by the nix code to build Idris packages and development environments as a pure operation. The JSON output locks the exact version of the compiler and all the dependencies, including the hashes that nix needs to produce fixed-output derivations.

The output is provided on stdout, so you will want to pipe this into a file:

nix run idr2nix -- gen-sources package.ipkg > sources.json

This will parse the provided ipkg, use the pack database to resolve the dependencies, prefetch them to generate the hashes, and then output the sources JSON.

#Dealing with multiple ipkg files

The gen-sources subcommand can take multiple ipkgs as arguments, producing a single merged sources.json that contains all the dependencies for all the provided ipgks:

nix run idr2nix -- gen-sources package1.ipkg package2.ipkg > sources.json

#idr2nix flake usage

First, add idr2nix to your inputs, optionally instructing it to follow your nixpkgs:

{
  inputs = {
    idr2nix.url = "git+https://git.sr.ht/~thatonelutenist/idr2nix?ref=trunk";
    idr2nix.inputs.nixpkgs.follows = "nixpkgs";
  };
}

#Package a single binary

The idris.single attribute is a function that generates the flake contents for an Idris project packaging a single binary output and an associated devShell, it takes the following arguments:

  • packageName: The name of the package to generate
  • sources: The contents of the generated sources JSON
  • ipkg: The ipkg to build the binary from
  • src: The location of the Idris project to build (usually ./.)
  • idris2api: Whether or not to include the idris2api in the generated Idris prefix by default (false by default)
  • extraDeps: A function taking in the nixpkgs package collection and returning a list of packages to be included in the buildInputs of the resulting Idris2 package, empty by default
  • extraNativeDeps: A function taking in the nixpkgs package collection and returning a list of packages to be included in the nativeBuildInputs of the resulting Idris2 package, empty by default
  • extraBuildArgs: An attribute set that gets merged with the mkDerivation arguments used to build the idris prefix as well as the mkShell arguments used to build the devShell
  • extraShellPackages: A function taking in the nixpkgs package collection as an argument, and returning a list of packages to add to the devShell

Both the contents of extraDeps as well as extraNativeDeps will be included in the generated devShell by default.

An example flake.nix packaging pack, which requires the idris2api package:

{
  inputs = { idr2nix.url = "git+https://git.sr.ht/~thatonelutenist/idr2nix?ref=trunk"; };
  description = "Simple Test Package";

  outputs = { self, nixpkgs, idr2nix }:
    idr2nix.idris.single {
      packageName = "pack";
      sources = builtins.fromJSON (builtins.readFile ./pack.json);
      ipkg = "pack.ipkg";
      src = ./.;
      idris2api = true;
    };
}

#Package multiple binaries

The idris.multiple attribute is a function that generates the flake contents for an Idris project packaging multiple binary outputs and an associated devShell, it takes the following arguments:

  • packageDetails: A list of attrSets containing the name and ipkg values for each of the binary packages to generate
  • sources: The contents of the generated sources JSON
  • src: The location of the Idris project to build (usually ./.)
  • idris2api: Whether or not to include the idris2api in the generated Idris prefix by default (false by default)
  • extraDeps: A function taking in the nixpkgs package collection and returning a list of packages to be included in the buildInputs of the resulting Idris2 package, empty by default
  • extraNativeDeps: A function taking in the nixpkgs package collection and returning a list of packages to be included in the nativeBuildInputs of the resulting Idris2 package, empty by default
  • extraBuildArgs: An attribute set that gets merged with the mkDerivation arguments (for all packages) used to build the idris prefix as well as the mkShell arguments used to build the devShell
  • extraShellPackages: A function taking in the nixpkgs package collection as an argument, and returning a list of packages to add to the devShell

Both the contents of extraDeps as well as extraNativeDeps will be included in the generated devShell by default.

An example flake.nix packaging pack and micropack, both from the pack repository:

{
  inputs = { idr2nix.url = "git+https://git.sr.ht/~thatonelutenist/idr2nix?ref=trunk"; };
  description = "Simple Test Package";

  outputs = { self, nixpkgs, idr2nix }:
    idr2nix.idris.multiple {
      sources = builtins.fromJSON (builtins.readFile ./pack.json);
      packageDetails = [
        {
          name = "pack";
          ipkg = "pack.ipkg";
        }
        {
          name = "micropack";
          ipkg = "micropack.ipkg";
        }
      ];
      defaultPackage = "pack";
      src = ./.;
      idris2api = true;
    };
}