source: project/wiki/eggs tutorial @ 27001

Last change on this file since 27001 was 27001, checked in by Mario Domenech Goulart, 9 years ago

eggs tutorial (wiki): remove "the easy way" and "for advanced users" from section titles about hosting eggs onthe chicken svn and other VCS repositories, respectively.

File size: 12.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
16We will assume your extension is called ''mpeg3''.  Replace occurences of that string throughout this file with the actual name of your extension.
17
18== Programming your extension
19
20=== Code layout
21
22You should always use the module system for extensions to avoid creating name-conflicts
23if one of your exported toplevel identifiers clashes with an already existing definition.
24Modules also allow to export syntax definitions in a clean and easy-to-use way.
25
26=== Testing your extension
27
28Create a {{tests}} directory in your egg tree and put your test code in a {{tests/run.scm}} file.  This file is used by chicken-install when called with the {{-test}} command line option and by [[http://tests.call-cc.org|the test infrastructure]] to run tests and report their status.
29
30{{tests/run.scm}} should exit zero when all tests pass or a non-zero value when some test fails.  If you are using the [[/egg/test|test egg]], you can use the {{test-exit}} procedure to properly report the test status.
31
32Before 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:
33
34  $ chicken-install salmonella # in case you don't have salmonella installed
35  $ cd egg-dir # the directory where yor egg code is stored
36  $ salmonella --this-egg
37
38Salmonella 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:
39
40  $ salmonella-log-viewer salmonella.log
41
42See the [[/egg/salmonella|salmonella documentation]] for more information on how to test eggs.
43
44
45== Additional files
46
47
48=== Documentation
49
50Providing good documentation for your eggs is a fundamental part of their overall quality.
51
52You 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.
53
54You 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/4/eggname-here and use it to edit the wiki contents.
55
56If 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:
57
58  $ svn co https://code.call-cc.org/svn/chicken-eggs/wiki
59
60==== Sections
61
62We recommend that each page for an egg is given at least the following sections:
63
64; 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.
65; Description : Must briefly describe and state the purpose of the egg.
66; Authors : The egg authors and maintainers
67; 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.
68; 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).
69; 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.
70; License : The license for your egg (see the [[eggs-licensing|Eggs Licensing]] page)
71; Version History : Should list all releases of the egg and a description of their differences with the previous versions.
72
73
74=== The setup file
75
76In order for {{chicken-install}} to install your extension, we recommend that you create a {{mpeg3.setup}} file with information about your egg.
77{{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]].
78
79If your egg does not contain macros, your setup file should look similar to the following:
80
81<enscript highlight=scheme>
82; These two instructions will produce statically and dynamically linkable object files "mpeg3.o" and "mpeg3.so" respectively.
83(compile -s -O2 -d1 mpeg3.scm -j mpeg3)
84(compile -s mpeg.import.scm -O2 -d0)
85(compile -c -O2 -d1 mpeg3.scm -unit mpeg3 -j mpeg3)
86;
87(install-extension
88  ; Name of your extension:
89  'mpeg3
90  ; Files to install for your extension:
91  '("mpeg3.o" "mpeg3.so" "mpeg3.import.so")
92  ; Assoc list with properties for your extension:
93  '((version "1.2") ;; version number should be a string
94    (static "mpeg3.o"))) ;; for static linking
95</enscript>
96
97The first line will cause {{mpeg3.scm}} to be compiled into
98{{mpeg3.so}} (a shared library for dynamic loading), which is installed by {{install-extension}}.
99The {{-j}} option will make sure that an ''import library'' is generated, that, after compilation,
100provides module meta-information and exported syntax.
101
102The second line will compile the generated import library.
103
104The third line will cause {{mpeg3.scm}} to be compiled into
105{{mpeg3.o}} (a static module for static linking), which is installed by {{install-extension}}.
106
107If 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.
108
109
110=== The meta file
111
112Finally, you will need to create {{mpeg3.meta}}, with information about your egg.
113This file is used by the process that releases and uploads new eggs.
114It should contain a single s-expr as follows:
115
116<enscript highlight=scheme>(
117; Your egg's license:
118(license "BSD")
119
120; Pick one from the list of categories (see below) for your egg and enter it
121; here.
122(category web)
123
124; A list of eggs mpeg3 depends on.  If none, you can omit this declaration
125; altogether. `depends' is an alias to `needs'.
126; Notice that you should NOT put Chicken units (e.g., srfi-1, srfi-13
127; and many others) in `needs' or in `depends'.
128(needs sandbox syntax-case)
129
130; A list of eggs required for TESTING ONLY.  See the `Tests' section.
131; Just like `needs' and `depends', `test-depends' should NOT contain
132; Chicken units.
133(test-depends test)
134
135(author "Your Name Goes Here")
136(synopsis "A basic description of the purpose of the egg."))
137</enscript>
138
139For the category entry you can use any of the following:
140
141;code-generation: Code generation
142;crypt: Cryptography
143;data: Algorithms and data-structures
144;db: Databases
145;debugging: Debugging tools
146;doc-tools: Documentation tools
147;egg-tools: Egg tools
148;ffi: Interfacing to other languages
149;graphics: Graphics
150;io: Input/Output
151;lang-exts: Language extensions
152;logic: Logic programming
153;macros: Macros and meta-syntax
154;math: Mathematical libraries
155;misc: Miscellaneous
156;net: Networking
157;oop: Object-oriented programming
158;os: OS interface
159;parsing: Data formats and parsing
160;sound: Sound related stuff
161;testing: Unit-testing
162;tools: Command line tools
163;ui: User interface toolkits
164;web: Web programming
165;xml: XML processing
166;hell: Concurrency and parallelism
167;uncategorized: Uncategorized
168;obsolete: Unsupported or redundant
169
170Make sure you read [[Eggs Licensing]]!
171
172More information about extension meta properties can be found here at
173the [[Metafile reference]].
174
175=== Tests
176
177[[/man/4/Extensions|chicken-install]] can automatically run a test suite on a freshly installed egg, if the egg directory
178contains a directory named {{tests}}, which should include a Scheme source file named {{run.scm}}.
179When {{chicken-install}} is invoked with the {{-test}} option, then this file will be executed
180(with {{test}} being the current working directory). It is recommended to add a test suite
181to 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.'''
182
183If 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.
184
185For proper integration to the [[http://tests.call-cc.org|test infrastructure]],
186{{run.scm}} should exit {{0}} (zero) when all tests
187pass or any other number in case some test fails.  If you are using
188the [[/egg/test|test]] egg, a call to {{test-exit}} makes {{run.scm}}
189exit properly.
190
191== Managing eggs in the Chicken hosted repository
192
193If you don't already have your own hosted version control system, you can host your eggs inside the Chicken hosted repository, and let us do the hard work.
194
195=== Obtaining an account in the repository
196
197We host Chicken Extensions in the following [[http://subversion.apache.org/|Subversion]] repository:
198
199* https://code.call-cc.org/svn/chicken-eggs/ (user=anonymous, empty password)
200
201In order to create your extensions you will need access to this repository.  See the [[/contribute|Contribute]] page for information about how to request an account.
202
203With this information we will create a directory for your extension and create you an account with the appropriate access rights.
204
205To checkout this directory run the following command:
206
207 $ svn checkout https://code.call-cc.org/svn/chicken-eggs/release/4/mpeg3
208
209
210=== Directory structure
211
212The directory for your egg will have the following subdirectories:
213
214; {{trunk}} : Here you can keep the latest (potentially unstable) development version for your egg.
215; {{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.
216; {{branches}} : Contains, as subdirectories, any special branches of the code that need to be maintained apart from the trunk.
217; {{extra}} : files that you want to keep under version control but are not required to be installed by {{chicken-install}}
218
219For documentation, there is a {{wiki}} directory at the top-level of the repository. It holds the entire contents for this wiki.
220
221
222=== Importing your files
223
224You will initially copy your files to the {{trunk}} directory, add them manually and commit your changes.  For example:
225
226 $ svn add trunk/mpeg3.scm
227 $ svn add trunk/mpeg3.setup
228 $ svn add trunk/mpeg3.meta
229 $ svn commit -m "Importing mpeg3 extension."
230
231=== Making a new release
232
233Once the code in {{trunk}} is reasonably stable and you want to make a new release, copy it to a new directory under {{tags}}.
234The directory should be named after the software version.
235Software versions should have the form of a list of numbers separated by a dot
236(eg. “1.3.4” is a valid software version, whereas “1.3-0” or “1.3rc0” are not).
237
238For example, to make the 1.3 release for mpeg3, you would run the following commands (at the directory where you checked out your egg):
239
240 $ svn copy trunk tags/1.3
241 $ svn commit -m "Releasing version 1.3."
242
243== Managing eggs in your own source control system
244
245You can also host your eggs in your own source control system - including distributed ones. To do this, you need to be able to host a publicly-readable repository somewhere.
246
247Full instructions on how to do this, with notes for all the version control systems we've tried (please add instructions if you use another!) are available at [[releasing-your-egg]]
248
249== Caveats
250
251=== License
252
253This 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 its dependencies's licenses.
254
255== Post check in notes
256
257Once 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.
258
259Strive 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.