diff options
author | Jan Tojnar <jtojnar@gmail.com> | 2021-06-05 21:22:45 +0200 |
---|---|---|
committer | Jan Tojnar <jtojnar@gmail.com> | 2021-06-07 06:34:59 +0200 |
commit | 6ecc641d087df8b8896ebd876bba592e981877c9 (patch) | |
tree | c3dc98e6b6a4a6474b21ad06e7bbc96d0e8abaf5 /doc/languages-frameworks/agda.section.md | |
parent | ce6b1a4f8f9cbbb7fd2d1c637bcc39fff1ef49df (diff) | |
download | nixlib-6ecc641d087df8b8896ebd876bba592e981877c9.tar nixlib-6ecc641d087df8b8896ebd876bba592e981877c9.tar.gz nixlib-6ecc641d087df8b8896ebd876bba592e981877c9.tar.bz2 nixlib-6ecc641d087df8b8896ebd876bba592e981877c9.tar.lz nixlib-6ecc641d087df8b8896ebd876bba592e981877c9.tar.xz nixlib-6ecc641d087df8b8896ebd876bba592e981877c9.tar.zst nixlib-6ecc641d087df8b8896ebd876bba592e981877c9.zip |
doc: prepare for commonmark
We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly. Notably: - Line breaks in lists behave differently. - Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75 - The auto_identifiers uses a different algorithm – I made the previous ones explicit. - Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist While at it, I also fixed the following issues: - ShellSesssion was used - Removed some pointless docbook tags.
Diffstat (limited to 'doc/languages-frameworks/agda.section.md')
-rw-r--r-- | doc/languages-frameworks/agda.section.md | 35 |
1 files changed, 21 insertions, 14 deletions
diff --git a/doc/languages-frameworks/agda.section.md b/doc/languages-frameworks/agda.section.md index 1675fcb0a79c..2b7c35f68d3b 100644 --- a/doc/languages-frameworks/agda.section.md +++ b/doc/languages-frameworks/agda.section.md @@ -1,6 +1,6 @@ # Agda {#agda} -## How to use Agda +## How to use Agda {#how-to-use-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. @@ -43,6 +43,7 @@ agda.withPackages (p: [ ``` You can also reference a GitHub repository + ```nix agda.withPackages (p: [ (p.standard-library.overrideAttrs (oldAttrs: { @@ -59,6 +60,7 @@ agda.withPackages (p: [ 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 { @@ -92,20 +94,21 @@ See [Building Agda Packages](#building-agda-packages) for more information on `m 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 -``` + ```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 -``` + ``` + 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 +## 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: @@ -116,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: @@ -140,19 +144,21 @@ agdaPackages.mkDerivation { } ``` -### Building Agda packages +### 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: @@ -182,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). |