From 5bbb538e7261294c694fce1534efcf2d9b02672b Mon Sep 17 00:00:00 2001 From: Corbin Date: Tue, 17 Aug 2021 09:56:42 -0700 Subject: doc: Explain how to use and maintain CHICKEN. Also add information about egg2nix. Includes suggestions from code review. Co-authored-by: sterni --- 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 (limited to 'doc/languages-frameworks') diff --git a/doc/languages-frameworks/chicken.section.md b/doc/languages-frameworks/chicken.section.md new file mode 100644 index 0000000000000..d8c35bd20c506 --- /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 f221693e764c8..2c34a29d4863f 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -9,6 +9,7 @@ + -- cgit 1.4.1