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

Last change on this file since 35833 was 35833, checked in by evhan, 5 months ago

man/5: Indent egg property tags so they're boxed and highlighted

File size: 10.0 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
73==== test-dependencies
74
75 [egg property] (test-dependencies EGG ...)
76
77Lists eggs that are required for this egg to run the tests
78(if tests exist.) This only has an effect if the {{-test}}
79option has been given to {{chicken-install}}.
80
81==== build-dependencies
82
83 [egg property] (build-dependencies EGG ...)
84
85Lists eggs that are build-time dependencies for this egg,
86i.e. there are required to build, but not to run the contained
87code. Currently this is treated identical to {{dependencies}}.
88
89==== foreign-dependencies
90
91 [egg property] (foreign-dependencies NAME ...)
92
93Lists external dependencies like native code libraries
94or system-specific packages and is currently only used for
95documentation purposes.
96
97==== platform
98
99 [egg property] (platform PLATFORM)
100
101Specifies for which platform this egg is intended. {{PLATFORM}}
102should be a symbol naming the target platform ({{windows}}, {{linux}}
103or {{unix}}) or a boolean combination of platform values, allowed
104are {{(not PLATFORM)}}, {{(or PLATFORM ...)}} and {{(and PLATFORM ...)}}.
105If the expression can not be satisfied, then installation of this
106egg will abort.
107
108==== components
109
110 [egg property] (components COMPONENT ...)
111
112Lists components (extensions, programs, include- or data files)
113that this extension installs. See below for information on how
114to specify component-specific information.
115
116==== host
117
118 [egg property] (host PROP ...)
119
120Recursively process {{PROP ...}}, but only for the host (build)
121platform, in case this is a "cross-chicken", a CHICKEN installation
122intended for cross compilation.
123
124==== target
125
126 [egg property] (target PROP ...)
127
128Recursively process {{PROP ...}}, but only for the target
129platform, in case this is a "cross-chicken", a CHICKEN installation
130intended for cross compilation.
131
132=== Components
133
134==== extension
135
136 [egg property] (extension NAME PROP ...)
137
138Specifies an extension library component. The properties
139{{PROP...}} are processed recursively and apply only to this
140component.
141
142==== data
143
144 [egg property] (data NAME PROP ...)
145
146Specifies one or more arbitrary data files.
147
148==== generated-source-file
149
150 [egg property] (generated-source-file NAME PROP ...)
151
152Specifies a file that is generated during the process of building
153the egg.
154
155==== c-include
156
157 [egg property] (c-include NAME PROP ...)
158
159Specifies one or more C include files.
160
161==== scheme-include
162
163 [egg property] (scheme-include NAME PROP ...)
164
165Specifies one or more Scheme include files.
166
167==== program
168
169 [egg property] (program NAME PROP ...)
170
171Specifies an executable program.
172
173=== Component properties
174
175==== host
176
177 [egg property] (host PROP ...)
178
179Process {{PROP ...}} recursively for the current component, but
180apply the properties only to the host (build) part, when using
181a CHICKEN installation intended for cross-compilation.
182
183==== target
184
185 [egg property] (target PROP ...)
186
187Process {{PROP ...}} recursively for the current component, but
188apply the properties only to the target part, when using
189a CHICKEN installation intended for cross-compilation.
190
191==== linkage
192
193 [egg property] (linkage LINKAGE)
194
195Define whether the component should be linked dynamically or
196statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This
197property only makes sense for extension libraries.
198
199==== types-file
200
201 [egg property] (types-file [NAME])
202
203Specifies that a "type-database" file should be generated and
204installed for this component. This property is only used for
205extension libraries. The name is optional and defaults to the
206name of the extensions (with the proper extension).
207
208If {{NAME}} is a list of the form {{(predefined [NAME])}}, then
209no types file is created during compilation and an existing types file
210for this extension is assumed and installed.
211
212==== inline-file
213
214 [egg property] (inline-file [NAME])
215
216Specifies that an "inline" file should be generated and installed
217for this component. This property is only used for extension
218libraries. The name is optional and defaults to the
219name of the extensions (with the proper extension).
220
221==== custom-build
222
223 [egg property] (custom-build STRING)
224
225Specifies a custom build operation that should be executed instead of
226the default build operations. This property is mandatory for
227components of type {{generated-source-file}}. {{STRING}} should be the
228name of a shell command (e.g., a script) and thus may be platform
229sensitive.  The path to the file is prepended implicitly, so you
230should '''not''' prefix it with {{./}}.  On Windows, a file with the
231{{.bat}} extension will be picked before a plain file with no
232extension.
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, the following environment variables
238are set in the execution environment of the script:
239
240* {{CHICKEN_CC}}: name of the C compiler used for building CHICKEN
241* {{CHICKEN_CXX}}: name of the C++ compiler set during the build of CHICKEN
242* {{CHICKEN_CSC}}: path to {{csc}}
243* {{CHICKEN_CSI}}: path to {{csi}}
244
245
246==== csc-options
247
248 [egg property] (csc-options OPTION ...)
249
250Specifies additional compiler options for {{csc}} that should be
251used when building this component. If this property is not
252given, the default options are used, which are {{-O2 -d1}}
253for extensions and programs and {{-O2 -d0}} for import
254libraries.
255
256Note that the options are quoted when passed to csc during the
257compilation of the extension, so multiple options should be specified
258as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}
259(the latter would be a single option containing a whitespace character).
260
261==== link-options
262
263 [egg property] (link-options OPTION ...)
264
265Specifies additional link options for {{csc}} that should be
266used when building this component.
267
268Note that the options are quoted when passed to csc during the
269compilation of the extension, so multiple options should be specified
270as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}
271(the latter would be a single option containing a whitespace character).
272
273==== source
274
275 [egg property] (source NAME)
276
277Specifies an alternative source file, in case it has a name
278distinct from the component name. By default the source file
279for a component is named after the component, with the {{.scm}}
280extension added.
281
282==== install-name
283
284 [egg property] (install-name NAME)
285
286Specifies an alternative installation name of the component,
287if it differs from the actual component name. This property
288is most useful if an egg installs an extension and a program
289of the same name, but needs to distinguish the components during
290build time.
291
292==== component-dependencies
293
294 [egg property] (component-dependencies NAME ...)
295
296Specifies dependencies to other components. {{NAME ...}} must
297be the names of extension, program, scheme-include- or generated source file
298components that should be built before the current component.
299
300==== source-dependencies
301
302 [egg property] (source-dependencies NAME ...)
303
304Specifies dependencies to additional source files. {{NAME ...}} must
305denote filenames of which the program or extension depends.
306A program or extension implicitly depends on its source file and
307and on the egg-specification file.
308
309==== destination
310
311 [egg property] (destination NAME)
312
313Specifies an alternative installation destination for the
314built component and only applies
315to components of type {{data}}, {{c-include}} and {{scheme-include}}.
316This property should only be used in extreme
317cases, as it is recommended to use the default installation
318locations, which are:
319
320* for C include files: {{<PREFIX>/include/chicken/}}
321
322* for Scheme include files: {{<PREFIX>/share/chicken/}}
323
324* for data files: {{<PREFIX>/share/chicken/}}
325
326==== files
327
328 [egg property] (files NAME ...)
329
330Specifies source files for this component and only applies
331to components of type {{data}}, {{c-include}} and {{scheme-include}}.
332
333==== modules
334
335 [egg property] (modules NAME ...)
336
337Specifies modules that the component (usually an extension) contains.
338{{chicken-install}} will compile and install all import libraries for the given modules.
339If this property is not given, then it is assumed that the extension has a single
340module of the same name as the component.
341
342---
343
344Previous: [[Extension tools]]
345
346Next: [[Units and linking model]]
Note: See TracBrowser for help on using the repository browser.