Eggs Tutorial - The CHICKEN Scheme wiki

Introduction

This document explains how to create an official CHICKEN Extension.

CHICKEN extensions can greatly enhance the functionality available in CHICKEN. They can define and export new convenient functions, wrap and make available libraries written in other languages (typically C) or even extend the basic language.

A good way to start getting involved in the CHICKEN community is to contribute new eggs. Not only this will benefit other users, who will now be able to use your egg, it will also benefit you as you'll gain access to all the infrastructure for managing eggs (eg. you will be able to install your eggs using chicken-install) and other users might start helping improve your eggs. You can create an egg from software you've written yourself, or else with free software libraries you've ported from other Schemes (or even other languages).

Naming your extension

Egg names tend to follow a very simple naming scheme. Most eggs use only lowercase ASCII letters, digits and dashes.

Although it should be technically possible to have other characters in egg names (e.g., uppercase letters, underscore, plus sign), it's highly recommendable to stick to avoid them, if anything, for the sake of consistency.

The following characters are allowed in egg names:

   0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ+-_

The chicken name is reserved, as it can be used by eggs to specify the minimum required version of CHICKEN.

Programming your extension

Code layout

You should always use the module system for extensions to avoid creating name-conflicts if one of your exported toplevel identifiers clashes with an already existing definition. Modules also allow to export syntax definitions in a clean and easy-to-use way.

Documentation

Providing good documentation for your eggs is a fundamental part of their overall quality. Documentation for eggs is stored in wiki format in the CHICKEN subversion repository (see this document for information on how to request an account).

You can enter your entire documentation for your egg into this wiki. This has the advantage of inviting other members of the CHICKEN community to help improve the documentation for your eggs. Also, eggs documented in the CHICKEN wiki are automatically indexed by our API browser.

You can either use your favourite text editor to edit wiki files (then commit your changes to the subversion repository) or point your browser to http://wiki.call-cc.org/eggref/5/eggname-here and use it to edit the wiki contents.

If you decide to edit the wiki files locally using a text editor then commiting to the repository, you'll need to check out a copy of the subversion repository for wiki files:

 $ svn co https://code.call-cc.org/svn/chicken-eggs/wiki

Sections

We recommend that each page for an egg is given at least the following sections:

Your egg's name: The very first section of the documentation is taken as the title for your wiki page. Your egg's name is usually a good page title.
Description: Must briefly describe and state the purpose of the egg.
Authors: The egg authors and maintainers
Repository: Link to the code repository of the egg
Requirements: Should list other eggs that are required to build (compile-time) or load (runtime) this egg. Each entry should be linked to the respective egg.
API: The API description. Be sure to semantically format the procedures, macros, parameters, classes etc (see the Extensions for CHICKEN documentation section at the Editing help page).
Examples: Must provide simple examples of the most important functions in the egg. Note that all examples should be entirely self-contained; basically, pasting them in csi should work, which means, among other things, that they should include the use or require-extension lines loading the egg. Each example should be its own subsection and the actual code should follow a brief explanation of what it does.
License: The license for your egg (see the Eggs Licensing page)
Version History: Should list all releases of the egg and a description of their differences with the previous versions.

Egg build system and metadata

CHICKEN 5 introduced an new format for the system to build eggs, which is incompatible with the one for CHICKEN 4. Below you can find information on CHICKEN 5. For information on CHICKEN 4, see Eggs tutorial for CHICKEN 4.

The build system for eggs in CHICKEN 5 reads .egg files, which contain information about the egg and describe how eggs are to be built.

See the manual section on extensions for more information and simple examples on how to write .egg files and Egg specification format for the specification of .egg files.

For practical examples, see what existing eggs do.

Egg categories

For the category entry, used by .egg files you can use any of the following possibilities:

