source: project/wiki/man/4/Extensions @ 21989

Last change on this file since 21989 was 21989, checked in by Mario Domenech Goulart, 9 years ago

Extensions (wiki manual): fixed link to make egg.

File size: 26.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. Normally the C compiler 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-install}} 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
79For more details on creating extensions, see the [[/eggs tutorial|eggs tutorial]].
80
81
82=== Procedures and macros available in setup scripts
83
84==== install-extension
85
86<procedure>(install-extension ID FILELIST [INFOLIST])</procedure>
87
88Installs the extension library with the name {{ID}}. All files given in the list of strings
89{{FILELIST}} will be copied to the extension repository. It should be noted here that
90the extension id has to be identical to the name of the file implementing the extension. The
91extension may load or include other files, or may load other extensions at runtime specified
92by the {{require-at-runtime}} property.
93
94{{FILELIST}} may be a filename, a list of filenames, or a list of pairs of
95the form {{(SOURCE DEST)}} (if you want to copy into a particular sub-directory - the
96destination directory will be created as needed). If {{DEST}} is a relative pathname,
97it will be copied into the extension repository.
98
99The optional argument {{INFOLIST}} should be an association list that
100maps symbols to values, this list will be stored as {{ID.setup-info}} at the same
101location as the extension code. Currently the following properties are used:
102
103===== syntax
104
105 [extension property] (syntax)
106
107Marks the extension as syntax-only. No code is compiled, the extension is intended
108as a file containing macros to be loaded at compile/macro-expansion time.
109
110===== require-at-runtime
111
112 [extension property] (require-at-runtime ID ...)
113
114Specifies extensions that should be loaded (via {{require}}) at runtime. This is mostly
115useful for syntax extensions that need additional support code at runtime.
116
117===== import-only
118
119  [extension property] (import-only)
120
121Specifies that this extension only provides a expansion-time code in an import library and
122does not require code to be loaded at runtime.
123
124===== version
125
126 [extension property] (version STRING)
127
128Specifies version string.
129
130===== static
131
132 [extension property] (static STRING)
133
134If the extension also provides a static library, then STRING should
135contain the name of that library. Used by {{csc}} when compiling with
136the {{-static-extension}} option.
137
138===== static-options
139
140 [extension property] (static-options STRING)
141
142Additional options that should be passed to the linker when linking
143with the static version of an extension (see {{static}} above). Used
144by {{csc}} when compiling with the {{-static-extension}} option.
145
146All other properties are currently ignored. The {{FILELIST}} argument may also be a single
147string.
148
149==== install-program
150
151<procedure>(install-program ID FILELIST [INFOLIST])</procedure>
152
153Similar to {{install-extension}}, but installs an executable program in the
154executable path (usually {{/usr/local/bin}}).
155
156==== install-script
157
158<procedure>(install-script ID FILELIST [INFOLIST])</procedure>
159
160Similar to {{install-program}}, but additionally changes the file permissions of all
161files in {{FILELIST}} to executable (for installing shell-scripts).
162
163==== standard-extension
164
165<procedure>(standard-extension ID VERSION #!key static info)</procedure>
166
167A convenience procedure that combines the compilation and installation of
168a simple single-file extension. This is roughly equivalent to:
169
170  (compile -s -O2 -d1 ID.scm -j ID)
171  (compile -c -O2 -d1 ID.scm -j ID -unit ID)  ; if STATIC is not given or true
172  (compile -s -O2 -d0 ID.import.scm)
173 
174  (install-extension
175   'ID
176   '("ID.o" "ID.so" "ID.import.so")
177   '((version 1.0)
178     ... `INFO' ...
179     (static "ID.o")))   ; if `static' is given and true
180
181{{VERSION}} may be {{#f}}, in that case the version obtained from where the
182extension has been retrieved wil be taken. If installed directly from a local
183directory, the version will default to {{"unknown"}}.
184
185
186==== run
187
188<macro>(run FORM ...)</macro>
189
190Runs the shell command {{FORM}}, which is wrapped in an implicit {{quasiquote}}.
191{{(run (csc ...))}} is treated specially and passes {{-v}} (if {{-verbose}} has been given
192to {{chicken-install}}) and {{-feature compiling-extension}} options to the compiler.
193
194
195==== compile
196
197<macro>(compile FORM ...)</macro>
198
199Equivalent to {{(run (csc FORM ...))}}.
200
201
202==== make
203
204<macro>(make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)</macro>
205
206A ''make'' macro that executes the expressions {{COMMAND ...}}, when any of the dependents
207{{DEPENDENT ...}} have changed, to build {{TARGET}}. This is the same as the {{make}}
208extension, which is available separately. For more information, see
209[[http://wiki.call-cc.org/egg/make|make]].
210
211
212==== patch
213
214<procedure>(patch WHICH REGEX SUBST)</procedure>
215
216Replaces all occurrences of the regular expression {{REGEX}} with the string {{SUBST}},
217in the file given in {{WHICH}}. If {{WHICH}} is a string, the file will be patched and
218overwritten. If {{WHICH}} is a list of the form {{OLD NEW}}, then a different file named
219{{NEW}} will be generated.
220
221==== copy-file
222
223<procedure>(copy-file FROM TO)</procedure>
224
225Copies the file or directory (recursively) given in the string {{FROM}} to the destination
226file or directory {{TO}}.
227
228==== move-file
229
230<procedure>(move-file FROM TO)</procedure>
231
232Moves the file or directory (recursively) given in the string {{FROM}} to the destination
233file or directory {{TO}}.
234
235==== remove-file*
236
237<procedure>(remove-file* PATH)</procedure>
238
239Removes the file or directory given in the string {{PATH}}, if it exists.
240
241
242==== find-library
243
244<procedure>(find-library NAME PROC)</procedure>
245
246Returns {{#t}} if the library named {{libNAME.[a|so]}} (unix) or {{NAME.lib}} (windows)
247could be found by compiling and linking a test program. {{PROC}} should be the name of a
248C function that must be provided by the library. If no such library was found or the function could not
249be resolved, {{#f}} is returned.
250
251==== find-header
252
253<procedure>(find-header NAME)</procedure>
254
255Returns {{#t}} if a C include-file with the given name is available, or {{#f}} otherwise.
256
257==== try-compile
258
259<procedure>(try-compile CODE #!key cc cflags ldflags compile-only c++)</procedure>
260
261Returns {{#t}} if the C code in {{CODE}} compiles and links successfully, or {{#f}} otherwise.
262The keyword parameters {{cc}} (compiler name, defaults to the C compiler used to build this system),
263{{cflags}} and {{ldflags}} accept additional compilation and
264linking options. If {{compile-only}} is true, then no linking step takes place.
265If the keyword argument {{c++}} is given and true, then the code will be compiled in C++ mode.
266
267
268==== create-directory/parents
269
270<procedure>(create-directory/parents PATH)</procedure>
271
272Creates the directory given in the string {{PATH}}, with all parent directories as needed.
273
274
275==== extension-name-and-version
276
277<parameter>extension-name-and-version</parameter>
278
279Returns a list containing the name and version of the currently installed
280extension as strings. If the setup script is not invoked via {{chicken-install}},
281then name and version will be empty.
282
283
284==== version>=?
285
286<procedure>(version>=? V1 V2)</procedure>
287
288Compares the version numbers {{V1}} and {{V2}} and returns {{#t}} if
289{{V1}} is "less" than {{V2}} or {{#f}} otherwise. A version number can
290be an integer, a floating-point number or a string. {{version>=?}}
291handles dot-separated version-indicators of the form {{"X.Y. .."}}.
292
293If one version number is the prefix of the other, then the shorter version
294is considered "less" than the longer.
295
296
297==== installation-prefix
298
299<procedure>(installation-prefix)</procedure>
300
301An alternative installation prefix that will be prepended to extension
302installation paths if specified. It is set by the {{-prefix}}
303option or environment variable {{CHICKEN_INSTALL_PREFIX}}.
304
305
306==== program-path
307
308<parameter>(program-path [PATH])</parameter>
309
310Holds the path where executables are installed and defaults to either {{$CHICKEN_PREFIX/bin}},
311if the environment variable {{CHICKEN_PREFIX}} is set or the
312path where the CHICKEN binaries ({{chicken}}, {{csi}}, etc.) are installed.
313
314
315==== setup-root-directory
316
317<parameter>(setup-root-directory [PATH])</parameter>
318
319Contains the path of the directory where {{chicken-install}} was invoked.
320
321
322==== setup-install-mode
323
324<parameter>(setup-install-mode [BOOL])</parameter>
325
326Reflects the setting of the {{-no-install}} option, i.e. is {{#f}}, if {{-no-install}} was
327given to {{chicken-install}}.
328
329==== required-chicken-version
330
331<procedure>(required-chicken-version VERSION)</procedure>
332
333Signals an error if the version of CHICKEN that this script runs under is lexicographically less than
334{{VERSION}} (the argument will be converted to a string, first).
335
336
337==== required-extension-version
338
339<procedure>(required-extension-version EXTENSION1 VERSION1 ...)</procedure>
340
341Checks whether the extensions {{EXTENSION1 ...}} are installed and at least of version {{VERSION1 ...}}.
342The test is made by lexicographically comparing the string-representations of the given version with the version
343of the installed extension. If one of the listed extensions is not installed, has no associated version information
344or is of a version older than the one specified.
345
346
347==== host-extension
348
349<parameter>host-extension</parameter>
350
351For a cross-compiling CHICKEN, when compiling an extension, then it
352should be built for the host environment (as opposed to the target
353environment). This parameter is controlled by the {{-host}} command-line
354option. A setup script should perform the proper steps of compiling any
355code by passing {{-host}} when invoking {{csc}} or using the {{compile}}
356macro.
357
358
359=== Examples for extensions
360
361==== A simple library
362
363The simplest case is a single file that does not export any syntax. For example
364
365<enscript highlight=scheme>
366;;;; hello.scm
367
368(define (hello name)
369  (print "Hello, " name " !") )
370</enscript>
371
372We need a {{.setup}} script to build and install our nifty extension:
373
374<enscript highlight=scheme>
375;;;; hello.setup
376
377;; compile the code into a dynamically loadable shared object
378;; (will generate hello.so)
379(compile -s hello.scm)
380
381;; Install as extension library
382(install-extension 'hello "hello.so")
383</enscript>
384
385Lastly, we need a file {{hello.meta}} defining a minimal set of properties:
386
387<enscript highlight=scheme>
388;;;; hello.meta
389
390((author "Me")
391 (synopsis "A cool hello-world library")
392 (license "GPLv3"))
393</enscript>
394
395(for more information about available properties, see
396[[/Metafile reference|the metafile reference]])
397
398After entering
399
400 $ chicken-install
401
402at the shell prompt (and in the same directory where the two files
403exist), the file {{hello.scm}} will be compiled into a dynamically
404loadable library. If the compilation succeeds, {{hello.so}} will
405be stored in the repository, together with a file named
406{{hello.setup-info}} containing an a-list with metadata (what
407you stored above in {{hello.meta}}).
408If no extension name is given to {{chicken-install}}, it will simply
409execute the any files with the {{.setup}} extension it can find.
410
411Use it like any other CHICKEN extension:
412
413 $ csi -q
414 #;1> (require-library hello)
415 ; loading /usr/local/lib/chicken/4/hello.so ...
416 #;2> (hello "me")
417 Hello, me!
418 #;3>
419
420==== An application
421
422Here we create a simple application:
423
424<enscript highlight=scheme>
425;;;; hello2.scm
426
427(print "Hello, ")
428(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))
429(print "!")
430</enscript>
431
432We also need a setup script:
433
434<enscript highlight=scheme>
435;;;; hello2.setup
436
437(compile hello2.scm)  ; compile `hello2'
438(install-program 'hello2 "hello2") ; name of the extension and files to be installed
439</enscript>
440
441<enscript highlight=scheme>
442;;;; hello2.meta
443
444((author "Me")
445 (synopsis "A cool hello-world application")
446 (license "proprietary"))
447</enscript>
448
449To use it, just run {{chicken-install}} in the same directory:
450
451 $ chicken-install
452
453(Here we omit the extension name)
454
455Now the program {{hello2}} will be installed in the same location as
456the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will
457normally be {{/usr/local/bin}}.  Note that you need write-permissions
458for those locations and may have to run {{chicken-install}} with
459administrative rights or use the {{-sudo}} option.
460
461The extension can be used from the command line:
462
463 $ hello2 one two three
464 Hello,
465 one two three !
466
467De-installation is just as easy - use the {{chicken-uninstall}}
468program to remove one or more extensions from the local repository:
469
470 $ chicken-uninstall hello2
471
472==== A module exporting syntax
473
474The hello module was just a shared library, and not a module.
475
476To create an extension that exports syntax see the chapter on
477[[http://wiki.call-cc.org/man/4/Modules%20and%20macros|Modules and
478macros]].  We will show a simple example here: a module {{my-lib}}
479that exports one macro ({{prog1}}) and one procedure ({{my-sum}}):
480
481<enscript highlight=scheme>
482;;; my-lib.scm
483
484(module my-lib
485  *
486  (import scheme chicken)
487
488(define-syntax prog1
489  (syntax-rules ()
490    ((_ e1 e2 ...)
491     (let ((result e1))
492       (begin e2 ...)
493       result))))
494
495(define my-sum
496  (lambda (numbers)
497    (prog1
498      (apply + numbers)
499      (display "my-sum used one more time!")
500      (newline))))
501
502)
503</enscript>
504
505The {{prog1}} macro is similar to Common Lisp's {{prog1}}: it
506evaluates a list of forms, but returns the value of the first form.
507
508The meta file:
509
510<enscript highlight=scheme>
511;;; my-lib.meta
512
513((licence "BSD")
514 (author "Me again")
515 (synopsis "My own cool libraries"))
516</enscript>
517
518The setup file is:
519
520<enscript highlight=scheme>
521;;; my-lib.setup
522
523(compile -s -O3 -d1 "my-lib.scm" -j my-lib)
524(compile -c -O3 -d1 "my-lib.scm" -unit my-lib)
525(compile -s -O3 -d0 "my-lib.import.scm")
526
527(install-extension
528 'my-lib
529 '("my-lib.o" "my-lib.so" "my-lib.import.so")
530 '((version 1.0)
531   (static "my-lib.o")))
532</enscript>
533
534The first line tells the compiler to create a shared ({{-s}}) library
535and to create an import file ({{my-lib.import.scm}}, because of the
536{{-j}} flag).  The second line creates a static library
537{{my-lib.o}}. The third line compiles the import file created by the
538first one.
539
540IMPORTANT: the module name exported by my-lib.scm must be the same
541module name passed to the compiler using the -j option, otherwise the
542imports file will not be generated!
543
544Running {{chicken-install}} on the same directory will install the extension.
545
546Next, it should be possible to load the library:
547
548 $ csi -q
549 #;1> (use my-lib)
550 ; loading /usr/local/lib/chicken/5/my-lib.import.so ...
551 ; loading /usr/local/lib/chicken/5/scheme.import.so ...
552 ; loading /usr/local/lib/chicken/5/chicken.import.so ...
553 ; loading /usr/local/lib/chicken/5/my-lib.so ...
554 #;2> (my-sum '(10 20 30))
555 my-sum used one more time!
556 60
557 #;3> (my-sum '(-1 1 0))
558 my-sum used one more time!
559 0
560 #;4> (prog1 (+ 2 2) (print "---"))
561 ---
562 4
563
564==== Notes on chicken-install
565
566When running {{chicken-install}} with an argument {{NAME}}, for which
567no associated {{.setup}} file exists, then it will try to download the
568extension via HTTP from the CHICKEN code repository at
569[[http://code.call-cc.org/svn/chicken-eggs/]]. Extensions that are
570required to compile and/or use the requested extension are downloaded
571and installed automatically.
572
573To query the list of currently installed extensions, use
574{{chicken-status}}. It can list what extensions are installed and
575what files belong to a particular installed extension.
576
577
578=== chicken-install reference
579
580Available options:
581
582; {{-h   -help}} : show this message and exit
583; {{-v   -version}} : show version and exit
584; {{-force}} : don't ask, install even if versions don't match
585; {{-k   -keep}} : keep temporary files
586; {{-l   -location LOCATION}} : install from given location instead of default
587; {{-t   -transport TRANSPORT}} : use given transport instead of default
588; {{-proxy HOST[:PORT]}} : connect via HTTP proxy
589; {{-s   -sudo}} : use {{sudo(1)}} for installing or removing files
590; {{-r   -retrieve}} : only retrieve egg into current directory, don't install
591; {{-n   -no-install}} : do not install, just build (implies {{-keep}})
592; {{-p   -prefix PREFIX}} : change installation prefix to {{PREFIX}}
593; {{-host}} : when cross-compiling, compile extension for host only
594; {{-target}} : when cross-compiling, compile extension for target only
595; {{-test}} : run included test-cases, if available
596; {{-username USER}} : set username for transports that require this
597; {{-password PASS}} : set password for transports that require this
598; {{-i   -init DIRECTORY}} : initialize empty alternative repository
599; {{-u   -update-db}} : update export database
600; {{-repository}} : print path to extension repository
601; {{-deploy}} : install extension in the application directory for a deployed application (see [[Deployment]] for more information)
602; {{-trunk}} : build trunk instead of tagged version (only local)
603; {{-D   -feature FEATURE}} : pass this on to subinvocations of {{csi}} and {{csc}} (when done via {{compile}} or {{(run (csc ...))}})
604; {{-debug}} : print full call-trace when encountering errors in the setup script
605; {{-keep-going}} : continue installation, even if a dependency fails
606
607{{chicken-install}} recognizes the {{http_proxy}} environment variable, if set.
608
609
610=== chicken-uninstall reference
611
612; {{-h   -help}} : show usage information and exit
613; {{-v   -version}} : show version and exit
614; {{-force}} : don't ask, delete whatever matches
615; {{-s   -sudo}} : use {{sudo(1)}} for deleting files
616; {{-host}} : when cross-compiling, remove extensions for host system only
617; {{-target}} : when cross-compiling, remove extensions for target system only
618; {{-exact}} : match extension-name exactly (do not match as pattern)
619
620=== chicken-status reference
621
622; {{-h   -help}} : show usage information and exit
623; {{-v   -version}} : show version and exit
624; {{-f   -files}} : list installed files
625; {{-host}} : when cross-compiling, show extensions for host system only
626; {{-target}} : when cross-compiling, show extensions for target system only
627; {{-exact}} : match extension-name exactly (do not match as pattern)
628
629
630=== Security
631
632When extensions are downloaded and installed one is executing code
633from potentially compromised systems. This applies also when
634{{chicken-install}} executes system tests for required extensions. As
635the code has been retrieved over the network effectively untrusted
636code is going to be evaluated. When {{chicken-install}} is run as
637''root'' the whole system is at the mercy of the build instructions
638(note that this is also the case every time you install software via
639{{sudo make install}}, so this is not specific to the CHICKEN
640extension mechanism).
641
642Security-conscious users should never run {{chicken-install}} as root.
643A simple remedy is to keep the repository inside a user's home
644directory (see the section "Changing repository location" below).
645Alternatively obtain write/execute access to the default location of the repository
646(usually {{/usr/local/lib/chicken}}) to avoid running as
647root. {{chicken-install}} also provides a {{-sudo}} option to perform
648the last installation steps as root user, but do building and other
649.setup script processing as normal. A third solution is to
650override {{VARDIR}} when building the system
651(for example by passing {{"VARDIR=/foo/bar"}} on the make command line,
652or by modifying {{config.make}}. Eggs will then be installed in
653{{$(VARDIR)/chicken/5}}.
654
655=== Changing repository location
656
657When Chicken is installed a repository for eggs is created and initialized
658in a default location (usually something like {{/usr/local/lib/chicken/5/}}).
659It is possible to keep an eggs repository in another location. This can be
660configured at build-time by passing {{VARDIR=<directory>}} to {{make(3)}}
661or by modifying the {{config.make}} configuration file. If you want to
662override this location after chicken is installed, you can create an
663initial repository directory with some default extensions and set the
664{{CHICKEN_REPOSITORY}} environment variable:
665
666First, initialize the new repository with
667
668  chicken-install -init ~/myeggs/lib/chicken/5
669
670Then set this environment variable:
671
672  export CHICKEN_REPOSITORY=~/myeggs/lib/chicken/5
673
674{{CHICKEN_REPOSITORY}} is the place where extensions are to be
675loaded from for all chicken-based programs (which includes all
676the tools).
677
678You can install eggs with
679
680  chicken-install -p ~/myeggs <package>
681
682See that the argument to chicken-install is just {{~/myeggs}}, while everywhere else it's
683{{~/myeggs/lib/chicken/5}}.
684
685When you load eggs from the interpreter, you will see messages showing
686where libraries are being loaded from:
687
688 #;1> (use numbers)
689 ; loading /home/jdoe/myeggs/lib/chicken/5/numbers.import.so ...
690 ; loading /home/jdoe/myeggs/lib/chicken/5/scheme.import.so ...
691 ; loading /home/jdoe/myeggs/lib/chicken/5/chicken.import.so ...
692 ; loading /home/jdoe/myeggs/lib/chicken/5/foreign.import.so ...
693 ; loading /home/jdoe/myeggs/lib/chicken/5/regex.import.so ...
694 ; loading /home/jdoe/myeggs/lib/chicken/5/numbers.so ...
695 #;2>
696
697=== Other modes of installation
698
699It is possible to install extensions directly from a
700[[http://subversion.apache.org/|Subversion]] repository or from a local
701checkout of the repository tree by using the {{-transport}} and
702{{-location}} options when invoking {{chicken-install}}. Three possible
703transport mechanisms are currently supported:
704
705; {{http}} : download extension sources via HTTP from a web-server (this is the default)
706; {{svn}} : perform an {{svn export}} from the central extension repository; this will require a {{svn(1)}} client to be installed on the machine
707; {{local}} : use sources from the local filesystem and build directly in the source directory
708
709The {{-location}} option specifies where to look for the source
710repository and names a web URL, a subversion repository URL or a
711filesystem path, respectively. A list of locations to try when
712retrieving extensions is stored in the file {{setup.defaults}}
713(usually installed in {{/usr/local/share/chicken}}). For {{http}}
714transports, {{chicken-install}} will detect networking timeouts and
715try alternative locations, as listed in the file.
716
717Dependency information, which is necessary to ensure required
718extensions are also installed, is processed automatically.
719
720=== Linking extensions statically
721
722The compiler and {{chicken-install}} support statically linked
723eggs. The general approach is to generate an object file or static
724library (in addition to the usual
725shared library) in your {{.setup}} script and install it along with the
726dynamically loadable extension. The setup properties {{static}}
727should contain the name of the object file (or static library) to be
728linked, when {{csc}} gets passed the {{-static-extension}} option:
729
730<enscript highlight=scheme>
731 (compile -s -O2 -d1 my-ext.scm)   ; dynamically loadable "normal" version
732 (compile -c -O2 -d1 my-ext -unit my-ext)  ; statically linkable version
733 (install-extension
734   'my-ext
735   '("my-ext.so" "my-ext.o")
736   '((static "my-ext.o")) )
737</enscript>
738
739Note the use of the {{-unit}} option in the second compilation step: static
740linking must use static library units. {{chicken-install}} will perform
741platform-dependent file-extension translation for the file list, but does currently
742not do that for the {{static}} extension property.
743
744To actually link with the static version of {{my-ext}}, do:
745
746 % csc -static-extension my-ext my-program.scm
747
748The compiler will try to do the right thing, but can not handle all
749extensions, since the ability to statically link eggs is relatively
750new. Eggs that support static linking are designated as being able to
751do so. If you require a statically linkable version of an egg that has
752not been converted yet, contact the extension author or the CHICKEN
753mailing list.
754
755---
756Previous: [[Interface to external functions and variables]]
757
758Next: [[Deployment]]
Note: See TracBrowser for help on using the repository browser.