source: project/wiki/chicken-setup @ 2904

Last change on this file since 2904 was 2904, checked in by felix winkelmann, 14 years ago

bugfix in tinyclos

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