code-generation: Code generation
crypt: Cryptography
data: Algorithms and data-structures
db: Databases
debugging: Debugging tools
doc-tools: Documentation tools
egg-tools: Egg tools
ffi: Interfacing to other languages
graphics: Graphics
io: Input/Output
lang-exts: Language extensions
logic: Logic programming
macros: Macros and meta-syntax
math: Mathematical libraries
misc: Miscellaneous
net: Networking
oop: Object-oriented programming
os: OS interface
parsing: Data formats and parsing
sound: Sound related stuff
testing: Unit-testing
tools: Command line tools
ui: User interface toolkits
web: Web programming
xml: XML processing
hell: Concurrency and parallelism
uncategorized: Uncategorized
obsolete: Unsupported or redundant

Licensing

Please refer to Eggs Licensing.

Tests

chicken-install can automatically run a test suite on a freshly installed egg, if the egg directory contains a directory named tests, which should include a Scheme source file named run.scm. When chicken-install is invoked with the -test option, then this file will be executed (with test being the current working directory). It is recommended to add a test suite to your extension, as it allows some sort of automated testing of installed extensions.

chicken-install determines whether the test suite succeeded or not based on the exit code from tests/run.scm. Success is indicated with exit code 0 and any other exit code indicates failures. The tests/run.scm program is supposed to follow that protocol, otherwise failures might be go unnoticed if always exits 0. If you are using the test egg, you can use (test-exit) at the end of tests to make tests/run.scm properly report the exit code to chicken-install.

If your tests depend on extra eggs, do not use dependencies/build-dependencies to require them. Use test-dependencies instead, so they'll only be required when chicken-install is used with the -test option.

With regard to the test infrastructure, notice that only the latest released egg versions are tested.

Testing your extension

Before publishing your egg, it is recommended to run test-new-egg on it to try to catch some common mistakes in advance.

Assuming the release of your egg is ready (i.e., the code is available in the source repository and a tag to represent the egg version has been created), you can just run:

 $ chicken-install test-new-egg # in case you don't have test-new-egg installed
 $ test-new-egg <egg-name> <URL of the .release-info file>

test-new-egg will make sure that releases of your egg can be fetched and installed.

After your egg has been published (i.e., the .release-info file is known to work fine), the next releases can be tested with salmonella. Here's how you can do that:

 $ chicken-install salmonella # in case you don't have salmonella installed
 $ cd egg-dir # the directory where your egg code is stored
 $ salmonella

Salmonella will report to the standard output a summary of the tests it performs. It also generates a detailed log file containing all the data generated along the tests execution. You can use salmonella-log-viewer to see details about the whole test procedure:

 $ salmonella-log-viewer salmonella.log

See the salmonella documentation for more information on how to test eggs.

If your egg installs an executable file and tests call that file, take a look at this caveat.

Managing and hosting eggs

CHICKEN currently supports distributing eggs hosted on remote repositories (in the past, we had a central Subversion repository which is now deprecated for new eggs). So, you can host your egg code on popular repository providers like github, bitbucket etc, or even using your own server.

See the Releasing your egg document for information on how to host egg code and manage releases.

Caveats

License

This may seem a bit annoying but since we have had this a couple of times on our mailing list, please make sure that your egg's license is compatible with the licenses of its dependencies.

Adding your egg to the official egg index

Once you have a release-info file for your egg which passes the tests with test-new-egg, you can request it to be added to the official egg index, so that it can be fetched by chicken-install.

To do that, send a message to the chicken-users mailing list announcing your egg and requesting it to be added to the official index.

Post check-in notes

Tests

Once your code hits the eggs repository, it'll be daily tested by salmonella to check if it can be installed by chicken-install. See http://tests.call-cc.org for more information.

Documentation

Strive to keep the documentation for your eggs in good shape and up to date. It highly influences the quality of your eggs.

Tagging and versioning

Under absolutely no circumstance tags in eggs source repositories should be removed, moved (i.e., point to another commit) or renamed.

Our eggs servers periodically poll egg source repositories for new egg versions and fetch them when they are not cached on the egg servers side. Code corresponding to tags that have already been fetched will not be fetched again. So, if you remove, move or rename a tag, those operations will not be reflected in the sources cached on the egg servers side and will create inconsistencies between the code cached on egg servers and the source repository.