# idr2nix

[`idr2nix`](https://sr.ht/~thatonelutenist/idr2nix/) is a work in progress
utility for adapting [Idris 2](https://github.com/idris-lang/Idris2) projects to
[Nix](https://nixos.org/) flakes, using the
[idris2-pack](https://github.com/stefan-hoeck/idris2-pack)
[database](https://github.com/stefan-hoeck/idris2-pack-db).

# `idr2nix` CLI Usage

## Installation

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

```sh
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:

```sh
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:

```sh
# 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:

```sh
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`:

```sh
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:

```nix
{
  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

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:

```nix
{
  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

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:

```nix
{
  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;
    };
}
```