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

Last change on this file since 34915 was 34915, checked in by sjamaan, 4 years ago

man/5: Update "Extensions" section to current chicken-5 branch version

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