~ chicken-core (chicken-5) /manual/Extensions
Trap1[[tags: manual]]2[[toc:]]34== Introduction to extensions56=== Extension libraries78Extension libraries (''eggs'') are extensions to the core9functionality provided by the basic CHICKEN system, to be built and10installed separately. The mechanism for loading compiled extensions11is based on dynamically loadable code and as such is only available on12systems on which loading compiled code at runtime is13supported. Currently these are most UNIX-compatible platforms that14provide the {{libdl}} functionality like Linux, Solaris, BSD, Mac OS X15and Windows using Cygwin.1617On systems where dynamic loading is not available, extensions can18still be built and linked as static object files.1920Note: eggs may also be normal applications or shell scripts, but21are usually libraries.2223Extensions are technically nothing but dynamically loadable compiled24files with added meta-data that describes dependencies to other25eggs, version information and things like the author/maintainer26of the egg. Three tools provide an easy to use interface for27installing eggs, removing them and querying the current28status of installed eggs.293031=== Installing eggs3233To install an egg, run the {{chicken-install}} program34with the egg name as argument. The egg archive is35downloaded, its contents extracted and the contained egg description36file is analyzed and the appropriate commands executed.37This file is an abstract description of the contents of38the egg and39will be translated by {{chicken-install}} into build- and installation40scripts for the current platform. After running these scripts (and41if all goes well), the egg is installed and will be available42like a built-in library. The format and meaning43of the file will be described below.4445Installation will copy46a number of given files into the local egg repository or in the47path where the CHICKEN executables are located (in the case of48executable programs or scripts). Additionally the list of installed49files, and user-defined metadata is stored in the repository.5051If 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 arbitrary55order, unless the egg descriptions specify dependencies.5657==== Installing eggs that use libraries5859Sometimes an egg requires a C library to compile. Compilation60can fail when your system has this library in a nonstandard61location. Normally the C compiler searches in the default locations62{{/usr}} and {{/usr/local}}, and in the prefix where CHICKEN itself63was installed. Sometimes this is not enough, so you'll need to supply64{{chicken-install}} with some extra hints to the C compiler/linker. Here's65an example:6667 CSC_OPTIONS='-I/usr/pkg/include/mysql -L/usr/pkg/lib/mysql -L -R/usr/pkg/lib/mysql' chicken-install mysql6869This installs the mysql egg with the extra compiler options -I and -L70to set the include path and the library search path. The second -L71switch passes the -R option directly to the linker, which causes the72library path to get hardcoded into the resulting extension file (for73systems that do not use {{ld.so.conf}}).7475The environment variables {{CHICKEN_C_INCLUDE_PATH}} and {{CHICKEN_C_LIBRARY_PATH}}76can also be used to override include- and linker-paths. Each of these variables77may contain one or more directory names, separated by {{:}} or {{;}} and will78be passed using {{-I}} and {{-L}} to the C compiler.7980Finally, you can use the {{custom-build}} egg file property to use a81custom script to compile your extension's code. See below for more information.8283=== Creating eggs8485An egg can be created by placing the code and some special86files in a directory of its own.87For example, if your egg is called {{foo}}, create a directory called {{foo}}88and put the egg code there (the directory's name is not actually important).8990Eggs need an egg description file {{<egg name>.egg}}. This file91indicates how the egg is to be compiled and provides some information92about the egg (author, license, dependencies etc).9394The format of these files is described in full in the chapter entitled95"[[Egg specification format]]". Below we'll give a few brief96examples of simple eggs.979899=== Examples for extensions100101==== A simple library102103The simplest case is a single file that does not export any syntax.104For example105106<enscript highlight=scheme>107;;;; hello.scm108109(define (hello name)110 (print "Hello, " name " !") )111</enscript>112113We need an {{.egg}} file to build and install our nifty extension:114115<enscript highlight=scheme>116;;;; hello.egg117118((author "Me")119 (synopsis "A cool hello-world library")120 (license "GPLv3")121 (components (extension hello)))122</enscript>123124After entering125126 $ chicken-install127128at the shell prompt (and in the same directory where the two files129exist), the file {{hello.scm}} will be compiled into a dynamically130loadable library and a statically linkable object.131If the compilation succeeds, {{hello.so}} and {{hello.o}} will132be stored in the repository, together with a file named133{{hello.egg-info}} containing an a-list with metadata (what134you stored above in {{hello.egg}} plus some additional metadata).135If no extension name is given to {{chicken-install}}, it will simply136process any files with the {{.egg}} extension it can find.137138Use it like any other CHICKEN extension:139140 $ csi -q141 #;1> (require-library hello)142 ; loading /usr/local/lib/chicken/8/hello.so ...143 #;2> (hello "me")144 Hello, me!145 #;3>146147==== An application148149Here we create a simple application:150151<enscript highlight=scheme>152;;;; hello2.scm153(import scheme chicken.format chicken.process-context)154(print "Hello, ")155(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))156(print "!")157</enscript>158159We also need an egg file:160161<enscript highlight=scheme>162;;;; hello2.egg163((author "Me")164 (synopsis "A cool hello-world application")165 (license "proprietary")166 (components (program hello2)))167</enscript>168169To use it, just run {{chicken-install}} in the same directory:170171 $ chicken-install172173(Here we omit the extension name)174175Now the program {{hello2}} will be installed in the same location as176the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will177normally be {{/usr/local/bin}}. Note that you need write-permissions178for those locations and may have to run {{chicken-install}} with179administrative rights or use the {{-sudo}} option.180181The extension can be used from the command line:182183 $ hello2 one two three184 Hello,185 one two three !186187De-installation is just as easy - use the {{chicken-uninstall}}188program to remove one or more extensions from the local repository:189190 $ chicken-uninstall hello2191192==== A module exporting syntax193194The hello module was just a shared library, and not a module.195196To create an extension that exports syntax see the chapter on197[[Modules]]. We will show a simple example here: a module {{my-lib}}198that exports one macro ({{prog1}}) and one procedure ({{my-sum}}):199200<enscript highlight=scheme>201;;; my-lib.scm202203(module my-lib204 *205 (import scheme (chicken base))206207(define-syntax prog1208 (syntax-rules ()209 ((_ e1 e2 ...)210 (let ((result e1))211 (begin e2 ...)212 result))))213214(define my-sum215 (lambda (numbers)216 (prog1217 (apply + numbers)218 (display "my-sum used one more time!")219 (newline))))220221)222</enscript>223224The {{prog1}} macro is similar to Common Lisp's {{prog1}}: it225evaluates a list of forms, but returns the value of the first form.226227The egg file:228229<enscript highlight=scheme>230;;; my-lib.egg231232((components (extension my-lib))233 (version 1.0)234 (license "BSD")235 (author "Me again")236 (synopsis "My own cool libraries"))237</enscript>238239Running {{chicken-install}} on the same directory will install the extension.240241Next, it should be possible to load the library:242243 $ csi -q244 #;1> (import my-lib)245 ; loading /usr/local/lib/chicken/6/my-lib.import.so ...246 ; loading /usr/local/lib/chicken/6/scheme.import.so ...247 ; loading /usr/local/lib/chicken/6/chicken.import.so ...248 ; loading /usr/local/lib/chicken/6/my-lib.so ...249 #;2> (my-sum '(10 20 30))250 my-sum used one more time!251 60252 #;3> (my-sum '(-1 1 0))253 my-sum used one more time!254 0255 #;4> (prog1 (+ 2 2) (print "---"))256 ---257 4258259To query the list of currently installed extensions, use260{{chicken-status}}. It can list what extensions are installed and261what files belong to a particular installed extension.262263For more information about the available tools and the various options264they provide, consult the [[Extension tools]] chapter. Again, for a265full list of allowed declarations in the {{.egg}} file, see the266[[Egg specification format]] chapter.267268---269Previous: [[Declarations]]270271Next: [[Extension tools]]