source: project/wiki/man/4/Deployment @ 25875

Last change on this file since 25875 was 25875, checked in by felix winkelmann, 9 years ago

merged some manual changes from master into wiki

File size: 7.7 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Deployment
6
7CHICKEN generates fully native binaries that can be distributed like
8normal C/C++ programs. There are various methods of deployment,
9depending on platform, linkage, external dependencies and whether
10the application should be built from sources or precompiled and
11whether the CHICKEN runtime-libraries are expected on the destination
12system or if the application should be completely self-contained.
13
14=== Simple executables
15
16The simplest form of deployment is the single executable. The runtime
17library ({{libchicken.so}} or {{libchicken.dll}}) is required for these
18programs to run, unless you link your application statically:
19
20  % csc myprogram.scm
21  % ldd myprogram               # on linux
22            linux-gate.so.1 =>  (0xb805c000)
23            libchicken.so.5 => /home/felix/chicken/core/lib/libchicken.so.5 (0xb7c22000)
24            libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7bec000)
25            libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7be7000)
26            libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7a84000)
27            /lib/ld-linux.so.2 (0xb805d000)
28  % ls -l myprogram
29  -rwxr-xr-x 1 felix felix   34839 2010-02-22 20:19 x
30
31Linking your application statically will include the runtime library in the executable,
32but this will increase its size substantially:
33
34  % ls myprogram
35  -rwxr-xr-x 1 felix felix 3566656 2010-02-22 20:30 myprogram
36
37Programs distributed this way can only use [[Extensions]] if these extensions
38get linked in statically, which is basically supported but not available for all
39extensions.
40
41=== Self contained applications
42
43The solution to many of these problems is creating an application directory that contains
44the executable, the runtime libraries, extensions and additional support files needed by the
45program. The executable has to be linked specially to make sure the correct included
46runtime library is used. You do this by using the {{-deploy}} options provided by
47the compiler driver, {{csc}}:
48
49  % csc -deploy myprogram.scm
50  % ls -l myprogram
51  -rwxr-xr-x 1 felix felix 7972753 2010-02-22 20:19 libchicken.so.5
52  -rwxr-xr-x 1 felix felix   34839 2010-02-22 20:19 myprogram
53  % ldd myprogram
54          linux-gate.so.1 =>  (0xb806a000)
55          libchicken.so.5 => /home/felix/tmp/myprogram/libchicken.so.5 (0xb7c30000)
56          libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7bfa000)
57          libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7bf5000)
58          libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7a92000)
59          /lib/ld-linux.so.2 (0xb806b000)
60
61As can be seen here, {{myprogram}} is prepared to load the contained {{libchicken}},
62not any installed in the system that happens to have the same name.
63
64You can even install extensions inside the application directory:
65
66  % chicken-install -deploy -p $PWD/myprogram defstruct
67  ...
68  % ls -l myprogram
69  -rwxr-xr-x 1 felix felix   82842 2010-02-22 20:24 defstruct.import.so
70  -rw-r--r-- 1 felix felix     182 2010-02-22 20:24 defstruct.setup-info
71  -rwxr-xr-x 1 felix felix   11394 2010-02-22 20:24 defstruct.so
72  -rwxr-xr-x 1 felix felix 7972753 2010-02-22 20:19 libchicken.so.5
73  -rwxr-xr-x 1 felix felix   34839 2010-02-22 20:19 myprogram
74
75We can check with ldd that those compiled extension libraries are linked with
76the correct library:
77
78  % ldd myprogram/*.so
79  /home/felix/tmp/myprogram/defstruct.import.so:
80          linux-gate.so.1 =>  (0xb7f4f000)
81          libchicken.so.5 => /home/felix/tmp/myprogram/libchicken.so.5 (0xb7b08000)
82          libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7ad2000)
83          libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7acd000)
84          libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb796a000)
85          /lib/ld-linux.so.2 (0xb7f50000)
86  /home/felix/tmp/myprogram/defstruct.so:
87          linux-gate.so.1 =>  (0xb80c9000)
88          libchicken.so.5 => /home/felix/tmp/myprogram/libchicken.so.5 (0xb7c8c000)
89          libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7c56000)
90          libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7c51000)
91          libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7aee000)
92          /lib/ld-linux.so.2 (0xb80ca000)
93
94The {{-deploy}} option passed to {{csc}} when compiling {{myprogram.scm}} has
95taken care of setting up the application directory as the "repository" for
96extensions that the program will use at runtime:
97
98  % myprogram/myprogram -:d
99  [debug] application startup...
100  [debug] heap resized to 500000 bytes
101  [debug] stack bottom is 0xbfdbdf60.
102  [debug] entering toplevel toplevel...
103  [debug] stack resized to 131072 bytes
104  [debug] entering toplevel library_toplevel...
105  [debug] entering toplevel eval_toplevel...
106  [debug] entering toplevel expand_toplevel...
107  [debug] loading compiled module `/home/felix/tmp/myprogram/defstruct.so' (handle is 0x886ce98)
108  ...
109
110There is one restriction that you should be aware of: you cannot
111{{chicken-install -deploy}} an uninstalled extension, e.g.
112directly from an SVN checkout.  You must first install it on your
113build system normally with {{chicken-install}}, so that {{csc}} can
114find its import library in the system-wide repository (or in a custom
115one if you have set {{CHICKEN_REPOSITORY}}).  This is only needed
116while you are deploying the extension into the application directory; once
117deployed, of course, it's totally self-contained.
118
119You can execute the program from its location, or you can install a symbolic
120link pointing to it - it will find the correct directory where the actual
121executable is located.
122
123The application directory is fully "portable" in the sense that it will run directly
124from an USB-stick or any other removable media. At runtime the program can find
125out its location by invoking the {{repository-path}} procedure, which will return
126the full pathname in which the application is located.
127
128Should the program depend on more libraries which are not available by
129default on the intended target systems, and which you would like to
130include in your application, you will have to hunt them down yourself
131and place them in the application directory. If these again have
132dependencies, things will get complicated and will involve things like
133patching binaries or writing "trampoline" shell scripts to run your
134application.
135
136Deployment is fully compatible with "cross CHICKENs" (see [[Cross development]]).
137
138==== Platform-specific notes
139
140===== Linux
141
142Deployment is fully supported on Linux
143
144===== Windows
145
146Deployment is fully supported on Windows. Since Windows looks up
147dynamic link libraries in the programs original location by default,
148adding third-party libraries to the application directory is no
149problem. The freely available [[http://dependencywalker.com|Dependency
150Walker]] tool is helpful to find out what DLLs your application
151depends on.
152
153===== MacOS X
154
155On the Macintosh, passing the {{-gui}} option to {{csc}} will result in a
156true GUI application bundle (named {{<your-program>.app}}).
157
158Invoking
159
160  % otool -L <yourprogram>
161
162will list dynamic libraries that your application needs.
163
164===== Other UNIX flavors
165
166Setting up the application executable to load runtime libraries from
167the same directory is supported on FreeBSD, OpenBSD and Solaris.
168NetBSD supports this from version 5.0 onwards - this is currently
169disabled in {{csc}} for this particular platform.
170
171=== Deploying source code
172
173An alternative to deploying binaries is deployment as compiled
174C sources. Usually, you just need to ship your application code,
175compiled to {{.c}} files and the {{chicken.h}} and {{runtime.c}}
176files from the CHICKEN sources. You will also need the {{.c}} files
177of any library units your program uses (at least {{library.c}} and
178{{build-version.c}}). Compiling everything and
179linking it together should work on most systems. Consult the
180CHICKEN makefiles for more information about optimization options,
181etc.
182
183
184---
185Previous: [[Extensions]]
186
187Next: [[Cross development]]
Note: See TracBrowser for help on using the repository browser.