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

Last change on this file since 35557 was 35557, checked in by felix winkelmann, 3 years ago

man/5: documented new -dependency egg properties

File size: 9.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 [[/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
226instead of the default build operations. This property is mandatory
227for components of type {{generated-source-file}}. {{STRING}}
228usually contains a shell command and thus may be platform sensitive.
229
230The script will be made executable on UNIX systems, if necessary,
231and will be invoked like the {{csc}} program and
232is executed with the location of the CHICKEN
233binaries in the {{PATH}}. Also, tjhe environment variables
234{{CHICKEN_CC}} and {{CHICKEN_CXX}} are set to the
235names of the C and C++ compiler that were used for building the
236system.
237
238==== csc-options
239
240[egg property] (csc-options OPTION ...)
241
242Specifies additional compiler options for {{csc}} that should be
243used when building this component. If this property is not
244given, the default options are used, which are {{-O2 -d1}}
245for extensions and programs and {{-O2 -d0}} for import
246libraries.
247
248Note that the options are quoted when passed to csc during the
249compilation of the extension, so multiple options should be specified
250as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}
251(the latter would be a single option containing a whitespace character).
252
253==== link-options
254
255[egg property] (link-options OPTION ...)
256
257Specifies additional link options for {{csc}} that should be
258used when building this component.
259
260Note that the options are quoted when passed to csc during the
261compilation of the extension, so multiple options should be specified
262as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}
263(the latter would be a single option containing a whitespace character).
264
265==== source
266
267[egg property] (source NAME)
268
269Specifies an alternative source file, in case it has a name
270distinct from the component name. By default the source file
271for a component is named after the component, with the {{.scm}}
272extension added.
273
274==== install-name
275
276[egg property] (install-name NAME)
277
278Specifies an alternative installation name of the component,
279if it differs from the actual component name. This property
280is most useful if an egg installs an extension and a program
281of the same name, but needs to distinguish the components during
282build time.
283
284==== component-dependencies
285
286[egg property] (component-dependencies NAME ...)
287
288Specifies dependencies to other components. {{NAME ...}} must
289be the names of extension, program, scheme-include- or generated source file
290components that should be built before the current component.
291
292==== source-dependencies
293
294[egg property] (source-dependencies NAME ...)
295
296Specifies dependencies to additional source files. {{NAME ...}} must
297denote filenames of which the program or extension depends.
298A program or extension implicitly depends on its source file and
299and on the egg-specification file.
300
301==== destination
302
303[egg property] (destination NAME)
304
305Specifies an alternative installation destination for the
306built component and only applies
307to components of type {{data}}, {{c-include}} and {{scheme-include}}.
308This property should only be used in extreme
309cases, as it is recommended to use the default installation
310locations, which are:
311
312* for C include files: {{<PREFIX>/include/chicken/}}
313
314* for Scheme include files: {{<PREFIX>/share/chicken/}}
315
316* for data files: {{<PREFIX>/share/chicken/}}
317
318==== files
319
320[egg property] (files NAME ...)
321
322Specifies source files for this component and only applies
323to components of type {{data}}, {{c-include}} and {{scheme-include}}.
324
325
326---
327
328Previous: [[Extension tools]]
329
330Next: [[Units and linking model]]
Note: See TracBrowser for help on using the repository browser.