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

Last change on this file since 36570 was 36570, checked in by sjamaan, 2 years ago

man/5: Update with missing distribution-files property

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