pyrox.dev
1# Agda {#agda}
2
3## How to use Agda
4
5Agda is available as the [agda](https://search.nixos.org/packages?channel=unstable&show=agda&from=0&size=30&sort=relevance&query=agda)
6package.
7
8The `agda` package installs an Agda-wrapper, which calls `agda` with `--library-file`
9set to a generated library-file within the nix store, this means your library-file in
10`$HOME/.agda/libraries` will be ignored. By default the agda package installs Agda
11with no libraries, i.e. the generated library-file is empty. To use Agda with libraries,
12the `agda.withPackages` function can be used. This function either takes:
13
14* A list of packages,
15* or a function which returns a list of packages when given the `agdaPackages` attribute set,
16* or an attribute set containing a list of packages and a GHC derivation for compilation (see below).
17* or an attribute set containing a function which returns a list of packages when given the `agdaPackages` attribute set and a GHC derivation for compilation (see below).
18
19For example, suppose we wanted a version of Agda which has access to the standard library. This can be obtained with the expressions:
20
21```nix
22agda.withPackages [ agdaPackages.standard-library ]
23```
24
25or
26
27```nix
28agda.withPackages (p: [ p.standard-library ])
29```
30
31or can be called as in the [Compiling Agda](#compiling-agda) section.
32
33If you want to use a different version of a library (for instance a development version)
34override the `src` attribute of the package to point to your local repository
35
36```nix
37agda.withPackages (p: [
38 (p.standard-library.overrideAttrs (oldAttrs: {
39 version = "local version";
40 src = /path/to/local/repo/agda-stdlib;
41 }))
42])
43```
44
45You can also reference a GitHub repository
46```nix
47agda.withPackages (p: [
48 (p.standard-library.overrideAttrs (oldAttrs: {
49 version = "1.5";
50 src = fetchFromGitHub {
51 repo = "agda-stdlib";
52 owner = "agda";
53 rev = "v1.5";
54 sha256 = "16fcb7ssj6kj687a042afaa2gq48rc8abihpm14k684ncihb2k4w";
55 };
56 }))
57])
58```
59
60If you want to use a library not added to Nixpkgs, you can add a
61dependency to a local library by calling `agdaPackages.mkDerivation`.
62```nix
63agda.withPackages (p: [
64 (p.mkDerivation {
65 pname = "your-agda-lib";
66 version = "1.0.0";
67 src = /path/to/your-agda-lib;
68 })
69])
70```
71
72Again you can reference GitHub
73
74```nix
75agda.withPackages (p: [
76 (p.mkDerivation {
77 pname = "your-agda-lib";
78 version = "1.0.0";
79 src = fetchFromGitHub {
80 repo = "repo";
81 owner = "owner";
82 version = "...";
83 rev = "...";
84 sha256 = "...";
85 };
86 })
87])
88```
89
90See [Building Agda Packages](#building-agda-packages) for more information on `mkDerivation`.
91
92Agda will not by default use these libraries. To tell Agda to use a library we have some options:
93
94* Call `agda` with the library flag:
95```ShellSession
96$ agda -l standard-library -i . MyFile.agda
97```
98* Write a `my-library.agda-lib` file for the project you are working on which may look like:
99```
100name: my-library
101include: .
102depend: standard-library
103```
104* Create the file `~/.agda/defaults` and add any libraries you want to use by default.
105
106More information can be found in the [official Agda documentation on library management](https://agda.readthedocs.io/en/v2.6.1/tools/package-system.html).
107
108## Compiling Agda
109Agda modules can be compiled using the GHC backend with the `--compile` flag. A version of `ghc` with `ieee754` is made available to the Agda program via the `--with-compiler` flag.
110This can be overridden by a different version of `ghc` as follows:
111
112```nix
113agda.withPackages {
114 pkgs = [ ... ];
115 ghc = haskell.compiler.ghcHEAD;
116}
117```
118
119## Writing Agda packages
120To write a nix derivation for an Agda library, first check that the library has a `*.agda-lib` file.
121
122A derivation can then be written using `agdaPackages.mkDerivation`. This has similar arguments to `stdenv.mkDerivation` with the following additions:
123
124* `everythingFile` can be used to specify the location of the `Everything.agda` file, defaulting to `./Everything.agda`. If this file does not exist then either it should be patched in or the `buildPhase` should be overridden (see below).
125* `libraryName` should be the name that appears in the `*.agda-lib` file, defaulting to `pname`.
126* `libraryFile` should be the file name of the `*.agda-lib` file, defaulting to `${libraryName}.agda-lib`.
127
128Here is an example `default.nix`
129
130```nix
131{ nixpkgs ? <nixpkgs> }:
132with (import nixpkgs {});
133agdaPackages.mkDerivation {
134 version = "1.0";
135 pname = "my-agda-lib";
136 src = ./.;
137 buildInputs = [
138 agdaPackages.standard-library
139 ];
140}
141```
142
143### Building Agda packages
144The default build phase for `agdaPackages.mkDerivation` simply runs `agda` on the `Everything.agda` file.
145If something else is needed to build the package (e.g. `make`) then the `buildPhase` should be overridden.
146Additionally, a `preBuild` or `configurePhase` can be used if there are steps that need to be done prior to checking the `Everything.agda` file.
147`agda` and the Agda libraries contained in `buildInputs` are made available during the build phase.
148
149### Installing Agda packages
150The default install phase copies Agda source files, Agda interface files (`*.agdai`) and `*.agda-lib` files to the output directory.
151This can be overridden.
152
153By default, Agda sources are files ending on `.agda`, or literate Agda files ending on `.lagda`, `.lagda.tex`, `.lagda.org`, `.lagda.md`, `.lagda.rst`. The list of recognised Agda source extensions can be extended by setting the `extraExtensions` config variable.
154
155## Adding Agda packages to Nixpkgs
156
157To add an Agda package to `nixpkgs`, the derivation should be written to `pkgs/development/libraries/agda/${library-name}/` and an entry should be added to `pkgs/top-level/agda-packages.nix`. Here it is called in a scope with access to all other Agda libraries, so the top line of the `default.nix` can look like:
158
159```nix
160{ mkDerivation, standard-library, fetchFromGitHub }:
161```
162
163Note that the derivation function is called with `mkDerivation` set to `agdaPackages.mkDerivation`, therefore you
164could use a similar set as in your `default.nix` from [Writing Agda Packages](#writing-agda-packages) with
165`agdaPackages.mkDerivation` replaced with `mkDerivation`.
166
167Here is an example skeleton derivation for iowa-stdlib:
168
169```nix
170mkDerivation {
171 version = "1.5.0";
172 pname = "iowa-stdlib";
173
174 src = ...
175
176 libraryFile = "";
177 libraryName = "IAL-1.3";
178
179 buildPhase = ''
180 patchShebangs find-deps.sh
181 make
182 '';
183}
184```
185This library has a file called `.agda-lib`, and so we give an empty string to `libraryFile` as nothing precedes `.agda-lib` in the filename. This file contains `name: IAL-1.3`, and so we let `libraryName = "IAL-1.3"`. This library does not use an `Everything.agda` file and instead has a Makefile, so there is no need to set `everythingFile` and we set a custom `buildPhase`.
186
187When writing an Agda package it is essential to make sure that no `.agda-lib` file gets added to the store as a single file (for example by using `writeText`). This causes Agda to think that the nix store is a Agda library and it will attempt to write to it whenever it typechecks something. See [https://github.com/agda/agda/issues/4613](https://github.com/agda/agda/issues/4613).