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

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

Updated info on 'copy-to-home' to reflect Ivan's reality.

File size: 11.5 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 directory ''{{(installation-prefix)}}
171share chicken''. This is usually the same as {{(chicken-home)}}.
172
173
174=== SRFI-29 Bundle Support
175
176Installation of SRFI-29 Bundles.
177
178See [[srfi-29]].
179
180==== install-srfi-29-bundle
181
182<procedure>(install-srfi-29-bundle NAME [BUNDLE-SPECIFICATION-COMPONENT ...])</procedure>
183
184Copies the local {{srfi-29-bundle}} file to the
185''srfi-29-bundle-directory''.
186
187
188=== Compile Support
189
190the basename of the source file and
191
192Compiles the source for {{NAME}}.
193
194{{COMPILE-OPTION}} is any object acceptable as a '''{{compile}}''' option.
195
196{{COMPILE-OPTIONS}} is {{(list-of COMPILE-OPTION ...)}}.
197
198The {{COMPILE-OPTIONS}} is always expanded in the {{comple}} command in the
199last position.
200
201{{INLINE?}} is a {{boolean}} indicating whether a global inline is created. The
202inline file is named {{(make-pathname #f NAME "inline")}}. Does not
203enable cross-module inlining.
204
205==== compile-static
206
207<procedure>(compile-static NAME [#:options COMPILE-OPTIONS] [#:inline? INLINE?])</procedure>
208
209Compiles to object file with unit-name {{NAME}}.
210
211No linking is performed!
212
213==== compile-shared
214
215<procedure>(compile-shared NAME [#:options COMPILE-OPTIONS] [#:inline? INLINE?])</procedure>
216
217Compiles to shared file.
218
219==== compile-shared-module
220
221<procedure>(compile-shared-module NAME [#:options COMPILE-OPTIONS] [#:inline? INLINE?])</procedure>
222
223Compiles source and import to shared files.
224
225==== Parameters
226
227These are '''always''' expanded in the {{comple}} command in the first
228position.
229
230===== default-static-compile-options
231
232<parameter>(default-static-compile-options) => COMPILE-OPTIONS</parameter>
233<parameter>(default-static-compile-options COMPILE-OPTIONS)</parameter>
234
235===== default-shared-compile-options
236
237<parameter>(default-shared-compile-options) => COMPILE-OPTIONS</parameter>
238<parameter>(default-shared-compile-options COMPILE-OPTIONS)</parameter>
239
240===== default-static-compile-options
241
242<parameter>(default-import-compile-options) => COMPILE-OPTIONS</parameter>
243<parameter>(default-import-compile-options COMPILE-OPTIONS)</parameter>
244
245
246=== Install Support
247
248Installs the compiled-extension for {{NAME}}.
249
250{{INSTALL-OPTION}} is any object acceptable as an {{install-extension}} command
251options list option.
252
253{{INSTALL-OPTIONS}} is {{(list-of INSTALL-OPTION ...)}}.
254
255The {{INSTALL-OPTIONS}} is always expanded in the {{install-extension}}
256command options list in the last position.
257
258{{FILENAMES}} is a {{(list-of FILENAME ...)}}. These name local files (local to
259the building egg directory) that are to expanded in the {{install-extension}}
260command files list.
261
262==== install-static-extension
263
264<procedure>(install-static-extension NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
265
266Installs a compiled-static-extension.
267
268==== install-shared-extension
269
270<procedure>(install-shared-extension NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
271
272Installs a compiled-shared-extension.
273
274==== install-shared-extension-module
275
276<procedure>(install-shared-extension-module NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
277
278Installs a compiled-shared-extension-module.
279
280==== install-shared+static-extension-module
281
282<procedure>(install-shared+static-extension-module NAME VERSION [#:options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
283
284Installs a compiled-shared-extension-module and a compiled-static-extension.
285
286==== install-extension-tag
287
288<procedure>(install-extension-tag NAME VERSION)</procedure>
289
290Installs an empty extension with {{NAME}} and {{VERSION}}.
291
292
293==== Parameters
294
295These are '''always''' expanded in the {{install-extension}} command options
296list in the first position.
297
298===== default-static-install-options
299
300<parameter>(default-static-install-options) => INSTALL-OPTIONS</parameter>
301<parameter>(default-static-install-options INSTALL-OPTIONS)</parameter>
302
303===== default-shared-install-options
304
305<parameter>(default-static-install-options) => INSTALL-OPTIONS</parameter>
306<parameter>(default-static-install-options INSTALL-OPTIONS)</parameter>
307
308===== default-shared-module-install-options
309
310<parameter>(default-shared-module-install-options) => INSTALL-OPTIONS</parameter>
311<parameter>(default-shared-module-install-options INSTALL-OPTIONS)</parameter>
312
313===== default-shared+static-module-install-options
314
315<parameter>(default-shared+static-module-install-options) => INSTALL-OPTIONS</parameter>
316<parameter>(default-shared+static-module-install-options INSTALL-OPTIONS)</parameter>
317
318
319=== Setup Support
320
321Compiles & installs the extension for {{NAME}}.
322
323==== setup-static-extension
324
325<procedure>(setup-static-extension NAME VERSION [#:compile-options COMPILE-OPTIONS] [#:inline? INLINE?] [#:install-options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
326
327Compiles & installs a static-extension.
328
329==== setup-shared-extension
330
331<procedure>(setup-shared-extension NAME VERSION [#:compile-options COMPILE-OPTIONS] [#:inline? INLINE?] [#:install-options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
332
333Compiles & installs a shared-extension.
334
335==== setup-shared-extension-module
336
337<procedure>(setup-shared-extension-module NAME VERSION [#:compile-options COMPILE-OPTIONS] [#:inline? INLINE?] [#:install-options INSTALL-OPTIONS] [#:files FILENAMES])</procedure>
338
339Compiles & installs a shared-extension-module.
340
341==== setup-shared+static-extension-module
342
343<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>
344
345Compiles & installs a shared-extension-module and a static-extension.
346
347
348
349== Usage
350
351<enscript language=scheme>
352(include "setup-helper")
353</enscript>
354
355
356== Examples
357
358<enscript language=scheme>
359;;;; example.setup -*- Hen -*-
360
361(include "setup-helper")
362
363; Paranoid
364(verify-extension-name "example")
365
366(setup-shared-extension-module
367  (extension-name) (extension-version)
368  compile-options: '(-extend easyffi) install-options: '((syntax)))
369</enscript>
370
371
372== Requirements
373
374None
375
376
377== Notes
378
379* Static extension support is suspect.
380
381
382== Bugs and Limitations
383
384
385== Author
386
387[[/users/kon lovett|kon lovett]]
388
389
390== Version history
391
392; 1.1.4 : Fix for 'copy-to-home' when '(installation-prefix)' is #f. [Ivan Raikov]
393; 1.1.3 : Fix for 'copy-to-home' when '(chicken-home)' is not proper location of ".../share/chicken". [Ivan Raikov]
394; 1.1.2 : Need for explicit use of "setup-api". [Ivan Raikov]
395; 1.1.1 : Fix for SRFI 29 bundle directory support.
396; 1.1.0 : Added 'install-extension-tag'.
397; 1.0.0 : Initial release.
398
399
400== License
401
402Copyright (C) 2009 Kon Lovett.  All rights reserved.
403
404Permission is hereby granted, free of charge, to any person obtaining a
405copy of this software and associated documentation files (the Software),
406to deal in the Software without restriction, including without limitation
407the rights to use, copy, modify, merge, publish, distribute, sublicense,
408and/or sell copies of the Software, and to permit persons to whom the
409Software is furnished to do so, subject to the following conditions:
410
411The above copyright notice and this permission notice shall be included
412in all copies or substantial portions of the Software.
413
414THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
415IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
416FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
417THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
418OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
419ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
420OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.