Eggs Tutorial (historical revision 29613)

You are looking at historical revision 29613 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-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).

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

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.

Additional files

Documentation

Providing good documentation for your eggs is a fundamental part of their overall quality.

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.

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/4/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 ckeck 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
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.

The setup file

In order for chicken-install to install your extension, we recommend that you create a mpeg3.setup file with information about your egg. chicken-install will load this file. chicken-install adds some new procedures to the environment, which are documented in the "Extensions" 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 -j mpeg3)
(compile -s mpeg.import.scm -O2 -d0)

(install-extension
 ;; Name of your extension:
 'mpeg3
 ;; Files to install for your extension:
 '("mpeg3.so" "mpeg3.import.so")
 ;; Assoc list with properties for your extension:
 '((version "1.2")))

The first line will cause mpeg3.scm to be compiled into mpeg3.so (a shared library for dynamic loading), which is installed by install-extension. The -j option will make sure that an import library is generated for your module(s) which, after compilation, provide module meta-information and exported syntax. Alternatively you can use -J without any arguments to generate import libraries for all defined modules.

The second line will compile the generated import library.

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.

Note that version is represented by a string. That's because numbers can be tricky to represent versions. Integers are usually not enough to represent minor/major changes, and floating point numbers require you to determine the number of minor releases a priori, otherwise you'll inevitably end up with version 1.10, which is numerically equivalent to 1.1, and that would cause problems when chicken-install tries to match versions to determine dependencies.

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:

(
; Your egg's license:
(license "BSD")

; 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. `depends' is an alias to `needs'.
; Notice that you should NOT put Chicken units (e.g., srfi-1, srfi-13
; and many others) in `needs' or in `depends'.
(needs sandbox syntax-case)

; A list of eggs required for TESTING ONLY.  See the `Tests' section.
; Just like `needs' and `depends', `test-depends' should NOT contain
; Chicken units.
(test-depends test)

(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
hell: Concurrency and parallelism
uncategorized: Uncategorized
obsolete: Unsupported or redundant

Make sure you read Eggs Licensing!

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

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

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

For proper integration to the test infrastructure, run.scm should exit 0 (zero) when all tests pass or any other number in case some test fails. If you are using the test egg, a call to test-exit makes run.scm exit properly.

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 salmonella on it to try to catch some common mistakes in advance. Here's how you can do that:

 $ chicken-install salmonella # in case you don't have salmonella installed
 $ cd egg-dir # the directory where yor 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

Managing eggs in the Chicken hosted repository

If you don't already have your own hosted version control system, you can host your eggs inside the Chicken hosted repository, and let us do the hard work.

Obtaining an account in the repository

We host Chicken Extensions in the following Subversion repository:

https://code.call-cc.org/svn/chicken-eggs/ (user=anonymous, empty password)

In order to create your extensions you will need access to this repository. See the Contribute page for information about how to request an account.

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://code.call-cc.org/svn/chicken-eggs/release/4/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 from the trunk.
extra: files that you want to keep under version control but are not required to be installed by chicken-install

For documentation, there is a wiki directory at the top-level of the repository. It holds the entire contents for this wiki.

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

Eggs Tutorial