Merge pull request #110491 from neosimsim/agda-doc-fix-install-command

agda: fix code snippet for installing Agda

1 files changed, 90 insertions, 9 deletions

diff --git a/doc/languages-frameworks/agda.section.md b/doc/languages-frameworks/agda.section.md
index 30a266502bf..1675fcb0a79 100644
--- a/doc/languages-frameworks/agda.section.md
+++ b/doc/languages-frameworks/agda.section.md
@@ -2,16 +2,19 @@
 
 ## 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,9 +30,66 @@ 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
+
+```nix
+agda.withPackages (p: [
+  (p.standard-library.overrideAttrs (oldAttrs: {
+    version = "local version";
+    src = /path/to/local/repo/agda-stdlib;
+  }))
+])
+```
+
+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";
+    };
+  }))
+])
+```
+
+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;
+  })
+])
+```
+
+Again you can reference GitHub
 
-Agda will not by default use these libraries. To tell Agda to use the library we have some options:
+```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
@@ -46,7 +106,7 @@ depend: standard-library
 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.
+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
@@ -65,6 +125,21 @@ 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`.
 
+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
 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.
@@ -80,10 +155,16 @@ By default, Agda sources are files ending on `.agda`, or literate Agda files end
 ## 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 {