You are looking at historical revision 18489 of this page. It may differ significantly from its current revision.

Deployment

CHICKEN generates fully native binaries that can be distributed like normal C/C++ programs. There are various methods of deployment, depending on platform, linkage, external dependencies and whether the application should be built from sources or precompiled and whether the CHICKEN runtime-libraries are expected on the destination system or if the application should be completely self-contained.

Simple executables

The simplest form of deployment is the single executable. The runtime libraries (libchicken.so or libchicken.dll is required for these programs to run, unless you link your application statically:

 % csc myprogram.scm
 % ldd myprogram               # on linux
           linux-gate.so.1 =>  (0xb805c000)
           libchicken.so.5 => /home/felix/chicken/core/lib/libchicken.so.5 (0xb7c22000)
           libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7bec000)
           libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7be7000)
           libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7a84000)
           /lib/ld-linux.so.2 (0xb805d000)
 % ls -l myprogram
 -rwxr-xr-x 1 felix felix   34839 2010-02-22 20:19 x

Linking your application statically will include the runtime library in the executable, but this will increase its size substantially:

 % ls myprogram
 -rwxr-xr-x 1 felix felix 3566656 2010-02-22 20:30 myprogram

Programs distributed this way can only use Extensions if these extensions get linked in statically, which is basically supported but not available for all extensions.

Self contained applications

The solution to many of these problems is creating an application directory that contains the executable, the runtime libraries, extensions and additional support files needed by the program. The executable has to be linked specially to make sure the correct included runtime library is used. You do this by using the -deploy options provided by the compiler driver, csc:

 % csc -deploy myprogram.scm
 % ls -l myprogram
 -rwxr-xr-x 1 felix felix 7972753 2010-02-22 20:19 libchicken.so.5
 -rwxr-xr-x 1 felix felix   34839 2010-02-22 20:19 myprogram
 % ldd myprogram
         linux-gate.so.1 =>  (0xb806a000)
         libchicken.so.5 => /home/felix/tmp/myprogram/libchicken.so.5 (0xb7c30000)
         libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7bfa000)
         libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7bf5000)
         libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7a92000)
         /lib/ld-linux.so.2 (0xb806b000)

As can be seen here, myprogram is prepared to load the contained libchicken, not any installed in the system that happens to have the same name.

You can even install extensions inside the application directory:

 % chicken-install -deploy -p $PWD/myprogram defstruct
 ...
 % ls -l myprogram
 -rwxr-xr-x 1 felix felix   82842 2010-02-22 20:24 defstruct.import.so
 -rw-r--r-- 1 felix felix     182 2010-02-22 20:24 defstruct.setup-info
 -rwxr-xr-x 1 felix felix   11394 2010-02-22 20:24 defstruct.so
 -rwxr-xr-x 1 felix felix 7972753 2010-02-22 20:19 libchicken.so.5
 -rwxr-xr-x 1 felix felix   34839 2010-02-22 20:19 myprogram

We can check with ldd that those compiled extension libraries are linked with the correct library:

 % ldd myprogram/*.so
 /home/felix/tmp/myprogram/defstruct.import.so:
         linux-gate.so.1 =>  (0xb7f4f000)
         libchicken.so.5 => /home/felix/tmp/myprogram/libchicken.so.5 (0xb7b08000)
         libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7ad2000)
         libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7acd000)
         libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb796a000)
         /lib/ld-linux.so.2 (0xb7f50000)
 /home/felix/tmp/myprogram/defstruct.so:
         linux-gate.so.1 =>  (0xb80c9000)
         libchicken.so.5 => /home/felix/tmp/myprogram/libchicken.so.5 (0xb7c8c000)
         libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7c56000)
         libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7c51000)
         libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7aee000)
         /lib/ld-linux.so.2 (0xb80ca000)

The -deploy option passed to csc when compiling myprogram.scm has taken care of setting up the application directory as the "repository" for extensions that the program will use at runtime:

 % myprogram/myprogram -:d
 [debug] application startup...
 [debug] heap resized to 500000 bytes
 [debug] stack bottom is 0xbfdbdf60.
 [debug] entering toplevel toplevel...
 [debug] stack resized to 131072 bytes
 [debug] entering toplevel library_toplevel...
 [debug] entering toplevel eval_toplevel...
 [debug] entering toplevel expand_toplevel...
 [debug] loading compiled module `/home/felix/tmp/myprogram/defstruct.so' (handle is 0x886ce98)
 ...

There is one restriction that you should be aware of, though: any extension that you install inside an application directory must first be installed system-wide (unless you use a custom repository with the CHICKEN_REPOSITORY environment variable), so that csc/chicken will find an import library for the extension. Just make sure you have all the extensions installed that you use in an application (something you will normally have anyway).

You can execute the program from its location, or you can install a symbolic link pointing to it - it will find the correct directory where the actual executable is located.

The application directory is fully "portable" in the sense that it will run directly from an USB-stick or any other removable media. At runtime the program can find out its location by invoking the repository-path procedure, which will return the full pathname in which the application is located.

Should the program depend on more libraries which are not available by default on the intended target systems, and which you would like to include in your application, you will have to hunt them down yourself and place them in the application directory. If these again have dependencies, things will get complicated and will involve things like patching binaries or writing "trampoline" shell scripts to run your application.

Platform-specific notes

Linux

Deployment is fully suppored on Linux

Windows

Deployment is fully supported on Windows. Since Windows looks up dynamic link libraries in the programs original location by default, adding third-party libraries to the application directory is no problem. The freely available depends tool is helpful to find out what DLLs your application depends on:

 [[http://dependencywalker.com/]]
MacOS X

On the Macintosh, passing the -gui option to csc will result in a true GUI application bundle (named <your-program>.app).

Invoking

 % otool -L <yourprogram>

will list dynamic libraries that your application needs.

Other UNIX flavors

Setting up the application executable to load runtime libraries from the same directory is supported on FreeBSD, OpenBSD and Solaris. NetBSD supports this from version 5.0 onwards - this is currently disabled in csc for this particular platform.

Deploying source code

An alternative to deploying binaries is deployment as compiled C sources. Usually, you just need to ship your application code, compiled to .c files and the chicken.h and runtime.c files from the CHICKEN sources. You will also need the .c files of any library units your program uses. Compiling everything and linking it together should work on most systems. Consult the CHICKEN makefiles for more information about optimization options, etc.


Previous: Extensions

Next: Data representation