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

Last change on this file since 37719 was 37719, checked in by sjamaan, 2 months ago

Sync manual from git to wiki

File size: 12.6 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===== distribution-files
109
110 [egg property] (distribution-files FILE ...)
111
112List of files required for the installation of the egg.  This
113form is not handled by chicken-install, but by henrietta-cache to
114determine what to cache. If the repository contains additional
115files that are unneeded for the egg to be installed, you can list
116all the required files in this clause to reduce the amount of data
117cached by egg servers.
118
119==== components
120
121 [egg property] (components COMPONENT ...)
122
123Lists components (extensions, programs, include- or data files)
124that this extension installs. See below for information on how
125to specify component-specific information.
126
127==== host
128
129 [egg property] (host PROP ...)
130
131Recursively process {{PROP ...}}, but only for the host (build)
132platform, in case this is a "cross-chicken", a CHICKEN installation
133intended for cross compilation.
134
135==== target
136
137 [egg property] (target PROP ...)
138
139Recursively process {{PROP ...}}, but only for the target
140platform, in case this is a "cross-chicken", a CHICKEN installation
141intended for cross compilation.
142
143==== component-options
144
145 [egg property] (component-options OPTIONSPEC ...)
146
147Specifies global options for all programs and extensions compiled for this egg.
148{{OPTIONSPEC}} may be {{csc-options}}, {{link-options}} or {{linkage}} specifications.
149
150==== cond-expand
151
152 [egg property] (cond-expand CLAUSE ...)
153
154Conditionally expand egg specification forms, depending on system
155features. Each {{CLAUSE}} should be of the form
156{{(TEST PROPERTY)}} where {{TEST}} is a feature identifier or a
157conditional form, in the same syntax as used in the {{cond-expand}}
158syntactic form.
159
160In addition to normal system-wide feature identifiers, feature identifiers
161given via the {{-feature}} option to {{chicken-install}} are visible in
162the tests. Also, the features {{target}}, {{host}}, {{dynamic}} and
163{{static}} are visible, depending on surrounding egg specification
164forms for constraining mode and linkage.
165
166==== error
167
168 [egg property] (error STRING ARG ...)
169
170Signal an error and abort processing. Mostly useful inside {{cond-expand}} forms.
171
172=== Components
173
174==== extension
175
176 [egg property] (extension NAME PROP ...)
177
178Specifies an extension library component. The properties
179{{PROP...}} are processed recursively and apply only to this
180component.
181
182==== data
183
184 [egg property] (data NAME PROP ...)
185
186Specifies one or more arbitrary data files.
187
188==== generated-source-file
189
190 [egg property] (generated-source-file NAME PROP ...)
191
192Specifies a file that is generated during the process of building
193the egg.
194
195==== c-include
196
197 [egg property] (c-include NAME PROP ...)
198
199Specifies one or more C include files.
200
201==== scheme-include
202
203 [egg property] (scheme-include NAME PROP ...)
204
205Specifies one or more Scheme include files.
206
207==== program
208
209 [egg property] (program NAME PROP ...)
210
211Specifies an executable program.
212
213==== c-object
214
215 [egg property] (c-object NAME PROP ...)
216
217Specifies a compiled C/C++ object file. Usually this component type
218is required if you want to link a separately compiled C/C++ module
219with your extension or program. C-objects are compiled like Scheme
220source files with the {{csc}} tool to ensure the same C compiler
221options and toolchain is used as for regular Scheme files compiled
222to C. If you want to pass compiler-specific options to the build
223of the C object, use the {{csc-options}} property and precede
224C compiler options with {{-C}}.
225
226
227=== Component properties
228
229==== host
230
231 [egg property] (host PROP ...)
232
233Process {{PROP ...}} recursively for the current component, but
234apply the properties only to the host (build) part, when using
235a CHICKEN installation intended for cross-compilation.
236
237==== target
238
239 [egg property] (target PROP ...)
240
241Process {{PROP ...}} recursively for the current component, but
242apply the properties only to the target part, when using
243a CHICKEN installation intended for cross-compilation.
244
245==== linkage
246
247 [egg property] (linkage LINKAGE)
248
249Define whether the component should be linked dynamically or
250statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This
251property only makes sense for extension libraries.
252
253==== types-file
254
255 [egg property] (types-file [NAME])
256
257Specifies that a "type-database" file should be generated and
258installed for this component. This property is only used for
259extension libraries. The name is optional and defaults to the
260name of the extensions (with the proper extension).
261
262If {{NAME}} is a list of the form {{(predefined [NAME])}}, then
263no types file is created during compilation and an existing types file
264for this extension is assumed and installed.
265
266==== inline-file
267
268 [egg property] (inline-file [NAME])
269
270Specifies that an "inline" file should be generated and installed
271for this component. This property is only used for extension
272libraries. The name is optional and defaults to the
273name of the extensions (with the proper extension).
274
275==== custom-build
276
277 [egg property] (custom-build STRING)
278
279Specifies a custom build operation that should be executed instead of
280the default build operations. This property is mandatory for
281components of type {{generated-source-file}}. {{STRING}} should be the
282name of a shell command (e.g., a script) and thus may be platform
283sensitive.  The path to the file is prepended implicitly, so you
284should '''not''' prefix it with {{./}}.  On Windows, a file with the
285{{.bat}} extension will be picked before a plain file with no
286extension.
287
288The script will be made executable on UNIX systems, if necessary,
289and will be invoked like the {{csc}} program and
290is executed with the location of the CHICKEN
291binaries in the {{PATH}}. Also, the following environment variables
292are set in the execution environment of the script:
293
294* {{CHICKEN_CC}}: name of the C compiler used for building CHICKEN
295* {{CHICKEN_CXX}}: name of the C++ compiler set during the build of CHICKEN
296* {{CHICKEN_CSC}}: path to {{csc}}
297* {{CHICKEN_CSI}}: path to {{csi}}
298
299
300==== csc-options
301
302 [egg property] (csc-options OPTION ...)
303
304Specifies additional compiler options for {{csc}} that should be
305used when building this component. If this property is not
306given, the default options are used, which are {{-O2 -d1}}
307for extensions and programs and {{-O2 -d0}} for import
308libraries.
309
310Note that the options are quoted when passed to csc during the
311compilation of the extension, so multiple options should be specified
312as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}
313(the latter would be a single option containing a whitespace character).
314
315==== link-options
316
317 [egg property] (link-options OPTION ...)
318
319Specifies additional link options for {{csc}} that should be
320used when building this component.
321
322Note that the options are quoted when passed to csc during the
323compilation of the extension, so multiple options should be specified
324as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}
325(the latter would be a single option containing a whitespace character).
326
327Note that in order to pass linker options to the underlying C-compiler, these must
328be prefixed with {{-L}}, eg. {{(link-options "-L" "-lpng")}}.
329
330==== source
331
332 [egg property] (source NAME)
333
334Specifies an alternative source file, in case it has a name
335distinct from the component name. By default the source file
336for a component is named after the component, with the {{.scm}}
337extension added.
338
339==== install-name
340
341 [egg property] (install-name NAME)
342
343Specifies an alternative installation name of the component,
344if it differs from the actual component name. This property
345is most useful if an egg installs an extension and a program
346of the same name, but needs to distinguish the components during
347build time.
348
349==== component-dependencies
350
351 [egg property] (component-dependencies NAME ...)
352
353Specifies dependencies to other components. {{NAME ...}} must
354be the names of extension, program, scheme-include- or generated source file
355components that should be built before the current component.
356
357==== source-dependencies
358
359 [egg property] (source-dependencies NAME ...)
360
361Specifies dependencies to additional source files. {{NAME ...}} must
362denote filenames of which the program or extension depends.
363A program or extension implicitly depends on its source file and
364and on the egg-specification file.
365
366==== objects
367
368 [egg property] (objects NAME ...)
369
370Specifies that the components of type {{c-object}} should be linked
371to this component and that the object components are dependencies.
372
373
374==== destination
375
376 [egg property] (destination NAME)
377
378Specifies an alternative installation destination for the
379built component and only applies
380to components of type {{data}}, {{c-include}} and {{scheme-include}}.
381This property should only be used in extreme
382cases, as it is recommended to use the default installation
383locations, which are:
384
385* for C include files: {{<PREFIX>/include/chicken/}}
386
387* for Scheme include files: {{<PREFIX>/share/chicken/}}
388
389* for data files: {{<PREFIX>/share/chicken/}}
390
391==== files
392
393 [egg property] (files NAME ...)
394
395Specifies source files for this component and only applies
396to components of type {{data}}, {{c-include}} and {{scheme-include}}.
397Both files and directories may be given and parent directories
398are created as needed.
399
400==== modules
401
402 [egg property] (modules NAME ...)
403
404Specifies modules that the component (usually an extension) contains.
405{{chicken-install}} will compile and install all import libraries for the given modules.
406If this property is not given, then it is assumed that the extension has a single
407module of the same name as the component.
408
409==== cond-expand
410
411 [egg property] (cond-expand CLAUSE ...)
412
413Similar to the toplevel {{cond-expand}} clause and may appear inside
414component specifications.
415
416==== error
417
418 [egg property] (error STRING ARG ...)
419
420Similar to the toplevel {{error}} form, may appear inside component specifications.
421
422---
423
424Previous: [[Extension tools]]
425
426Next: [[Units and linking model]]
Note: See TracBrowser for help on using the repository browser.