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

Last change on this file since 35525 was 35525, checked in by felix, 5 months ago

man/5: restructuring, fixed links, added csi module, simplification

File size: 8.1 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Introduction to extensions
5
6=== Extension libraries
7
8Extension libraries (''eggs'') are extensions to the core
9functionality provided by the basic CHICKEN system, to be built and
10installed separately.  The mechanism for loading compiled extensions
11is based on dynamically loadable code and as such is only available on
12systems on which loading compiled code at runtime is
13supported. Currently these are most UNIX-compatible platforms that
14provide the {{libdl}} functionality like Linux, Solaris, BSD, Mac OS X
15and Windows using Cygwin.
16
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
97=== Examples for extensions
98
99==== A simple library
100
101The simplest case is a single file that does not export any syntax.
102For example
103
104<enscript highlight=scheme>
105;;;; hello.scm
106
107(define (hello name)
108  (print "Hello, " name " !") )
109</enscript>
110
111We need an {{.egg}} file to build and install our nifty extension:
112
113<enscript highlight=scheme>
114;;;; hello.egg
115
116((author "Me")
117 (synopsis "A cool hello-world library")
118 (license "GPLv3")
119 (components (extension hello)))
120</enscript>
121
122After entering
123
124 $ chicken-install
125
126at the shell prompt (and in the same directory where the two files
127exist), the file {{hello.scm}} will be compiled into a dynamically
128loadable library and a statically linkable object.
129If the compilation succeeds, {{hello.so}} and {{hello.o}} will
130be stored in the repository, together with a file named
131{{hello.egg-info}} containing an a-list with metadata (what
132you stored above in {{hello.egg}} plus some additional metadata).
133If no extension name is given to {{chicken-install}}, it will simply
134process the any files with the {{.egg}} extension it can find.
135
136Use it like any other CHICKEN extension:
137
138 $ csi -q
139 #;1> (require-library hello)
140 ; loading /usr/local/lib/chicken/8/hello.so ...
141 #;2> (hello "me")
142 Hello, me!
143 #;3>
144
145==== An application
146
147Here we create a simple application:
148
149<enscript highlight=scheme>
150;;;; hello2.scm
151
152(print "Hello, ")
153(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))
154(print "!")
155</enscript>
156
157We also need an egg file:
158
159;;;; hello2.egg
160
161<enscript highlight=scheme>
162((author "Me")
163 (synopsis "A cool hello-world application")
164 (license "proprietary")
165 (components (program hello2)))
166</enscript>
167
168To use it, just run {{chicken-install}} in the same directory:
169
170 $ chicken-install
171
172(Here we omit the extension name)
173
174Now the program {{hello2}} will be installed in the same location as
175the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will
176normally be {{/usr/local/bin}}.  Note that you need write-permissions
177for those locations and may have to run {{chicken-install}} with
178administrative rights or use the {{-sudo}} option.
179
180The extension can be used from the command line:
181
182 $ hello2 one two three
183 Hello,
184 one two three !
185
186De-installation is just as easy - use the {{chicken-uninstall}}
187program to remove one or more extensions from the local repository:
188
189 $ chicken-uninstall hello2
190
191==== A module exporting syntax
192
193The hello module was just a shared library, and not a module.
194
195To create an extension that exports syntax see the chapter on
196[[Modules]].  We will show a simple example here: a module {{my-lib}}
197that exports one macro ({{prog1}}) and one procedure ({{my-sum}}):
198
199<enscript highlight=scheme>
200;;; my-lib.scm
201
202(module my-lib
203  *
204  (import scheme chicken)
205
206(define-syntax prog1
207  (syntax-rules ()
208    ((_ e1 e2 ...)
209     (let ((result e1))
210       (begin e2 ...)
211       result))))
212
213(define my-sum
214  (lambda (numbers)
215    (prog1
216      (apply + numbers)
217      (display "my-sum used one more time!")
218      (newline))))
219
220)
221</enscript>
222
223The {{prog1}} macro is similar to Common Lisp's {{prog1}}: it
224evaluates a list of forms, but returns the value of the first form.
225
226The egg file:
227
228<enscript highlight=scheme>
229;;; my-lib.egg
230
231((components (extension my-lib))
232 (version 1.0)
233 (licence "BSD")
234 (author "Me again")
235 (synopsis "My own cool libraries"))
236</enscript>
237
238Running {{chicken-install}} on the same directory will install the extension.
239
240Next, it should be possible to load the library:
241
242 $ csi -q
243 #;1> (import my-lib)
244 ; loading /usr/local/lib/chicken/6/my-lib.import.so ...
245 ; loading /usr/local/lib/chicken/6/scheme.import.so ...
246 ; loading /usr/local/lib/chicken/6/chicken.import.so ...
247 ; loading /usr/local/lib/chicken/6/my-lib.so ...
248 #;2> (my-sum '(10 20 30))
249 my-sum used one more time!
250 60
251 #;3> (my-sum '(-1 1 0))
252 my-sum used one more time!
253 0
254 #;4> (prog1 (+ 2 2) (print "---"))
255 ---
256 4
257
258To query the list of currently installed extensions, use
259{{chicken-status}}. It can list what extensions are installed and
260what files belong to a particular installed extension.
261
262For more information about the available tools and the various
263options they provide, consult the [[Extension tools]] chapter.
264
265
266---
267Previous: [[Interface to external functions and variables]]
268
269Next: [[Extension tools]]
Note: See TracBrowser for help on using the repository browser.