You are looking at historical revision 19518 of this page. It may differ significantly from its current revision.
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.
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
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.
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).
You can enter your entire documentation for your egg into this wiki. You'll use a file called mpeg3 in ther directory eggref/4/. 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.
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.
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) (compile -c -O2 -d1 mpeg3.scm -unit mpeg3 -j mpeg3) ; (install-extension ; Name of your extension: 'mpeg3 ; Files to install for your extension: '("mpeg3.o" "mpeg3.so" "mpeg3.import.so") ; Assoc list with properties for your extension: '((version 1.2) (static "mpeg3.o"))) ;; for static linking
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, that, after compilation, provides module meta-information and exported syntax.
The second line will compile the generated import library.
The third line will cause mpeg3.scm to be compiled into mpeg3.o (a static module for static linking), which is installed by install-extension.
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.
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:
( ; 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") ; 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. If you are making an egg for chicken 3 and you need to use ; procedures from the `files' unit, be sure to include the `files' egg in the ; `needs' section (chicken versions < 3.4.0 don't provide the `files' unit). ; `depends' is an alias to `needs'. (needs sandbox syntax-case) ; A list of eggs required for TESTING ONLY. See the `Tests' section. (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
- Algorithms and data-structures
- Debugging tools
- Documentation tools
- Egg tools
- Interfacing to other languages
- Language extensions
- Logic programming
- Macros and meta-syntax
- Mathematical libraries
- Object-oriented programming
- OS interface
- Data formats and parsing
- Sound related stuff
- Command line tools
- User interface toolkits
- Web programming
- XML processing
- Concurrency and parallelism
- Unsupported or redundant
Make sure you read eggs licencing!
More information about extension meta properties can be found here at the Metafile reference.
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, don't 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.
Managing eggs in the repository
Obtaining an account in the repository
We keep all 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
The directory for your egg will have the following subdirectories:
- Here you can keep the latest (potentially unstable) development version for your egg.
- 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.
- Contains, as subdirectories, any special branches of the code that need to be maintained apart from the trunk.
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."
Post check in notes
Strive to keep the documentation for your eggs in good shape and up to date. It highly influences the quality of your egg.