~ chicken-core (chicken-5) 1ccb70cb50e9afdf62b2a185110ac2a698b97792
commit 1ccb70cb50e9afdf62b2a185110ac2a698b97792
Merge: 2aa701a3 49042434
Author: felix <felix@call-with-current-continuation.org>
AuthorDate: Thu Feb 25 16:13:19 2010 +0100
Commit: felix <felix@call-with-current-continuation.org>
CommitDate: Thu Feb 25 16:13:19 2010 +0100
resolved conflicts; enabled $ORIGIN for openbsd
diff --cc csc.scm
index a26037cc,35d99b7e..52f05546
--- a/csc.scm
+++ b/csc.scm
@@@ -62,8 -63,10 +63,10 @@@
(define mingw (eq? (build-platform) 'mingw32))
(define msvc (eq? (build-platform) 'msvc))
(define osx (eq? (software-version) 'macosx))
- (define hpux-hppa (and (eq? (software-version) 'hpux)
- (eq? (machine-type) 'hppa)))
+ (define win (or mingw msvc))
+
+ (define elf
- (memq (software-version) '(linux freebsd solaris)))
++ (memq (software-version) '(linux freebsd solaris openbsd)))
(define (quit msg . args)
(fprintf (current-error-port) "~a: ~?~%" CSC_PROGRAM msg args)
diff --cc manual/Deployment
index 00000000,239e8acd..6684e7a9
mode 000000,100644..100644
--- a/manual/Deployment
+++ b/manual/Deployment
@@@ -1,0 -1,164 +1,185 @@@
+ [[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
+
+ (Note that the prefix must be an absolute path)
+
+ 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.
++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]]
Trap