source: project/wiki/eggref/4/setup-helper @ 14218

Last change on this file since 14218 was 14218, checked in by Kon Lovett, 11 years ago

Release.

File size: 11.1 KB
Line 
1[[tags: egg]]
2
3== setup-helper
4
5[[toc:]]
6
7
8== Documentation
9
10Shortcut routines providing common install process patterns of Chicken
11extensions.
12
13
14=== Extension Information
15
16{{NAME}} is a {{string}} or {{symbol}}. The name of the extension.
17
18{{VERSION}} is a {{string}} or {{number}}.
19
20
21(Note - '''{{extension-name-and-version}}''', '''{{extension-name}}''' and
22'''{{extension-version}}''' are actually part of the '''{{setup-api}}'''.)
23
24==== extension-name-and-version
25
26<parameter>(extension-name-and-version) => NAME+VERSION</parameter>
27<parameter>(extension-name-and-version NAME+VERSION)</parameter>
28
29{{NAME+VERSION}} is {{(list NAME VERSION)}}.
30
31==== extension-name
32
33<procedure>(extension-name) => STRING</procedure>
34
35Returns the {{extension-name}} component of {{(extension-name-and-version)}}.
36
37==== extension-version
38
39<procedure>(extension-version [DEFAULT]) => STRING</procedure>
40
41Returns the {{extension-version}} component of {{(extension-name-and-version)}}.
42
43Should the {{(second (extension-name-and-version))}} be ''empty'' the
44{{DEFAULT}} is returned.
45
46==== verify-extension-name
47
48<procedure>(verify-extension-name NAME)</procedure>
49
50Raises an error should '''{{chicken-install}}''' know the extension by a
51different name.
52
53Use when paranoid.
54
55
56=== Filename Support
57
58Makes stereotypical {{filenames}} & {{pathnames}}.
59
60{{FILE}} is a {{string}} or {{symbol}}.
61
62{{EXTENSION}} is a {{string}} or {{symbol}}.
63
64{{DIRECTORY}} is as {{(make-pathname (pathname-directory DIRECTORY) (pathname-file DIRECTORY))}}.
65
66{{FILENAME}} is as {{(make-pathname #f FILE [EXTENSION])}}.
67
68{{PATHNAME}} is as {{(make-pathname DIRECTORY FILE [EXTENSION])}}.
69
70==== filename
71
72<procedure>(filename FILE [EXTENSION]) => FILENAME</procedure>
73
74Returns an filename for {{FILE}} and {{EXTENSION}}.
75
76==== document-filename
77
78<procedure>(document-filename FILE) => FILENAME</procedure>
79
80Returns a "html" filename for {{FILE}}.
81
82==== source-filename
83
84<procedure>(source-filename FILE) => FILENAME</procedure>
85
86Returns "scm" filename for {{FILE}}.
87
88==== shared-library-filename
89
90<procedure>(shared-library-filename FILE) => FILENAME</procedure>
91
92Returns a platform-specific dynamic-link-library filename for {{FILE}}.
93
94==== shared-filename
95
96<procedure>(shared-filename FILE) => FILENAME</procedure>
97
98Returns a platform-specific dynamic-load-file filename for {{FILE}}.
99
100==== static-library-filename
101
102<procedure>(static-library-filename FILE) => FILENAME</procedure>
103
104Returns a platform-specific static-link-library filename for {{FILE}}.
105
106==== static-filename
107
108<procedure>(static-filename FILE) => FILENAME</procedure>
109
110Returns a platform-specific object-file filename for {{FILE}}.
111
112==== import-filename
113
114<procedure>(import-filename FILE) => FILENAME</procedure>
115
116Returns an "import" filename for {{FILE}}.
117
118==== source-import-filename
119
120<procedure>(source-import-filename FILE) => FILENAME</procedure>
121
122Returns an "import.scm" filename for {{FILE}}.
123
124==== shared-import-filename
125
126<procedure>(shared-import-filename FILE) => FILENAME</procedure>
127
128Returns a platform-specific dynamic-load-file "import" filename for {{FILE}}.
129
130==== inline-filename
131
132<procedure>(inline-filename FILE) => FILENAME</procedure>
133
134Returns an "inline" filename for {{FILE}}.
135
136==== program-filename
137
138<procedure>(program-filename FILE) => FILENAME</procedure>
139
140Returns a platform-specific executable filename for {{FILE}}.
141
142==== make-repository-pathname
143
144<procedure>(make-repository-pathname FILE) => PATHNAME</procedure>
145
146Returns a pathname for {{FILE}} in the ''{{(chicken-repository)}}''.
147
148
149=== File Copy Support
150
151Copy local file (local to the building egg directory) to some directory. These
152use the {{copy-file}} setup-api routine.
153
154==== copy-file-to-directory
155
156<procedure>(copy-file-to-directory FILENAME DIRECTORY)</procedure>
157
158Copies the local file {{FILENAME}} to the {{DIRECTORY}.
159
160==== copy-to-repository
161
162<procedure>(copy-to-repository FILENAME)</procedure>
163
164Copies the local file {{FILENAME}} to the ''{{(chicken-repository)}}''.
165
166==== copy-to-home
167
168<procedure>(copy-to-home FILENAME)</procedure>
169
170Copies the local file {{FILENAME}} to the ''{{(chicken-home)}}''.
171
172
173=== SRFI-29 Bundle Support
174
175Installation of SRFI-29 Bundles.
176
177See [[srfi-29]].
178
179==== install-srfi-29-bundle
180
181<procedure>(install-srfi-29-bundle NAME [BUNDLE-SPECIFICATION-COMPONENT ...])</procedure>
182
183Copies the local {{srfi-29-bundle}} file to the
184''srfi-29-bundle-directory''.
185
186
187=== Compile Support
188
189the basename of the source file and
190
191Compiles the source for {{NAME}}.
192
193{{COMPILE-OPTION}} is any object acceptable as a '''{{compile}}''' option.
194
195{{COMPILE-OPTIONS}} is {{(list-of INSTALL-OPTION ...)}}.
196
197The {{COMPILE-OPTIONS}} is always expanded in the {{comple}} command in the
198last position.
199
200{{INLINE?}} is a {{boolean}} indicating whether a global inline is created. The
201inline file is named {{(make-pathname #f NAME "inline")}}. Does not
202enable cross-module inlining.
203
204==== compile-static
205
206<procedure>(compile-static NAME [#:options COMPILE-OPTIONS] [#:inline? INLINE?])</procedure>
207
208Compiles to object file with unit-name {{NAME}}.
209
210No linking is performed!
211
212==== compile-shared
213
214<procedure>(compile-shared NAME [#:options COMPILE-OPTIONS] [#:inline? INLINE?])</procedure>
215
216Compiles to shared file.
217
218==== compile-shared-module
219
220<procedure>(compile-shared-module NAME [#:options COMPILE-OPTIONS] [#:inline? INLINE?])</procedure>
221
222Compiles source and import to shared files.
223
224==== Parameters
225
226These are '''always''' expanded in the {{comple}} command in the first
227position.
228
229===== default-static-compile-options
230
231<parameter>(default-static-compile-options) => COMPILE-OPTIONS</parameter>
232<parameter>(default-static-compile-options COMPILE-OPTIONS)</parameter>
233
234===== default-shared-compile-options
235
236<parameter>(default-shared-compile-options) => COMPILE-OPTIONS</parameter>
237<parameter>(default-shared-compile-options COMPILE-OPTIONS)</parameter>
238
239===== default-static-compile-options
240
241<parameter>(default-import-compile-options) => COMPILE-OPTIONS</parameter>
242<parameter>(default-import-compile-options COMPILE-OPTIONS)</parameter>
243
244
245=== Install Support
246
247Installs the compiled-extension for {{NAME}}.
248
249{{INSTALL-OPTION}} is any object acceptable as an {{install-extension}} command
250options list option.
251
252{{INSTALL-OPTIONS}} is {{(list-of INSTALL-OPTION ...)}}.
253
254The {{INSTALL-OPTIONS}} is always expanded in the {{install-extension}}
255command options list in the last position.
256
257{{FILENAMES}} is a {{(list-of FILENAME ...)}}. These name local files (local to
258the building egg directory) that are to expanded in the {{install-extension}}
259command files list.
260
261==== install-static-extension
262
263<procedure>(install-static-extension NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
264
265Installs a compiled-static-extension.
266
267==== install-shared-extension
268
269<procedure>(install-shared-extension NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
270
271Installs a compiled-shared-extension.
272
273==== install-shared-extension-module
274
275<procedure>(install-shared-extension-module NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
276
277Installs a compiled-shared-extension-module.
278
279==== install-shared+static-extension-module
280
281<procedure>(install-shared+static-extension-module NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
282
283Installs a compiled-shared-extension-module and a compiled-static-extension.
284
285==== install-extension-tag
286
287<procedure>(install-extension-tag NAME VERSION)</procedure>
288
289Installs an empty extension with {{NAME}} and {{VERSION}}.
290
291
292==== Parameters
293
294These are '''always''' expanded in the {{install-extension}} command options
295list in the first position.
296
297===== default-static-install-options
298
299<parameter>(default-static-install-options) => INSTALL-OPTIONS</parameter>
300<parameter>(default-static-install-options INSTALL-OPTIONS)</parameter>
301
302===== default-shared-install-options
303
304<parameter>(default-static-install-options) => INSTALL-OPTIONS</parameter>
305<parameter>(default-static-install-options INSTALL-OPTIONS)</parameter>
306
307===== default-shared-module-install-options
308
309<parameter>(default-shared-module-install-options) => INSTALL-OPTIONS</parameter>
310<parameter>(default-shared-module-install-options INSTALL-OPTIONS)</parameter>
311
312===== default-shared+static-module-install-options
313
314<parameter>(default-shared+static-module-install-options) => INSTALL-OPTIONS</parameter>
315<parameter>(default-shared+static-module-install-options INSTALL-OPTIONS)</parameter>
316
317
318=== Setup Support
319
320Compiles & installs the extension for {{NAME}}.
321
322==== setup-static-extension
323
324<procedure>(setup-static-extension NAME VERSION [#:compile-options COMPILE-OPTIONS] [#:inline? INLINE?] [#:install-options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
325
326Compiles & installs a static-extension.
327
328==== setup-shared-extension
329
330<procedure>(setup-shared-extension NAME VERSION [#:compile-options COMPILE-OPTIONS] [#:inline? INLINE?] [#:install-options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
331
332Compiles & installs a shared-extension.
333
334==== setup-shared-extension-module
335
336<procedure>(setup-shared-extension-module NAME VERSION [#:compile-options COMPILE-OPTIONS] [#:inline? INLINE?] [#:install-options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
337
338Compiles & installs a shared-extension-module.
339
340==== setup-shared+static-extension-module
341
342<procedure>(setup-shared+static-extension-module NAME VERSION [#:shared-compile-options COMPILE-OPTIONS] [#:shared-inline? INLINE?] [#:static-compile-options COMPILE-OPTIONS] [#:static-inline? INLINE?] [#:install-options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
343
344Compiles & installs a shared-extension-module and a static-extension.
345
346
347
348== Usage
349
350<enscript language=scheme>
351(include "setup-helper")
352</enscript>
353
354
355== Examples
356
357<enscript language=scheme>
358;;;; example.setup -*- Hen -*-
359
360(include "setup-helper")
361
362; Paranoid
363(verify-extension-name "example")
364
365(setup-shared-extension-module
366  (extension-name) (extension-version)
367  compile-options: '(-extend easyffi) install-options: '((syntax)))
368</enscript>
369
370
371== Requirements
372
373None
374
375
376== Notes
377
378* Static extension support is suspect.
379
380
381== Bugs and Limitations
382
383
384== Author
385
386[[/users/kon lovett|kon lovett]]
387
388
389== Version history
390
391; 1.1.0 : Added 'install-extension-tag'.
392; 1.0.0 : Initial release.
393
394
395== License
396
397Copyright (C) 2009 Kon Lovett.  All rights reserved.
398
399Permission is hereby granted, free of charge, to any person obtaining a
400copy of this software and associated documentation files (the Software),
401to deal in the Software without restriction, including without limitation
402the rights to use, copy, modify, merge, publish, distribute, sublicense,
403and/or sell copies of the Software, and to permit persons to whom the
404Software is furnished to do so, subject to the following conditions:
405
406The above copyright notice and this permission notice shall be included
407in all copies or substantial portions of the Software.
408
409THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
410IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
411FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
412THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
413OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
414ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
415OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.