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

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 mpeg3. Replace occurences of that string throughout this file with the actual of your extension.

Programming your extension

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 mpeg3.scm.
• Otherwise:
  • Write your macros and any code that needs to be available at compile time in mpeg3.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 mpeg3-base.scm. This file will be compiled into mpeg3-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 mpeg3.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 code

To test your extension the best practice seems to be to load it directly from the source code (unless it uses foreign code).

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.

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

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

Note that the first 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.scm in the list of files to install.
3. In the list of properties it should include (syntax) and (require-at-runtime mpeg3).

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/

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 Meta file

...