source: project/README @ 711

Notes for Extension Maintainers
===============================


This directory contains the development files for the official extensions of the
CHICKEN Scheme implementation. You will find one directory for each extension
containing all relevant files needed to build and distribute it.

The extensions are stored in a subversion repository. If you want to know more
about Subversion, visit http://subversion.tigris.org/.

The URL of the repository is 

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

To download the tree, enter

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

  (login "anonymous", password is "")

To gain write-access to the repository, contact felix@call-with-current-continuation.org,
or ask on the CHICKEN mailing list.

Each subdirectory for an egg should contain the following structure:

- If the author doesn't want to use the Subversion eggs' repository
  much, just use it to occasionally upload releases, everything should
  go directly under eggname.  There should be a eggname/eggname.meta
  file with the semantics described bellow.

- If the author does want to use the features provided by Subversion
  and make the eggs repository its main development repository, it
  should have the following structure:

    trunk/ - Contains the latest (possibly experimental/unstable)
    version of the code.

    branches/ - Contains, as subdirectories, any special branches of
    the code that need to be maintained apart of the trunk.

    tags/ - Contains special tags for the code (such as those for each
    release).  Once created, a tag should never change (just like a
    release should never change).

  This layout is explained in the book Version Control with Subversion
  and has become a standard for many projects.

  To make a release the following should be done (where VERSION is of
  the form "1.0", "1.1", etc.):

    svn cp eggname/trunk eggname/tags/VERSION
    svn ps latest VERSION eggname/tags

  The ps (property set) sets a Subversion property on the tags
  directory for the egg with the name (version) of the latest release,
  to make it possible for tools (eg. egg-post-commit) to find it
  (without requiring any intelligence to compare version numbers on
  their part).

  Note that every release must have the eggname.meta file with the semantics
  described bellow (and, for that reason, so should trunk/, even though nothing
  will read that file from there).

If you make any changes and commit them to the repository, a script on the 
server will create the egg (the packaged extension) and move it to the official
site from which it can be downloaded via the `chicken-setup' tool. All that is
required is a separate description named `EXTENSION.meta' that holds meta-information
describing the author, required files and the category. The format is quite simple,
it simple contains a list of sub-lists holding meta-properties. Here a simple 
example, taken from the `ajax' egg:


((egg "ajax.egg")
 (synopsis "Using xmlHttpRequest with the Spiffy web-server")
 (needs md5 url spiffy)
 (category web)
 (license "MIT")
 (author "felix <felix@call-with-current-continuation.org>")
 (files "ajax.setup" "ajax.scm" "ajax.html" "prototype.js"))


You should at least provide the following properties:

  (synopsis STRING)

    A short description of the extension.

  (author STRING)

    The author, optionally with an e-mail address, if desired.

  (files STRING ...)

    The names of all files that should be contained in the egg.

  (egg STRING)

    The name of the egg file.

  (license STRING)

    The license under which the code is released. Please make sure you use the
    proper license if you package code written by others.

  (category SYMBOL)

    A category under which the egg should be listed on the egg-index page at
    http://www.call-with-current-continuation.org/eggs/index.html.

    Currently the set of categories is fixed, use one of:

      lang-exts   Language extensions
      graphics    Graphics
      debugging   Debugging tools
      net         Networking
      io          Input/Output
      db          Databases
      ffi         Interfacing to other languages
      web         Web programming
      xml         XML processing
      doc-tools   Documentation tools
      math        Mathematical libraries
      oop         Object-oriented programming
      data        Algorithms and data-structures
      parsing     Data formats and parsing
      tools       Tools
      testing     Unit-testing
      crypt       Cryptography
      ui          User interface toolkits
      code-generation Run-time code generation
      misc        Miscellaneous

  (needs SYMBOL ...)

    Any extensions needed to build and use this extension. This should be the
    raw extension-identifier, the same that you would use in a `require-extension'
    form.

You should provide a HTML file with documentation, if possible using Zbigniew
Szadkowski's `eggdoc' extension (see http://www.call-with-current-continuation.org/eggs/eggdoc).
If named `EXTENSION-NAME.html', then it will be automatically uploaded to call/cc.org.

One final note: please keep the version numbers up-to date and add changes to the doc.scm
or (if no eggdoc-script exists) the html file.


Many thanks for contributing!