source: project/wiki/eggs tutorial @ 40154

Last change on this file since 40154 was 40154, checked in by Mario Domenech Goulart, 2 months ago

eggs tutorial: typo fixes and small rewording

File size: 9.2 KB
Line 
1== Eggs Tutorial
2
3[[toc:]]
4[[tags:tutorials eggs]]
5
6== Introduction
7
8This document explains how to create an official CHICKEN Extension.
9
10[[eggs|CHICKEN extensions]] can greatly enhance the functionality available in CHICKEN.
11They can define and export new convenient functions, wrap and make available libraries written in other languages (typically C) or even extend the basic language.
12
13A good way to start getting involved in the CHICKEN community is to contribute new eggs.
14Not 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).
15
16== Programming your extension
17
18=== Code layout
19
20You should always use the module system for extensions to avoid creating name-conflicts
21if one of your exported toplevel identifiers clashes with an already existing definition.
22Modules also allow to export syntax definitions in a clean and easy-to-use way.
23
24=== Documentation
25
26Providing 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).
27
28You 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]].
29
30You 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.
31
32If 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:
33
34  $ svn co https://code.call-cc.org/svn/chicken-eggs/wiki
35
36==== Sections
37
38We recommend that each page for an egg is given at least the following sections:
39
40; 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.
41; Description : Must briefly describe and state the purpose of the egg.
42; Authors : The egg authors and maintainers
43; Repository : Link to the code repository of the egg
44; 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.
45; 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).
46; 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.
47; License : The license for your egg (see the [[eggs-licensing|Eggs Licensing]] page)
48; Version History : Should list all releases of the egg and a description of their differences with the previous versions.
49
50
51=== Egg build system and metadata
52
53CHICKEN 5 introduced an new format for the system to build eggs, which
54is incompatible with the one for CHICKEN 4.  Below you can find
55information on CHICKEN 5.  For information on CHICKEN 4, see
56[[/eggs-tutorial-4|Eggs tutorial for CHICKEN 4]].
57
58The build system for eggs in CHICKEN 5 reads {{.egg}} files, which
59contain information about the egg and describe how eggs are to be built.
60
61See [[/man/5/Extensions|the manual section on extensions]] for more
62information and simple examples on how to write {{.egg}} files and
63[[/man/5/Egg specification format|Egg specification format]] for
64the specification of {{.egg}} files.
65
66For practical examples, see what
67[[https://code.call-cc.org/cgi-bin/gitweb.cgi?p=eggs-5-latest.git;a=tree|existing eggs]]
68do.
69
70
71==== Egg categories
72
73For the category entry, used by {{.egg}} files you can use any of the
74following possibilities:
75
76;code-generation: Code generation
77;crypt: Cryptography
78;data: Algorithms and data-structures
79;db: Databases
80;debugging: Debugging tools
81;doc-tools: Documentation tools
82;egg-tools: Egg tools
83;ffi: Interfacing to other languages
84;graphics: Graphics
85;io: Input/Output
86;lang-exts: Language extensions
87;logic: Logic programming
88;macros: Macros and meta-syntax
89;math: Mathematical libraries
90;misc: Miscellaneous
91;net: Networking
92;oop: Object-oriented programming
93;os: OS interface
94;parsing: Data formats and parsing
95;sound: Sound related stuff
96;testing: Unit-testing
97;tools: Command line tools
98;ui: User interface toolkits
99;web: Web programming
100;xml: XML processing
101;hell: Concurrency and parallelism
102;uncategorized: Uncategorized
103;obsolete: Unsupported or redundant
104
105=== Licensing
106
107Please refer to [[Eggs Licensing]].
108
109
110=== Tests
111
112[[/man/5/Extensions|chicken-install]] can automatically run a test suite on a freshly installed egg, if the egg directory
113contains a directory named {{tests}}, which should include a Scheme source file named {{run.scm}}.
114When {{chicken-install}} is invoked with the {{-test}} option, then this file will be executed
115(with {{test}} being the current working directory). It is recommended to add a test suite
116to your extension, as it allows some sort of automated testing of installed extensions.
117
118
119{{chicken-install}} determines whether the test suite succeeded or not
120based on the exit code from {{tests/run.scm}}.  Success is indicated
121with exit code {{0}} and any other exit code indicates failures.  The
122{{tests/run.scm}} program is supposed to follow that protocol,
123otherwise failures might be go unnoticed if always exits {{0}}.  If
124you are using the [[/egg/test|test egg]], you can use {{(test-exit)}}
125at the end of tests to make {{tests/run.scm}} properly report the exit
126code to {{chicken-install}}.
127
128If your tests depend on extra eggs, '''do not''' use
129{{dependencies}}/{{build-dependencies}} to require them.  Use
130{{test-dependencies}} instead, so they'll only be required when
131{{chicken-install}} is used with the {{-test}} option.
132
133With regard to the test infrastructure, notice that only the latest
134released egg versions are tested.
135
136==== Testing your extension
137
138Before publishing your egg, it is recommended to run
139[[/egg/test-new-egg|test-new-egg]] on it to try to catch some common
140mistakes in advance.
141
142Assuming the release of your egg is ready (i.e., the code is available
143in the source repository and a tag to represent the egg version has
144been created), you can just run:
145
146  $ chicken-install test-new-egg # in case you don't have test-new-egg installed
147  $ test-new-egg <egg-name> <URL of the .release-info file>
148
149{{test-new-egg}} will make sure that releases of your egg can be
150fetched and installed.
151
152After your egg has been published (i.e., the {{.release-info}} file is
153known to work fine), the next releases can be tested with salmonella.
154Here's how you can do that:
155
156  $ chicken-install salmonella # in case you don't have salmonella installed
157  $ cd egg-dir # the directory where your egg code is stored
158  $ salmonella
159
160Salmonella 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:
161
162  $ salmonella-log-viewer salmonella.log
163
164See the [[/egg/salmonella|salmonella documentation]] for more information on how to test eggs.
165
166If 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]].
167
168== Managing and hosting eggs
169
170CHICKEN currently supports distributing eggs hosted on remote
171repositories (in the past, we had a [[chicken-svn-for-eggs|central
172Subversion repository]] which is now deprecated for new eggs).  So,
173you can host your egg code on popular repository providers like
174[[http://github.com|github]], [[http://bitbucket.org|bitbucket]] etc,
175or even using your own server.
176
177See the [[/releasing-your-egg|Releasing your egg]] document for
178information on how to host egg code and manage releases.
179
180== Caveats
181
182=== License
183
184This 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.
185
186== Post check in notes
187
188Once 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.
189
190Strive to keep the documentation for your eggs in good shape and up to date. It highly influences the quality of your eggs.
Note: See TracBrowser for help on using the repository browser.