source: project/wiki/eggs tutorial @ 15206

Last change on this file since 15206 was 15206, checked in by svnwiki, 11 years ago

Changes applied for Anonymous (98.216.110.149) through svnwiki:

+note galinha.ucpel.tche.br/svn/chicken-eggs/ isn't browsable. To avoid 'try,fail,puzzle,disappointment' sapping folk's interest and energy.

File size: 10.8 KB
Line 
1[[toc:]]
2[[tags:tutorials eggs]]
3
4== Introduction
5
6This document explains how to create an official Chicken Extension.
7
8[[eggs|Chicken extensions]] can greatly enhance the functionality available in Chicken.
9They can define and export new convenient functions, wrap and make available libraries written in other languages (typically C) or even extend the basic language.
10
11A good way to start getting involved in the Chicken community is to contribute new eggs.
12Not 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.
13
14We will assume your extension is called ''mpeg3'' (which is the name of an already existing [[mpeg3|egg]]).  Replace occurences of that string throughout this file with the actual name of your extension.
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=== Testing your extension
25
26To 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).
27
28== Additional files
29
30=== Documentation
31
32There are basically two alternative options to provide documentation for your egg.
33Which you choose is up to you.
34The following sections describes them.
35
36==== Hand written HTML
37
38==== Using eggdoc
39
40The [[eggdoc]] extension translates an SXML dialect into HTML. The
41best way to learn about eggdoc is to study one of the many existing
42examples in the extension repository.
43
44==== Using the wiki
45
46You can enter your entire documentation for your egg into this wiki.
47You'll use a file called {{mpeg3}} at the root of this wiki.
48The following are some examples:
49
50* [[stream-ext]] egg
51* [[stream-wiki]] egg
52
53This has the advantage of inviting other members of the Chicken community to help improve the documentation for your egg.
54
55To set this up, add "(doc-from-wiki)" to the egg's .meta file (see the meta file section below).
56
57Whenever a new release for your egg is made, its associated file from the wiki will be converted to HTML and shipped with it (as {{mpeg3.html}}) as well as uploaded to <http://www.call-with-current-continuation.org/eggs/>.
58
59If you follow this route, it would be a good idea to consult the [[eggs guidelines|guidelines for documenting eggs in the wiki]].
60
61=== The setup file
62
63In order for {{chicken-install}} to install your extension, we recommend that you create a {{mpeg3.setup}} file with information about your egg.
64{{chicken-install}} will load this file. {{chicken-install}} adds some new procedures to the environment, which are documented in [[/man/4/Extensions#procedures-and-macros-available-in-setup-scripts|the "Extensions" section of the manual]].
65
66If your egg does not contain macros, your setup file should look similar to the following:
67
68<enscript highlight=scheme>
69; These two instructions will produce statically and dynamically linkable object files "mpeg3.o" and "mpeg3.so" respectively.
70(compile -s -O2 -d1 mpeg3.scm -j mpeg3)
71(compile -s mpeg.import.scm -O2 -d0)
72(compile -c -O2 -d1 mpeg3.scm -unit mpeg3)
73;
74(install-extension
75  ; Name of your extension:
76  'mpeg3
77  ; Files to install for your extension:
78  '("mpeg3.o" "mpeg3.so" "mpeg3.import.so")
79  ; Assoc list with properties for your extension:
80  '((version 1.2)
81    (static "mpeg3.o") ;; for static linking
82    (documentation "mpeg3.html")))</enscript>
83
84The first line will cause {{mpeg3.scm}} to be compiled into
85{{mpeg3.so}} (a shared library for dynamic loading), which is installed by {{install-extension}}.
86The {{-j}} option will make sure that an ''import library'' is generated, that, after compilation,
87provides module meta-information and exported syntax.
88
89The second line will compile the generated import library.
90
91The third line will cause {{mpeg3.scm}} to be compiled into
92{{mpeg3.o}} (a static module for static linking), which is installed by {{install-extension}}.
93
94If 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.
95
96If you are using the wiki for your documentation, {{mpeg3.html}}
97will be created as part of the process that uploads your egg to call-with-current-continuation.org.
98That means that testing your setup script will fail, as it won't find it.
99For that reason, you will need to create a dummy {{mpeg3.html}} file temporarily, which you won't be releasing nor uploading to the Subversion repository for eggs (described below).
100
101=== The meta file
102
103Finally, you will need to create {{mpeg3.meta}}, with information about your egg.
104This file is used by the process that releases and uploads new eggs.
105It should contain a single s-expr as follows:
106
107<enscript highlight=scheme>(
108
109 ; List here all the files that should be bundled as part of your egg.  Note
110 ; that (1) mpeg3.meta does not need to be listed here and (2) you might
111 ; want to include mpeg3-base.scm (if it exists).
112
113 (files "mpeg3.scm" "mpeg3.html" "mpeg3.setup")
114
115 ; The following is used to add additional documents to the install,
116 ; so the auto-generated or wiki documents can like to them.  All
117 ; file names listed here will have "[eggname]-" added to the front, so
118 ; if you put "doc.html" here, make sure "mpeg3-doc.html" exists.
119
120 (documentation "doc.html")
121
122 ; Your egg's license:
123
124 (license "GPL")
125
126 ; Pick one from the list of categories (see below) for your egg and enter it
127 ; here.
128
129 (category web)
130
131 ; A list of eggs mpeg3 depends on.  If none, you can omit this declaration
132 ; altogether. If you are making an egg for chicken 3 and you need to use
133 ; procedures from the `files' unit, be sure to include the `files' egg in the
134 ; `needs' section (chicken versions < 3.4.0 don't provide the `files' unit).
135
136 (needs sandbox syntax-case)
137
138 (author "Your Name Goes Here")
139 (synopsis "A basic description of the purpose of the egg."))</enscript>
140
141For the category entry you can use any of the following:
142
143;code-generation: Code generation
144;crypt: Cryptography
145;data: Algorithms and data-structures
146;db: Databases
147;debugging: Debugging tools
148;doc-tools: Documentation tools
149;egg-tools: Egg tools
150;ffi: Interfacing to other languages
151;graphics: Graphics
152;io: Input/Output
153;lang-exts: Language extensions
154;logic: Logic programming
155;macros: Macros and meta-syntax
156;math: Mathematical libraries
157;misc: Miscellaneous
158;net: Networking
159;oop: Object-oriented programming
160;os: OS interface
161;parsing: Data formats and parsing
162;sound: Sound related stuff
163;testing: Unit-testing
164;tools: Command line tools
165;ui: User interface toolkits
166;web: Web programming
167;xml: XML processing
168
169Make sure you read [[eggs licencing]]!
170
171More information about extension meta properties can be found here at
172the [[Metafile reference]].
173
174=== Tests
175
176[[/man/4/Extensions|chicken-install]] can automatically run a test suite on a freshly installed egg, if the egg directory
177contains a directory named {{tests}}, which should include a Scheme source file named {{run.scm}}.
178When {{chicken-install}} is invoked with the {{-test}} option, then this file will be executed
179(with {{test}} being the current working directory). It is recommended to add a test suite
180to 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.'''
181
182== Managing eggs in the repository
183
184=== Obtaining an account in the repository
185
186We keep all Chicken Extensions in the following [[http://subversion.tigris.org/|Subversion]]
187repository:
188
189* https://galinha.ucpel.tche.br/svn/chicken-eggs/ (not anonymously browsable)
190
191You can see a graph of some stats about it here:
192
193* http://freaks-unidos.net/svn-graph/chicken-eggs/ (broken link 2009-07-10)
194
195In order to create your extensions you will need access to this repository.
196Send an email to the Chicken Users mailing list and state:
197
198* A brief description of the purpose of your extension
199* The name you want to use for your extension
200* The username you want to use to access the repository (unless you already have one).
201
202With this information we will create a directory for your extension and create you an account with the appropriate access rights.
203
204To checkout this directory run the following command:
205
206 svn checkout https://galinha.ucpel.tche.br/svn/chicken-eggs/release/4/mpeg3
207
208=== Directory structure
209
210The directory for your egg will have the following subdirectories:
211
212; {{trunk}} : Here you can keep the latest (potentially unstable) development version for your egg.
213; {{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.
214; {{branches}} : Contains, as subdirectories, any special branches of the code that need to be maintained apart of the trunk.
215
216Furthermore, there is a {{wiki}} directory at the top-level of the repository.
217It holds the entire contents for this wiki.
218This can be helpful if you decide to use it to document your egg.
219
220=== Importing your files
221
222You will initially copy your files to the {{trunk}} directory, add them manually and commit your changes.  For example:
223
224 svn add trunk/mpeg3.scm
225 svn add trunk/mpeg3.setup
226 svn add trunk/mpeg3.meta
227 svn commit -m "Importing mpeg3 extension."
228
229=== Making a new release
230
231Once the code in {{trunk}} is reasonably stable and you want to make a new release, copy it to a new directory under {{tags}}.
232The directory should be named after the software version.
233Software versions should have the form of a list of numbers separated by a dot
234(eg. “1.3.4” is a valid software version, whereas “1.3-0” or “1.3rc0” are not).
235
236For example, to make the 1.3 release for mpeg3, you would run the following commands (at the directory where you checked out your egg):
237
238 svn copy trunk tags/1.3
239 svn commit -m "Releasing version 1.3."
240
241Tagged extensions in the repository will have an additional file when wrapped up for upload
242to the CHICKEN website called {{version}} - this file contains the version number (the tag)
243of the packaged egg.
244
245Uploading the egg on the CHICKEN website for downloading via {{chicken-setup}} happens automatically -
246a background job periodically checks the source code repository for updates and wraps up the eggs, copying them
247to the call/cc.org web-server (see also [[periodic-tasks]]). Should there be a problem (your egg doesn't show up, or whatever), send an email to any of the following persons asking them to help with uploading:
248
249* [[Felix Winkelmann]] <bunny351@gmail.com>
250* [[Alejandro Forero Cuervo]] <azul@freaks-unidos.net>
251* [[Mario Domenech Goulart]] <mario @ ucpel . tche . br>
Note: See TracBrowser for help on using the repository browser.