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

Last change on this file since 13551 was 13551, checked in by Kon Lovett, 12 years ago

Added 'setup-helper' doc.

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