source: project/wiki/man/5/Cross development @ 35525

Last change on this file since 35525 was 35525, checked in by felix, 7 weeks ago

man/5: restructuring, fixed links, added csi module, simplification

File size: 8.3 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Cross Development
6
7Since CHICKEN generates C code, it is relatively easy to create
8programs and libraries for a different architecture than the one the
9compiler is executing on, a process commonly called ''cross
10compiling''. Basically you can simply compile Scheme code to C and
11then invoke your target-specific cross compiler.  To automate the
12process of invoking the correct C compiler with the correct settings
13and to simplify the use of extensions, CHICKEN can be built in a
14special "cross-compilation" mode.
15
16Note: in the following text we refer to the "target" as being the
17platform on which the software is intended to run in the end. We use
18the term "host" as the system that builds this software. Others use a
19different nomenclature or switch the meaning of the words.
20
21=== Preparations
22
23Make sure you have a cross-toolchain in your {{PATH}}. In this
24example, a Linux system is used to generate binaries for an ARM based
25embedded system.
26
27==== Building the target libraries
28
29First you need a version of the runtime system ({{libchicken}}),
30compiled for the target system. Obtain and unpack a tarball of the
31CHICKEN sources, or check out the code from the official code
32repository, then build the libraries and necessary development files:
33
34 make ARCH= \
35     PREFIX=/usr \
36     PLATFORM=linux \
37     HOSTSYSTEM=arm-none-linux-gnueabi \
38     DESTDIR=$HOME/target \
39     TARGET_FEATURES="-no-feature x86 -feature arm" \
40     install
41
42This will build CHICKEN and install it in {{~/target}}, which we use
43as a temporary place to store the target files. A few things to note:
44
45* {{ARCH}} is empty, since we don't want the build process to detect the architecture (since the target-architecture is likely to be different).  If you know the right string to represent target architecture (see {{C_PLATFORM_TYPE}} in {{chicken.h}} for the supported options), you can set {{ARCH}} with that value.
46* {{PREFIX}} gives the prefix ''on the target system'', under which the
47libraries will finally be installed. In this case it will be {{/usr/lib}}.
48
49* {{PLATFORM}} determines the target platform. It must be one of the officially
50supported platforms CHICKEN runs on.
51
52* {{HOSTSYSTEM}} is an identifier for the target system and will be used as
53the name prefix of the cross C compiler (in this case {{arm-none-linux-gnueabi-gcc}}).
54If your cross compiler does not follow this convention, pass {{C_COMPILER}} and
55{{LIBRARIAN}} to the {{make(1)}} invocation, with the names of the C compiler and
56{{ar(1)}} tool, respectively.
57
58* {{DESTDIR}} holds the directory where the compiled library files will temporarily
59be installed into.
60
61* {{TARGET_FEATURES}} contains extra options to be passed to the target-specific
62Scheme translator; in this case we disable and enable features so that code like
63the following will do the right thing when cross-compiled:
64
65<enscript hightlight=scheme>
66(cond-expand
67  (x86 <do this ...>)
68  ...)
69</enscript>
70
71* If you obtained the sources from a source-code repository and not
72from an official release tarball, you will need a {{chicken}}
73executable to compile the Scheme sources of the runtime system. In
74this case pass yet another variable to the {{make(1)}} invocation:
75{{CHICKEN=<where the "chicken" executable is>}}.
76
77* You can also put all those variables into a file, say {{config.mk}}
78and run {{make CONFIG=config.mk}}.
79
80You should now have these files on {{~/target}}:
81
82 |-- bin
83 |   |-- chicken
84 |   |-- chicken-bug
85 |   |-- chicken-install
86 |   |-- chicken-profile
87 |   |-- chicken-status
88 |   |-- chicken-uninstall
89 |   |-- csc
90 |   `-- csi
91 |-- include
92 |   |-- chicken-config.h
93 |   `-- chicken.h
94 |-- lib
95 |   |-- chicken
96 |   |   `-- 9
97 |   |       :
98 |   |
99 |   |-- libchicken.a
100 |   |-- libchicken.so -> libchicken.so.9
101 |   `-- libchicken.so.9
102 `-- share
103     |-- chicken
104     |   |-- doc
105     :   ;   :
106     |   |
107     |   `-- setup.defaults
108     `-- man
109         `-- man1
110             :
111
112You should now transfer {{libchicken.so}} to the target system, and place
113it in {{/usr}}.
114
115==== Building the "cross chicken"
116
117Next, we will build another chicken, one that uses the cross C compiler to
118generate target-specific code that uses the target-specific runtime library
119we have just built.
120
121Again, unpack a CHICKEN release tarball or a source tree and run
122{{make(1)}} once again:
123
124 make PLATFORM=linux \
125     PREFIX=$HOME/cross-chicken \
126     TARGETSYSTEM=arm-none-linux-gnueabi \
127     PROGRAM_PREFIX=arm- \
128     TARGET_PREFIX=$HOME/target/usr \
129     TARGET_RUN_PREFIX=/usr \
130     install
131
132* {{PREFIX}} gives the place where the "cross chicken" should be installed
133into. It is recommended not to install into a standard location (like {{/usr/local}}
134or {{$HOME}}) - some files will conflict with a normal CHICKEN installation.
135
136* {{TARGETSYSTEM}} gives the name-prefix of the cross C compiler.
137
138* {{PROGRAM_PREFIX}} determines the name-prefix of the CHICKEN tools to be created.
139
140* {{TARGET_PREFIX}} specifies where the target-specific files (libraries and
141headers) are located. This is the location where we installed the runtime
142system into.
143
144* {{TARGET_RUN_PREFIX}} holds the PREFIX that will be effective at runtime
145(so {{libchicken.so}} will be found in {{$TARGET_RUN_PREFIX/lib}}).
146
147* Make sure to use the same version of the CHICKEN sources for the target and
148the cross build.
149
150* If you build the cross chicken from repository sources, the same note
151about the {{CHICKEN}} variable applies as given above.
152
153In {{~/cross-chicken}}, you should find the following:
154
155 |-- bin
156 |   |-- arm-chicken
157 |   |-- arm-chicken-install
158 |   |-- arm-chicken-profile
159 |   |-- arm-chicken-status
160 |   |-- arm-chicken-uninstall
161 |   |-- arm-csc
162 |   `-- arm-csi
163 |-- include
164 |   |-- chicken-config.h
165 |   `-- chicken.h
166 |-- lib
167 |   |-- chicken
168 |   |   `-- 9
169 |   |       :
170 |   |
171 |   |-- libchicken.a
172 |   |-- libchicken.so -> libchicken.so.9
173 |   `-- libchicken.so.9
174 `-- share
175     |-- chicken
176     |   |-- doc
177     :   ;   :
178     |   |
179     |   `-- setup.defaults
180     `-- man
181         `-- man1
182             :
183
184To make sure that the right C compiler is used, we ask {{arm-csc}} to show
185the name of the cross C compiler:
186
187  % ~/cross-chicken/arm-csc -cc-name
188  arm-none-linux-gnueabi-gcc
189
190Looks good.
191
192=== Using it
193
194==== Compiling simple programs
195
196  % ~/cross-chicken/arm-csc -v hello.scm
197  /home/felix/cross-chicken/arm-cross-chicken/bin/arm-chicken hello.scm -output-file hello.c -quiet
198  arm-none-linux-gnueabi-gcc hello.c -o hello.o -c -fno-strict-aliasing -DHAVE_CHICKEN_CONFIG_H -g -Wall \
199    -Wno-unused -I /home/felix/cross-chicken/arm-chicken/include
200  rm hello.c
201  arm-none-linux-gnueabi-gcc hello.o -o hello -L/home/felix/cross-chicken/arm-chicken/lib  -Wl,-R/usr/lib -lm \
202    -ldl -lchicken
203  rm hello.o
204
205Is it an ARM binary?
206
207  % file hello
208  hello: ELF 32-bit LSB executable, ARM, version 1 (SYSV), for GNU/Linux 2.6.16, dynamically linked (uses shared libs), not stripped
209
210Yes, looks good.
211
212==== Compiling extensions
213
214By default, the tools that CHICKEN provides to install, list and uninstall
215extensions will operate on both the host and the target repository.
216So running {{arm-chicken-install}} will compile and install the extension
217for the host system and for the cross-target. To selectively install, uninstall
218or list extensions for either the host or the target system use the
219{{-host}} and {{-target}} options for the tools.
220
221=== "Target-only" extensions
222
223Sometimes an extension will only be compilable for the target platform
224(for example libraries that use system-dependent features). In this
225case you will have to work around the problem that the host-compiler
226still may need compile-time information from the target-only
227extension, like the import library of modules. One option is to copy
228the import-library source file into the repository of the host compiler:
229
230 # optionally, you can compile the import library:
231 # ~/cross-chicken/arm-csc -O3 -d0 -s target-only-extension.import.scm
232 cp target-only-extension.import.scm ~/cross-chicken/lib/chicken/9
233
234=== Final notes
235
236Cross-development is a very tricky process - it often involves countless
237manual steps and it is very easy to forget an important detail or mix
238up target and host systems. Also, full 100% platform neutrality is
239hard to achieve. CHICKEN tries very hard to make this transparent, but
240at the price of considerable complexity in the code that manages
241extensions.
242
243
244----
245Previous: [[Deployment]]
246Next: [[Bugs and limitation]]
Note: See TracBrowser for help on using the repository browser.