source: project/chicken/trunk/manual/Extensions @ 12840

Last change on this file since 12840 was 12840, checked in by felix winkelmann, 11 years ago

removed nonsensical option

File size: 19.5 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Extensions
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
20Extensions are technically nothing but dynamically loadable compiled
21files with added meta-data that describes dependencies to other
22extensions, version information and things like the author/maintainer
23of the extension. Three tools provide an easy to use interface for
24installing extensions, removing them and querying the current
25status of installed extensions.
26
27
28=== Installing extensions
29
30To install an extension library, run the {{chicken-install}} 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-install}}. 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 local extension repository or in the
44path where the CHICKEN executables are located (in the case of
45executable programs or scripts). Additionally the list of installed
46files, and user-defined metadata is stored in the repository.
47
48If no extension name is given on the command-line, then all {{.setup}}
49scripts in the current directory are processed, in the order given
50on the command line.
51
52==== Installing extensions that use libraries
53
54Sometimes an extension requires a C library to compile. Compilation
55can fail when your system has this library in a nonstandard
56location. Luckily, normally Chicken searches in the default locations
57{{/usr}} and {{/usr/local}}, and in the prefix where Chicken itself
58was installed. Sometimes this is not enough, so you'll need to supply
59{{chicken-install}} with some extra hints to the C compiler/linker. Here's
60an example:
61
62  CSC_OPTIONS='-I/usr/pkg/include/mysql -L/usr/pkg/lib/mysql -L -R/usr/pkg/lib/mysql' chicken-install mysql
63
64This installs the mysql egg with the extra compiler options -I and -L
65to set the include path and the library search path. The second -L
66switch passes the -R option directly to the linker, which causes the
67library path to get hardcoded into the resulting extension file (for
68systems that do not use {{ld.so.conf}}).
69
70=== Creating extensions
71
72Extensions can be created by creating an (optionally gzipped) {{tar}}
73archive named {{EXTENSION.egg}} containing all needed files plus a
74{{.setup}} script in the root directory.  After {{chicken-setup}} has
75extracted the files, the setup script will be invoked. There are no
76additional constraints on the structure of the archive, but the setup
77script has to be in the root path of the archive.
78
79
80=== Procedures and macros available in setup scripts
81
82==== install-extension
83
84 (install-extension ID FILELIST [INFOLIST])
85
86Installs the extension library with the name {{ID}}. All files given in the list of strings
87{{FILELIST}} will be copied to the extension repository. It should be noted here that
88the extension id has to be identical to the name of the file implementing the extension. The
89extension may load or include other files, or may load other extensions at runtime specified
90by the {{require-at-runtime}} property.
91
92{{FILELIST}} may be a filename, a list of filenames, or a list of pairs of
93the form {{(SOURCE DEST)}} (if you want to copy into a particular sub-directory - the
94destination directory will be created as needed). If {{DEST}} is a relative pathname,
95< it will be copied into the extension repository.
96
97The optional argument {{INFOLIST}} should be an association list that
98maps symbols to values, this list will be stored as {{ID.setup-info}} at the same
99location as the extension code. Currently the following properties are used:
100
101===== syntax
102
103 [extension property] (syntax)
104
105Marks the extension as syntax-only. No code is compiled, the extension is intended
106as a file containing macros to be loaded at compile/macro-expansion time.
107
108===== require-at-runtime
109
110 [extension property] (require-at-runtime ID ...)
111
112Specifies extensions that should be loaded (via {{require}}) at runtime. This is mostly
113useful for syntax extensions that need additional support code at runtime.
114
115===== version
116
117 [extension property] (version STRING)
118
119Specifies version string.
120
121===== static
122
123 [extension property] (static STRING)
124
125If the extension also provides a static library, then STRING should
126contain the name of that library. Used by {{csc}} when compiling with
127the {{-static-extensions}} option.
128
129===== static-options
130
131 [extension property] (static-options STRING)
132
133Additional options that should be passed to the linker when linking
134with the static version of an extension (see {{static}} above). Used
135by {{csc}} when compiling with the {{-static-extensions}} option.
136
137All other properties are currently ignored. The {{FILELIST}} argument may also be a single
138string.
139
140==== install-program
141
142 [procedure] (install-program ID FILELIST [INFOLIST])
143
144Similar to {{install-extension}}, but installs an executable program in the
145executable path (usually {{/usr/local/bin}}).
146
147==== install-script
148
149 [procedure] (install-script ID FILELIST [INFOLIST])
150
151Similar to {{install-program}}, but additionally changes the file permissions of all
152files in {{FILELIST}} to executable (for installing shell-scripts).
153
154
155==== run
156
157 [syntax] (run FORM ...)
158
159Runs the shell command {{FORM}}, which is wrapped in an implicit {{quasiquote}}.
160{{(run (csc ...))}} is treated specially and passes {{-v}} (if {{-verbose}} has been given
161to {{chicken-install}}) and {{-feature compiling-extension}} options to the compiler.
162
163==== compile
164
165 [syntax] (compile FORM ...)
166
167Equivalent to {{(run (csc FORM ...))}}.
168
169==== make
170
171 [syntax] (make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)
172
173A ''make'' macro that executes the expressions {{COMMAND ...}}, when any of the dependents
174{{DEPENDENT ...}} have changed, to build {{TARGET}}. This is the same as the {{make}}
175extension, which is available separately. For more information, see
176[[http://www.call-with-current-continuation.org/eggs/make.html|make]].
177
178
179==== patch
180
181 [procedure] (patch WHICH REGEX SUBST)
182
183Replaces all occurrences of the regular expression {{REGEX}} with the string {{SUBST}},
184in the file given in {{WHICH}}. If {{WHICH}} is a string, the file will be patched and
185overwritten. If {{WHICH}} is a list of the form {{OLD NEW}}, then a different file named
186{{NEW}} will be generated.
187
188==== copy-file
189
190 [procedure] (copy-file FROM TO)
191
192Copies the file or directory (recursively) given in the string {{FROM}} to the destination
193file or directory {{TO}}.
194
195==== move-file
196
197 [procedure] (move-file FROM TO)
198
199Moves the file or directory (recursively) given in the string {{FROM}} to the destination
200file or directory {{TO}}.
201
202==== remove-file*
203
204 [procedure] (remove-file* PATH)
205
206Removes the file or directory given in the string {{PATH}}.
207
208
209==== find-library
210
211 [procedure] (find-library NAME PROC)
212
213Returns {{#t}} if the library named {{libNAME.[a|so]}} (unix) or {{NAME.lib}} (windows)
214could be found by compiling and linking a test program. {{PROC}} should be the name of a
215C function that must be provided by the library. If no such library was found or the function could not
216be resolved, {{#f}} is returned.
217
218==== find-header
219
220 [procedure] (find-header NAME)
221
222Returns {{#t}} if a C include-file with the given name is available, or {{#f}} otherwise.
223
224==== try-compile
225
226 [procedure] (try-compile CODE #!key cc cflags ldflags compile-only c++)
227
228Returns {{#t}} if the C code in {{CODE}} compiles and links successfully, or {{#f}} otherwise.
229The keyword parameters {{cc}} (compiler name, defaults to the C compiler used to build this system),
230{{cflags}} and {{ldflags}} accept additional compilation and
231linking options. If {{compile-only}} is true, then no linking step takes place.
232If the keyword argument {{c++}} is given and true, then the code will be compiled in C++ mode.
233
234
235==== create-directory
236
237 [procedure] (create-directory PATH)
238
239Creates the directory given in the string {{PATH}}, with all parent directories as needed.
240
241
242==== chicken-prefix
243
244 [parameter] chicken-prefix
245
246The installation prefix specified when CHICKEN was built.
247
248==== installation-prefix
249
250 [parameter] installation-prefix
251
252An alternative installation prefix that will be prepended to extension
253installation paths if specified. It is set by the {{-install-prefix}}
254option or environment variable {{CHICKEN_INSTALL_PREFIX}}.
255
256==== program-path
257
258 [parameter] (program-path [PATH])
259
260Holds the path where executables are installed and defaults to either {{$CHICKEN_PREFIX/bin}},
261if the environment variable {{CHICKEN_PREFIX}} is set or the
262path where the CHICKEN binaries ({{chicken}}, {{csi}}, etc.) are installed.
263
264
265==== setup-root-directory
266
267 [parameter] (setup-root-directory [PATH])
268
269Contains the path of the directory where {{chicken-setup}} was invoked.
270
271
272==== setup-install-flag
273
274 [parameter] (setup-install-flag [BOOL])
275
276Reflects the setting of the {{-no-install}} option, i.e. is {{#f}}, if {{-no-install}} was
277given to {{chicken-install}}.
278
279==== required-chicken-version
280
281 [procedure] (required-chicken-version VERSION)
282
283Signals an error if the version of CHICKEN that this script runs under is lexicographically less than
284{{VERSION}} (the argument will be converted to a string, first).
285
286
287==== required-extension-version
288
289 [procedure] (required-extension-version EXTENSION1 VERSION1 ...)
290
291Checks whether the extensions {{EXTENSION1 ...}} are installed and at least of version {{VERSION1 ...}}.
292The test is made by lexicographically comparing the string-representations of the given version with the version
293of the installed extension. If one of the listed extensions is not installed, has no associated version information
294or is of a version older than the one specified.
295
296
297==== cross-chicken
298
299 [procedure] (cross-chicken)
300
301Returns {{#t}} if this system is configured for cross-compilation or {{#f}}
302otherwise.
303
304
305==== host-extension
306
307 [parameter] host-extension
308
309For a cross-compiling CHICKEN, when compiling an extension, then it
310should be built for the host environment (as opposed to the target
311environment). This parameter is controlled by the {{-host-extension}} command-line
312option. A setup script should perform the proper steps of compiling any
313code by passing {{-host}} when invoking {{csc}} or using the {{compile}}
314macro.
315
316
317=== Examples for extensions
318
319The simplest case is a single file that does not export any syntax. For example
320
321<enscript highlight=scheme>
322;;;; hello.scm
323
324(define (hello name)
325  (print "Hello, " name " !") )
326</enscript>
327
328We need a {{.setup}} script to build and install our nifty extension:
329
330<enscript highlight=scheme>
331;;;; hello.setup
332
333;; compile the code into a dynamically loadable shared object
334;; (will generate hello.so)
335(compile -s hello.scm)
336
337;; Install as extension library
338(install-extension 'hello "hello.so")
339</enscript>
340
341Lastly, we need a file {{hello.meta}} defining a minimal set of properties:
342
343<enscript highlight=scheme>
344;;;; hello.meta
345
346((author "Me")
347 (synopsis "A cool hello-world library")
348 (license "GPLv3")
349 (files "hello.scm" "hello.setup"))
350</enscript>
351
352(for more information about available properties, see {{Metafile reference}})
353
354After entering
355
356 $ chicken-install
357
358at the shell prompt (and in the same directory where the two files
359exist), the file {{hello.scm}} will be compiled into a dynamically
360loadable library. If the compilation succeeds, {{hello.so}} will
361be stored in the repository, together with a file named
362{{hello.setup-info}} containing an a-list with metadata (what
363you stored above in {{hello.meta}}).
364If no extension name is given to {{chicken-install}}, it will simply
365execute the any files with the {{.setup}} extension it can find.
366
367Use it like any other CHICKEN extension:
368
369 $ csi -q
370 #;1> (require-extension hello)
371 ; loading /usr/local/lib/chicken/4/hello.so ...
372 #;2> (hello "me")
373 Hello, me!
374 #;3>
375
376Here we create a simple application:
377
378<enscript highlight=scheme>
379;;;; hello2.scm
380
381(print "Hello, ")
382(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))
383(print "!")
384</enscript>
385
386We also need a setup script:
387
388<enscript highlight=scheme>
389;;;; hello2.setup
390
391(compile hello2.scm)  ; compile `hello2'
392(install-program 'hello2 "hello2") ; name of the extension and files to be installed
393</enscript>
394
395<enscript highlight=scheme>
396;;;; hello2.meta
397
398((author "Me")
399 (synopsis "A cool hello-world application")
400 (license "proprietary")
401 (files "hello.scm" "hello.setup"))
402</enscript>
403
404To use it, just run {{chicken-install}} in the same directory:
405
406 $ chicken-install
407
408(Here we omit the extension name)
409
410Now the program {{hello2}} will be installed in the same location as
411the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will
412normally be {{/usr/local/bin}}.  Note that you need write-permissions
413for those locations and may have to run {{chicken-install}} with
414administrative rights or use the {{-sudo}} option.
415
416De-installation is just as easy - use the {{chicken-uninstall}}
417program to remove one or more extensions from the local repository:
418
419 $ chicken-uninstall hello2
420
421When running {{chicken-install}} with an argument {{NAME}}, for which
422no associated {{.setup}} file exists, then it will try to download the
423extension via HTTP from the CHICKEN code repository at
424[[http://chicken.wiki.br/svn/chicken-eggs/]]. Extensions that are
425required to compile and/or use the requested extension are downloaded
426and installed automatically.
427
428To query the list of currently installed extensions, use
429{{chicken-status}}. It can list what extensions are installed and
430what files belong to a particular installed extension.
431
432
433=== chicken-install reference
434
435Available options:
436
437; {{-h   -help}} : show this message and exit
438; {{-v   -version}} : show version and exit
439; {{-force}} : don't ask, install even if versions don't match
440; {{-k   -keep}} : keep temporary files
441; {{-l   -location LOCATION}} : install from given location instead of default
442; {{-t   -transport TRANSPORT}} : use given transport instead of default
443; {{-s   -sudo}} : use {{sudo(1)}} for installing or removing files
444; {{-r   -retrieve}} : only retrieve egg into current directory, don't install
445; {{-n   -no-install}} : do not install, just build (implies {{-keep}})
446; {{-p   -prefix PREFIX}} : change installation prefix to {{PREFIX}}
447; {{-host-extension}} : when cross-compiling, compile extension for host
448; {{-test}} : run included test-cases, if available
449; {{-username USER}} : set username for transports that require this
450; {{-password PASS}} : set password for transports that require this
451; {{-i   -init DIRECTORY}} : initialize empty alternative repository
452; {{-u   -update-db}} : update export database
453
454
455=== chicken-uninstall reference
456
457; {{-h   -help}} : show usage information and exit
458; {{-v   -version}} : show version and exit
459; {{-force}} : don't ask, delete whatever matches
460; {{-s   -sudo}} : use {{sudo(1)}} for deleting files
461
462
463=== chicken-status reference
464
465; {{-h   -help}} : show usage information and exit
466; {{-v   -version}} : show version and exit
467; {{-f   -files}} : list installed files
468
469
470=== Security
471
472When extensions are downloaded and installed one is executing code
473from potentially compromised systems. This applies also when
474{{chicken-install}} executes system tests for required extensions. As
475the code has been retrieved over the network effectively untrusted
476code is going to be evaluated. When {{chicken-install}} is run as
477''root'' the whole system is at the mercy of the build instructions
478(note that this is also the case every time you install software via
479{{sudo make install}}, so this is not specific to the CHICKEN
480extension mechanism).
481
482Security-conscious users should never run {{chicken-install}} as root.
483A simple remedy is to set the environment variable
484{{CHICKEN_REPOSITORY}}, which will transparently place the repository
485at an arbitrary user-selected location (don't forget to initialize it
486first with {{chicken-install -init <directory>}}).  Alternatively
487obtain write/execute access to the default location of the repository
488(usually {{/usr/local/lib/chicken}}) to avoid running as
489root. {{chicken-install}} also provides a {{-sudo}} option to perform
490the last installation steps as root user, but do building and other
491.setup script processing as normal.
492
493
494=== Other modes of installation
495
496It is possible to install extensions directly from a
497[[http://subversion.tigris.org|Subversion]] repository or from a local
498checkout of the repository tree by using the {{-transport}} and
499{{-location}} options when invoking {{chicken-install}}. Three possible
500transport mechanisms are currently supported:
501
502; {{http}} : download extension sources via HTTP from a web-server (this is the default)
503; {{svn}} : perform an {{svn export}} from the central extension repository; this will require a {{svn(1)}} client to be installed on the machine
504; {{local}} : use sources from the local filesystem and build directly in the source directory
505
506The {{-location}} option specifies where to look for the source
507repository and names a web URL, a subversion repository URL or a
508filesystem path, respectively. A list of locations to try when
509retrieving extensions is stored in the file {{setup.defaults}}
510(usually installed in {{/usr/local/share/chicken}}). For {{http}}
511transports, {{chicken-install}} will detect networking timeouts and
512try alternative locations, as listed in the file.
513
514Dependency information, which is necessary to ensure required
515extensions are also installed, is processed automatically.
516
517=== Linking extensions statically
518
519The compiler and {{chicken-install}} support statically linked
520eggs. The general approach is to generate an object file or static
521library (in addition to the usual
522shared library) in your {{.setup}} script and install it along with the
523dynamically loadable extension. The setup properties {{static}}
524should contain the name of the object file (or static library) to be
525linked, when {{csc}} gets passed the {{-static-extensions}} option:
526
527<enscript highlight=scheme>
528(compile -s -O2 -d1 my-ext.scm)   ; dynamically loadable "normal" version
529(compile -c -O2 -d1 my-ext -unit my-ext)  ; statically linkable version
530(install-extension
531  'my-ext
532  '("my-ext.so" "my-ext.o")
533  '((static "my-ext.o")) )
534</enscript>
535
536Note the use of the {{-unit}} option in the second compilation step: static
537linking must use static library units. {{chicken-install}} will perform
538platform-dependent file-extension translation for the file list, but does currently
539not do that for the {{static}} extension property.
540
541To actually link with the static version of {{my-ext}}, do:
542
543 % csc -static-extensions my-program.scm -uses my-ext
544
545The compiler will try to do the right thing, but can not handle all
546extensions, since the ability to statically link eggs is relatively
547new. Eggs that support static linking are designated as being able to
548do so. If you require a statically linkable version of an egg that has
549not been converted yet, contact the extension author or the CHICKEN
550mailing list.
551
552
553Previous: [[Interface to external functions and variables]]
554
555Next: [[Data representation]]
Note: See TracBrowser for help on using the repository browser.