[[tags: manual]]
[[toc:]]


== 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 wether
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.

Deployment is fully compatible with "cross CHICKENs" (see [[Cross development]]).

==== 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: [[Cross development]]
