source: project/wiki/chicken-setup @ 13186

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

Changes applied for mario (201.40.162.47) through svnwiki:

Typo fix.

File size: 26.3 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==== Installing extensions that use libraries
55
56Sometimes 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
60This 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
64Extensions can be created by creating an (optionally gzipped) {{tar}}
65archive named {{EXTENSION.egg}} containing all needed files plus a
66{{.setup}} script in the root directory.  After {{chicken-setup}} has
67extracted the files, the setup script will be invoked. There are no
68additional constraints on the structure of the archive, but the setup
69script 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
78Installs 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
80the extension id has to be identical to the name of the file implementing the extension. The
81extension may load or include other files, or may load other extensions at runtime specified
82by the {{require-at-runtime}} property.
83
84{{FILELIST}} may be a filename, a list of filenames, or a list of pairs of
85the form {{(SOURCE DEST)}} (if you want to copy into a particular sub-directory - the
86destination directory will be created as needed). If {{DEST}} is a relative pathname,
87< it will be copied into the extension repository.
88
89The optional argument {{INFOLIST}} should be an association list that
90maps symbols to values, this list will be stored as {{ID.setup-info}} at the same
91location as the extension code. Currently the following properties are used:
92
93===== syntax
94
95 [extension property] (syntax)
96
97Marks the extension as syntax-only. No code is compiled, the extension is intended
98as 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
104Specifies extensions that should be loaded (via {{require}}) at runtime. This is mostly
105useful for syntax extensions that need additional support code at runtime.
106
107===== version
108
109 [extension property] (version STRING)
110
111Specifies version string.
112
113===== documentation
114
115 [extension property] (documentation FILENAME)
116
117The filename of a HTML document containing extension-specific documentation.
118This file should be given in the file-list passed to {{install-extension}} and
119a 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
126Copies the given files into the examples directory, which is usually
127{{$prefix/share/chicken/examples}}
128or {{(make-pathname (chicken-home) "examples")}}).
129
130Note that the files listed in this property should not be listed in the normal
131list of files to install passed to {{install-extension}}. This is the only
132exception - other files that are installed in the repository must be given
133in the file list.
134
135===== exports
136
137 [extension property] (exports EXPORT ...)
138
139Add export-information to the generated extension-information. {{EXPORT}} may be
140a symbol naming an exported toplevel variable or a string designating a file with
141exported 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
148If the extension also provides a static library, then STRING should
149contain the name of that library. Used by {{csc}} when compiling with
150the {{-static-extensions}} option.
151
152===== static-options
153
154 [extension property] (static-options STRING)
155
156Additional options that should be passed to the linker when linking
157with the static version of an extension (see {{static}} above). Used
158by {{csc}} when compiling with the {{-static-extensions}} option.
159
160All other properties are currently ignored. The {{FILELIST}} argument may also be a single
161string.
162
163==== install-program
164
165 [procedure] (install-program ID FILELIST [INFOLIST])
166
167Similar to {{install-extension}}, but installs an executable program in the
168executable path (usually {{/usr/local/bin}}).
169
170==== install-script
171
172 [procedure] (install-script ID FILELIST [INFOLIST])
173
174Similar to {{install-program}}, but additionally changes the file permissions of all
175files in {{FILELIST}} to executable (for installing shell-scripts).
176
177
178==== run
179
180 [syntax] (run FORM ...)
181
182Runs 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
184to {{chicken-setup}}) and {{-feature compiling-extension}} options to the compiler.
185
186==== compile
187
188 [syntax] (compile FORM ...)
189
190Equivalent to {{(run (csc FORM ...))}}.
191
192==== make
193
194 [syntax] (make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)
195
196A ''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}}
198extension, 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
206Replaces all occurrences of the regular expression {{REGEX}} with the string {{SUBST}},
207in the file given in {{WHICH}}. If {{WHICH}} is a string, the file will be patched and
208overwritten. 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
215Copies the file or directory (recursively) given in the string {{FROM}} to the destination
216file or directory {{TO}}.
217
218==== move-file
219
220 [procedure] (move-file FROM TO)
221
222Moves the file or directory (recursively) given in the string {{FROM}} to the destination
223file or directory {{TO}}.
224
225==== remove-file*
226
227 [procedure] (remove-file* PATH)
228
229Removes the file or directory given in the string {{PATH}}.
230
231
232==== find-library
233
234 [procedure] (find-library NAME PROC)
235
236Returns {{#t}} if the library named {{libNAME.[a|so]}} (unix) or {{NAME.lib}} (windows)
237could be found by compiling and linking a test program. {{PROC}} should be the name of a
238C function that must be provided by the library. If no such library was found or the function could not
239be resolved, {{#f}} is returned.
240
241==== find-header
242
243 [procedure] (find-header NAME)
244
245Returns {{#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
251Returns {{#t}} if the C code in {{CODE}} compiles and links successfully, or {{#f}} otherwise.
252The keyword parameters {{cc}} (compiler name, defaults to the C compiler used to build this system),
253{{cflags}} and {{ldflags}} accept additional compilation and
254linking options. If {{compile-only}} is true, then no linking step takes place.
255If 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
262Creates the directory given in the string {{PATH}}, with all parent directories as needed.
263
264
265==== chicken-prefix
266
267 [parameter] chicken-prefix
268
269The installation prefix specified when CHICKEN was built.
270
271==== installation-prefix
272
273 [parameter] installation-prefix
274
275An alternative installation prefix that will be prepended to extension
276installation paths if specified. It is set by the {{-install-prefix}}
277option or environment variable {{CHICKEN_INSTALL_PREFIX}}.
278
279==== program-path
280
281 [parameter] (program-path [PATH])
282
283Holds the path where executables are installed and defaults to either {{$CHICKEN_PREFIX/bin}},
284if the environment variable {{CHICKEN_PREFIX}} is set or the
285path where the CHICKEN binaries ({{chicken}}, {{csi}}, etc.) are installed.
286
287
288==== setup-root-directory
289
290 [parameter] (setup-root-directory [PATH])
291
292Contains the path of the directory where {{chicken-setup}} was invoked.
293
294==== setup-build-directory
295
296 [parameter] (setup-build-directory [PATH])
297
298Contains the path of the directory where the extension is built. This is not necessarily identical
299to {{setup-root-directory}}.
300
301
302==== setup-verbose-flag
303
304 [parameter] (setup-verbose-flag [BOOL])
305
306Reflects the setting of the {{-verbose}} option, i.e. is {{#t}}, if {{-verbose}} was
307given.
308
309
310==== setup-install-flag
311
312 [parameter] (setup-install-flag [BOOL])
313
314Reflects the setting of the {{--no-install}} option, i.e. is {{#f}}, if {{-no-install}} was
315given.
316
317==== required-chicken-version
318
319 [procedure] (required-chicken-version VERSION)
320
321Signals 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
329Checks whether the extensions {{EXTENSION1 ...}} are installed and at least of version {{VERSION1 ...}}.
330The test is made by lexicographically comparing the string-representations of the given version with the version
331of the installed extension. If one of the listed extensions is not installed, has no associated version information
332or is of a version older than the one specified.
333
334
335==== cross-chicken
336
337 [procedure] (cross-chicken)
338
339Returns {{#t}} if this system is configured for cross-compilation or {{#f}}
340otherwise.
341
342
343==== host-extension
344
345 [parameter] host-extension
346
347For a cross-compiling CHICKEN, when compiling an extension, then it
348should be built for the host environment (as opposed to the target
349environment). This parameter is controlled by the {{-host-extension}} command-line
350option. A setup script should perform the proper steps of compiling any
351code by passing {{-host}} when invoking {{csc}} or using the {{compile}}
352macro.
353
354
355=== Examples for extensions
356
357The 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
366We 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
379After entering
380
381 $ chicken-setup hello
382
383at the shell prompt (and in the same directory where the two files
384exist), the file {{hello.scm}} will be compiled into a dynamically
385loadable library. If the compilation succeeds, {{hello.so}} will
386be stored in the repository, together with a file named
387{{hello.setup-info}} containing an a-list with metadata.
388If no extension name is given to {{chicken-setup}}, it will simply
389execute the first file with the {{.setup}} extension it can find.
390
391Use 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
400Here 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
410We 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
419To use it, just run {{chicken-setup}} in the same directory:
420
421 $ chicken-setup
422
423(Here we omit the extension name)
424
425Now the program {{hello2}} will be installed in the same location as
426the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will
427normally be {{/usr/local/bin}}.  Note that you need write-permissions
428for those locations and may have to run {{chicken-setup}} with
429administrative rights.
430
431Uninstallation is just as easy:
432
433 $ chicken-setup -uninstall hello2
434
435{{chicken-setup}} provides a {{make}} macro, so build operations can
436be of arbitrary complexity. When running {{chicken-setup}} with an
437argument {{NAME}}, for which no associated file {{NAME.setup}},
438{{NAME.egg}} or {{NAME.scm}} exists will ask you to download the
439extension via HTTP from the default URL
440[[http://www.call-with-current-continuation.org/eggs]]. You can use
441the {{-host}} option to specify an alternative source
442location. Extensions that are required to compile and/or use the
443requested extension are downloaded and installed automatically.
444
445If the given extension name contains a path prefix and the {{-host}}
446option is given, then {{chicken-setup}} can also download and install
447eggs from an arbitrary HTTP server. Alternatively you can pass a full
448URL (including the {{http://}} prefix. Note that no dependency checks
449are done when downloading eggs directly with the URL syntax.
450
451Finally a somewhat more complex example: We want to package a syntax
452extension with additional support code that is to be loaded at
453run-time of any Scheme code that uses that extension. We create a
454''glass'' lambda, a procedure with free variables that can be
455manipulated 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
482Here 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
494The 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
505The invocation of {{install-extension}} provides the files that are to
506be copied into the extension repository, and a metadata list that
507specifies that the extension {{glass}} is a syntax extension and that,
508if it is declared to be used by other code (either with the
509{{require-extension}} or {{require-for-syntax}} form), then client
510code should perform an implicit {{(require 'glass-support)}} at
511startup.
512
513This can be conveniently packaged as an ''egg'':
514
515 $ tar cfz glass.egg glass.setup glass.scm glass-support.scm
516
517And 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
530Available 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
564Note 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
570depends on the {{tar}} and {{gunzip}} tools to extract the contents of
571an egg. The best way is to download an egg either manually (or with
572{{chicken-setup -fetch}}) and extract its contents with a separate
573program (like {{winzip}}). The {{CHICKEN_REPOSITORY}} environment
574variable has to be set to a
575directory where your compiled extensions should be located.
576
577The {{.setup}} scripts will not always work under Windows, and the
578extensions may require libraries that are not provided for Windows or
579work differently. Under these circumstances it is recommended to
580perform the required steps to build an extension manually.
581
582The required UNIX tools are also available as Windows binaries.
583Google or ask on the CHICKEN mailing list if you need help locating
584them.
585
586
587=== Security
588
589When extensions are downloaded and installed one is executing code
590from potentially compromised systems. This applies also when {{chicken-setup}}
591executes system tests for required extensions. As the code has been
592retrieved over the network effectively untrusted code is going to be
593evaluated. When {{chicken-setup}} is run as ''root'' the whole system
594is at the mercy of the build instructions (note that this is also
595the case every time you install software via {{sudo make install}}, so this
596is not specific to the CHICKEN extension mechanism).
597
598Security-conscious users should never run {{chicken-setup}} as root.
599A simple remedy is to set the environment variable {{CHICKEN_REPOSITORY}},
600which will transparently place the repository at an arbitrary user-selected
601location. Alternatively obtain write/execute access to the default location
602of the repository (usually {{/usr/local/lib/chicken}}) to avoid running
603as root.
604
605
606=== Other modes of installation
607
608It is possible to install extensions directly from a
609[[http://subversion.tigris.org|Subversion]] repository or from a local
610checkout by using the {{-svn}} or {{-local}} options. By using
611either the {{svn}} client program (which must be installed) or
612file-system operations, all necessary files will be copied into the
613current directory (creating a subdirectory named
614{{EXTENSIONNAME.egg-dir}}), built and subsequently installed.
615
616Dependency information, which is necessary to ensure required
617extensions are also installed, is downloaded automatically.  If you
618have no internet connection or don't want to connect, you can also use
619a 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]],
622writing it to stdout. Redirecting this output into a file and passing
623the file via the {{-tree}} option to {{chicken-setup}} allows you now
624to use the local repository file:
625
626Retrieve complete extension repository (big):
627
628 % cd /opt
629 % svn co https://galinha.ucpel.tche.br/svn/chicken-eggs/release/3 eggs
630
631Get your own copy of the repository file:
632
633 % chicken-setup -fetch-tree >~/my-repository-file
634
635Now you can install eggs from your local checkout, with full
636dependency 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
644The compiler and [[chicken-setup]] support statically linked
645eggs. The general approach is to generate an object file or static
646library (in addition to the usual
647shared library) in your {{.setup}} script and install it along with the
648dynamically loadable extension. The setup properties {{static}}
649should contain the name of the object file (or static library) to be
650linked, 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
661Note the use of the {{-unit}} option in the second compilation step: static
662linking must use static library units. {{chicken-setup}} will perform
663platform-dependent file-extension translation for the file list, but does currently
664not do that for the {{static}} extension property.
665
666To actually link with the static version of {{my-ext}}, do:
667
668 % csc -static-extensions my-program.scm -uses my-ext
669
670The compiler will try to do the right thing, but can not handle all
671extensions, since the ability to statically link eggs is relatively
672new. Eggs that support static linking are designated as being able to
673do so. If you require a statically linkable version of an egg that has
674not been converted yet, contact the extension author or the CHICKEN
675mailing list.
676
677
678Previous: [[Interface to external functions and variables]]
679
680Next: [[Data representation]]
Note: See TracBrowser for help on using the repository browser.