source: project/wiki/man/5/Egg specification format @ 35525

Last change on this file since 35525 was 35525, checked in by felix, 7 weeks ago

man/5: restructuring, fixed links, added csi module, simplification

File size: 9.1 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Format of the egg description file
6
7An egg description is basically an association list holding
8information about the components of the egg. An egg may contain
9multiple components: libraries, programs, Scheme or C include files
10and arbitrary data files. Dependencies between eggs can be
11specified as can be dependencies between components of an egg.
12
13A list of valid properties follows.
14
15=== Global properties
16
17==== version
18
19[egg property] (version STRING)
20
21Specifies version string for this egg. {{STRING}} should have
22the format {{<MAJOR>.<MINOR>.<PATCHLEVEL>}}, where only the
23{{<MAJOR>}} part is mandatory.
24
25Eggs from remote egg servers are automatically versioned - the
26version is part of the protocol to retrieve the egg and does not
27have to be specified in the {{.egg}} file. Eggs installed from
28local directories (see below) should explicitly specify a version.
29
30==== synopsis
31
32[egg property] (synopsis STRING)
33
34Gives a short description of this egg.
35
36==== author
37
38[egg property] (author STRING)
39
40Names the author or authors of the contained code.
41
42==== maintainer
43
44[egg property] (maintainer STRING)
45
46Names the maintainer of this code, if different from author(s).
47
48==== category
49
50[egg property] (category NAME)
51
52Gives the category under which this egg should be contained.
53See [[/chicken-projects/egg-index-5.html|the egg index]]
54for a list of currently used categories.
55
56==== license
57
58[egg property] (license STRING)
59
60Names the license under which this code is available.
61
62==== dependencies
63
64[egg property] (dependencies EGG ...)
65
66Lists eggs that this egg depends on, and which should be
67built and installed if they do not already exist in the repository.
68{{EGG}} should be whether a symbol or a list of the form
69{{EGGNAME VERSION}}, where the former means to install the
70newest available egg with this name and the latter specifies
71a specific version or higher.
72
73Note that this property
74has a different meaning depending on whether it appears at
75toplevel in an egg description or inside a component.
76
77==== test-dependencies
78
79[egg property] (test-dependencies EGG ...)
80
81Lists eggs that are required for this egg to run the tests
82(if tests exist.) This only has an effect if the {{-test}}
83option has been given to {{chicken-install}}.
84
85==== build-dependencies
86
87[egg property] (build-dependencies EGG ...)
88
89Lists eggs that are build-time dependencies for this egg,
90i.e. there are required to build, but not to run the contained
91code. Currently this is treated identical to {{dependencies}}.
92
93==== foreign-dependencies
94
95[egg property] (foreign-dependencies NAME ...)
96
97Lists external dependencies like native code libraries
98or system-specific packages and is currently only used for
99documentation purposes.
100
101==== platform
102
103[egg property] (platform PLATFORM)
104
105Specifies for which platform this egg is intended. {{PLATFORM}}
106should be a symbol naming the target platform ({{windows}}, {{linux}}
107or {{unix}}) or a boolean combination of platform values, allowed
108are {{(not PLATFORM)}}, {{(or PLATFORM ...)}} and {{(and PLATFORM ...)}}.
109If the expression can not be satisfied, then installation of this
110egg will abort.
111
112==== components
113
114[egg property] (components COMPONENT ...)
115
116Lists components (extensions, programs, include- or data files)
117that this extension installs. See below for information on how
118to specify component-specific information.
119
120==== host
121
122[egg property] (host PROP ...)
123
124Recursively process {{PROP ...}}, but only for the host (build)
125platform, in case this is a "cross-chicken", a CHICKEN installation
126intended for cross compilation.
127
128==== target
129
130[egg property] (target PROP ...)
131
132Recursively process {{PROP ...}}, but only for the target
133platform, in case this is a "cross-chicken", a CHICKEN installation
134intended for cross compilation.
135
136==== Components
137
138==== extension
139
140[egg property] (extension NAME PROP ...)
141
142Specifies an extension library component. The properties
143{{PROP...}} are processed recursively and apply only to this
144component.
145
146==== data
147
148[egg property] (data NAME PROP ...)
149
150Specifies one or more arbitrary data files.
151
152==== generated-source-file
153
154[egg property] (generated-source-file NAME PROP ...)
155
156Specifies a file that is generated during the process of building
157the egg.
158
159==== c-include
160
161[egg property] (c-include NAME PROP ...)
162
163Specifies one or more C include files.
164
165==== scheme-include
166
167[egg property] (scheme-include NAME PROP ...)
168
169Specifies one or more Scheme include files.
170
171==== program
172
173[egg property] (program NAME PROP ...)
174
175Specifies an executable program.
176
177==== Component properties
178
179==== host
180
181[egg property] (host PROP ...)
182
183Process {{PROP ...}} recursively for the current component, but
184apply the properties only to the host (build) part, when using
185a CHICKEN installation intended for cross-compilation.
186
187==== target
188
189[egg property] (target PROP ...)
190
191Process {{PROP ...}} recursively for the current component, but
192apply the properties only to the target part, when using
193a CHICKEN installation intended for cross-compilation.
194
195==== linkage
196
197[egg property] (linkage LINKAGE)
198
199Define whether the component should be linked dynamically or
200statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This
201property only makes sense for extension libraries.
202
203==== types-file
204
205[egg property] (types-file [NAME])
206
207Specifies that a "type-database" file should be generated and
208installed for this component. This property is only used for
209extension libraries. The name is optional and defaults to the
210name of the extensions (with the proper extension).
211
212If {{NAME}} is a list of the form {{(predefined [NAME])}}, then
213no types file is created during compilation and an existing types file
214for this extension is assumed and installed.
215
216==== inline-file
217
218[egg property] (inline-file [NAME])
219
220Specifies that an "inline" file should be generated and installed
221for this component. This property is only used for extension
222libraries. The name is optional and defaults to the
223name of the extensions (with the proper extension).
224
225==== custom-build
226
227[egg property] (custom-build STRING)
228
229Specifies a custom build operation that should be executed
230instead of the default build operations. This property is mandatory
231for components of type {{generated-source-file}}. {{STRING}}
232usually contains a shell command and thus may be platform sensitive.
233
234The script will be made executable on UNIX systems, if necessary,
235and will be invoked like the {{csc}} program and
236is executed with the location of the CHICKEN
237binaries in the {{PATH}}. Also, tjhe environment variables
238{{CHICKEN_CC}} and {{CHICKEN_CXX}} are set to the
239names of the C and C++ compiler that were used for building the
240system.
241
242==== csc-options
243
244[egg property] (csc-options OPTION ...)
245
246Specifies additional compiler options for {{csc}} that should be
247used when building this component. If this property is not
248given, the default options are used, which are {{-O2 -d1}}
249for extensions and programs and {{-O2 -d0}} for import
250libraries.
251
252Note that the options are quoted when passed to csc during the
253compilation of the extension, so multiple options should be specified
254as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}
255(the latter would be a single option containing a whitespace character).
256
257==== link-options
258
259[egg property] (link-options OPTION ...)
260
261Specifies additional link options for {{csc}} that should be
262used when building this component.
263
264Note that the options are quoted when passed to csc during the
265compilation of the extension, so multiple options should be specified
266as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}
267(the latter would be a single option containing a whitespace character).
268
269==== source
270
271[egg property] (source NAME)
272
273Specifies an alternative source file, in case it has a name
274distinct from the component name. By default the source file
275for a component is named after the component, with the {{.scm}}
276extension added.
277
278==== install-name
279
280[egg property] (install-name NAME)
281
282Specifies an alternative installation name of the component,
283if it differs from the actual component name. This property
284is most useful if an egg installs an extension and a program
285of the same name, but needs to distinguish the components during
286build time.
287
288==== dependencies
289
290[egg property] (dependencies NAME ...)
291
292Specifies dependencies between components. Note that this use
293of the {{dependencies}} property is different from the property
294of the same name that is used at the "global" level of the
295egg description file.
296
297==== destination
298
299[egg property] (destination NAME)
300
301Specifies an alternative installation destination for the
302built component and only applies
303to components of type {{data}}, {{c-include}} and {{scheme-include}}.
304This property should only be used in extreme
305cases, as it is recommended to use the default installation
306locations, which are:
307
308* for C include files: {{<PREFIX>/include/chicken/}}
309
310* for Scheme include files: {{<PREFIX>/share/chicken/}}
311
312* for data files: {{<PREFIX>/share/chicken/}}
313
314==== files
315
316[egg property] (files NAME ...)
317
318Specifies source files for this component and only applies
319to components of type {{data}}, {{c-include}} and {{scheme-include}}.
320
321
322---
323
324Previous: [[Extension tools]]
325
326Next: [[Units and the linking model]]
Note: See TracBrowser for help on using the repository browser.