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

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

Update usage.

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