source: project/wiki/eggs tutorial @ 37951

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

eggs tutorial: adapt to provide information on eggs for CHICKEN 5

File size: 11.8 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 ckeck 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; 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.
44; 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).
45; 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.
46; License : The license for your egg (see the [[eggs-licensing|Eggs Licensing]] page)
47; Version History : Should list all releases of the egg and a description of their differences with the previous versions.
48
49
50=== Egg build system and metadata
51
52CHICKEN 5 introduced an new format for the system to build eggs, which
53is incompatible with the one for CHICKEN 4.  Below you can find
54information about both.
55
56
57==== For CHICKEN 5
58
59The build system for eggs in CHICKEN 5 reads {{.egg}} files, which
60contain information about the egg and describe how eggs are to be built.
61
62See [[/man/5/Extensions|the manual section on extensions]] for more
63information and simple examples on how to write {{.egg}} files and
64[[/man/5/Egg%20specification%20format|Egg specification format]] for
65the specification of {{.egg}} files.
66
67For practical examples, see what
68[[https://code.call-cc.org/cgi-bin/gitweb.cgi?p=eggs-5-latest.git;a=tree|existing eggs]]
69do.
70
71
72==== For CHICKEN 4
73
74CHICKEN 4 uses two separate files for the build system: a {{.setup}}
75with instructions on how to build the egg; and a {{.meta}} file
76containing metadata on the egg (license, dependencies, synopsis,
77author etc.).
78
79Below is an example of an extension is called ''mpeg3''.  Replace
80occurences of that string throughout this file with the actual name of
81your extension.
82
83
84===== The setup file
85
86In order for {{chicken-install}} to install your extension, we recommend that you create a {{mpeg3.setup}} file with information about your egg.
87{{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]].
88
89If your egg does not contain macros, your setup file should look similar to the following:
90
91<enscript highlight=scheme>
92;; These two instructions will produce statically and dynamically linkable object files "mpeg3.o" and "mpeg3.so" respectively.
93(compile -s -O3 -d1 mpeg3.scm -j mpeg3)
94(compile -s mpeg.import.scm -O3 -d0)
95
96(install-extension
97 ;; Name of your extension:
98 'mpeg3
99 ;; Files to install for your extension:
100 '("mpeg3.so" "mpeg3.import.so")
101 ;; Assoc list with properties for your extension:
102 '((version "1.2")))
103</enscript>
104
105The first line will cause {{mpeg3.scm}} to be compiled into
106{{mpeg3.so}} (a shared library for dynamic loading), which is installed by {{install-extension}}.
107The {{-j}} option will make sure that an ''import library'' is generated for your module(s) which, after compilation,
108provide module meta-information and exported syntax. Alternatively you can use {{-J}} without any arguments to generate import libraries for all defined modules.
109
110The second line will compile the generated import library.
111
112If 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.
113
114Note that version is represented by a string.  That's because numbers can be tricky to represent versions.  Integers are usually not enough to represent minor/major changes, and floating point numbers require you to determine the number of minor releases a priori, otherwise you'll inevitably end up with version 1.10, which is numerically equivalent to 1.1, and that would cause problems when chicken-install tries to match versions to determine dependencies.
115
116===== The meta file
117
118Finally, you will need to create {{mpeg3.meta}}, with information about your egg.
119This file is used by the process that releases and uploads new eggs.
120It should contain a single s-expr as follows:
121
122<enscript highlight=scheme>(
123; Your egg's license:
124(license "BSD")
125
126; Pick one from the list of categories (see below) for your egg and enter it
127; here.
128(category web)
129
130; A list of eggs mpeg3 depends on.  If none, you can omit this declaration
131; altogether. `depends' is an alias to `needs'.
132; Notice that you should NOT put CHICKEN units (e.g., srfi-1, srfi-13
133; and many others) in `needs' or in `depends'.
134(needs sandbox syntax-case)
135
136; A list of eggs required for TESTING ONLY.  See the `Tests' section.
137; Just like `needs' and `depends', `test-depends' should NOT contain
138; CHICKEN units.
139(test-depends test)
140
141(author "Your Name Goes Here")
142(synopsis "A basic description of the purpose of the egg."))
143</enscript>
144
145More information about extension meta properties can be found here at
146the [[Metafile reference]].
147
148
149==== Egg categories
150
151For the category entry, used by for {{.meta}} and {{.egg}} files
152(CHICKEN 4 and 5, respectively) you can use any of the following
153possibilities:
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;hell: Concurrency and parallelism
181;uncategorized: Uncategorized
182;obsolete: Unsupported or redundant
183
184=== Licensing
185
186Please refer to [[Eggs Licensing]].
187
188
189=== Tests
190
191[[/man/5/Extensions|chicken-install]] can automatically run a test suite on a freshly installed egg, if the egg directory
192contains a directory named {{tests}}, which should include a Scheme source file named {{run.scm}}.
193When {{chicken-install}} is invoked with the {{-test}} option, then this file will be executed
194(with {{test}} being the current working directory). It is recommended to add a test suite
195to 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.'''
196
197If your tests depend on extra eggs, '''do not''' use {{needs}}/{{depends}} to require them.  Use {{test-depends}} instead, so they'll only be required when {{chicken-install}} is used with the {{-test}} option.
198
199For proper integration to the [[http://tests.call-cc.org|test infrastructure]],
200{{run.scm}} should exit {{0}} (zero) when all tests
201pass or any other number in case some test fails.  If you are using
202the [[/egg/test|test]] egg, a call to {{test-exit}} makes {{run.scm}}
203exit properly.
204
205With regard to the test infrastructure, notice that only the latest released egg versions are tested.
206
207==== Testing your extension
208
209Before publishing your egg, it is recommended to run [[/egg/salmonella|salmonella]] on it to try to catch some common mistakes in advance.  Here's how you can do that:
210
211  $ chicken-install salmonella # in case you don't have salmonella installed
212  $ cd egg-dir # the directory where your egg code is stored
213  $ salmonella
214
215Salmonella 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:
216
217  $ salmonella-log-viewer salmonella.log
218
219See the [[/egg/salmonella|salmonella documentation]] for more information on how to test eggs.
220
221If your egg installs an executable file and tests call that file, take a look at [[http://wiki.call-cc.org/eggref/4/salmonella#testing-executable-files-installed-by-eggs|this caveat]].
222
223== Managing and hosting eggs
224
225CHICKEN currently supports distributing eggs hosted on remote
226repositories (in the past, we had a [[chicken-svn-for-eggs|central
227Subversion repository]] which is now deprecated for new eggs).  So,
228you can host your egg code on popular repository providers like
229[[http://github.com|github]], [[http://bitbucket.org|bitbucket]] etc,
230or even using your own server.
231
232See the [[/releasing-your-egg|Releasing your egg]] document for
233information on how to host egg code and manage releases.
234
235== Caveats
236
237=== License
238
239This 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.
240
241== Post check in notes
242
243Once 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.
244
245Strive 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.