~ chicken-core (master) /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 its code and some special86files in a directory named after the desired name of the egg.87For example, if your88egg is called {{foo}}, create a directory called {{foo}}89and put the egg code there.9091Eggs need an egg description file {{<egg name>.egg}}. This file92indicates how the egg is to be compiled and provides some information93about the egg (author, license, dependencies etc).9495The format of these files is described in full in the chapter entitled96"[[Egg specification format]]". Below we'll give a few brief97examples of simple eggs.9899100=== Examples for extensions101102==== A simple library103104The simplest case is a single file that does not export any syntax.105For example106107<enscript highlight=scheme>108;;;; hello.scm109110(define (hello name)111 (print "Hello, " name " !") )112</enscript>113114We need an {{.egg}} file to build and install our nifty extension:115116<enscript highlight=scheme>117;;;; hello.egg118119((author "Me")120 (synopsis "A cool hello-world library")121 (license "GPLv3")122 (components (extension hello)))123</enscript>124125After entering126127 $ chicken-install128129at the shell prompt (and in the same directory where the two files130exist), the file {{hello.scm}} will be compiled into a dynamically131loadable library and a statically linkable object.132If the compilation succeeds, {{hello.so}} and {{hello.o}} will133be stored in the repository, together with a file named134{{hello.egg-info}} containing an a-list with metadata (what135you stored above in {{hello.egg}} plus some additional metadata).136If no extension name is given to {{chicken-install}}, it will simply137process any files with the {{.egg}} extension it can find.138139Use it like any other CHICKEN extension:140141 $ csi -q142 #;1> (require-library hello)143 ; loading /usr/local/lib/chicken/8/hello.so ...144 #;2> (hello "me")145 Hello, me!146 #;3>147148==== An application149150Here we create a simple application:151152<enscript highlight=scheme>153;;;; hello2.scm154(import scheme chicken.format chicken.process-context)155(print "Hello, ")156(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))157(print "!")158</enscript>159160We also need an egg file:161162<enscript highlight=scheme>163;;;; hello2.egg164((author "Me")165 (synopsis "A cool hello-world application")166 (license "proprietary")167 (components (program hello2)))168</enscript>169170To use it, just run {{chicken-install}} in the same directory:171172 $ chicken-install173174(Here we omit the extension name)175176Now the program {{hello2}} will be installed in the same location as177the other CHICKEN tools (like {{chicken}}, {{csi}}, etc.), which will178normally be {{/usr/local/bin}}. Note that you need write-permissions179for those locations and may have to run {{chicken-install}} with180administrative rights or use the {{-sudo}} option.181182The extension can be used from the command line:183184 $ hello2 one two three185 Hello,186 one two three !187188De-installation is just as easy - use the {{chicken-uninstall}}189program to remove one or more extensions from the local repository:190191 $ chicken-uninstall hello2192193==== A module exporting syntax194195The hello module was just a shared library, and not a module.196197To create an extension that exports syntax see the chapter on198[[Modules]]. We will show a simple example here: a module {{my-lib}}199that exports one macro ({{prog1}}) and one procedure ({{my-sum}}):200201<enscript highlight=scheme>202;;; my-lib.scm203204(module my-lib205 *206 (import scheme (chicken base))207208(define-syntax prog1209 (syntax-rules ()210 ((_ e1 e2 ...)211 (let ((result e1))212 (begin e2 ...)213 result))))214215(define my-sum216 (lambda (numbers)217 (prog1218 (apply + numbers)219 (display "my-sum used one more time!")220 (newline))))221222)223</enscript>224225The {{prog1}} macro is similar to Common Lisp's {{prog1}}: it226evaluates a list of forms, but returns the value of the first form.227228The egg file:229230<enscript highlight=scheme>231;;; my-lib.egg232233((components (extension my-lib))234 (version 1.0)235 (license "BSD")236 (author "Me again")237 (synopsis "My own cool libraries"))238</enscript>239240Running {{chicken-install}} on the same directory will install the extension.241242Next, it should be possible to load the library:243244 $ csi -q245 #;1> (import my-lib)246 ; loading /usr/local/lib/chicken/6/my-lib.import.so ...247 ; loading /usr/local/lib/chicken/6/scheme.import.so ...248 ; loading /usr/local/lib/chicken/6/chicken.import.so ...249 ; loading /usr/local/lib/chicken/6/my-lib.so ...250 #;2> (my-sum '(10 20 30))251 my-sum used one more time!252 60253 #;3> (my-sum '(-1 1 0))254 my-sum used one more time!255 0256 #;4> (prog1 (+ 2 2) (print "---"))257 ---258 4259260To query the list of currently installed extensions, use261{{chicken-status}}. It can list what extensions are installed and262what files belong to a particular installed extension.263264For more information about the available tools and the various options265they provide, consult the [[Extension tools]] chapter. Again, for a266full list of allowed declarations in the {{.egg}} file, see the267[[Egg specification format]] chapter.268269---270Previous: [[Declarations]]271272Next: [[Extension tools]]