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

• tutorials

Introduction

Warning: This is a draft. It could contain misleading information.

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 (C, more often than not) or even extend the basic language.

We will assume your extension is called eggname. Replace occurences of that string throughout this file with the actual of your extension.

Programming your extension

Code layout

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

• If your extension doesn't contain macros (and thus it doesn't need to be available at compile time), as is the case with most:
  • Write all your code in eggname.scm.
• Otherwise:
  • Write your macros and any code that needs to be available at compile time in eggname.scm. You'll soon setup your egg in such a way that this file won't get compiled (but rather loaded during compilation).
  • Write your function definitions and any code that should be available at run-time in eggname-base.scm. This file will be compiled into eggname-base.so, which will be loaded at runtime. If your extension has code that should be compiled and doesn't define new macros (as is the case with most), you should write it in eggname.scm. It should contain all the symbols in your extension that you want to compile and make available to user programs at run-time.

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 uisng your egg.

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).

TODO: Add information about debugging?

Additional files

The setup file

In order for chicken-setup to install your extension, we recommend that you create a eggname.setup file with information about your egg. chicken-setup will load this file.

In the case of eggs that only define runtime symbols, this step is entirely optional: you could ship your egg as a single .scm file. However, using a .setup file is still recommended as it will also allow you to state the version of your egg (which chicken-setup -list will print).

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

(compile -s -O2 -d1 eggname.scm)
(install-extension
  ; Name of your extension:
  'eggname
  ; Files to install for your extension:
  '("eggname.so" "eggname.html")
  ; Assoc list with properties for your extension:
  '((version 1.2)
    (documentation "eggname.html")))

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

If your extension includes syntax it should:

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

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

Documentation

TODO: Explain eggdoc as well as the option of using the wiki to document eggs.

The meta file

TODO: Explain the purpose and syntax.

Managing eggs in the repository

Obtaining an account in the repository

We keep all Chicken Extensions in the following Subversion repository:

• https://secure.afc.no-ip.info/svn/chicken-eggs/

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

• http://freaks-unidos.net/svn-graph/chicken-eggs/

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

• A brief description of the purpose of your extension
• The name you want to use for your extension
• The username you want to use to access the repository (unless you already have one).

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://secure.afc.no-ip.info/svn/chicken-eggs/eggname

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.

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/eggname.scm
svn add trunk/eggname.setup
svn add trunk/eggname.meta
svn commit -m "Importing eggname 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 and set the latest Subversion property of the tags directory to its version number. For example, to make the 1.3 release for eggname, you would run the following commands (at the directory where you checked out your egg):

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

Once you've done this, send an email to any of the following persons asking them to upload your egg (this process is still manual; we will probably authomatize it at some point in the future):

• Felix Winklemann <bunny351@gmail.com>
• Alejandro Forero Cuervo <azul@freaks-unidos.net>