1 | [[tags: manual]] |
---|
2 | [[toc:]] |
---|
3 | |
---|
4 | == chicken-setup |
---|
5 | |
---|
6 | === Extension libraries |
---|
7 | |
---|
8 | Extension libraries (''eggs'') are extensions to the core |
---|
9 | functionality provided by the basic CHICKEN system, to be built and |
---|
10 | installed separately. The mechanism for loading compiled extensions |
---|
11 | is based on dynamically loadable code and as such is only available on |
---|
12 | systems on which loading compiled code at runtime is |
---|
13 | supported. Currently these are most UNIX-compatible platforms that |
---|
14 | provide the {{libdl}} functionality like Linux, Solaris, BSD, Mac OS X |
---|
15 | and Windows using Cygwin. |
---|
16 | |
---|
17 | Note: Extension may also be normal applications or shell scripts, but |
---|
18 | are usually libraries. |
---|
19 | |
---|
20 | {{chicken-setup}} will download the source code for extension |
---|
21 | automatically from the canonical server at |
---|
22 | [[http://www.call-with-current-continuation.org/eggs]] if the |
---|
23 | requested egg does not exist in the current directory. Various |
---|
24 | command-line options exist for customizing the process and/or |
---|
25 | retrieving the egg from other locations or in other formats. |
---|
26 | |
---|
27 | |
---|
28 | === Installing extensions |
---|
29 | |
---|
30 | To install an extension library, run the {{chicken-setup}} program |
---|
31 | with the extension name as argument. The extension archive is |
---|
32 | downloaded, its contents extracted and the contained ''setup'' script |
---|
33 | is executed. This setup script is a normal Scheme source file, which |
---|
34 | will be interpreted by {{chicken-setup}}. The complete language |
---|
35 | supported by {{csi}} is available, and the library units {{srfi-1 |
---|
36 | regex utils posix tcp}} are loaded. Additional libraries can be loaded |
---|
37 | at run-time. |
---|
38 | |
---|
39 | The setup script should perform all necessary steps to build the new |
---|
40 | library (or application). After a successful build, the extension can |
---|
41 | be installed by invoking one of the procedures {{install-extension}}, |
---|
42 | {{install-program}} or {{install-script}}. These procedures will copy |
---|
43 | a number of given files into the extension repository or in the path |
---|
44 | where the CHICKEN executables are located (in the case of executable |
---|
45 | programs or scripts). Additionally the list of installed files, and |
---|
46 | user-defined metadata is stored in the repository. |
---|
47 | |
---|
48 | If no extension name is given on the command-line, and if none of the |
---|
49 | options {{-list}}, {{-version}}, {{-repository}} (without argument), |
---|
50 | {{-program-path}} (without argument), {{-fetch}}, {{-fetch-tree}} or |
---|
51 | {{-docindex}} is given, then all {{.setup}} scripts in the current |
---|
52 | directory are processed. |
---|
53 | |
---|
54 | |
---|
55 | === Creating extensions |
---|
56 | |
---|
57 | Extensions can be created by creating an (optionally gzipped) {{tar}} |
---|
58 | archive named {{EXTENSION.egg}} containing all needed files plus a |
---|
59 | {{.setup}} script in the root directory. After {{chicken-setup}} has |
---|
60 | extracted the files, the setup script will be invoked. There are no |
---|
61 | additional constraints on the structure of the archive, but the setup |
---|
62 | script has to be in the root path of the archive. |
---|
63 | |
---|
64 | |
---|
65 | === Procedures and macros available in setup scripts |
---|
66 | |
---|
67 | ==== install-extension |
---|
68 | |
---|
69 | (install-extension ID FILELIST [INFOLIST]) |
---|
70 | |
---|
71 | Installs the extension library with the name {{ID}}. All files given in the list of strings |
---|
72 | {{FILELIST}} will be copied to the extension repository. It should be noted here that |
---|
73 | the extension id has to be identical to the name of the file implementing the extension. The |
---|
74 | extension may load or include other files, or may load other extensions at runtime specified |
---|
75 | by the {{require-at-runtime}} property. |
---|
76 | |
---|
77 | {{FILELIST}} may be a filename, a list of filenames, or a list of pairs of |
---|
78 | the form {{(SOURCE DEST)}} (if you want to copy into a particular sub-directory - the |
---|
79 | destination directory will be created as needed). If {{DEST}} is a relative pathname, |
---|
80 | < it will be copied into the extension repository. |
---|
81 | |
---|
82 | The optional argument {{INFOLIST}} should be an association list that |
---|
83 | maps symbols to values, this list will be stored as {{ID.setup-info}} at the same |
---|
84 | location as the extension code. Currently the following properties are used: |
---|
85 | |
---|
86 | ===== syntax |
---|
87 | |
---|
88 | [extension property] (syntax) |
---|
89 | |
---|
90 | Marks the extension as syntax-only. No code is compiled, the extension is intended |
---|
91 | as a file containing macros to be loaded at compile/macro-expansion time. |
---|
92 | |
---|
93 | ===== require-at-runtime |
---|
94 | |
---|
95 | [extension property] (require-at-runtime ID ...) |
---|
96 | |
---|
97 | Specifies extensions that should be loaded (via {{require}}) at runtime. This is mostly |
---|
98 | useful for syntax extensions that need additional support code at runtime. |
---|
99 | |
---|
100 | ===== version |
---|
101 | |
---|
102 | [extension property] (version STRING) |
---|
103 | |
---|
104 | Specifies version string. |
---|
105 | |
---|
106 | ===== documentation |
---|
107 | |
---|
108 | [extension property] (documentation FILENAME) |
---|
109 | |
---|
110 | The filename of a HTML document containing extension-specific documentation. |
---|
111 | This file should be given in the file-list passed to {{install-extension}} and |
---|
112 | a link to it will be automatically included in the index page (accessible via |
---|
113 | {{chicken-setup -docindex}}). |
---|
114 | |
---|
115 | ===== examples |
---|
116 | |
---|
117 | [extension property] (examples FILENAME ...) |
---|
118 | |
---|
119 | Copies the given files into the examples directory, which is usually |
---|
120 | {{$prefix/share/chicken/examples}} |
---|
121 | or {{(make-pathname (chicken-home) "examples")}}). |
---|
122 | |
---|
123 | Note that the files listed in this property should not be listed in the normal |
---|
124 | list of files to install passed to {{install-extension}}. This is the only |
---|
125 | exception - other files that are installed in the repository must be given |
---|
126 | in the file list. |
---|
127 | |
---|
128 | ===== exports |
---|
129 | |
---|
130 | [extension property] (exports EXPORT ...) |
---|
131 | |
---|
132 | Add export-information to the generated extension-information. {{EXPORT}} may be |
---|
133 | a symbol naming an exported toplevel variable or a string designating a file with |
---|
134 | exported variables, as generated by the {{-emit-exports}} option or the |
---|
135 | {{emit-exports}} declaration specifier. |
---|
136 | |
---|
137 | ===== static |
---|
138 | |
---|
139 | [extension property] (static STRING) |
---|
140 | |
---|
141 | If the extension also provides a static library, then STRING should |
---|
142 | contain the name of that library. Used by {{csc}} when compiling with |
---|
143 | the {{-static-extensions}} option. |
---|
144 | |
---|
145 | ===== static-options |
---|
146 | |
---|
147 | [extension property] (static-options STRING) |
---|
148 | |
---|
149 | Additional options that should be passed to the linker when linking |
---|
150 | with the static version of an extension (see {{static}} above). Used |
---|
151 | by {{csc}} when compiling with the {{-static-extensions}} option. |
---|
152 | |
---|
153 | All other properties are currently ignored. The {{FILELIST}} argument may also be a single |
---|
154 | string. |
---|
155 | |
---|
156 | ==== install-program |
---|
157 | |
---|
158 | [procedure] (install-program ID FILELIST [INFOLIST]) |
---|
159 | |
---|
160 | Similar to {{install-extension}}, but installs an executable program in the |
---|
161 | executable path (usually {{/usr/local/bin}}). |
---|
162 | |
---|
163 | ==== install-script |
---|
164 | |
---|
165 | [procedure] (install-script ID FILELIST [INFOLIST]) |
---|
166 | |
---|
167 | Similar to {{install-program}}, but additionally changes the file permissions of all |
---|
168 | files in {{FILELIST}} to executable (for installing shell-scripts). |
---|
169 | |
---|
170 | |
---|
171 | ==== run |
---|
172 | |
---|
173 | [syntax] (run FORM ...) |
---|
174 | |
---|
175 | Runs the shell command {{FORM}}, which is wrapped in an implicit {{quasiquote}}. |
---|
176 | {{(run (csc ...))}} is treated specially and passes {{-v}} (if {{-verbose}} has been given |
---|
177 | to {{chicken-setup}}) and {{-feature compiling-extension}} options to the compiler. |
---|
178 | |
---|
179 | ==== compile |
---|
180 | |
---|
181 | [syntax] (compile FORM ...) |
---|
182 | |
---|
183 | Equivalent to {{(run (csc FORM ...))}}. |
---|
184 | |
---|
185 | ==== make |
---|
186 | |
---|
187 | [syntax] (make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS) |
---|
188 | |
---|
189 | A ''make'' macro that executes the expressions {{COMMAND ...}}, when any of the dependents |
---|
190 | {{DEPENDENT ...}} have changed, to build {{TARGET}}. This is the same as the {{make}} |
---|
191 | extension, which is available separately. For more information, see |
---|
192 | [[http://www.call-with-current-continuation.org/eggs/make.html|make]]. |
---|
193 | |
---|
194 | |
---|
195 | ==== patch |
---|
196 | |
---|
197 | [procedure] (patch WHICH REGEX SUBST) |
---|
198 | |
---|
199 | Replaces all occurrences of the regular expression {{REGEX}} with the string {{SUBST}}, |
---|
200 | in the file given in {{WHICH}}. If {{WHICH}} is a string, the file will be patched and |
---|
201 | overwritten. If {{WHICH}} is a list of the form {{OLD NEW}}, then a different file named |
---|
202 | {{NEW}} will be generated. |
---|
203 | |
---|
204 | ==== copy-file |
---|
205 | |
---|
206 | [procedure] (copy-file FROM TO) |
---|
207 | |
---|
208 | Copies the file or directory (recursively) given in the string {{FROM}} to the destination |
---|
209 | file or directory {{TO}}. |
---|
210 | |
---|
211 | ==== move-file |
---|
212 | |
---|
213 | [procedure] (move-file FROM TO) |
---|
214 | |
---|
215 | Moves the file or directory (recursively) given in the string {{FROM}} to the destination |
---|
216 | file or directory {{TO}}. |
---|
217 | |
---|
218 | ==== remove-file* |
---|
219 | |
---|
220 | [procedure] (remove-file* PATH) |
---|
221 | |
---|
222 | Removes the file or directory given in the string {{PATH}}. |
---|
223 | |
---|
224 | |
---|
225 | ==== find-library |
---|
226 | |
---|
227 | [procedure] (find-library NAME PROC) |
---|
228 | |
---|
229 | Returns {{#t}} if the library named {{libNAME.[a|so]}} (unix) or {{NAME.lib}} (windows) |
---|
230 | could be found by compiling and linking a test program. {{PROC}} should be the name of a |
---|
231 | C function that must be provided by the library. If no such library was found or the function could not |
---|
232 | be resolved, {{#f}} is returned. |
---|
233 | |
---|
234 | ==== find-header |
---|
235 | |
---|
236 | [procedure] (find-header NAME) |
---|
237 | |
---|
238 | Returns {{#t}} if a C include-file with the given name is available, or {{#f}} otherwise. |
---|
239 | |
---|
240 | ==== try-compile |
---|
241 | |
---|
242 | [procedure] (try-compile CODE #!key cc cflags ldflags compile-only c++) |
---|
243 | |
---|
244 | Returns {{#t}} if the C code in {{CODE}} compiles and links successfully, or {{#f}} otherwise. |
---|
245 | The keyword parameters {{cc}} (compiler name, defaults to the C compiler used to build this system), |
---|
246 | {{cflags}} and {{ldflags}} accept additional compilation and |
---|
247 | linking options. If {{compile-only}} is true, then no linking step takes place. |
---|
248 | If the keyword argument {{c++}} is given and true, then the code will be compiled in C++ mode. |
---|
249 | |
---|
250 | |
---|
251 | ==== create-directory |
---|
252 | |
---|
253 | [procedure] (create-directory PATH) |
---|
254 | |
---|
255 | Creates the directory given in the string {{PATH}}, with all parent directories as needed. |
---|
256 | |
---|
257 | |
---|
258 | ==== installation-prefix |
---|
259 | |
---|
260 | [parameter] installation-prefix |
---|
261 | |
---|
262 | Holds the prefix under which CHICKEN executables and libraries have been installed (either |
---|
263 | the value of the environment variable {{CHICKEN_PREFIX}} or whatever prefix was |
---|
264 | specified at the time the system was built. |
---|
265 | |
---|
266 | |
---|
267 | ==== program-path |
---|
268 | |
---|
269 | [parameter] (program-path [PATH]) |
---|
270 | |
---|
271 | Holds the path where executables are installed and defaults to either {{$CHICKEN_PREFIX/bin}}, |
---|
272 | if the environment variable {{CHICKEN_PREFIX}} is set or the |
---|
273 | path where the CHICKEN binaries ({{chicken}}, {{csi}}, etc.) are installed. |
---|
274 | |
---|
275 | |
---|
276 | ==== setup-root-directory |
---|
277 | |
---|
278 | [parameter] (setup-root-directory [PATH]) |
---|
279 | |
---|
280 | Contains the path of the directory where {{chicken-setup}} was invoked. |
---|
281 | |
---|
282 | ==== setup-build-directory |
---|
283 | |
---|
284 | [parameter] (setup-build-directory [PATH]) |
---|
285 | |
---|
286 | Contains the path of the directory where the extension is built. This is not necessarily identical |
---|
287 | to {{setup-root-directory}}. |
---|
288 | |
---|
289 | |
---|
290 | ==== setup-verbose-flag |
---|
291 | |
---|
292 | [parameter] (setup-verbose-flag [BOOL]) |
---|
293 | |
---|
294 | Reflects the setting of the {{-verbose}} option, i.e. is {{#t}}, if {{-verbose}} was |
---|
295 | given. |
---|
296 | |
---|
297 | |
---|
298 | ==== setup-install-flag |
---|
299 | |
---|
300 | [parameter] (setup-install-flag [BOOL]) |
---|
301 | |
---|
302 | Reflects the setting of the {{--no-install}} option, i.e. is {{#f}}, if {{-no-install}} was |
---|
303 | given. |
---|
304 | |
---|
305 | ==== required-chicken-version |
---|
306 | |
---|
307 | [procedure] (required-chicken-version VERSION) |
---|
308 | |
---|
309 | Signals an error if the version of CHICKEN that this script runs under is lexicographically less than |
---|
310 | {{VERSION}} (the argument will be converted to a string, first). |
---|
311 | |
---|
312 | |
---|
313 | ==== required-extension-version |
---|
314 | |
---|
315 | [procedure] (required-extension-version EXTENSION1 VERSION1 ...) |
---|
316 | |
---|
317 | Checks whether the extensions {{EXTENSION1 ...}} are installed and at least of version {{VERSION1 ...}}. |
---|
318 | The test is made by lexicographically comparing the string-representations of the given version with the version |
---|
319 | of the installed extension. If one of the listed extensions is not installed, has no associated version information |
---|
320 | or is of a version older than the one specified. |
---|
321 | |
---|
322 | |
---|
323 | ==== cross-chicken |
---|
324 | |
---|
325 | [procedure] (cross-chicken) |
---|
326 | |
---|
327 | Returns {{#t}} if this system is configured for cross-compilation or {{#f}} |
---|
328 | otherwise. |
---|
329 | |
---|
330 | |
---|
331 | ==== host-extension |
---|
332 | |
---|
333 | [parameter] host-extension |
---|
334 | |
---|
335 | For a cross-compiling CHICKEN, when compiling an extension, then it |
---|
336 | should be built for the host environment (as opposed to the target |
---|
337 | environment). This parameter is controlled by the {{-host-extension}} command-line |
---|
338 | option. A setup script should perform the proper steps of compiling any |
---|
339 | code by passing {{-host}} when invoking {{csc}} or using the {{compile}} |
---|
340 | macro. |
---|
341 | |
---|
342 | |
---|
343 | === Examples for extensions |
---|
344 | |
---|
345 | The simplest case is a single file that does not export any syntax. For example |
---|
346 | |
---|
347 | <enscript highlight=scheme> |
---|
348 | ;;;; hello.scm |
---|
349 | |
---|
350 | (define (hello name) |
---|
351 | (print "Hello, " name " !") ) |
---|
352 | </enscript> |
---|
353 | |
---|
354 | We need a {{.setup}} script to build and install our nifty extension: |
---|
355 | |
---|
356 | <enscript highlight=scheme> |
---|
357 | ;;;; hello.setup |
---|
358 | |
---|
359 | ;; compile the code into a dynamically loadable shared object |
---|
360 | ;; (will generate hello.so) |
---|
361 | (compile -s hello.scm) |
---|
362 | |
---|
363 | ;; Install as extension library |
---|
364 | (install-extension 'hello "hello.so") |
---|
365 | </enscript> |
---|
366 | |
---|
367 | After entering |
---|
368 | |
---|
369 | $ chicken-setup hello |
---|
370 | |
---|
371 | at the shell prompt (and in the same directory where the two files |
---|
372 | exist), the file {{hello.scm}} will be compiled into a dynamically |
---|
373 | loadable library. If the compilation succeeds, {{hello.so}} will |
---|
374 | be stored in the repository, together with a file named |
---|
375 | {{hello.setup-info}} containing an a-list with metadata. |
---|
376 | If no extension name is given to {{chicken-setup}}, it will simply |
---|
377 | execute the first file with the {{.setup}} extension it can find. |
---|
378 | |
---|
379 | Use it like any other CHICKEN extension: |
---|
380 | |
---|
381 | $ csi -q |
---|
382 | #;1> (require-extension hello) |
---|
383 | ; loading /usr/local/lib/chicken/1/hello.so ... |
---|
384 | #;2> (hello "me") |
---|
385 | Hello, me! |
---|
386 | #;3> |
---|
387 | |
---|
388 | Here we create a simple application: |
---|
389 | |
---|
390 | <enscript highlight=scheme> |
---|
391 | ;;;; hello2.scm |
---|
392 | |
---|
393 | (print "Hello, ") |
---|
394 | (for-each (lambda (x) (printf "~A " x)) (command-line-arguments)) |
---|
395 | (print "!") |
---|
396 | </enscript> |
---|
397 | |
---|
398 | We also need a setup script: |
---|
399 | |
---|
400 | <enscript highlight=scheme> |
---|
401 | ;;;; hello2.setup |
---|
402 | |
---|
403 | (compile hello2.scm) ; compile `hello2' |
---|
404 | (install-program 'hello2 "hello2") ; name of the extension and files to be installed |
---|
405 | </enscript> |
---|
406 | |
---|
407 | To use it, just run {{chicken-setup}} in the same directory: |
---|
408 | |
---|
409 | $ chicken-setup |
---|
410 | |
---|
411 | (Here we omit the extension name) |
---|
412 | |
---|
413 | Now the program {{hello2}} will be installed in the same location as |
---|
414 | the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will |
---|
415 | normally be {{/usr/local/bin}}. Note that you need write-permissions |
---|
416 | for those locations and may have to run {{chicken-setup}} with |
---|
417 | administrative rights. |
---|
418 | |
---|
419 | Uninstallation is just as easy: |
---|
420 | |
---|
421 | $ chicken-setup -uninstall hello2 |
---|
422 | |
---|
423 | {{chicken-setup}} provides a {{make}} macro, so build operations can |
---|
424 | be of arbitrary complexity. When running {{chicken-setup}} with an |
---|
425 | argument {{NAME}}, for which no associated file {{NAME.setup}}, |
---|
426 | {{NAME.egg}} or {{NAME.scm}} exists will ask you to download the |
---|
427 | extension via HTTP from the default URL |
---|
428 | [[http://www.call-with-current-continuation.org/eggs]]. You can use |
---|
429 | the {{-host}} option to specify an alternative source |
---|
430 | location. Extensions that are required to compile and/or use the |
---|
431 | requested extension are downloaded and installed automatically. |
---|
432 | |
---|
433 | If the given extension name contains a path prefix and the {{-host}} |
---|
434 | option is given, then {{chicken-setup}} can also download and install |
---|
435 | eggs from an arbitrary HTTP server. Alternatively you can pass a full |
---|
436 | URL (including the {{http://}} prefix. Note that no dependency checks |
---|
437 | are done when downloading eggs directly with the URL syntax. |
---|
438 | |
---|
439 | Finally a somewhat more complex example: We want to package a syntax |
---|
440 | extension with additional support code that is to be loaded at |
---|
441 | run-time of any Scheme code that uses that extension. We create a |
---|
442 | ''glass'' lambda, a procedure with free variables that can be |
---|
443 | manipulated from outside: |
---|
444 | |
---|
445 | <enscript highlight=scheme> |
---|
446 | ;;;; glass.scm |
---|
447 | |
---|
448 | (define-macro (glass-lambda llist vars . body) |
---|
449 | ;; Low-level macros are fun! |
---|
450 | (let ([lvar (gensym)] |
---|
451 | [svar (gensym)] |
---|
452 | [x (gensym)] |
---|
453 | [y (gensym)] |
---|
454 | [yn (gensym)] ) |
---|
455 | `(let ,(map (lambda (v) (list v #f)) vars) |
---|
456 | (define (,svar ,x . ,y) |
---|
457 | (let* ([,yn (pair? ,y)] |
---|
458 | [,y (and ,yn (car ,y))] ) |
---|
459 | (case ,x |
---|
460 | ,@(map (lambda (v) |
---|
461 | `([,v] (if ,yn |
---|
462 | (set! ,v ,y) |
---|
463 | ,v) ) ) |
---|
464 | vars) |
---|
465 | (else (error "variable not found" ,x)) ) ) ) |
---|
466 | (define ,lvar (lambda ,llist ,@body)) |
---|
467 | (extend-procedure ,lvar ,svar) ) ) ) |
---|
468 | </enscript> |
---|
469 | |
---|
470 | Here some support code that needs to be loaded at runtime: |
---|
471 | |
---|
472 | <enscript highlight=scheme> |
---|
473 | ;;;; glass-support.scm |
---|
474 | |
---|
475 | (require-extension lolevel) |
---|
476 | |
---|
477 | (define glass-lambda-accessor procedure-data) |
---|
478 | (define (glass-lambda-ref gl v) ((procedure-data gl) v)) |
---|
479 | (define (glass-lambda-set! gl v x) ((procedure-data gl) v x)) |
---|
480 | </enscript> |
---|
481 | |
---|
482 | The setup script looks like this: |
---|
483 | |
---|
484 | <enscript highlight=scheme> |
---|
485 | (compile -s glass-support.scm) |
---|
486 | |
---|
487 | (install-extension |
---|
488 | 'glass |
---|
489 | '("glass.scm" "glass-support.so") |
---|
490 | '((syntax) (require-at-runtime glass-support)) ) |
---|
491 | </enscript> |
---|
492 | |
---|
493 | The invocation of {{install-extension}} provides the files that are to |
---|
494 | be copied into the extension repository, and a metadata list that |
---|
495 | specifies that the extension {{glass}} is a syntax extension and that, |
---|
496 | if it is declared to be used by other code (either with the |
---|
497 | {{require-extension}} or {{require-for-syntax}} form), then client |
---|
498 | code should perform an implicit {{(require 'glass-support)}} at |
---|
499 | startup. |
---|
500 | |
---|
501 | This can be conveniently packaged as an ''egg'': |
---|
502 | |
---|
503 | $ tar cfz glass.egg glass.setup glass.scm glass-support.scm |
---|
504 | |
---|
505 | And now we use it: |
---|
506 | |
---|
507 | $ chicken-setup glass |
---|
508 | $ csi -quiet |
---|
509 | #;1> (require-extension glass) |
---|
510 | ; loading /usr/local/lib/chicken/1/glass.scm ... |
---|
511 | ; loading /usr/local/lib/chicken/1/glass-support.so ... |
---|
512 | #;2> (define foo (glass-lambda (x) (y) (+ x y))) |
---|
513 | #;3> (glass-lambda-set! foo 'y 99) |
---|
514 | #;4> (foo 33) |
---|
515 | 132 |
---|
516 | === chicken-setup reference |
---|
517 | |
---|
518 | Available options: |
---|
519 | |
---|
520 | ; {{-h -help}} : Show usage information and exit. |
---|
521 | ; {{-V -version}} : Display version and exit. |
---|
522 | ; {{-R -repository [PATHNAME]}} : When used without an argument, the path of the extension repository is displayed on standard output. When given an argument, the repository pathname (and the {{repository-path}} parameter) will be set to {{PATHNAME}} for all subsequent operations. The default repository path is the installation library directory (usually {{/usr/local/lib/chicken}}), or (if set) the directory given in the environment variable {{CHICKEN_REPOSITORY}}. {{PATHNAME}} should be an absolute pathname. |
---|
523 | ; {{-P -program-path [PATHNAME]}} : When used without an argument, the path for executables is displayed on standard output. When given an argument, the program path for installing executables and scripts will be set to {{PATHNAME}} for all subsequent operations. {{PATHNAME}} should be an absolute pathname. |
---|
524 | ; {{-h -host HOSTNAME[:PORT]}} : Specifies alternative host for downloading extensions, optionally with a TCP port number (which defaults to 80). |
---|
525 | ; {{-u -uninstall EXTENSION}} : Removes all files that were installed for {{EXTENSION}} from the file-system, together with any metadata that has been stored. |
---|
526 | ; {{-l -list [NAME ...]}} : List all installed extensions or show extension information. |
---|
527 | ; {{-r -run FILENAME}} : Load and execute given file. |
---|
528 | ; {{-s -script FILENAME}} :Executes the given Scheme source file with all remaining arguments and exit. The ''she-bang'' shell script header is recognized, so you can write Scheme scripts that use {{chicken-setup}} just as with {{csi}}. |
---|
529 | ; {{-e -eval EXPRESSION}} : Evaluates the given expression(s) |
---|
530 | ; {{-v -verbose}} : Display additional debug information |
---|
531 | ; {{-k -keep}} : Keep temporary files and directories |
---|
532 | ; {{-c -csc-option OPTION}} : Passes {{OPTION}} as an extra argument to invocations of the compiler-driver ({{csc}}); this works only if {{csc}} is invoked as {{(run (csc ...))}} |
---|
533 | ; {{-d -dont-ask}} : Do not ask the user before trying to download required extensions |
---|
534 | ; {{-n -no-install}} : Do not install generated binaries and/or support files; any invocations of {{install-program}}, {{install-extension}} or {{install-script}} will be be no-ops |
---|
535 | ; {{-i -docindex}} : Displays the path to the index-page of any installed extension-documentation; if the index page does not exist, it is created |
---|
536 | ; {{-t -test EXTENSION ...}} : return success if all given extensions are installed |
---|
537 | ; {{-ls EXTENSION}} : List installed files for extension |
---|
538 | ; {{-fetch-tree}} : Download and print the repository catalog |
---|
539 | ; {{-create-tree DIRECTORY}} : Create a fresh, minimal repository catalog and writes it to stdout |
---|
540 | ; {{-t -test}} : If the extension sources contain a directory named {{tests}} and this directory includes a file named {{run.scm}} then this file is executed (with {{tests}} being the current working directory) |
---|
541 | ; {{-tree FILENAME}} : Download and show the repository catalog |
---|
542 | ; {{-svn URL}} : Fetch extension from [[http://subversion.tigris.org|Subversion]] repository |
---|
543 | ; {{-revision REV}} : Specifies SVN revision to check out |
---|
544 | ; {{-local PATHNAME}} : Fetch extension from local file |
---|
545 | ; {{-destdir PATHNAME}} : Specify alternative installation prefix (for packaging) |
---|
546 | ; {{-host-extension}} : Compile extension in "host" mode (sets the parameter {{host-extension}} to {{#f}}) |
---|
547 | ; {{--}} : Ignore all following arguments |
---|
548 | |
---|
549 | Note that the options are processed exactly in the order in which they appear in the command-line. |
---|
550 | |
---|
551 | |
---|
552 | === Windows notes |
---|
553 | |
---|
554 | {{chicken-setup}} works on Windows, when compiled with Visual C++, but |
---|
555 | depends on the {{tar}} and {{gunzip}} tools to extract the contents of |
---|
556 | an egg. The best way is to download an egg either manually (or with |
---|
557 | {{chicken-setup -fetch}}) and extract its contents with a separate |
---|
558 | program (like {{winzip}}). the {{CHICKEN_REPOSITORY}} environment |
---|
559 | variable has to be set to a |
---|
560 | directory where your compiled extensions should be located. |
---|
561 | |
---|
562 | The {{.setup}} scripts will not always work under Windows, and the |
---|
563 | extensions may require libraries that are not provided for Windows or |
---|
564 | work differently. Under these circumstances it is recommended to |
---|
565 | perform the required steps to build an extension manually. |
---|
566 | |
---|
567 | The required UNIX tools are also available as Windows binaries. |
---|
568 | Google or ask on the CHICKEN mailing list if you need help locating |
---|
569 | them. |
---|
570 | |
---|
571 | |
---|
572 | === Security |
---|
573 | |
---|
574 | When extensions are downloaded and installed one is executing code |
---|
575 | from potentially compromised systems. This applies also when {{chicken-setup}} |
---|
576 | executes system tests for required extensions. As the code has been |
---|
577 | retrieved over the network effectively untrusted code is going to be |
---|
578 | evaluated. When {{chicken-setup}} is run as ''root'' the whole system |
---|
579 | is at the mercy of the build instructions (note that this is also |
---|
580 | the case every time you install software via {{sudo make install}}, so this |
---|
581 | is not specific to the CHICKEN extension mechanism). |
---|
582 | |
---|
583 | Security-conscious users should never run {{chicken-setup}} as root. |
---|
584 | A simple remedy is to set the environment variable {{CHICKEN_REPOSITORY}}, |
---|
585 | which will transparently place the repository at an arbitrary user-selected |
---|
586 | location. Alternatively obtain write/execute access to the default location |
---|
587 | of the repository (usually {{/usr/local/lib/chicken}}) to avoid running |
---|
588 | as root. |
---|
589 | |
---|
590 | |
---|
591 | === Other modes of installation |
---|
592 | |
---|
593 | It is possible to install extensions directly from a |
---|
594 | [[http://subversion.tigris.org|Subversion]] repository or from a local |
---|
595 | checkout by using the {{-svn}} or {{-local}} options. By using |
---|
596 | either the {{svn}} client program (which must be installed) or |
---|
597 | file-system operations, all necessary files will be copied into the |
---|
598 | current directory (creating a subdirectory named |
---|
599 | {{EXTENSIONNAME.egg-dir}}), built and subsequently installed. |
---|
600 | |
---|
601 | Dependency information, which is necessary to ensure required |
---|
602 | extensions are also installed, is downloaded automatically. If you |
---|
603 | have no internet connection or don't want to connect, you can also use |
---|
604 | a local file containing the necessary dependency information. The |
---|
605 | {{-fetch-tree}} option retrieves the canonical ''repository file'' at |
---|
606 | [[http://www.call-with-current-continuation.org/eggs/repository]], |
---|
607 | writing it to stdout. Redirecting this output into a file and passing |
---|
608 | the file via the {{-tree}} option to {{chicken-setup}} allows you now |
---|
609 | to use the local repository file: |
---|
610 | |
---|
611 | Retrieve complete extension repository (big): |
---|
612 | |
---|
613 | % cd /opt |
---|
614 | % svn co https://galinha.ucpel.tche.br/svn/chicken-eggs/release/3 eggs |
---|
615 | |
---|
616 | Get your own copy of the repository file: |
---|
617 | |
---|
618 | % chicken-setup -fetch-tree >~/my-repository-file |
---|
619 | |
---|
620 | Now you can install eggs from your local checkout, with full |
---|
621 | dependency tracking and without being connected to the internet: |
---|
622 | |
---|
623 | % cd ~/tmp |
---|
624 | % chicken-setup -local /opt/eggs -tree ~/my-repository-file opengl |
---|
625 | |
---|
626 | |
---|
627 | === Linking extensions statically |
---|
628 | |
---|
629 | The compiler and [[chicken-setup]] support statically linked |
---|
630 | eggs. The general approach is to generate an object file or static |
---|
631 | library (in addition to the usual |
---|
632 | shared library) in your {{.setup}} script and install it along with the |
---|
633 | dynamically loadable extension. The setup properties {{static}} |
---|
634 | should contain the name of the object file (or static library) to be |
---|
635 | linked, when {{csc}} gets passed the {{-static-extensions}} option: |
---|
636 | |
---|
637 | <enscript highlight=scheme> |
---|
638 | (compile -s -O2 -d1 my-ext.scm) ; dynamically loadable "normal" version |
---|
639 | (compile -c -O2 -d1 my-ext -unit my-ext) ; statically linkable version |
---|
640 | (install-extension |
---|
641 | 'my-ext |
---|
642 | '("my-ext.so" "my-ext.o") |
---|
643 | '((static "my-ext.o")) ) |
---|
644 | </enscript> |
---|
645 | |
---|
646 | Note the use of the {{-unit}} option in the second compilation step: static |
---|
647 | linking must use static library units. {{chicken-setup}} will perform |
---|
648 | platform-dependent file-extension translation for the file list, but does currently |
---|
649 | not do that for the {{static}} extension property. |
---|
650 | |
---|
651 | To actually link with the static version of {{my-ext}}, do: |
---|
652 | |
---|
653 | % csc -static-extensions my-program.scm -uses my-ext |
---|
654 | |
---|
655 | The compiler will try to do the right thing, but can not handle all |
---|
656 | extensions, since the ability to statically link eggs is relatively |
---|
657 | new. Eggs that support static linking are designated as being able to |
---|
658 | do so. If you require a statically linkable version of an egg that has |
---|
659 | not been converted yet, contact the extension author or the CHICKEN |
---|
660 | mailing list. |
---|
661 | |
---|
662 | |
---|
663 | Previous: [[Interface to external functions and variables]] |
---|
664 | |
---|
665 | Next: [[Data representation]] |
---|