source: project/wiki/man/5/Deployment @ 35527

Last change on this file since 35527 was 35472, checked in by felix, 15 months ago

man/5: added (short) deployment chapter

File size: 4.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
14There are several options for distributing software written in CHICKEN for
15use on other machines or by other people:
16
17* Distribute source code, which requires that the target system has a compatible version of CHICKEN installed
18* Distribute C files generated from Scheme source code and compile them binaries on the target system - this also requires a matching CHICKEN installation on the target
19* Distribute compiled binaries, either statically linked or built in such a way that all required extensions and libraries are included in the distribution
20
21The rest of this chapter addresses the third option, for which several options exist,
22depending on your needs and how self-contained you want your deployed
23binary to be.
24
25The simplest form of deployment is the single executable. The runtime
26library ({{libchicken.so}} or {{libchicken.dll}}) is required for these
27programs to run, unless you link your application statically:
28
29  % csc myprogram.scm
30  % ldd myprogram               # on linux
31            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 myprogram
38  -rwxr-xr-x 1 felix felix   34839 2010-02-22 20:19 x
39
40=== Static linking
41
42Linking your application statically will include the runtime library in the executable:
43
44  % csc -static myprogram.scm
45  % ldd myprogram
46            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)
51
52[[Extensions]] are transparently linked in statically, if you provide the {{-static}}
53option to {{csc}}, provided the extension is avaiable as a static object file
54(this applies to most extensions by default).
55
56=== Shipping the runtime library
57
58An alternate way of distributing compiled code is to ship the runtime library
59{{libchicken.so}} together with the executable, possibly including any extensions
60that you use. To make this work, any runtime linker paths compiled into
61binary objects need to be deleted or changed by using a tool like {{chrpath(1)}}
62or {{patchelf(1)}}, to a value that indicates that
63the 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 the
65extension repository ({{$PREFIX/lib/chicken/$BINARYVERSION}}).
66
67Alternatively start your program through a separate
68script that sets {{LD_LIBRARY_PATH}} (or {{DYLD_LIBRARY_PATH}} on
69MacOS X).
70For more details, consult
71the documentation of the operating system that you use to build your
72deployed binaries.
73
74A directory containing all binaries is fully "portable" in the sense that it will run directly
75from an USB-stick or any other removable media. At runtime the program can find
76out its location by invoking the {{repository-path}} procedure, which will return
77the full pathname in which the application is located.
78
79Should the program depend on more libraries which are not available by
80default on the intended target systems, and which you would like to
81include in your application, you will have to track them down yourself
82and place them in the application directory.
83
84=== Platform specific notes
85
86==== Windows
87
88Deployment is fully supported on Windows. Since Windows looks up
89dynamic link libraries in the programs original location by default,
90adding third-party libraries to the application directory is no
91problem. The freely available [[http://dependencywalker.com|Dependency
92Walker]] tool is helpful to find out what DLLs your application
93depends on.
94
95==== MacOS X
96
97The {{otool(1)}} program will show you dynamic libraries that your
98application requires. {{DYLD_LIBRARY_PATH}}
99can be set to override runtime linker paths and {{install_name_tool(1)}}
100is available to patch runtime linker paths directly. All of these tools
101require the Xcode command-line tools too be installed.
102
103
104---
105Previous: [[Units and the linking model]]
106
107Next: [[Cross development]]
Note: See TracBrowser for help on using the repository browser.