You are looking at historical revision 10437 of this page. It may differ significantly from its current revision.

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-setup) and other users might start helping improve your eggs.

We will assume your extension is called mpeg3 (which is the name of an already existing egg). Replace occurences of that string throughout this file with the actual name of your extension.

Programming your extension

Code layout

You should write the code for your extension in the following files:

We strongly recommend that you add a (declare (export ...)) declaration to your runtime file explicitly listing all the symbols that should be exported to programs using your egg. This not only avoids name clashes, but it also serves as some implicit sort of documentation as to what the public interface exported by the egg is (which should not, ever, replace your standard documentation!).

Testing your extension

To test your extension the best practice seems to be to load it directly from the source code (unless it uses foreign code, in which case you'll need to compile it and load your .so file).

Additional files

Documentation

There are basically two alternative options to provide documentation for your egg. Which you choose is up to you. The following sections describes them.

Hand written HTML

Using eggdoc

The eggdoc extension translates an SXML dialect into HTML. The best way to learn about eggdoc is to study one of the many existing examples in the extension repository.

Using the wiki

You can enter your entire documentation for your egg into this wiki. You'll use a file called mpeg3 at the root of this wiki. The following are some examples:

This has the advantage of inviting other members of the Chicken community to help improve the documentation for your egg.

To set this up, add "(doc-from-wiki)" to the egg's .meta file (see the meta file section below).

Whenever a new release for your egg is made, its associated file from the wiki will be converted to HTML and shipped with it (as mpeg3.html) as well as uploaded to <http://www.call-with-current-continuation.org/eggs/>.

If you follow this route, it would be a good idea to consult the guidelines for documenting eggs in the wiki.

The setup file

In order for chicken-setup to install your extension, we recommend that you create a mpeg3.setup file with information about your egg. chicken-setup will load this file. chicken-setup adds some new procedures to the environment, which are documented in the chicken-setup section of the manual.

If your egg does not contain macros, your setup file should look similar to the following:

; These two instructions will produce statically and dynamically linkable object files "mpeg3.o" and "mpeg3.so" respectively.
(compile -s -O2 -d1 mpeg3.scm)
(compile -c -O2 -d1 mpeg3.scm -unit mpeg3)
;
(install-extension
  ; Name of your extension:
  'mpeg3
  ; Files to install for your extension:
  '("mpeg3.o" "mpeg3.so" "mpeg3.html")
  ; Assoc list with properties for your extension:
  '((version 1.2)
    (static "mpeg3.o") ;; for static linking
    (documentation "mpeg3.html")))

Note that the first line will cause mpeg3.scm to be compiled into mpeg3.o, which is installed by install-extension.

Note that the second line will cause mpeg3.scm to be compiled into mpeg3.so, which is installed by install-extension.

If your extension includes syntax it should:

  1. Compile mpeg3-base.scm (instead of mpeg3.scm), according to the semantics for those files.
  2. List both mpeg3.scm (macros) and mpeg3-base.so in the list of files to install.
  3. In the list of properties it should include (syntax) and (require-at-runtime mpeg3).

If your egg requires your code to be linked against a specific library or certain flags (eg. -l) to be passed to the C compiler, you should specify them here.

If you are using the wiki for your documentation, mpeg3.html will be created as part of the process that uploads your egg to call-with-current-continuation.org. That means that testing your setup script will fail, as it won't find it. For that reason, you will need to create a dummy mpeg3.html file temporarily, which you won't be releasing nor uploading to the Subversion repository for eggs (described below).

The meta file

Finally, you will need to create mpeg3.meta, with information about your egg. This file is used by the process that releases and uploads new eggs. It should contain a single s-expr as follows:

((egg "mpeg3.egg") ; This should never change

 ; List here all the files that should be bundled as part of your egg.  Note
 ; that (1) mpeg3.meta does not need to be listed here and (2) you might
 ; want to include mpeg3-base.scm (if it exists).

 (files "mpeg3.scm" "mpeg3.html" "mpeg3.setup")

 ; The following should only be present if the egg's documentation should be
 ; generated from the wiki:

 (doc-from-wiki)

 ; The following is used to add additional documents to the install,
 ; so the auto-generated or wiki documents can like to them.  All
 ; file names listed here will have "[eggname]-" added to the front, so
 ; if you put "doc.html" here, make sure "mpeg3-doc.html" exists.

 (documentation "doc.html")

 ; Your egg's license:

 (license "GPL")

 ; Pick one from the list of categories (see below) for your egg and enter it
 ; here.

 (category web)

 ; A list of eggs mpeg3 depends on.  If none, you can omit this declaration
 ; altogether:

 (needs sandbox syntax-case)

 (author "Your Name Goes Here")
 (synopsis "A basic description of the purpose of the egg."))

For the category entry you can use any of the following:

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

Make sure you read eggs licencing!

More information about extension meta properties can be found here at the Metafile reference.

Tests

chicken-setup 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-setup 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. If "run.scm" never calls "error" during the execution then the test is considered successful.

Managing eggs in the repository

Obtaining an account in the repository

We keep all Chicken Extensions in the following Subversion repository:

You can see a graph of some stats about it here:

In order to create your extensions you will need access to this repository. Send an email to the Chicken Users mailing list and state:

With this information we will create a directory for your extension and create you an account with the appropriate access rights.

To checkout this directory run the following command:

svn checkout https://galinha.ucpel.tche.br/svn/chicken-eggs/release/3/mpeg3

Directory structure

The directory for your egg will have the following subdirectories:

trunk
Here you can keep the latest (potentially unstable) development version for your egg.
tags
You should keep one subdirectory of this directory for every release for your egg. The names of the directories here should correspond to the version number of their associated release.
branches
Contains, as subdirectories, any special branches of the code that need to be maintained apart of the trunk.

Furthermore, there is a wiki directory at the top-level of the repository. It holds the entire contents for this wiki. This can be helpful if you decide to use it to document your egg.

Importing your files

You will initially copy your files to the trunk directory, add them manually and commit your changes. For example:

svn add trunk/mpeg3.scm
svn add trunk/mpeg3.setup
svn add trunk/mpeg3.meta
svn commit -m "Importing mpeg3 extension."

Making a new release

Once the code in trunk is reasonably stable and you want to make a new release, copy it to a new directory under tags. The directory should be named after the software version. Software versions should have the form of a list of numbers separated by a dot (eg. “1.3.4” is a valid software version, whereas “1.3-0” or “1.3rc0” are not).

For example, to make the 1.3 release for mpeg3, you would run the following commands (at the directory where you checked out your egg):

svn copy trunk tags/1.3
svn commit -m "Releasing version 1.3."

Tagged extensions in the repository will have an additional file when wrapped up for upload to the CHICKEN website called version - this file contains the version number (the tag) of the packaged egg.

Uploading the egg on the CHICKEN website for downloading via chicken-setup happens automatically - a background job periodically checks the source code repository for updates and wraps up the eggs, copying them to the call/cc.org web-server (see also periodic-tasks). Should there be a problem (your egg doesn't show up, or whatever), send an email to any of the following persons asking them to help with uploading: