diff options
Diffstat (limited to 'meta/recipes-core/glibc/glibc/eglibc.patch')
-rw-r--r-- | meta/recipes-core/glibc/glibc/eglibc.patch | 602 |
1 files changed, 602 insertions, 0 deletions
diff --git a/meta/recipes-core/glibc/glibc/eglibc.patch b/meta/recipes-core/glibc/glibc/eglibc.patch new file mode 100644 index 0000000000..fdfabc3a06 --- /dev/null +++ b/meta/recipes-core/glibc/glibc/eglibc.patch | |||
@@ -0,0 +1,602 @@ | |||
1 | Instruction documents from eglibc | ||
2 | |||
3 | Upstream-Status: Pending | ||
4 | |||
5 | Index: git/EGLIBC.cross-building | ||
6 | =================================================================== | ||
7 | --- /dev/null 1970-01-01 00:00:00.000000000 +0000 | ||
8 | +++ git/EGLIBC.cross-building 2014-08-27 07:27:25.580070587 +0000 | ||
9 | @@ -0,0 +1,383 @@ | ||
10 | + -*- mode: text -*- | ||
11 | + | ||
12 | + Cross-Compiling EGLIBC | ||
13 | + Jim Blandy <jimb@codesourcery.com> | ||
14 | + | ||
15 | + | ||
16 | +Introduction | ||
17 | + | ||
18 | +Most GNU tools have a simple build procedure: you run their | ||
19 | +'configure' script, and then you run 'make'. Unfortunately, the | ||
20 | +process of cross-compiling the GNU C library is quite a bit more | ||
21 | +involved: | ||
22 | + | ||
23 | +1) Build a cross-compiler, with certain facilities disabled. | ||
24 | + | ||
25 | +2) Configure the C library using the compiler you built in step 1). | ||
26 | + Build a few of the C run-time object files, but not the rest of the | ||
27 | + library. Install the library's header files and the run-time | ||
28 | + object files, and create a dummy libc.so. | ||
29 | + | ||
30 | +3) Build a second cross-compiler, using the header files and object | ||
31 | + files you installed in step 2. | ||
32 | + | ||
33 | +4) Configure, build, and install a fresh C library, using the compiler | ||
34 | + built in step 3. | ||
35 | + | ||
36 | +5) Build a third cross-compiler, based on the C library built in step 4. | ||
37 | + | ||
38 | +The reason for this complexity is that, although GCC and the GNU C | ||
39 | +library are distributed separately, they are not actually independent | ||
40 | +of each other: GCC requires the C library's headers and some object | ||
41 | +files to compile its own libraries, while the C library depends on | ||
42 | +GCC's libraries. EGLIBC includes features and bug fixes to the stock | ||
43 | +GNU C library that simplify this process, but the fundamental | ||
44 | +interdependency stands. | ||
45 | + | ||
46 | +In this document, we explain how to cross-compile an EGLIBC/GCC pair | ||
47 | +from source. Our intended audience is developers who are already | ||
48 | +familiar with the GNU toolchain and comfortable working with | ||
49 | +cross-development tools. While we do present a worked example to | ||
50 | +accompany the explanation, for clarity's sake we do not cover many of | ||
51 | +the options available to cross-toolchain users. | ||
52 | + | ||
53 | + | ||
54 | +Preparation | ||
55 | + | ||
56 | +EGLIBC requires recent versions of the GNU binutils, GCC, and the | ||
57 | +Linux kernel. The web page <http://www.eglibc.org/prerequisites> | ||
58 | +documents the current requirements, and lists patches needed for | ||
59 | +certain target architectures. As of this writing, these build | ||
60 | +instructions have been tested with binutils 2.22.51, GCC 4.6.2, | ||
61 | +and Linux 3.1. | ||
62 | + | ||
63 | +First, let's set some variables, to simplify later commands. We'll | ||
64 | +build EGLIBC and GCC for an ARM target, known to the Linux kernel | ||
65 | +as 'arm', and we'll do the build on an Intel x86_64 Linux box: | ||
66 | + | ||
67 | + $ build=x86_64-pc-linux-gnu | ||
68 | + $ host=$build | ||
69 | + $ target=arm-none-linux-gnueabi | ||
70 | + $ linux_arch=arm | ||
71 | + | ||
72 | +We're using the aforementioned versions of Binutils, GCC, and Linux: | ||
73 | + | ||
74 | + $ binutilsv=binutils-2.22.51 | ||
75 | + $ gccv=gcc-4.6.2 | ||
76 | + $ linuxv=linux-3.1 | ||
77 | + | ||
78 | +We're carrying out the entire process under '~/cross-build', which | ||
79 | +contains unpacked source trees for binutils, gcc, and linux kernel, | ||
80 | +along with EGLIBC svn trunk (which can be checked-out with | ||
81 | +'svn co http://www.eglibc.org/svn/trunk eglibc'): | ||
82 | + | ||
83 | + $ top=$HOME/cross-build/$target | ||
84 | + $ src=$HOME/cross-build/src | ||
85 | + $ ls $src | ||
86 | + binutils-2.22.51 eglibc gcc-4.6.2 linux-3.1 | ||
87 | + | ||
88 | +We're going to place our build directories in a subdirectory 'obj', | ||
89 | +we'll install the cross-development toolchain in 'tools', and we'll | ||
90 | +place our sysroot (containing files to be installed on the target | ||
91 | +system) in 'sysroot': | ||
92 | + | ||
93 | + $ obj=$top/obj | ||
94 | + $ tools=$top/tools | ||
95 | + $ sysroot=$top/sysroot | ||
96 | + | ||
97 | + | ||
98 | +Binutils | ||
99 | + | ||
100 | +Configuring and building binutils for the target is straightforward: | ||
101 | + | ||
102 | + $ mkdir -p $obj/binutils | ||
103 | + $ cd $obj/binutils | ||
104 | + $ $src/$binutilsv/configure \ | ||
105 | + > --target=$target \ | ||
106 | + > --prefix=$tools \ | ||
107 | + > --with-sysroot=$sysroot | ||
108 | + $ make | ||
109 | + $ make install | ||
110 | + | ||
111 | + | ||
112 | +The First GCC | ||
113 | + | ||
114 | +For our work, we need a cross-compiler targeting an ARM Linux | ||
115 | +system. However, that configuration includes the shared library | ||
116 | +'libgcc_s.so', which is compiled against the EGLIBC headers (which we | ||
117 | +haven't installed yet) and linked against 'libc.so' (which we haven't | ||
118 | +built yet). | ||
119 | + | ||
120 | +Fortunately, there are configuration options for GCC which tell it not | ||
121 | +to build 'libgcc_s.so'. The '--without-headers' option is supposed to | ||
122 | +take care of this, but its implementation is incomplete, so you must | ||
123 | +also configure with the '--with-newlib' option. While '--with-newlib' | ||
124 | +appears to mean "Use the Newlib C library", its effect is to tell the | ||
125 | +GCC build machinery, "Don't assume there is a C library available." | ||
126 | + | ||
127 | +We also need to disable some of the libraries that would normally be | ||
128 | +built along with GCC, and specify that only the compiler for the C | ||
129 | +language is needed. | ||
130 | + | ||
131 | +So, we create a build directory, configure, make, and install. | ||
132 | + | ||
133 | + $ mkdir -p $obj/gcc1 | ||
134 | + $ cd $obj/gcc1 | ||
135 | + $ $src/$gccv/configure \ | ||
136 | + > --target=$target \ | ||
137 | + > --prefix=$tools \ | ||
138 | + > --without-headers --with-newlib \ | ||
139 | + > --disable-shared --disable-threads --disable-libssp \ | ||
140 | + > --disable-libgomp --disable-libmudflap --disable-libquadmath \ | ||
141 | + > --disable-decimal-float --disable-libffi \ | ||
142 | + > --enable-languages=c | ||
143 | + $ PATH=$tools/bin:$PATH make | ||
144 | + $ PATH=$tools/bin:$PATH make install | ||
145 | + | ||
146 | + | ||
147 | +Linux Kernel Headers | ||
148 | + | ||
149 | +To configure EGLIBC, we also need Linux kernel headers in place. | ||
150 | +Fortunately, the Linux makefiles have a target that installs them for | ||
151 | +us. Since the process does modify the source tree a bit, we make a | ||
152 | +copy first: | ||
153 | + | ||
154 | + $ cp -r $src/$linuxv $obj/linux | ||
155 | + $ cd $obj/linux | ||
156 | + | ||
157 | +Now we're ready to install the headers into the sysroot: | ||
158 | + | ||
159 | + $ PATH=$tools/bin:$PATH \ | ||
160 | + > make headers_install \ | ||
161 | + > ARCH=$linux_arch CROSS_COMPILE=$target- \ | ||
162 | + > INSTALL_HDR_PATH=$sysroot/usr | ||
163 | + | ||
164 | + | ||
165 | +EGLIBC Headers and Preliminary Objects | ||
166 | + | ||
167 | +Using the cross-compiler we've just built, we can now configure EGLIBC | ||
168 | +well enough to install the headers and build the object files that the | ||
169 | +full cross-compiler will need: | ||
170 | + | ||
171 | + $ mkdir -p $obj/eglibc-headers | ||
172 | + $ cd $obj/eglibc-headers | ||
173 | + $ BUILD_CC=gcc \ | ||
174 | + > CC=$tools/bin/$target-gcc \ | ||
175 | + > CXX=$tools/bin/$target-g++ \ | ||
176 | + > AR=$tools/bin/$target-ar \ | ||
177 | + > RANLIB=$tools/bin/$target-ranlib \ | ||
178 | + > $src/eglibc/libc/configure \ | ||
179 | + > --prefix=/usr \ | ||
180 | + > --with-headers=$sysroot/usr/include \ | ||
181 | + > --build=$build \ | ||
182 | + > --host=$target \ | ||
183 | + > --disable-profile --without-gd --without-cvs \ | ||
184 | + > --enable-add-ons=nptl,libidn,../ports | ||
185 | + | ||
186 | +The option '--prefix=/usr' may look strange, but you should never | ||
187 | +configure EGLIBC with a prefix other than '/usr': in various places, | ||
188 | +EGLIBC's build system checks whether the prefix is '/usr', and does | ||
189 | +special handling only if that is the case. Unless you use this | ||
190 | +prefix, you will get a sysroot that does not use the standard Linux | ||
191 | +directory layouts and cannot be used as a basis for the root | ||
192 | +filesystem on your target system compatibly with normal GLIBC | ||
193 | +installations. | ||
194 | + | ||
195 | +The '--with-headers' option tells EGLIBC where the Linux headers have | ||
196 | +been installed. | ||
197 | + | ||
198 | +The '--enable-add-ons=nptl,libidn,../ports' option tells EGLIBC to look | ||
199 | +for the listed glibc add-ons. Most notably the ports add-on (located | ||
200 | +just above the libc sources in the EGLIBC svn tree) is required to | ||
201 | +support ARM targets. | ||
202 | + | ||
203 | +We can now use the 'install-headers' makefile target to install the | ||
204 | +headers: | ||
205 | + | ||
206 | + $ make install-headers install_root=$sysroot \ | ||
207 | + > install-bootstrap-headers=yes | ||
208 | + | ||
209 | +The 'install_root' variable indicates where the files should actually | ||
210 | +be installed; its value is treated as the parent of the '--prefix' | ||
211 | +directory we passed to the configure script, so the headers will go in | ||
212 | +'$sysroot/usr/include'. The 'install-bootstrap-headers' variable | ||
213 | +requests special handling for certain tricky header files. | ||
214 | + | ||
215 | +Next, there are a few object files needed to link shared libraries, | ||
216 | +which we build and install by hand: | ||
217 | + | ||
218 | + $ mkdir -p $sysroot/usr/lib | ||
219 | + $ make csu/subdir_lib | ||
220 | + $ cp csu/crt1.o csu/crti.o csu/crtn.o $sysroot/usr/lib | ||
221 | + | ||
222 | +Finally, 'libgcc_s.so' requires a 'libc.so' to link against. However, | ||
223 | +since we will never actually execute its code, it doesn't matter what | ||
224 | +it contains. So, treating '/dev/null' as a C source file, we produce | ||
225 | +a dummy 'libc.so' in one step: | ||
226 | + | ||
227 | + $ $tools/bin/$target-gcc -nostdlib -nostartfiles -shared -x c /dev/null \ | ||
228 | + > -o $sysroot/usr/lib/libc.so | ||
229 | + | ||
230 | + | ||
231 | +The Second GCC | ||
232 | + | ||
233 | +With the EGLIBC headers and selected object files installed, we can | ||
234 | +now build a GCC that is capable of compiling EGLIBC. We configure, | ||
235 | +build, and install the second GCC, again building only the C compiler, | ||
236 | +and avoiding libraries we won't use: | ||
237 | + | ||
238 | + $ mkdir -p $obj/gcc2 | ||
239 | + $ cd $obj/gcc2 | ||
240 | + $ $src/$gccv/configure \ | ||
241 | + > --target=$target \ | ||
242 | + > --prefix=$tools \ | ||
243 | + > --with-sysroot=$sysroot \ | ||
244 | + > --disable-libssp --disable-libgomp --disable-libmudflap \ | ||
245 | + > --disable-libffi --disable-libquadmath \ | ||
246 | + > --enable-languages=c | ||
247 | + $ PATH=$tools/bin:$PATH make | ||
248 | + $ PATH=$tools/bin:$PATH make install | ||
249 | + | ||
250 | + | ||
251 | +EGLIBC, Complete | ||
252 | + | ||
253 | +With the second compiler built and installed, we're now ready for the | ||
254 | +full EGLIBC build: | ||
255 | + | ||
256 | + $ mkdir -p $obj/eglibc | ||
257 | + $ cd $obj/eglibc | ||
258 | + $ BUILD_CC=gcc \ | ||
259 | + > CC=$tools/bin/$target-gcc \ | ||
260 | + > CXX=$tools/bin/$target-g++ \ | ||
261 | + > AR=$tools/bin/$target-ar \ | ||
262 | + > RANLIB=$tools/bin/$target-ranlib \ | ||
263 | + > $src/eglibc/libc/configure \ | ||
264 | + > --prefix=/usr \ | ||
265 | + > --with-headers=$sysroot/usr/include \ | ||
266 | + > --with-kconfig=$obj/linux/scripts/kconfig \ | ||
267 | + > --build=$build \ | ||
268 | + > --host=$target \ | ||
269 | + > --disable-profile --without-gd --without-cvs \ | ||
270 | + > --enable-add-ons=nptl,libidn,../ports | ||
271 | + | ||
272 | +Note the additional '--with-kconfig' option. This tells EGLIBC where to | ||
273 | +find the host config tools used by the kernel 'make config' and 'make | ||
274 | +menuconfig'. These tools can be re-used by EGLIBC for its own 'make | ||
275 | +*config' support, which will create 'option-groups.config' for you. | ||
276 | +But first make sure those tools have been built by running some | ||
277 | +dummy 'make *config' calls in the kernel directory: | ||
278 | + | ||
279 | + $ cd $obj/linux | ||
280 | + $ PATH=$tools/bin:$PATH make config \ | ||
281 | + > ARCH=$linux_arch CROSS_COMPILE=$target- \ | ||
282 | + $ PATH=$tools/bin:$PATH make menuconfig \ | ||
283 | + > ARCH=$linux_arch CROSS_COMPILE=$target- \ | ||
284 | + | ||
285 | +Now we can configure and build the full EGLIBC: | ||
286 | + | ||
287 | + $ cd $obj/eglibc | ||
288 | + $ PATH=$tools/bin:$PATH make defconfig | ||
289 | + $ PATH=$tools/bin:$PATH make menuconfig | ||
290 | + $ PATH=$tools/bin:$PATH make | ||
291 | + $ PATH=$tools/bin:$PATH make install install_root=$sysroot | ||
292 | + | ||
293 | +At this point, we have a complete EGLIBC installation in '$sysroot', | ||
294 | +with header files, library files, and most of the C runtime startup | ||
295 | +files in place. | ||
296 | + | ||
297 | + | ||
298 | +The Third GCC | ||
299 | + | ||
300 | +Finally, we recompile GCC against this full installation, enabling | ||
301 | +whatever languages and libraries we would like to use: | ||
302 | + | ||
303 | + $ mkdir -p $obj/gcc3 | ||
304 | + $ cd $obj/gcc3 | ||
305 | + $ $src/$gccv/configure \ | ||
306 | + > --target=$target \ | ||
307 | + > --prefix=$tools \ | ||
308 | + > --with-sysroot=$sysroot \ | ||
309 | + > --enable-__cxa_atexit \ | ||
310 | + > --disable-libssp --disable-libgomp --disable-libmudflap \ | ||
311 | + > --enable-languages=c,c++ | ||
312 | + $ PATH=$tools/bin:$PATH make | ||
313 | + $ PATH=$tools/bin:$PATH make install | ||
314 | + | ||
315 | +The '--enable-__cxa_atexit' option tells GCC what sort of C++ | ||
316 | +destructor support to expect from the C library; it's required with | ||
317 | +EGLIBC. | ||
318 | + | ||
319 | +And since GCC's installation process isn't designed to help construct | ||
320 | +sysroot trees, we must manually copy certain libraries into place in | ||
321 | +the sysroot. | ||
322 | + | ||
323 | + $ cp -d $tools/$target/lib/libgcc_s.so* $sysroot/lib | ||
324 | + $ cp -d $tools/$target/lib/libstdc++.so* $sysroot/usr/lib | ||
325 | + | ||
326 | + | ||
327 | +Trying Things Out | ||
328 | + | ||
329 | +At this point, '$tools' contains a cross toolchain ready to use | ||
330 | +the EGLIBC installation in '$sysroot': | ||
331 | + | ||
332 | + $ cat > hello.c <<EOF | ||
333 | + > #include <stdio.h> | ||
334 | + > int | ||
335 | + > main (int argc, char **argv) | ||
336 | + > { | ||
337 | + > puts ("Hello, world!"); | ||
338 | + > return 0; | ||
339 | + > } | ||
340 | + > EOF | ||
341 | + $ $tools/bin/$target-gcc -Wall hello.c -o hello | ||
342 | + $ cat > c++-hello.cc <<EOF | ||
343 | + > #include <iostream> | ||
344 | + > int | ||
345 | + > main (int argc, char **argv) | ||
346 | + > { | ||
347 | + > std::cout << "Hello, C++ world!" << std::endl; | ||
348 | + > return 0; | ||
349 | + > } | ||
350 | + > EOF | ||
351 | + $ $tools/bin/$target-g++ -Wall c++-hello.cc -o c++-hello | ||
352 | + | ||
353 | + | ||
354 | +We can use 'readelf' to verify that these are indeed executables for | ||
355 | +our target, using our dynamic linker: | ||
356 | + | ||
357 | + $ $tools/bin/$target-readelf -hl hello | ||
358 | + ELF Header: | ||
359 | + ... | ||
360 | + Type: EXEC (Executable file) | ||
361 | + Machine: ARM | ||
362 | + | ||
363 | + ... | ||
364 | + Program Headers: | ||
365 | + Type Offset VirtAddr PhysAddr FileSiz MemSiz Flg Align | ||
366 | + PHDR 0x000034 0x10000034 0x10000034 0x00100 0x00100 R E 0x4 | ||
367 | + INTERP 0x000134 0x00008134 0x00008134 0x00013 0x00013 R 0x1 | ||
368 | + [Requesting program interpreter: /lib/ld-linux.so.3] | ||
369 | + LOAD 0x000000 0x00008000 0x00008000 0x0042c 0x0042c R E 0x8000 | ||
370 | + ... | ||
371 | + | ||
372 | +Looking at the dynamic section of the installed 'libgcc_s.so', we see | ||
373 | +that the 'NEEDED' entry for the C library does include the '.6' | ||
374 | +suffix, indicating that was linked against our fully build EGLIBC, and | ||
375 | +not our dummy 'libc.so': | ||
376 | + | ||
377 | + $ $tools/bin/$target-readelf -d $sysroot/lib/libgcc_s.so.1 | ||
378 | + Dynamic section at offset 0x1083c contains 24 entries: | ||
379 | + Tag Type Name/Value | ||
380 | + 0x00000001 (NEEDED) Shared library: [libc.so.6] | ||
381 | + 0x0000000e (SONAME) Library soname: [libgcc_s.so.1] | ||
382 | + ... | ||
383 | + | ||
384 | + | ||
385 | +And on the target machine, we can run our programs: | ||
386 | + | ||
387 | + $ $sysroot/lib/ld.so.1 --library-path $sysroot/lib:$sysroot/usr/lib \ | ||
388 | + > ./hello | ||
389 | + Hello, world! | ||
390 | + $ $sysroot/lib/ld.so.1 --library-path $sysroot/lib:$sysroot/usr/lib \ | ||
391 | + > ./c++-hello | ||
392 | + Hello, C++ world! | ||
393 | Index: git/EGLIBC.cross-testing | ||
394 | =================================================================== | ||
395 | --- /dev/null 1970-01-01 00:00:00.000000000 +0000 | ||
396 | +++ git/EGLIBC.cross-testing 2014-08-27 07:24:41.532070587 +0000 | ||
397 | @@ -0,0 +1,205 @@ | ||
398 | + -*- mode: text -*- | ||
399 | + | ||
400 | + Cross-Testing With EGLIBC | ||
401 | + Jim Blandy <jimb@codesourcery.com> | ||
402 | + | ||
403 | + | ||
404 | +Introduction | ||
405 | + | ||
406 | +Developers writing software for embedded systems often use a desktop | ||
407 | +or other similarly capable computer for development, but need to run | ||
408 | +tests on the embedded system, or perhaps on a simulator. When | ||
409 | +configured for cross-compilation, the stock GNU C library simply | ||
410 | +disables running tests altogether: the command 'make tests' builds | ||
411 | +test programs, but does not run them. EGLIBC, however, provides | ||
412 | +facilities for compiling tests and generating data files on the build | ||
413 | +system, but running the test programs themselves on a remote system or | ||
414 | +simulator. | ||
415 | + | ||
416 | + | ||
417 | +Test environment requirements | ||
418 | + | ||
419 | +The test environment must meet certain conditions for EGLIBC's | ||
420 | +cross-testing facilities to work: | ||
421 | + | ||
422 | +- Shared filesystems. The 'build' system, on which you configure and | ||
423 | + compile EGLIBC, and the 'host' system, on which you intend to run | ||
424 | + EGLIBC, must share a filesystem containing the EGLIBC build and | ||
425 | + source trees. Files must appear at the same paths on both systems. | ||
426 | + | ||
427 | +- Remote-shell like invocation. There must be a way to run a program | ||
428 | + on the host system from the build system, passing it properly quoted | ||
429 | + command-line arguments, setting environment variables, and | ||
430 | + inheriting the caller's standard input and output. | ||
431 | + | ||
432 | + | ||
433 | +Usage | ||
434 | + | ||
435 | +To use EGLIBC's cross-testing support, provide values for the | ||
436 | +following Make variables when you invoke 'make': | ||
437 | + | ||
438 | +- cross-test-wrapper | ||
439 | + | ||
440 | + This should be the name of the cross-testing wrapper command, along | ||
441 | + with any arguments. | ||
442 | + | ||
443 | +- cross-localedef | ||
444 | + | ||
445 | + This should be the name of a cross-capable localedef program, like | ||
446 | + that included in the EGLIBC 'localedef' module, along with any | ||
447 | + arguments needed. | ||
448 | + | ||
449 | +These are each explained in detail below. | ||
450 | + | ||
451 | + | ||
452 | +The Cross-Testing Wrapper | ||
453 | + | ||
454 | +To run test programs reliably, the stock GNU C library takes care to | ||
455 | +ensure that test programs use the newly compiled dynamic linker and | ||
456 | +shared libraries, and never the host system's installed libraries. To | ||
457 | +accomplish this, it runs the tests by explicitly invoking the dynamic | ||
458 | +linker from the build tree, passing it a list of build tree | ||
459 | +directories to search for shared libraries, followed by the name of | ||
460 | +the executable to run and its arguments. | ||
461 | + | ||
462 | +For example, where one might normally run a test program like this: | ||
463 | + | ||
464 | + $ ./tst-foo arg1 arg2 | ||
465 | + | ||
466 | +the GNU C library might run that program like this: | ||
467 | + | ||
468 | + $ $objdir/elf/ld-linux.so.3 --library-path $objdir \ | ||
469 | + ./tst-foo arg1 arg2 | ||
470 | + | ||
471 | +(where $objdir is the path to the top of the build tree, and the | ||
472 | +trailing backslash indicates a continuation of the command). In other | ||
473 | +words, each test program invocation is 'wrapped up' inside an explicit | ||
474 | +invocation of the dynamic linker, which must itself execute the test | ||
475 | +program, having loaded shared libraries from the appropriate | ||
476 | +directories. | ||
477 | + | ||
478 | +To support cross-testing, EGLIBC allows the developer to optionally | ||
479 | +set the 'cross-test-wrapper' Make variable to another wrapper command, | ||
480 | +to which it passes the entire dynamic linker invocation shown above as | ||
481 | +arguments. For example, if the developer supplies a wrapper of | ||
482 | +'my-wrapper hostname', then EGLIBC would run the test above as | ||
483 | +follows: | ||
484 | + | ||
485 | + $ my-wrapper hostname \ | ||
486 | + $objdir/elf/ld-linux.so.3 --library-path $objdir \ | ||
487 | + ./tst-foo arg1 arg2 | ||
488 | + | ||
489 | +The 'my-wrapper' command is responsible for executing the command | ||
490 | +given on the host system. | ||
491 | + | ||
492 | +Since tests are run in varying directories, the wrapper should either | ||
493 | +be in your command search path, or 'cross-test-wrapper' should give an | ||
494 | +absolute path for the wrapper. | ||
495 | + | ||
496 | +The wrapper must meet several requirements: | ||
497 | + | ||
498 | +- It must preserve the current directory. As explained above, the | ||
499 | + build directory tree must be visible on both the build and host | ||
500 | + systems, at the same path. The test wrapper must ensure that the | ||
501 | + current directory it inherits is also inherited by the dynamic | ||
502 | + linker (and thus the test program itself). | ||
503 | + | ||
504 | +- It must preserve environment variables' values. Many EGLIBC tests | ||
505 | + set environment variables for test runs; in native testing, it | ||
506 | + invokes programs like this: | ||
507 | + | ||
508 | + $ GCONV_PATH=$objdir/iconvdata \ | ||
509 | + $objdir/elf/ld-linux.so.3 --library-path $objdir \ | ||
510 | + ./tst-foo arg1 arg2 | ||
511 | + | ||
512 | + With the cross-testing wrapper, that invocation becomes: | ||
513 | + | ||
514 | + $ GCONV_PATH=$objdir/iconvdata \ | ||
515 | + my-wrapper hostname \ | ||
516 | + $objdir/elf/ld-linux.so.3 --library-path $objdir \ | ||
517 | + ./tst-foo arg1 arg2 | ||
518 | + | ||
519 | + Here, 'my-wrapper' must ensure that the value it sees for | ||
520 | + 'GCONV_PATH' will be seen by the dynamic linker, and thus 'tst-foo' | ||
521 | + itself. (The wrapper supplied with GLIBC simply preserves the | ||
522 | + values of *all* enviroment variables, with a fixed set of | ||
523 | + exceptions.) | ||
524 | + | ||
525 | + If your wrapper is a shell script, take care to correctly propagate | ||
526 | + environment variables whose values contain spaces and shell | ||
527 | + metacharacters. | ||
528 | + | ||
529 | +- It must pass the command's arguments, unmodified. The arguments | ||
530 | + seen by the test program should be exactly those seen by the wrapper | ||
531 | + (after whatever arguments are given to the wrapper itself). The | ||
532 | + EGLIBC test framework performs all needed shell word splitting and | ||
533 | + expansion (wildcard expansion, parameter substitution, and so on) | ||
534 | + before invoking the wrapper; further expansion may break the tests. | ||
535 | + | ||
536 | + | ||
537 | +The 'cross-test-ssh.sh' script | ||
538 | + | ||
539 | +If you want to use 'ssh' (or something sufficiently similar) to run | ||
540 | +test programs on your host system, EGLIBC includes a shell script, | ||
541 | +'scripts/cross-test-ssh.sh', which you can use as your wrapper | ||
542 | +command. This script takes care of setting the test command's current | ||
543 | +directory, propagating environment variable values, and carrying | ||
544 | +command-line arguments, all across an 'ssh' connection. You may even | ||
545 | +supply an alternative to 'ssh' on the command line, if needed. | ||
546 | + | ||
547 | +For more details, pass 'cross-test-ssh.sh' the '--help' option. | ||
548 | + | ||
549 | + | ||
550 | +The Cross-Compiling Locale Definition Command | ||
551 | + | ||
552 | +Some EGLIBC tests rely on locales generated especially for the test | ||
553 | +process. In a native configuration, these tests simply run the | ||
554 | +'localedef' command built by the normal EGLIBC build process, | ||
555 | +'locale/localedef', to process and install their locales. However, in | ||
556 | +a cross-compiling configuration, this 'localedef' is built for the | ||
557 | +host system, not the build system, and since it requires quite a bit | ||
558 | +of memory to run (we have seen it fail on systems with 64MiB of | ||
559 | +memory), it may not be practical to run it on the host system. | ||
560 | + | ||
561 | +If set, EGLIBC uses the 'cross-localedef' Make variable as the command | ||
562 | +to run on the build system to process and install locales. The | ||
563 | +localedef program built from the EGLIBC 'localedef' module is | ||
564 | +suitable. | ||
565 | + | ||
566 | +The value of 'cross-localedef' may also include command-line arguments | ||
567 | +to be passed to the program; if you are using EGLIBC's 'localedef', | ||
568 | +you may include endianness and 'uint32_t' alignment arguments here. | ||
569 | + | ||
570 | + | ||
571 | +Example | ||
572 | + | ||
573 | +In developing EGLIBC's cross-testing facility, we invoked 'make' with | ||
574 | +the following script: | ||
575 | + | ||
576 | + #!/bin/sh | ||
577 | + | ||
578 | + srcdir=... | ||
579 | + test_hostname=... | ||
580 | + localedefdir=... | ||
581 | + cross_gxx=...-g++ | ||
582 | + | ||
583 | + wrapper="$srcdir/scripts/cross-test-ssh.sh $test_hostname" | ||
584 | + localedef="$localedefdir/localedef --little-endian --uint32-align=4" | ||
585 | + | ||
586 | + make cross-test-wrapper="$wrapper" \ | ||
587 | + cross-localedef="$localedef" \ | ||
588 | + CXX="$cross_gxx" \ | ||
589 | + "$@" | ||
590 | + | ||
591 | + | ||
592 | +Other Cross-Testing Concerns | ||
593 | + | ||
594 | +Here are notes on some other issues which you may encounter in running | ||
595 | +the EGLIBC tests in a cross-compiling environment: | ||
596 | + | ||
597 | +- Some tests require a C++ cross-compiler; you should set the 'CXX' | ||
598 | + Make variable to the name of an appropriate cross-compiler. | ||
599 | + | ||
600 | +- Some tests require access to libstdc++.so.6 and libgcc_s.so.1; we | ||
601 | + simply place copies of these libraries in the top EGLIBC build | ||
602 | + directory. | ||