You can edit this page using wiki syntax for markup.

Article contents:== Eggs Tutorial [[toc:]] [[tags:tutorials eggs]] == Introduction This document explains how to create an official CHICKEN Extension. [[eggs|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). == Naming your extension Egg names tend to follow a very simple naming scheme. Most eggs use only lowercase ASCII letters, digits and dashes. Although it should be technically possible to have other characters in egg names (e.g., uppercase letters, underscore, plus sign), it's highly recommendable to stick to avoid them, if anything, for the sake of consistency. The following characters are allowed in egg names: 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ+-_ The {{chicken}} name is reserved, as it can be used by eggs to [[/manual/Egg specification format|specify the minimum required version of CHICKEN.]] == 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. === Documentation Providing good documentation for your eggs is a fundamental part of their overall quality. Documentation for eggs is stored in wiki format in the CHICKEN subversion repository (see [[/contribute#create-eggseggs|this document]] for information on how to request an account). 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. Also, eggs documented in the CHICKEN wiki are automatically indexed by our [[http://api.call-cc.org|API browser]]. 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/5/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 check 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 ; Repository : Link to the code repository of the egg ; 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 [[/edit-help|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|Eggs Licensing]] page) ; Version History : Should list all releases of the egg and a description of their differences with the previous versions. === Egg build system and metadata CHICKEN 5 introduced an new format for the system to build eggs, which is incompatible with the one for CHICKEN 4. Below you can find information on CHICKEN 5. For information on CHICKEN 4, see [[/eggs-tutorial-4|Eggs tutorial for CHICKEN 4]]. The build system for eggs in CHICKEN 5 reads {{.egg}} files, which contain information about the egg and describe how eggs are to be built. See [[/man/5/Extensions|the manual section on extensions]] for more information and simple examples on how to write {{.egg}} files and [[/man/5/Egg specification format|Egg specification format]] for the specification of {{.egg}} files. For practical examples, see what [[https://code.call-cc.org/cgi-bin/gitweb.cgi?p=eggs-5-latest.git;a=tree|existing eggs]] do. ==== Egg categories For the category entry, used by {{.egg}} files you can use any of the following possibilities: ;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 === Licensing Please refer to [[Eggs Licensing]]. === Tests [[/man/5/Extensions|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. {{chicken-install}} determines whether the test suite succeeded or not based on the exit code from {{tests/run.scm}}. Success is indicated with exit code {{0}} and any other exit code indicates failures. The {{tests/run.scm}} program is supposed to follow that protocol, otherwise failures might be go unnoticed if always exits {{0}}. If you are using the [[/egg/test|test egg]], you can use {{(test-exit)}} at the end of tests to make {{tests/run.scm}} properly report the exit code to {{chicken-install}}. If your tests depend on extra eggs, '''do not''' use {{dependencies}}/{{build-dependencies}} to require them. Use {{test-dependencies}} instead, so they'll only be required when {{chicken-install}} is used with the {{-test}} option. 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 [[/egg/test-new-egg|test-new-egg]] on it to try to catch some common mistakes in advance. Assuming the release of your egg is ready (i.e., the code is available in the source repository and a tag to represent the egg version has been created), you can just run: $ chicken-install test-new-egg # in case you don't have test-new-egg installed $ test-new-egg <egg-name> <URL of the .release-info file> {{test-new-egg}} will make sure that releases of your egg can be fetched and installed. After your egg has been published (i.e., the {{.release-info}} file is known to work fine), the next releases can be tested with salmonella. Here's how you can do that: $ chicken-install salmonella # in case you don't have salmonella installed $ cd egg-dir # the directory where your 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 [[/egg/salmonella|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 [[http://wiki.call-cc.org/eggref/5/salmonella#testing-executable-files-installed-by-eggs|this caveat]]. == Managing and hosting eggs CHICKEN currently supports distributing eggs hosted on remote repositories (in the past, we had a [[chicken-svn-for-eggs|central Subversion repository]] which is now deprecated for new eggs). So, you can host your egg code on popular repository providers like [[http://github.com|github]], [[http://bitbucket.org|bitbucket]] etc, or even using your own server. See the [[/releasing-your-egg|Releasing your egg]] document for information on how to host egg code and manage releases. == Caveats === License This may seem a bit annoying but since we have had this a couple of times on our mailing list, please make sure that your egg's license is compatible with the licenses of its dependencies. == Adding your egg to the official egg index Once you have a {{release-info}} file for your egg which passes the tests with [[/egg/test-new-egg|test-new-egg]], you can request it to be added to the [[//eggs.call-cc.org|official egg index]], so that it can be fetched by {{chicken-install}}. To do that, send a message to the [[https://lists.nongnu.org/mailman/listinfo/chicken-users|chicken-users mailing list]] announcing your egg and requesting it to be added to the official index. == Post check-in notes === Tests Once your code hits the eggs repository, it'll be daily tested by [[/egg/salmonella|salmonella]] to check if it can be installed by {{chicken-install}}. See [[http://tests.call-cc.org]] for more information. === Documentation Strive to keep the documentation for your eggs in good shape and up to date. It highly influences the quality of your eggs. === Tagging and versioning Under '''absolutely no circumstance''' tags in eggs source repositories should be removed, moved (i.e., point to another commit) or renamed. Our eggs servers periodically poll egg source repositories for new egg versions and fetch them when they are not cached on the egg servers side. Code corresponding to tags that have already been fetched '''will not''' be fetched again. So, if you remove, move or rename a tag, those operations '''will not''' be reflected in the sources cached on the egg servers side and will create inconsistencies between the code cached on egg servers and the source repository.Description of your changes:

I would like to authenticate

Spam control

What do you get when you subtract 21 from 19?