source: project/wiki/man/5/Extension tools @ 36689

Last change on this file since 36689 was 36689, checked in by sjamaan, 5 weeks ago

Sync manual to wiki

File size: 12.5 KB
1[[tags: manual]]
4== Extension tools
6The basic tools to install, uninstall and view "eggs" and the extensions
7are {{chicken-install}}, {{chicken-uninstall}} and {{chicken-status}}.
9{{chicken-install}} can be used in two modes: first, as a simple package
10manager that downloads publicly available eggs (and their dependencies, if
11necessary) and compiles the contained extensions, installing them on
12a user's system.
14For development of eggs, {{chicken-install}} can also be invoked
15without arguments, in a directory that contains an egg specification
16file and the associated source code, building all components and
17installing them.
19{{chicken-status}} simply lists installed eggs, the contained extensions,
20and optionally the files that where installed with a particular egg.
22Below you will find a description of the available command line options
23for all three programs. A specification of the egg description file
24format is [[Egg specification format|here]].
26=== Security
28When eggs are downloaded and installed one is executing code
29from potentially compromised systems. This applies also when
30{{chicken-install}} executes system tests for required eggs. As
31the code has been retrieved over the network effectively untrusted
32code is going to be evaluated. When {{chicken-install}} is run as
33''root'' the whole system is at the mercy of the build instructions
34(note that this is also the case every time you install software via
35{{sudo make install}}, so this is not specific to the CHICKEN
36egg mechanism).
38Security-conscious users should never run {{chicken-install}} as root.
39A simple remedy is to keep the repository inside a user's home
40directory (see the section "Changing repository location" below).
41Alternatively obtain write/execute access to the default location of the repository
42(usually {{/usr/local/lib/chicken}}) to avoid running as
43root. {{chicken-install}} also provides a {{-sudo}} option to perform
44the last installation steps as root user, but do building and other
45.setup script processing as normal. A third solution is to
46override {{VARDIR}} when building the system
47(for example by passing {{"VARDIR=/foo/bar"}} on the make command line,
48or by modifying {{config.make}}. Eggs will then be installed in
51=== Changing the repository location
53When CHICKEN is installed a repository for eggs is created and initialized
54in a default location (usually something like {{/usr/local/lib/chicken/9/}}).
55It is possible to keep an egg repository in another location. This can be
56configured at build-time by passing {{VARDIR=<directory>}} to {{make(3)}}
57or by modifying the {{config.make}} configuration file. If you want to
58override this location after chicken is installed, you can create a
59repository directory, set the
61environment variables to the full path of the new reopsitory and copy all files
62from the default repository into the new one.
64Note that your binary version can differ from the one given in
65the examples here, if your
66chicken version is older or newer than the one used in these examples.
67Check your default location for the correct binary-version number.
69{{CHICKEN_REPOSITORY_PATH}} is a directory (or a list of directories
70separated by {{:}}/{{;}}) where eggs are to be
71loaded from for all chicken-based programs. {{CHICKEN_INSTALL_REPOSITORY}}
72is the place where eggs will be installed and which the egg-related
73tools like {{chicken-install}}, {{chicken-uninstall}} and
74{{chicken-status}} consult and update. Make sure the paths given in these
75environment variables are absolute and not relative.
77=== Static linking
79Static linking of extensions and programs is fully supported and
80should be transparent to the user. Every extension will by
81default be compiled into a dynamically loadable and a statically
82linkable entity. By passing {{-static}} on the {{csc}} command-line,
83eggs that are available in static form will be linked instead of
84the dynamically loadable version. Use the {{linkage}} egg
85description property to select in what modes a component should
86be built.
88To identify the necessary object files during linking of
89extensions, {{csc}}
90creates so-called "link files" and installs them along the
91statically compiled object file in the local egg repository.
92These link files specify what objects should be linked when
93an application is using a static variant of an extension.
96=== Locations
98For experimentation or in-house builds of software it may be
99useful to have private egg repositories in addition to the
100official CHICKEN egg repository. This can be accomplished by
101defining so-called "locations", directories that contain egg
102source-code and description files and which should be scanned
103before trying to retrieve an egg via the network.
105The file {{<PREFIX>/share/chicken/setup.defaults}} holds various
106parameters that define where eggs should be downloaded, together
107with more obscure options, and can be used to customize the
108sources where eggs will be retrieved from. Adding a line of
109the form
111{{(location "<PATH>")}}
113will add {{<PATH>}} as an additional egg source, where {{<PATH>}}
114should be a directory in the local filesystem that contains
115any number of eggs, one directory for each, including the source code
116and the {{.egg}} files for each egg.
118Locations are searched before trying to retrieve from the network.
119Any number of locations may be defined.
122=== The egg cache
124Eggs are downloaded and built in the so called "egg cache", an
125intermediate location used for storing already downloaded source code
126and for providing a temporary location for building the eggs before
127they are installed.
129By default the cache is located in the directory
130{{.chicken-install.cache}} is the user's home directory ({{$HOME}} on
131UNIX, or {{%USERPROFILE%}} on Windows. If the respective environment
132variable is not set, then {{/tmp}} or {{/Temp}} is used.
134Built extensions and programs remain in the cache, to avoid rebuilding
135already compiled code and multiple downloads of eggs in case the
136installation of an egg fails - the dependencies will be cached after
137the first download and re-download is not needed.
139{{chicken-install}} tries to take extreme care to avoid stale binaries,
140but should you be in doubt, simply delete the directory, or run
141{{chicken-install -purge}} to clear the cache or parts of it.
143You can override the location of the cache by setting the
144{{CHICKEN_EGG_CACHE}} environment variable.
147=== Egg installation in detail
149==== Retrieval
151First the egg names given on the command line (or, if no arguments
152are given, all eggs identified by {{.egg}} files in the current
153directory, including any in a subdirectory named {{chicken}})
154must be retrieved, either from a local source or from the official
155egg repository. Should the egg exist in the egg cache we check
156whether this cached version is out of date. A cached egg is
157considered out of date, if a) it is locally available and all cached
158files belonging to the egg do not have newer timestamps than the
159local files, or b) if it is a remotely retrieved egg and no
160newer versions exist on the remote egg server and the last time
161the cache was filled from the remote location is not later than
162one hour. Additionally, if any changes in certain environment
163variables that may influence the compilation of an egg, or if
164the CHICKEN version changed, then retrieval of the egg sources
165is enforced in any case.
167If the egg is in the current directory, or in
168a "location" (as described above), the files are copied into
169the cache. If the egg is remotely available, then it is retrieved
170via HTTP from one of the egg servers defined in {{setup.defaults}}.
172Once the egg sources are retrieved and stored in the cache,
173their {{.egg}} files are loaded and validated. After this
174any egg dependencies are resolved and located in the cache,
175triggering a recursive retrieval, if necessary.
177==== Preparation
179Unless the {{-retrieve}} option was given, the eggs intended
180to be built and installed are now scheduled for compilation.
181The egg information from the {{.egg}} files is processed and
182translated into build and install scripts for the current
183platform - if this CHICKEN was configured for cross compilation,
184and no separate host- or target-build was selected, two sets
185of build/install scripts will be generated, one for the host
186system and one for the target.
188==== Building and installation
190Unless {{-dry-run}} was given on the command-line, the build-
191and install scripts are now executed, ordered by the dependency
192relationships between the full set of eggs that are scheduled
193for compilation. If the {{-test}} option was given and a file named
194{{run.scm}} exists in the {{tests}} subdirectory of the egg
195sources, then this script is executed. Should it terminate with
196an error or a non-zero exit code, the installation is still performed
197and {{chicken-install}} does not abort. Only after all scheduled
198eggs have been installed, {{chicken-install}} will terminate
199with a non-zero exit code.
201Note that the build process attempts to minimize re-building
202of already compiled files in the cache, using the {{chicken-do}}
203program. See the manual page for {{chicken-do}} for more details.
205From the egg-information in the {{.egg}} file, the set of files
206installed for a particular egg are added to the egg-information
207and stored together with the build-artifacts produced by the
208build scripts.
210=== chicken-install reference
212Available options:
214; {{-h   -help}} : show this message and exit
215; {{-version}} : show version and exit
216; {{-force}} : don't ask, install even if versions don't match
217; {{-k   -keep}} : keep temporary files
218; {{-s   -sudo}} : use external command to elevate privileges when installing or removing files
219; {{-no-install-dependencies}} : do not install dependencies
220; {{-r   -retrieve}} : only retrieve egg into current directory, don't install (giving -r more than once implies {{-recursive}})
221; {{-recursive}} : if {{-retrieve}} is given, retrieve also dependencies
222; {{-dry-run}} :  do not build or install, just print the locations of the generated build + install scripts
223; {{-list-versions}} : list available version for an extension (HTTP transport only)
224; {{-n   -no-install}} : do not install, only build the egg.
225; {{-purge}} : remove cached files for given eggs (or purge cache completely)
226; {{-cached}} : install from cache, do not download
227; {{-host}} : when cross-compiling, compile egg for host only
228; {{-target}} : when cross-compiling, compile egg for target only
229; {{-test}} : run included test-cases, if available
230; {{-u   -update-db}} : update export database
231; {{-repository}} : print path to egg repository
232; {{-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
233; {{-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
234; {{-v   -verbose}} : be verbose
235; {{ -defaults FILENAME }} :  use {{FILENAME}} as defaults instead of the installed {{setup.defaults}} file
237{{chicken-install}} recognizes the {{SUDO}}, {{http_proxy}} and {{proxy_auth}} environment variables, if set.
239When running {{chicken-install}} with an argument {{NAME}}, for which
240no associated {{.egg}} file exists, then it will try to download the
241extension via HTTP from the CHICKEN code repository at
242[[]]. Extensions that are
243required to compile and/or use the requested extension are downloaded
244and installed automatically.
247=== chicken-uninstall reference
249; {{-h   -help}} : show usage information and exit
250; {{-version}} : show version and exit
251; {{-force}} : don't ask, delete whatever matches
252; {{-match}} : treat egg-names as glob patterns
253; {{-s   -sudo}} : use external command to elevate privileges for deleting files
254; {{-host}} : when cross-compiling, remove eggs for host system only
255; {{-target}} : when cross-compiling, remove eggs for target system only
258=== chicken-status reference
260; {{-h   -help}} : show usage information and exit
261; {{-version}} : show version and exit
262; {{-f   -files}} : list installed files
263; {{-match}} : treat egg-names as glob patterns
264; {{-host}} : when cross-compiling, show eggs for host system only
265; {{-target}} : when cross-compiling, show eggs for target system only
266; {{-list}} : list installed egg version in format suitable for {{chicken-install -override}} or {{-from-list}}
267; {{-c   -components}} : list installed components
268; {{-cached}} : list eggs available in the cache directory
273Previous: [[Extensions]]
275Next: [[Egg specification format]]
Note: See TracBrowser for help on using the repository browser.