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

Last change on this file since 35563 was 35563, checked in by Mario Domenech Goulart, 3 years ago

man/5/Egg specification format: document CHICKEN_CSC and CHICKEN_CSI

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