~ chicken-core (master) /manual/Deployment
Trap1[[tags: manual]]2[[toc:]]345== Deployment67CHICKEN generates fully native binaries that can be distributed like8normal C/C++ programs. There are various methods of deployment,9depending on platform, linkage, external dependencies and whether10the application should be built from sources or precompiled and11whether the CHICKEN runtime-libraries are expected on the destination12system or if the application should be completely self-contained.1314There are several options for distributing software written in CHICKEN for15use on other machines or by other people:1617* Distribute source code, which requires that the target system has a compatible version of CHICKEN installed18* Distribute C files generated from Scheme source code and compile them to binaries on the target system - this also requires a matching CHICKEN installation on the target19* Distribute compiled binaries, either statically linked or built in such a way that all required extensions and libraries are included in the distribution2021The rest of this chapter addresses the third option, for which several options exist,22depending on your needs and how self-contained you want your deployed23binary to be.2425The simplest form of deployment is the single executable. The runtime26library ({{libchicken.so}}, {{libchicken.dylib}} or {{libchicken.dll}}) is required for these27programs to run, unless you link your application statically:2829 % csc myprogram.scm30 % ldd myprogram # on linux31 linux-gate.so.1 => (0xb805c000)32 libchicken.so.9 => /home/felix/chicken/core/lib/libchicken.so.9 (0xb7c22000)33 libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7bec000)34 libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7be7000)35 libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7a84000)36 /lib/ld-linux.so.2 (0xb805d000)37 % ls -l myprogram38 -rwxr-xr-x 1 felix felix 34839 2010-02-22 20:19 x3940=== Static linking4142Linking your application statically will include the runtime library in the executable:4344 % csc -static myprogram.scm45 % ldd myprogram46 linux-gate.so.1 => (0xb805c000)47 libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7bec000)48 libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7be7000)49 libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7a84000)50 /lib/ld-linux.so.2 (0xb805d000)5152[[Extensions]] are transparently linked in statically, if you provide the {{-static}}53option to {{csc}}, provided the extension is avaiable as a static object file54(this applies to most extensions by default).5556=== Shipping the runtime library5758An alternate way of distributing compiled code is to ship the runtime library59{{libchicken.so}} together with the executable, possibly including any extensions60that you use. To make this work, any runtime linker paths compiled into61binary objects need to be deleted or changed by using a tool like {{chrpath(1)}}62or {{patchelf(1)}}, to a value that indicates that63the library lookup should start in the same location as the main program.64(e.g. {{$ORIGIN}} on Linux). Don't forget to copy any extensions from the65extension repository ({{$PREFIX/lib/chicken/$BINARYVERSION}}).6667Alternatively start your program through a separate68script that sets {{LD_LIBRARY_PATH}} (or {{DYLD_LIBRARY_PATH}} on69MacOS X).70For more details, consult71the documentation of the operating system that you use to build your72deployed binaries.7374A directory containing all binaries is fully "portable" in the sense that it will run directly75from an USB-stick or any other removable media. At runtime the program can find76out its location by invoking the {{repository-path}} procedure, which will return77the full pathname in which the application is located.7879Should the program depend on more libraries which are not available by80default on the intended target systems, and which you would like to81include in your application, you will have to track them down yourself82and place them in the application directory.8384=== Distributing compiled C files8586It is possible to create distributions of Scheme projects that87have been compiled to C. The runtime system of CHICKEN consists of only88two handcoded C files ({{runtime.c}} and {{chicken.h}}), plus the files89{{chicken-config.h}} and {{buildtag.h}}, which are generated by the90build process. All other modules of the runtime system and the extension91libraries are just compiled Scheme code. The following example shows a92minimal application, which should run without changes on most operating93systems, like Windows, Linux or FreeBSD (note however that static94binaries are not supported on Mac OS X).9596Take the following "Hello World" program:9798<enscript highlight=scheme>99; hello.scm100101(print "Hello, world!")102</enscript>103104 % csc -t hello.scm -optimize-level 3 -output-file hello.c105106Compiled to C, we get {{hello.c}}. We need the files {{chicken.h}},107{{chicken-config.h}}, {{buildtag.h}} and {{runtime.c}}, which contain108the basic runtime system, plus the library files {{build-version.c}},109{{chicken-syntax.c}}, {{eval.c}}, {{expand.c}}, {{internal.c}},110{{library.c}} and {{modules.c}}, which contain the same functionality as111the library that is linked into plain CHICKEN-compiled applications:112113 % cd /tmp114 % echo '(print "Hello World.")' > hello.scm115 % csc -t hello.scm116 % cp $CHICKEN_BUILD/build-version.c .117 % cp $CHICKEN_BUILD/chicken-syntax.c .118 % cp $CHICKEN_BUILD/eval.c .119 % cp $CHICKEN_BUILD/expand.c .120 % cp $CHICKEN_BUILD/internal.c .121 % cp $CHICKEN_BUILD/library.c .122 % cp $CHICKEN_BUILD/modules.c .123 % cp $CHICKEN_BUILD/runtime.c .124 % cp $CHICKEN_BUILD/utf.c .125 % cp $CHICKEN_BUILD/chicken.h .126 % cp $CHICKEN_BUILD/chicken-config.h .127 % cp $CHICKEN_BUILD/buildtag.h .128 % gcc -Os -fomit-frame-pointer -DHAVE_CHICKEN_CONFIG_H hello.c \129 build-version.c chicken-syntax.c eval.c expand.c internal.c \130 library.c modules.c runtime.c \131 -o hello -lm132133Once we have all the files together, we can create a tarball:134135 % tar czf hello.tar.gz hello.c build-version.c chicken-syntax.c eval.c \136 expand.c internal.c library.c modules.c runtime.c utf.c chicken.h \137 chicken-config.h buildtag.h138139This is naturally rather simplistic. Things like enabling dynamic140loading and selecting supported features of the host system would need141more configuration- and build-time support. All this can be addressed142using more elaborate build-scripts, makefiles or by using143autoconf/automake.144145The {{chicken-config.h}} file may contain incorrect settings for your146deployment target. Especially when the architecture is different. In147that case you will have to adjust the values as needed.148149For more information, study the CHICKEN source code and/or ask on the CHICKEN150mailing lists to understand the implications and difficulties of this deployment151method in more detail.152153=== Platform specific notes154155==== Windows156157Deployment is fully supported on Windows. Since Windows looks up158dynamic link libraries in the programs original location by default,159adding third-party libraries to the application directory is no160problem. The freely available [[http://dependencywalker.com|Dependency161Walker]] tool is helpful to find out what DLLs your application162depends on.163164==== MacOS X165166The {{otool(1)}} program will show you dynamic libraries that your167application requires. {{DYLD_LIBRARY_PATH}}168can be set to override runtime linker paths and {{install_name_tool(1)}}169is available to patch runtime linker paths directly. All of these tools170require the Xcode command-line tools too be installed.171172173---174Previous: [[Units and linking model]]175176Next: [[Cross development]]