source: project/wiki/eggs tutorial @ 14110

Last change on this file since 14110 was 14110, checked in by sjamaan, 12 years ago

Fix most direct links to the manual sections

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