From 5bbb538e7261294c694fce1534efcf2d9b02672b Mon Sep 17 00:00:00 2001
From: Corbin <cds@corbinsimpson.com>
Date: Tue, 17 Aug 2021 09:56:42 -0700
Subject: [PATCH] doc: Explain how to use and maintain CHICKEN.

Also add information about egg2nix.

Includes suggestions from code review.

Co-authored-by: sterni <sternenseemann@systemli.org>
---
 doc/languages-frameworks/chicken.section.md | 49 +++++++++++++++++++++
 doc/languages-frameworks/index.xml          |  1 +
 2 files changed, 50 insertions(+)
 create mode 100644 doc/languages-frameworks/chicken.section.md

diff --git a/doc/languages-frameworks/chicken.section.md b/doc/languages-frameworks/chicken.section.md
new file mode 100644
index 000000000000..d8c35bd20c50
--- /dev/null
+++ b/doc/languages-frameworks/chicken.section.md
@@ -0,0 +1,49 @@
+# CHICKEN {#sec-chicken}
+
+[CHICKEN](https://call-cc.org/) is a
+[R⁵RS](https://schemers.org/Documents/Standards/R5RS/HTML/)-compliant Scheme
+compiler. It includes an interactive mode and a custom package format, "eggs".
+
+## Using Eggs
+
+Eggs described in nixpkgs are available inside the
+`chickenPackages.chickenEggs` attrset. Including an egg as a build input is
+done in the typical Nix fashion. For example, to include support for [SRFI
+189](https://srfi.schemers.org/srfi-189/srfi-189.html) in a derivation, one
+might write:
+
+```nix
+  buildInputs = [
+    chicken
+    chickenPackages.chickenEggs.srfi-189
+  ];
+```
+
+Both `chicken` and its eggs have a setup hook which configures the environment
+variables `CHICKEN_INCLUDE_PATH` and `CHICKEN_REPOSITORY_PATH`.
+
+## Updating Eggs
+
+nixpkgs only knows about a subset of all published eggs. It uses
+[egg2nix](https://github.com/the-kenny/egg2nix) to generate a
+package set from a list of eggs to include.
+
+The package set is regenerated by running the following shell commands:
+
+```
+$ nix-shell -p chickenPackages.egg2nix
+$ cd pkgs/development/compilers/chicken/5/
+$ egg2nix eggs.scm > eggs.nix
+```
+
+## Adding Eggs
+
+When we run `egg2nix`, we obtain one collection of eggs with
+mutually-compatible versions. This means that when we add new eggs, we may
+need to update existing eggs. To keep those separate, follow the procedure for
+updating eggs before including more eggs.
+
+To include more eggs, edit `pkgs/development/compilers/chicken/5/eggs.scm`.
+The first section of this file lists eggs which are required by `egg2nix`
+itself; all other eggs go into the second section. After editing, follow the
+procedure for updating eggs.
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index f221693e764c..2c34a29d4863 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -9,6 +9,7 @@
  <xi:include href="android.section.xml" />
  <xi:include href="beam.section.xml" />
  <xi:include href="bower.section.xml" />
+ <xi:include href="chicken.section.xml" />
  <xi:include href="coq.section.xml" />
  <xi:include href="crystal.section.xml" />
  <xi:include href="dhall.section.xml" />