diff options
author | Alyssa Ross <hi@alyssa.is> | 2021-06-22 15:01:47 +0000 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2021-06-22 16:57:59 +0000 |
commit | 633cab0ecb07627706c6b523e219490f019eaab5 (patch) | |
tree | 4fb472bdfe2723037dad53dc1b8a87c939015f5e /nixpkgs/doc/languages-frameworks/agda.section.md | |
parent | ffb691c199e7e0cbc4e45e5310779c9e3f7c2a73 (diff) | |
parent | 432fc2d9a67f92e05438dff5fdc2b39d33f77997 (diff) | |
download | nixlib-633cab0ecb07627706c6b523e219490f019eaab5.tar nixlib-633cab0ecb07627706c6b523e219490f019eaab5.tar.gz nixlib-633cab0ecb07627706c6b523e219490f019eaab5.tar.bz2 nixlib-633cab0ecb07627706c6b523e219490f019eaab5.tar.lz nixlib-633cab0ecb07627706c6b523e219490f019eaab5.tar.xz nixlib-633cab0ecb07627706c6b523e219490f019eaab5.tar.zst nixlib-633cab0ecb07627706c6b523e219490f019eaab5.zip |
Merge commit '432fc2d9a67f92e05438dff5fdc2b39d33f77997'
# Conflicts: # nixpkgs/pkgs/applications/editors/emacs/elisp-packages/elpa-generated.nix # nixpkgs/pkgs/applications/networking/mailreaders/thunderbird/default.nix # nixpkgs/pkgs/applications/window-managers/sway/default.nix # nixpkgs/pkgs/build-support/rust/default.nix # nixpkgs/pkgs/development/go-modules/generic/default.nix
Diffstat (limited to 'nixpkgs/doc/languages-frameworks/agda.section.md')
-rw-r--r-- | nixpkgs/doc/languages-frameworks/agda.section.md | 132 |
1 files changed, 110 insertions, 22 deletions
diff --git a/nixpkgs/doc/languages-frameworks/agda.section.md b/nixpkgs/doc/languages-frameworks/agda.section.md index 30a266502bf3..2b7c35f68d3b 100644 --- a/nixpkgs/doc/languages-frameworks/agda.section.md +++ b/nixpkgs/doc/languages-frameworks/agda.section.md @@ -1,17 +1,20 @@ # Agda {#agda} -## How to use Agda +## How to use Agda {#how-to-use-agda} -Agda can be installed from `agda`: -```ShellSession -$ nix-env -iA agda -``` +Agda is available as the [agda](https://search.nixos.org/packages?channel=unstable&show=agda&from=0&size=30&sort=relevance&query=agda) +package. -To use Agda with libraries, the `agda.withPackages` function can be used. This function either takes: +The `agda` package installs an Agda-wrapper, which calls `agda` with `--library-file` +set to a generated library-file within the nix store, this means your library-file in +`$HOME/.agda/libraries` will be ignored. By default the agda package installs Agda +with no libraries, i.e. the generated library-file is empty. To use Agda with libraries, +the `agda.withPackages` function can be used. This function either takes: * A list of packages, * or a function which returns a list of packages when given the `agdaPackages` attribute set, * or an attribute set containing a list of packages and a GHC derivation for compilation (see below). +* 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). For example, suppose we wanted a version of Agda which has access to the standard library. This can be obtained with the expressions: @@ -27,26 +30,86 @@ agda.withPackages (p: [ p.standard-library ]) or can be called as in the [Compiling Agda](#compiling-agda) section. -If you want to use a library in your home directory (for instance if it is a development version) then typecheck it manually (using `agda.withPackages` if necessary) and then override the `src` attribute of the package to point to your local repository. +If you want to use a different version of a library (for instance a development version) +override the `src` attribute of the package to point to your local repository -Agda will not by default use these libraries. To tell Agda to use the library we have some options: +```nix +agda.withPackages (p: [ + (p.standard-library.overrideAttrs (oldAttrs: { + version = "local version"; + src = /path/to/local/repo/agda-stdlib; + })) +]) +``` -* Call `agda` with the library flag: -```ShellSession -$ agda -l standard-library -i . MyFile.agda +You can also reference a GitHub repository + +```nix +agda.withPackages (p: [ + (p.standard-library.overrideAttrs (oldAttrs: { + version = "1.5"; + src = fetchFromGitHub { + repo = "agda-stdlib"; + owner = "agda"; + rev = "v1.5"; + sha256 = "16fcb7ssj6kj687a042afaa2gq48rc8abihpm14k684ncihb2k4w"; + }; + })) +]) ``` -* Write a `my-library.agda-lib` file for the project you are working on which may look like: + +If you want to use a library not added to Nixpkgs, you can add a +dependency to a local library by calling `agdaPackages.mkDerivation`. + +```nix +agda.withPackages (p: [ + (p.mkDerivation { + pname = "your-agda-lib"; + version = "1.0.0"; + src = /path/to/your-agda-lib; + }) +]) ``` -name: my-library -include: . -depend: standard-library + +Again you can reference GitHub + +```nix +agda.withPackages (p: [ + (p.mkDerivation { + pname = "your-agda-lib"; + version = "1.0.0"; + src = fetchFromGitHub { + repo = "repo"; + owner = "owner"; + version = "..."; + rev = "..."; + sha256 = "..."; + }; + }) +]) ``` + +See [Building Agda Packages](#building-agda-packages) for more information on `mkDerivation`. + +Agda will not by default use these libraries. To tell Agda to use a library we have some options: + +* Call `agda` with the library flag: + ```ShellSession + $ agda -l standard-library -i . MyFile.agda + ``` +* Write a `my-library.agda-lib` file for the project you are working on which may look like: + ``` + name: my-library + include: . + depend: standard-library + ``` * Create the file `~/.agda/defaults` and add any libraries you want to use by default. More information can be found in the [official Agda documentation on library management](https://agda.readthedocs.io/en/v2.6.1/tools/package-system.html). -## Compiling Agda -Agda modules can be compiled with the `--compile` flag. A version of `ghc` with `ieee754` is made available to the Agda program via the `--with-compiler` flag. +## Compiling Agda {#compiling-agda} + +Agda 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. This can be overridden by a different version of `ghc` as follows: ```nix @@ -56,7 +119,8 @@ agda.withPackages { } ``` -## Writing Agda packages +## Writing Agda packages {#writing-agda-packages} + To write a nix derivation for an Agda library, first check that the library has a `*.agda-lib` file. A derivation can then be written using `agdaPackages.mkDerivation`. This has similar arguments to `stdenv.mkDerivation` with the following additions: @@ -65,25 +129,48 @@ A derivation can then be written using `agdaPackages.mkDerivation`. This has sim * `libraryName` should be the name that appears in the `*.agda-lib` file, defaulting to `pname`. * `libraryFile` should be the file name of the `*.agda-lib` file, defaulting to `${libraryName}.agda-lib`. -### Building Agda packages +Here is an example `default.nix` + +```nix +{ nixpkgs ? <nixpkgs> }: +with (import nixpkgs {}); +agdaPackages.mkDerivation { + version = "1.0"; + pname = "my-agda-lib"; + src = ./.; + buildInputs = [ + agdaPackages.standard-library + ]; +} +``` + +### Building Agda packages {#building-agda-packages} + The default build phase for `agdaPackages.mkDerivation` simply runs `agda` on the `Everything.agda` file. If something else is needed to build the package (e.g. `make`) then the `buildPhase` should be overridden. Additionally, a `preBuild` or `configurePhase` can be used if there are steps that need to be done prior to checking the `Everything.agda` file. `agda` and the Agda libraries contained in `buildInputs` are made available during the build phase. -### Installing Agda packages +### Installing Agda packages {#installing-agda-packages} + The default install phase copies Agda source files, Agda interface files (`*.agdai`) and `*.agda-lib` files to the output directory. This can be overridden. By 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. -## Adding Agda packages to Nixpkgs +## Adding Agda packages to Nixpkgs {#adding-agda-packages-to-nixpkgs} To 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: + ```nix { mkDerivation, standard-library, fetchFromGitHub }: ``` -and `mkDerivation` should be called instead of `agdaPackages.mkDerivation`. Here is an example skeleton derivation for iowa-stdlib: + +Note that the derivation function is called with `mkDerivation` set to `agdaPackages.mkDerivation`, therefore you +could use a similar set as in your `default.nix` from [Writing Agda Packages](#writing-agda-packages) with +`agdaPackages.mkDerivation` replaced with `mkDerivation`. + +Here is an example skeleton derivation for iowa-stdlib: ```nix mkDerivation { @@ -101,6 +188,7 @@ mkDerivation { ''; } ``` + This 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`. When 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). |