source: project/README @ 931

Last change on this file since 931 was 931, checked in by felix, 12 years ago

removed dan's e-mail from dpfw.meta, new repo-addr in README, numbers fix (kon)

File size: 5.1 KB
Line 
1Notes for Extension Maintainers
2===============================
3
4
5This directory contains the development files for the official extensions of the
6CHICKEN Scheme implementation. You will find one directory for each extension
7containing all relevant files needed to build and distribute it.
8
9The extensions are stored in a subversion repository. If you want to know more
10about Subversion, visit http://subversion.tigris.org/.
11
12The URL of the repository is
13
14  https://galinha.ucpel.tche.br/svn/chicken-eggs
15
16To download the tree, enter
17
18  $ svn co https://galinha.ucpel.tche.br/svn/chicken-eggs
19
20  (login "anonymous", password is "")
21
22To gain write-access to the repository, contact felix@call-with-current-continuation.org,
23or ask on the CHICKEN mailing list.
24
25Each 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
65If you make any changes and commit them to the repository, a script on the
66server will create the egg (the packaged extension) and move it to the official
67site from which it can be downloaded via the `chicken-setup' tool. All that is
68required is a separate description named `EXTENSION.meta' that holds meta-information
69describing the author, required files and the category. The format is quite simple,
70it simple contains a list of sub-lists holding meta-properties. Here a simple
71example, 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
83You 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      macros      Macros and meta-syntax
134
135  (needs SYMBOL ...)
136
137    Any extensions needed to build and use this extension. This should be the
138    raw extension-identifier, the same that you would use in a `require-extension'
139    form.
140
141You should provide a HTML file with documentation, if possible using Zbigniew
142Szadkowski's `eggdoc' extension (see http://www.call-with-current-continuation.org/eggs/eggdoc).
143If named `EXTENSION-NAME.html', then it will be automatically uploaded to call/cc.org.
144
145One final note: please keep the version numbers up-to date and add changes to the doc.scm
146or (if no eggdoc-script exists) the html file.
147
148
149Many thanks for contributing!
Note: See TracBrowser for help on using the repository browser.