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