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

Last change on this file since 36014 was 36014, checked in by Mario Domenech Goulart, 18 months ago

/man/5/Egg specification format: fix link to the egg index

File size: 10.2 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 [[https://wiki.call-cc.org/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==== component-options
133
134[egg property] (component-options OPTIONSPEC ...)
135
136Specifies global options for all programs and extensions compiled for this egg.
137{{OPTIONSPEC}} may be {{csc-options}} or {{link-options}} specifications.
138
139=== Components
140
141==== extension
142
143 [egg property] (extension NAME PROP ...)
144
145Specifies an extension library component. The properties
146{{PROP...}} are processed recursively and apply only to this
147component.
148
149==== data
150
151 [egg property] (data NAME PROP ...)
152
153Specifies one or more arbitrary data files.
154
155==== generated-source-file
156
157 [egg property] (generated-source-file NAME PROP ...)
158
159Specifies a file that is generated during the process of building
160the egg.
161
162==== c-include
163
164 [egg property] (c-include NAME PROP ...)
165
166Specifies one or more C include files.
167
168==== scheme-include
169
170 [egg property] (scheme-include NAME PROP ...)
171
172Specifies one or more Scheme include files.
173
174==== program
175
176 [egg property] (program NAME PROP ...)
177
178Specifies an executable program.
179
180=== Component properties
181
182==== host
183
184 [egg property] (host PROP ...)
185
186Process {{PROP ...}} recursively for the current component, but
187apply the properties only to the host (build) part, when using
188a CHICKEN installation intended for cross-compilation.
189
190==== target
191
192 [egg property] (target PROP ...)
193
194Process {{PROP ...}} recursively for the current component, but
195apply the properties only to the target part, when using
196a CHICKEN installation intended for cross-compilation.
197
198==== linkage
199
200 [egg property] (linkage LINKAGE)
201
202Define whether the component should be linked dynamically or
203statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This
204property only makes sense for extension libraries.
205
206==== types-file
207
208 [egg property] (types-file [NAME])
209
210Specifies that a "type-database" file should be generated and
211installed for this component. This property is only used for
212extension libraries. The name is optional and defaults to the
213name of the extensions (with the proper extension).
214
215If {{NAME}} is a list of the form {{(predefined [NAME])}}, then
216no types file is created during compilation and an existing types file
217for this extension is assumed and installed.
218
219==== inline-file
220
221 [egg property] (inline-file [NAME])
222
223Specifies that an "inline" file should be generated and installed
224for this component. This property is only used for extension
225libraries. The name is optional and defaults to the
226name of the extensions (with the proper extension).
227
228==== custom-build
229
230 [egg property] (custom-build STRING)
231
232Specifies a custom build operation that should be executed instead of
233the default build operations. This property is mandatory for
234components of type {{generated-source-file}}. {{STRING}} should be the
235name of a shell command (e.g., a script) and thus may be platform
236sensitive.  The path to the file is prepended implicitly, so you
237should '''not''' prefix it with {{./}}.  On Windows, a file with the
238{{.bat}} extension will be picked before a plain file with no
239extension.
240
241The script will be made executable on UNIX systems, if necessary,
242and will be invoked like the {{csc}} program and
243is executed with the location of the CHICKEN
244binaries in the {{PATH}}. Also, the following environment variables
245are set in the execution environment of the script:
246
247* {{CHICKEN_CC}}: name of the C compiler used for building CHICKEN
248* {{CHICKEN_CXX}}: name of the C++ compiler set during the build of CHICKEN
249* {{CHICKEN_CSC}}: path to {{csc}}
250* {{CHICKEN_CSI}}: path to {{csi}}
251
252
253==== csc-options
254
255 [egg property] (csc-options OPTION ...)
256
257Specifies additional compiler options for {{csc}} that should be
258used when building this component. If this property is not
259given, the default options are used, which are {{-O2 -d1}}
260for extensions and programs and {{-O2 -d0}} for import
261libraries.
262
263Note that the options are quoted when passed to csc during the
264compilation of the extension, so multiple options should be specified
265as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}
266(the latter would be a single option containing a whitespace character).
267
268==== link-options
269
270 [egg property] (link-options OPTION ...)
271
272Specifies additional link options for {{csc}} that should be
273used when building this component.
274
275Note that the options are quoted when passed to csc during the
276compilation of the extension, so multiple options should be specified
277as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}
278(the latter would be a single option containing a whitespace character).
279
280==== source
281
282 [egg property] (source NAME)
283
284Specifies an alternative source file, in case it has a name
285distinct from the component name. By default the source file
286for a component is named after the component, with the {{.scm}}
287extension added.
288
289==== install-name
290
291 [egg property] (install-name NAME)
292
293Specifies an alternative installation name of the component,
294if it differs from the actual component name. This property
295is most useful if an egg installs an extension and a program
296of the same name, but needs to distinguish the components during
297build time.
298
299==== component-dependencies
300
301 [egg property] (component-dependencies NAME ...)
302
303Specifies dependencies to other components. {{NAME ...}} must
304be the names of extension, program, scheme-include- or generated source file
305components that should be built before the current component.
306
307==== source-dependencies
308
309 [egg property] (source-dependencies NAME ...)
310
311Specifies dependencies to additional source files. {{NAME ...}} must
312denote filenames of which the program or extension depends.
313A program or extension implicitly depends on its source file and
314and on the egg-specification file.
315
316==== destination
317
318 [egg property] (destination NAME)
319
320Specifies an alternative installation destination for the
321built component and only applies
322to components of type {{data}}, {{c-include}} and {{scheme-include}}.
323This property should only be used in extreme
324cases, as it is recommended to use the default installation
325locations, which are:
326
327* for C include files: {{<PREFIX>/include/chicken/}}
328
329* for Scheme include files: {{<PREFIX>/share/chicken/}}
330
331* for data files: {{<PREFIX>/share/chicken/}}
332
333==== files
334
335 [egg property] (files NAME ...)
336
337Specifies source files for this component and only applies
338to components of type {{data}}, {{c-include}} and {{scheme-include}}.
339
340==== modules
341
342 [egg property] (modules NAME ...)
343
344Specifies modules that the component (usually an extension) contains.
345{{chicken-install}} will compile and install all import libraries for the given modules.
346If this property is not given, then it is assumed that the extension has a single
347module of the same name as the component.
348
349---
350
351Previous: [[Extension tools]]
352
353Next: [[Units and linking model]]
Note: See TracBrowser for help on using the repository browser.