1 | Notes for Extension Maintainers |
---|
2 | =============================== |
---|
3 | |
---|
4 | |
---|
5 | This directory contains the development files for the official extensions of the |
---|
6 | CHICKEN Scheme implementation. You will find one directory for each extension |
---|
7 | containing all relevant files needed to build and distribute it. |
---|
8 | |
---|
9 | The extensions are stored in a subversion repository. If you want to know more |
---|
10 | about Subversion, visit http://subversion.tigris.org/. |
---|
11 | |
---|
12 | The URL of the repository is |
---|
13 | |
---|
14 | https://secure.afc.no-ip.info/svn/chicken-eggs |
---|
15 | |
---|
16 | To download the tree, enter |
---|
17 | |
---|
18 | $ svn co https://secure.afc.no-ip.info/svn/chicken-eggs |
---|
19 | |
---|
20 | (login "anonymous", password is "") |
---|
21 | |
---|
22 | To gain write-access to the repository, contact felix@call-with-current-continuation.org, |
---|
23 | or ask on the CHICKEN mailing list. |
---|
24 | |
---|
25 | Each subdirectory for an egg should contain the following structure: |
---|
26 | |
---|
27 | - If the author doesn't want to use the Subversion eggs' repository |
---|
28 | much, just use it to occasionally upload releases, everything should |
---|
29 | go directly under eggname. There should be a eggname/eggname.meta |
---|
30 | file with the semantics described bellow. |
---|
31 | |
---|
32 | - If the author does want to use the features provided by Subversion |
---|
33 | and make the eggs repository its main development repository, it |
---|
34 | should have the following structure: |
---|
35 | |
---|
36 | trunk/ - Contains the latest (possibly experimental/unstable) |
---|
37 | version of the code. |
---|
38 | |
---|
39 | branches/ - Contains, as subdirectories, any special branches of |
---|
40 | the code that need to be maintained apart of the trunk. |
---|
41 | |
---|
42 | tags/ - Contains special tags for the code (such as those for each |
---|
43 | release). Once created, a tag should never change (just like a |
---|
44 | release should never change). |
---|
45 | |
---|
46 | This layout is explained in the book Version Control with Subversion |
---|
47 | and has become a standard for many projects. |
---|
48 | |
---|
49 | To make a release the following should be done (where VERSION is of |
---|
50 | the form "1.0", "1.1", etc.): |
---|
51 | |
---|
52 | svn cp eggname/trunk eggname/tags/VERSION |
---|
53 | svn ps latest VERSION eggname/tags |
---|
54 | |
---|
55 | The ps (property set) sets a Subversion property on the tags |
---|
56 | directory for the egg with the name (version) of the latest release, |
---|
57 | to make it possible for tools (eg. egg-post-commit) to find it |
---|
58 | (without requiring any intelligence to compare version numbers on |
---|
59 | their part). |
---|
60 | |
---|
61 | Note that every release must have the eggname.meta file with the semantics |
---|
62 | described bellow (and, for that reason, so should trunk/, even though nothing |
---|
63 | will read that file from there). |
---|
64 | |
---|
65 | If you make any changes and commit them to the repository, a script on the |
---|
66 | server will create the egg (the packaged extension) and move it to the official |
---|
67 | site from which it can be downloaded via the `chicken-setup' tool. All that is |
---|
68 | required is a separate description named `EXTENSION.meta' that holds meta-information |
---|
69 | describing the author, required files and the category. The format is quite simple, |
---|
70 | it simple contains a list of sub-lists holding meta-properties. Here a simple |
---|
71 | example, taken from the `ajax' egg: |
---|
72 | |
---|
73 | |
---|
74 | ((egg "ajax.egg") |
---|
75 | (synopsis "Using xmlHttpRequest with the Spiffy web-server") |
---|
76 | (needs md5 url spiffy) |
---|
77 | (category web) |
---|
78 | (license "MIT") |
---|
79 | (author "felix <felix@call-with-current-continuation.org>") |
---|
80 | (files "ajax.setup" "ajax.scm" "ajax.html" "prototype.js")) |
---|
81 | |
---|
82 | |
---|
83 | You should at least provide the following properties: |
---|
84 | |
---|
85 | (synopsis STRING) |
---|
86 | |
---|
87 | A short description of the extension. |
---|
88 | |
---|
89 | (author STRING) |
---|
90 | |
---|
91 | The author, optionally with an e-mail address, if desired. |
---|
92 | |
---|
93 | (files STRING ...) |
---|
94 | |
---|
95 | The names of all files that should be contained in the egg. |
---|
96 | |
---|
97 | (egg STRING) |
---|
98 | |
---|
99 | The name of the egg file. |
---|
100 | |
---|
101 | (license STRING) |
---|
102 | |
---|
103 | The license under which the code is released. Please make sure you use the |
---|
104 | proper license if you package code written by others. |
---|
105 | |
---|
106 | (category SYMBOL) |
---|
107 | |
---|
108 | A category under which the egg should be listed on the egg-index page at |
---|
109 | http://www.call-with-current-continuation.org/eggs/index.html. |
---|
110 | |
---|
111 | Currently the set of categories is fixed, use one of: |
---|
112 | |
---|
113 | lang-exts Language extensions |
---|
114 | graphics Graphics |
---|
115 | debugging Debugging tools |
---|
116 | net Networking |
---|
117 | io Input/Output |
---|
118 | db Databases |
---|
119 | ffi Interfacing to other languages |
---|
120 | web Web programming |
---|
121 | xml XML processing |
---|
122 | doc-tools Documentation tools |
---|
123 | math Mathematical libraries |
---|
124 | oop Object-oriented programming |
---|
125 | data Algorithms and data-structures |
---|
126 | parsing Data formats and parsing |
---|
127 | tools Tools |
---|
128 | testing Unit-testing |
---|
129 | crypt Cryptography |
---|
130 | ui User interface toolkits |
---|
131 | code-generation Run-time code generation |
---|
132 | misc Miscellaneous |
---|
133 | |
---|
134 | (needs SYMBOL ...) |
---|
135 | |
---|
136 | Any extensions needed to build and use this extension. This should be the |
---|
137 | raw extension-identifier, the same that you would use in a `require-extension' |
---|
138 | form. |
---|
139 | |
---|
140 | You should provide a HTML file with documentation, if possible using Zbigniew |
---|
141 | Szadkowski's `eggdoc' extension (see http://www.call-with-current-continuation.org/eggs/eggdoc). |
---|
142 | If named `EXTENSION-NAME.html', then it will be automatically uploaded to call/cc.org. |
---|
143 | |
---|
144 | One final note: please keep the version numbers up-to date and add changes to the doc.scm |
---|
145 | or (if no eggdoc-script exists) the html file. |
---|
146 | |
---|
147 | |
---|
148 | Many thanks for contributing! |
---|