source: project/wiki/man/5/Extensions @ 34778

Last change on this file since 34778 was 34778, checked in by sjamaan, 3 years ago

man/5: Update Extensions with latest changes

File size: 27.5 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Eggs
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
17On systems where dynamic loading is not available, extensions can
18still be built and linked as static object files.
19
20Note: eggs may also be normal applications or shell scripts, but
21are usually libraries.
22
23Extensions are technically nothing but dynamically loadable compiled
24files with added meta-data that describes dependencies to other
25eggs, version information and things like the author/maintainer
26of the egg. Three tools provide an easy to use interface for
27installing eggs, removing them and querying the current
28status of installed eggs.
29
30
31=== Installing eggs
32
33To install an egg, run the {{chicken-install}} program
34with the egg name as argument. The egg archive is
35downloaded, its contents extracted and the contained egg description
36file is analyzed and the appropriate commands executed.
37This file is an abstract description of the contents of
38the egg and
39will be translated by {{chicken-install}} into build- and installation
40scripts for the current platform. After running these scripts (and
41if all goes well), the egg is installed and will be available
42like a built-in library. The format and meaning
43of the file will be described below.
44
45Installation will copy
46a number of given files into the local egg repository or in the
47path where the CHICKEN executables are located (in the case of
48executable programs or scripts). Additionally the list of installed
49files, and user-defined metadata is stored in the repository.
50
51If no egg name is given on the command-line, then all {{.egg}}
52files in the current directory are processed, including all {{.egg}}
53files in a subdirectory {{chicken}} (if such a directory exists),
54in some arbitrary
55order, unless the egg descriptions specify dependencies.
56
57==== Installing eggs that use libraries
58
59Sometimes an egg requires a C library to compile. Compilation
60can fail when your system has this library in a nonstandard
61location. Normally the C compiler searches in the default locations
62{{/usr}} and {{/usr/local}}, and in the prefix where CHICKEN itself
63was installed. Sometimes this is not enough, so you'll need to supply
64{{chicken-install}} with some extra hints to the C compiler/linker. Here's
65an example:
66
67  CSC_OPTIONS='-I/usr/pkg/include/mysql -L/usr/pkg/lib/mysql -L -R/usr/pkg/lib/mysql' chicken-install mysql
68
69This installs the mysql egg with the extra compiler options -I and -L
70to set the include path and the library search path. The second -L
71switch passes the -R option directly to the linker, which causes the
72library path to get hardcoded into the resulting extension file (for
73systems that do not use {{ld.so.conf}}).
74
75The environment variables {{CHICKEN_C_INCLUDE_PATH}} and {{CHICKEN_C_LIBRARY_PATH}}
76can also be used to override include- and linker-paths. Each of these variables
77may contain one or more directory names, separated by {{:}} or {{;}} and will
78be passed using {{-I}} and {{-L}} to the C compiler.
79
80=== Creating eggs
81
82An egg can be created by placing its code and some special
83files in a directory named after the desired name of the egg.
84For example, if your
85egg is called {{foo}}, create a directory called {{foo}}
86and put the egg code there.
87
88Eggs need an egg description file {{<egg name>.egg}}.
89This file indicates how
90the egg is to be compiled and provides some information
91about the egg (author, license, dependencies etc).
92
93=== Format of the egg description file
94
95An egg description is basically an association list holding
96information about the components of the egg. An egg may contain
97multiple components: libraries, programs, Scheme or C include files
98and arbitrary data files. Dependencies between eggs can be
99specified as can be dependencies between components of an egg.
100
101A list of valid properties follows.
102
103==== Global properties
104
105===== version
106
107[egg property] (version STRING)
108
109Specifies version string for this egg. {{STRING}} should have
110the format {{<MAJOR>.<MINOR>.<PATCHLEVEL>}}, where only the
111{{<MAJOR>}} part is mandatory.
112
113Eggs from remote egg servers are automatically versioned - the
114version is part of the protocol to retrieve the egg and does not
115have to be specified in the {{.egg}} file. Eggs installed from
116local directories (see below) should explicitly specify a version.
117
118===== synopsis
119
120[egg property] (synopsis STRING)
121
122Gives a short description of this egg.
123
124===== author
125
126[egg property] (author STRING)
127
128Names the author or authors of the contained code.
129
130===== maintainer
131
132[egg property] (maintainer STRING)
133
134Names the maintainer of this code, if different from author(s).
135
136===== category
137
138[egg property] (category NAME)
139
140Gives the category under which this egg should be contained.
141See [[/chicken-projects/egg-index-5.html|the egg index]]
142for a list of currently used categories.
143
144===== license
145
146[egg property] (license STRING)
147
148Names the license under which this code is available.
149
150===== dependencies
151
152[egg property] (dependencies EGG ...)
153
154Lists eggs that this egg depends on, and which should be
155built and installed if they do not already exist in the repository.
156{{EGG}} should be whether a symbol or a list of the form
157{{EGGNAME VERSION}}, where the former means to install the
158newest available egg with this name and the latter specifies
159a specific version or higher.
160
161Note that this property
162has a different meaning depending on whether it appears at
163toplevel in an egg description or inside a component.
164
165====== test-dependencies
166
167[egg property] (test-dependencies EGG ...)
168
169Lists eggs that are required for this egg to run the tests
170(if tests exist.) This only has an effect if the {{-test}}
171option has been given to {{chicken-install}}.
172
173====== build-dependencies
174
175[egg property] (build-dependencies EGG ...)
176
177Lists eggs that are build-time dependencies for this egg,
178i.e. there are required to build, but not to run the contained
179code. Currently this is treated identical to {{dependencies}}.
180
181====== foreign-dependencies
182
183[egg property] (foreign-dependencies NAME ...)
184
185Lists external dependencies like native code libraries
186or system-specific packages and is currently only used for
187documentation purposes.
188
189====== platform
190
191[egg property] (platform PLATFORM)
192
193Specifies for which platform this egg is intended. {{PLATFORM}}
194should be a symbol naming the target platform ({{windows}}, {{linux}}
195or {{unix}}) or a boolean combination of platform values, allowed
196are {{(not PLATFORM)}}, {{(or PLATFORM ...)}} and {{(and PLATFORM ...)}}.
197If the expression can not be satisfied, then installation of this
198egg will abort.
199
200====== components
201
202[egg property] (components COMPONENT ...)
203
204Lists components (extensions, programs, include- or data files)
205that this extension installs. See below for information on how
206to specify component-specific information.
207
208====== host
209
210[egg property] (host PROP ...)
211
212Recursively process {{PROP ...}}, but only for the host (build)
213platform, in case this is a "cross-chicken", a CHICKEN installation
214intended for cross compilation.
215
216====== target
217
218[egg property] (target PROP ...)
219
220Recursively process {{PROP ...}}, but only for the target
221platform, in case this is a "cross-chicken", a CHICKEN installation
222intended for cross compilation.
223
224===== Components
225
226====== extension
227
228[egg property] (extension NAME PROP ...)
229
230Specifies an extension library component. The properties
231{{PROP...}} are processed recursively and apply only to this
232component.
233
234====== data
235
236[egg property] (data NAME PROP ...)
237
238Specifies one or more arbitrary data files.
239
240====== generated-source-file
241
242[egg property] (generated-source-file NAME PROP ...)
243
244Specifies a file that is generated during the process of building
245the egg.
246
247====== c-include
248
249[egg property] (c-include NAME PROP ...)
250
251Specifies one or more C include files.
252
253====== scheme-include
254
255[egg property] (scheme-include NAME PROP ...)
256
257Specifies one or more Scheme include files.
258
259====== program
260
261[egg property] (program NAME PROP ...)
262
263Specifies an executable program.
264
265===== Component properties
266
267====== host
268
269[egg property] (host PROP ...)
270
271Process {{PROP ...}} recursively for the current component, but
272apply the properties only to the host (build) part, when using
273a CHICKEN installation intended for cross-compilation.
274
275====== target
276
277[egg property] (target PROP ...)
278
279Process {{PROP ...}} recursively for the current component, but
280apply the properties only to the target part, when using
281a CHICKEN installation intended for cross-compilation.
282
283====== linkage
284
285[egg property] (linkage LINKAGE)
286
287Define whether the component should be linked dynamically or
288statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This
289property only makes sense for extension libraries.
290
291====== types-file
292
293[egg property] (types-file [NAME])
294
295Specifies that a "type-database" file should be generated and
296installed for this component. This property is only used for
297extension libraries. The name is optional and defaults to the
298name of the extensions (with the proper extension).
299
300If {{NAME}} is a list of the form {{(predefined [NAME])}}, then
301no types file is created during compilation and an existing types file
302for this extension is assumed and installed.
303
304====== inline-file
305
306[egg property] (inline-file [NAME])
307
308Specifies that an "inline" file should be generated and installed
309for this component. This property is only used for extension
310libraries. The name is optional and defaults to the
311name of the extensions (with the proper extension).
312
313====== custom-build
314
315[egg property] (custom-build STRING)
316
317Specifies a custom build operation that should be executed
318instead of the default build operations. This property is mandatory
319for components of type {{generated-source-file}}. {{STRING}}
320usually contains a shell command and thus may be platform sensitive.
321
322====== csc-options
323
324[egg property] (csc-options OPTION ...)
325
326Specifies additional compiler options for {{csc}} that should be
327used when building this component. If this property is not
328given, the default options are used, which are {{-O2 -d1}}
329for extensions and programs and {{-O2 -d0}} for import
330libraries.
331
332====== link-options
333
334[egg property] (link-options OPTION ...)
335
336Specifies additional link options for {{csc}} that should be
337used when building this component.
338
339====== modules
340
341[egg property] (modules [MODULE ...])
342
343Specifies the modules that the extension component generates.  If this
344property is not specified, chicken-install assumes that a single
345module named after the extension file name will be emitted.
346
347This property can be used to specify that the extension doesn't
348generate any module (in this case {{(modules)}} should be used); or to
349specify the module names that the extension generates (a list of
350symbols).
351
352====== source
353
354[egg property] (source NAME)
355
356Specifies an alternative source file, in case it has a name
357distinct from the component name. By default the source file
358for a component is named after the component, with the {{.scm}}
359extension added.
360
361====== install-name
362
363[egg property] (install-name NAME)
364
365Specifies an alternative installation name of the component,
366if it differs from the actual component name. This property
367is most useful if an egg installs an extension and a program
368of the same name, but needs to distinguish the components during
369build time.
370
371====== dependencies
372
373[egg property] (dependencies NAME ...)
374
375Specifies dependencies between components. Note that this use
376of the {{dependencies}} property is different from the property
377of the same name that is used at the "global" level of the
378egg description file.
379
380====== destination
381
382[egg property] (destination NAME)
383
384Specifies an alternative installation destination for the
385built component and only applies
386to components of type {{data}}, {{c-include}} and {{scheme-include}}.
387This property should only be used in extreme
388cases, as it is recommended to use the default installation
389locations, which are:
390
391* for C include files: {{<PREFIX>/include/chicken/}}
392
393* for Scheme include files: {{<PREFIX>/share/chicken/}}
394
395* for data files: {{<PREFIX>/share/chicken/}}
396
397====== files
398
399[egg property] (files NAME ...)
400
401Specifies source files for this component and only applies
402to components of type {{data}}, {{c-include}} and {{scheme-include}}.
403
404=== Examples for extensions
405
406==== A simple library
407
408The simplest case is a single file that does not export any syntax.
409For example
410
411<enscript highlight=scheme>
412;;;; hello.scm
413
414(define (hello name)
415  (print "Hello, " name " !") )
416</enscript>
417
418We need an {{.egg}} file to build and install our nifty extension:
419
420<enscript highlight=scheme>
421;;;; hello.egg
422
423((author "Me")
424 (synopsis "A cool hello-world library")
425 (license "GPLv3")
426 (components (extension hello)))
427</enscript>
428
429After entering
430
431 $ chicken-install
432
433at the shell prompt (and in the same directory where the two files
434exist), the file {{hello.scm}} will be compiled into a dynamically
435loadable library and a statically linkable object.
436If the compilation succeeds, {{hello.so}} and {{hello.o}} will
437be stored in the repository, together with a file named
438{{hello.egg-info}} containing an a-list with metadata (what
439you stored above in {{hello.egg}} plus some additional metadata).
440If no extension name is given to {{chicken-install}}, it will simply
441process the any files with the {{.egg}} extension it can find.
442
443Use it like any other CHICKEN extension:
444
445 $ csi -q
446 #;1> (require-library hello)
447 ; loading /usr/local/lib/chicken/8/hello.so ...
448 #;2> (hello "me")
449 Hello, me!
450 #;3>
451
452==== An application
453
454Here we create a simple application:
455
456<enscript highlight=scheme>
457;;;; hello2.scm
458
459(print "Hello, ")
460(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))
461(print "!")
462</enscript>
463
464We also need an egg file:
465
466;;;; hello2.egg
467
468<enscript highlight=scheme>
469((author "Me")
470 (synopsis "A cool hello-world application")
471 (license "proprietary")
472 (components (program hello2)))
473</enscript>
474
475To use it, just run {{chicken-install}} in the same directory:
476
477 $ chicken-install
478
479(Here we omit the extension name)
480
481Now the program {{hello2}} will be installed in the same location as
482the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will
483normally be {{/usr/local/bin}}.  Note that you need write-permissions
484for those locations and may have to run {{chicken-install}} with
485administrative rights or use the {{-sudo}} option.
486
487The extension can be used from the command line:
488
489 $ hello2 one two three
490 Hello,
491 one two three !
492
493De-installation is just as easy - use the {{chicken-uninstall}}
494program to remove one or more extensions from the local repository:
495
496 $ chicken-uninstall hello2
497
498==== A module exporting syntax
499
500The hello module was just a shared library, and not a module.
501
502To create an extension that exports syntax see the chapter on
503[[Modules]].  We will show a simple example here: a module {{my-lib}}
504that exports one macro ({{prog1}}) and one procedure ({{my-sum}}):
505
506<enscript highlight=scheme>
507;;; my-lib.scm
508
509(module my-lib
510  *
511  (import scheme chicken)
512
513(define-syntax prog1
514  (syntax-rules ()
515    ((_ e1 e2 ...)
516     (let ((result e1))
517       (begin e2 ...)
518       result))))
519
520(define my-sum
521  (lambda (numbers)
522    (prog1
523      (apply + numbers)
524      (display "my-sum used one more time!")
525      (newline))))
526
527)
528</enscript>
529
530The {{prog1}} macro is similar to Common Lisp's {{prog1}}: it
531evaluates a list of forms, but returns the value of the first form.
532
533The egg file:
534
535<enscript highlight=scheme>
536;;; my-lib.egg
537
538((components (extension my-lib))
539 (version 1.0)
540 (licence "BSD")
541 (author "Me again")
542 (synopsis "My own cool libraries"))
543</enscript>
544
545Running {{chicken-install}} on the same directory will install the extension.
546
547Next, it should be possible to load the library:
548
549 $ csi -q
550 #;1> (import my-lib)
551 ; loading /usr/local/lib/chicken/6/my-lib.import.so ...
552 ; loading /usr/local/lib/chicken/6/scheme.import.so ...
553 ; loading /usr/local/lib/chicken/6/chicken.import.so ...
554 ; loading /usr/local/lib/chicken/6/my-lib.so ...
555 #;2> (my-sum '(10 20 30))
556 my-sum used one more time!
557 60
558 #;3> (my-sum '(-1 1 0))
559 my-sum used one more time!
560 0
561 #;4> (prog1 (+ 2 2) (print "---"))
562 ---
563 4
564
565==== Notes on chicken-install
566
567When running {{chicken-install}} with an argument {{NAME}}, for which
568no associated {{.egg}} file exists, then it will try to download the
569extension via HTTP from the CHICKEN code repository at
570[[http://code.call-cc.org/svn/chicken-eggs/]]. Extensions that are
571required to compile and/or use the requested extension are downloaded
572and installed automatically.
573
574To query the list of currently installed extensions, use
575{{chicken-status}}. It can list what extensions are installed and
576what files belong to a particular installed extension.
577
578
579=== chicken-install reference
580
581Available options:
582
583; {{-h   -help}} : show this message and exit
584; {{-version}} : show version and exit
585; {{-force}} : don't ask, install even if versions don't match
586; {{-k   -keep}} : keep temporary files
587; {{-s   -sudo}} : use external command to elevate privileges when installing or removing files
588; {{-no-install-deps}} : do not install dependencies
589; {{-r   -retrieve}} : only retrieve egg into current directory, don't install (giving -r more than once implies {{-recursive}})
590; {{-recursive}} : if {{-retrieve}} is given, retrieve also dependencies
591; {{-dry-run}} :  do not build or install, just print the locations of the generated build + install scripts
592; {{-list-versions}} : list available version for an extension (HTTP transport only)
593; {{-n   -no-install}} : do not install, only build the egg.
594; {{-purge}} : remove cached files for given eggs (or purge cache completely)
595; {{-host}} : when cross-compiling, compile egg for host only
596; {{-target}} : when cross-compiling, compile egg for target only
597; {{-test}} : run included test-cases, if available
598; {{-u   -update-db}} : update export database
599; {{-repository}} : print path to egg repository
600; {{-override FILENAME}} : override versions for installed eggs with information given in {{FILENAME}}, which can be generated by {{-scan}} or by the {{-list}} option of the {{chicken-status}} program
601: {{-from-list FILENAME}} : install eggs given in {{FILENAME}}, in the same format as produced by the {{-list}} option in {{chicken-status}}; this option may be given multiple times
602; {{-v   -verbose}} : be verbose
603
604{{chicken-install}} recognizes the {{SUDO}}, {{http_proxy}} and {{proxy_auth}} environment variables, if set.
605
606
607=== chicken-uninstall reference
608
609; {{-h   -help}} : show usage information and exit
610; {{-version}} : show version and exit
611; {{-force}} : don't ask, delete whatever matches
612; {{-match}} : treat egg-names as glob patterns
613; {{-s   -sudo}} : use external command to elevate privileges for deleting files
614; {{-host}} : when cross-compiling, remove eggs for host system only
615; {{-target}} : when cross-compiling, remove eggs for target system only
616
617=== chicken-status reference
618
619; {{-h   -help}} : show usage information and exit
620; {{-version}} : show version and exit
621; {{-f   -files}} : list installed files
622; {{-match}} : treat egg-names as glob patterns
623; {{-host}} : when cross-compiling, show eggs for host system only
624; {{-target}} : when cross-compiling, show eggs for target system only
625; {{-list}} : list installed egg version in format suitable for {{chicken-install -override}} or {{-from-list}}
626; {{-c   -components}} : list installed components
627
628
629=== Security
630
631When eggs are downloaded and installed one is executing code
632from potentially compromised systems. This applies also when
633{{chicken-install}} executes system tests for required eggs. As
634the code has been retrieved over the network effectively untrusted
635code is going to be evaluated. When {{chicken-install}} is run as
636''root'' the whole system is at the mercy of the build instructions
637(note that this is also the case every time you install software via
638{{sudo make install}}, so this is not specific to the CHICKEN
639egg mechanism).
640
641Security-conscious users should never run {{chicken-install}} as root.
642A simple remedy is to keep the repository inside a user's home
643directory (see the section "Changing repository location" below).
644Alternatively obtain write/execute access to the default location of the repository
645(usually {{/usr/local/lib/chicken}}) to avoid running as
646root. {{chicken-install}} also provides a {{-sudo}} option to perform
647the last installation steps as root user, but do building and other
648.setup script processing as normal. A third solution is to
649override {{VARDIR}} when building the system
650(for example by passing {{"VARDIR=/foo/bar"}} on the make command line,
651or by modifying {{config.make}}. Eggs will then be installed in
652{{$(VARDIR)/chicken/8}}.
653
654=== Changing the repository location
655
656When CHICKEN is installed a repository for eggs is created and initialized
657in a default location (usually something like {{/usr/local/lib/chicken/6/}}).
658It is possible to keep an egg repository in another location. This can be
659configured at build-time by passing {{VARDIR=<directory>}} to {{make(3)}}
660or by modifying the {{config.make}} configuration file. If you want to
661override this location after chicken is installed, you can create a
662repository directory, set the
663{{CHICKEN_INSTALL_REPOSITORY}} and/or {{CHICKEN_REPOSITORY_PATH}}
664environment variables and copy all files
665from the default repository into the new one.
666
667Note that your binary version can differ from the one given in
668the examples here, if your
669chicken version is older or newer than the one used in these examples.
670Check your default location for the correct binary-version number.
671
672{{CHICKEN_REPOSITORY_PATH}} is the place where eggs are to be
673loaded from for all chicken-based programs. {{CHICKEN_INSTALL_REPOSITORY}}
674is the place where eggs will be installed and which the egg-related
675tools like {{chicken-install}}, {{chicken-uninstall}} and
676{{chicken-status}} consult and update.
677
678
679=== Static linking
680
681Static linking of extensions and programs is fully supported and
682should be transparent to the user. Every extension will by
683default be compiled into a dynamically loadable and a statically
684linkable entity. By passing {{-static}} on the {{csc}} command-line,
685eggs that are available in static form will be linked instead of
686the dynamically loadable version. Use the {{linkage}} egg
687description property to select in what modes a component should
688be built.
689
690To identify the necessary object files during linking of
691extensions, {{csc}}
692creates so-called "link files" and installs them along the
693statically compiled object file in the local egg repository.
694These link files specify what objects should be linked when
695an application is using a static variant of an extension.
696
697
698=== Locations
699
700For experimentation or in-house builds of software it may be
701useful to have private egg repositories in addition to the
702official CHICKEN egg repository. This can be accomplished by
703defining so-called "locations", directories that contain egg
704source-code and description files and which should be scanned
705before trying to retrieve an egg via the network.
706
707The file {{<PREFIX>/share/chicken/setup.defaults}} holds various
708parameters that define where eggs should be downloaded, together
709with more obscure options, and can be used to customize the
710sources where eggs will be retrieved from. Adding a line of
711the form
712
713{{(location "<PATH>")}}
714
715will add {{<PATH>}} as an additional egg source, where {{<PATH>}}
716should be a directory in the local filesystem that contains
717any number of eggs, one directory for each, including the source code
718and the {{.egg}} files for each egg.
719
720Locations are searched before trying to retrieve from the network.
721Any number of locations may be defined.
722
723
724=== The egg cache
725
726Eggs are downloaded and built in the so called "egg cache", an
727intermediate location used for storing already downloaded source code
728and for providing a temporary location for building the eggs before
729they are installed.
730
731By default the cache is located in the directory
732{{.chicken-install.cache}} is the user's home directory ({{$HOME}} on
733UNIX, or {{%USERPROFILE%}} on Windows. If the respective environment
734variable is not set, then {{/tmp}} or {{/Temp}} is used.
735
736Built extensions and programs remain in the cache, to avoid rebuilding
737already compiled code and multiple downloads of eggs in case the
738installation of an egg fails - the dependencies will be cached after
739the first download and re-download is not needed.
740
741{{chicken-install}} tries to take extreme care to avoid stale binaries,
742but should you be in doubt, simply delete the directory, or run
743{{chicken-install -purge}} to clear the cache or parts of it.
744
745You can override the location of the cache by setting the
746{{CHICKEN_EGG_CACHE}} environment variable.
747
748
749=== Egg installation in detail
750
751==== Retrieval
752
753First the egg names given on the command line (or, if no arguments
754are given, all eggs identified by {{.egg}} files in the current
755directory, including any in a subdirectory named {{chicken}})
756must be retrieved, either from a local source or from the official
757egg repository. Should the egg exist in the egg cache we check
758whether this cached version is out of date. A cached egg is
759considered out of date, if a) it is locally available and all cached
760files belonging to the egg do not have newer timestamps than the
761local files, or b) if it is a remotely retrieved egg and no
762newer versions exist on the remote egg server and the last time
763the cache was filled from the remote location is not later than
764one hour. Additionally, if any changes in certain environment
765variables that may influence the compilation of an egg, or if
766the CHICKEN version changed, then retrieval of the egg sources
767is enforced in any case.
768
769If the egg is in the current directory, or in
770a "location" (as described above), the files are copied into
771the cache. If the egg is remotely available, then it is retrieved
772via HTTP from one of the egg servers defined in {{setup.defaults}}.
773
774Once the egg sources are retrieved and stored in the cache,
775their {{.egg}} files are loaded and validated. After this
776any egg dependencies are resolved and located in the cache,
777triggering a recursive retrieval, if necessary.
778
779==== Preparation
780
781Unless the {{-retrieve}} option was given, the eggs intended
782to be built and installed are now scheduled for compilation.
783The egg information from the {{.egg}} files is processed and
784translated into build and install scripts for the current
785platform - if this CHICKEN was configured for cross compilation,
786and no separate host- or target-build was selected, two sets
787of build/install scripts will be generated, one for the host
788system and one for the target.
789
790==== Building and installation
791
792Unless {{-dry-run}} was given on the command-line, the build-
793and install scripts are now executed, ordered by the dependency
794relationships between the full set of eggs that are scheduled
795for compilation. If the {{-test}} option was given and a file named
796{{run.scm}} exists in the {{tests}} subdirectory of the egg
797sources, then this script is executed. Should it terminate with
798an error or a non-zero exit code, the installation is still performed
799and {{chicken-install}} does not abort. Only after all scheduled
800eggs have been installed, {{chicken-install}} will terminate
801with a non-zero exit code.
802
803Note that the build process attempts to minimize re-building
804of already compiled files in the cache, using the {{chicken-do}}
805program. See the manual page for {{chicken-do}} for more details.
806
807From the egg-information in the {{.egg}} file, the set of files
808installed for a particular egg are added to the egg-information
809and stored together with the build-artifacts produced by the
810build scripts.
811
812---
813Previous: [[Interface to external functions and variables]]
814
815Next: [[Bugs and limitations]]
Note: See TracBrowser for help on using the repository browser.