annotate www/documentation.html @ 1558:3a213739ee1c

Pipe stderr through maybe_quiet in for-each-target.sh.
author Rob Landley <rob@landley.net>
date Tue, 13 Nov 2012 13:55:10 -0600
parents d4eb237dcc6f
children 307f4415d2bf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
881
0da87d1ef528 Update the web page. Put the left-side nav bar back, move about page to "about.html" and make news.html the default index. Add architectures page. Note that IRC discussion is now on #edev.
Rob Landley <rob@landley.net>
parents: 830
diff changeset
1 <!--#include file="header.html" -->
0da87d1ef528 Update the web page. Put the left-side nav bar back, move about page to "about.html" and make news.html the default index. Add architectures page. Note that IRC discussion is now on #edev.
Rob Landley <rob@landley.net>
parents: 830
diff changeset
2
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
3 <h1>Documentation for Aboriginal Linux</h1>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
4
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
5 <ul>
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
6 <li><a href="#what_is_it">What is Aboriginal Linux?</a></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
7 <li><a href="#how_system_image">How do I use system images?</a></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
8 <li><a href="#how_build_source">How do I build my own customized system images from source code?</a></li>
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
9 <li><a href="#how_implemented">How is Aboriginal Linux implemented?</a></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
10 <li><a href="#why">Why do things this way?</a></li>
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
11 <li><a href="#new_platform">Adding a new target platform</a></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
12 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
13
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
14 <hr />
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
15 <a name="what_is_it"><h1>What is Aboriginal Linux?</h1></a>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
16
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
17 <p>Aboriginal Linux is a toolkit for building custom virtual machines.
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
18 It lets you boot virtual PowerPC, ARM, MIPS and other exotic systems
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
19 on your x86 laptop, and do development in them.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
20
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
21 <p>The name "Aboriginal Linux" describes the project's goal of bootstrapping
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
22 a new Linux for a new target, doing all the cross compiling necessary to
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
23 transition to fully native development in the new environment. This new
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
24 Linux system can then be upgraded or replaced in-situ.</p>
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
25
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
26 <p>Aboriginal Linux provides an easy way to get started with embedded
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
27 development. It also lets you build your own code against uClibc and
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
28 test it on various hardware platforms, and even perform
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
29 cross-platform regression testing or portability auditing.</p>
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
30
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
31 <p>This documentation uses the name "Aboriginal Linux"
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
32 to refer to the <a href=downloads>build system</a> consisting of a series
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
33 of bash scripts and configuration files which download and compile software.
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
34 The output of that build system is referred to as a "<a
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
35 href=downloads/binaries>system image</a>". The build system
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
36 compiles a Linux development environment for the specified
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
37 target system, and packages it into a bootable binary system image.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
38
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
39 <p>The base development environment is built from seven source
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
40 packages: busybox, uClibc, gcc, binutils, make, bash, and the Linux
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
41 kernel. This is the smallest and simplest environment that can rebuild itself
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
42 entirely from source code, and thus the minimum a host system must
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
43 cross compile in order to create a fully independent native
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
44 development environment for a target.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
45
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
46 <p>Booting a development system image under an emulator such as <a
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
47 href=http://bellard.org/qemu/>QEMU</a> allows fully native builds for
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
48 supported target platforms to be performed on cheap and powerful
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
49 commodity PC hardware. You can then build and install additional
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
50 packages (zlib, bison, openssl...) within the virtual machine's native
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
51 development environment, without having to do any additional cross
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
52 compiling. Several <a href=downloads/binaries/control-images>build control
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
53 images</a> are provided to automate this task, and you're welcome to
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
54 create your own from those examples.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
55
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
56 <p>Aboriginal Linux currently includes full support for arm, mips, powerpc, x86,
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
57 x86-64 targets, and several other more exotic platforms; see the <a
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
58 href=screenshots>screenshots page</a> for a complete list. The goal
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
59 project is to support every target QEMU can emulate in "system" mode.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
60
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
61 <p>Aboriginal Linux is licensed under GPL version 2. Its component packages are
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
62 redistributed under their respective licenses (mostly GPL and LGPL).</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
63
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
64 <h2>Optional extras</h2>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
65
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
66 <p>Intermediate stages of the build (such as the cross compiler and the
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
67 the raw root filesystem directory) may also be useful to Linux developers,
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
68 so tarballs of them are saved during the build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
69
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
70 <p>By default the build cross-compiles some optional extra packages (distcc
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
71 and uClibc++) and preinstalls them into the target filesystem. This is
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
72 just a convenience; these packages build and install natively within the
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
73 minimal development system image just fine.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
74
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
75 <hr />
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
76 <a name="how_system_image"><h1>Using system images</h1></a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
77
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
78 <p>If you want to jump straight to building your own software natively for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
79 embedded targets, you can <a href=downloads/binaries>download a prebuilt
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
80 binary image</a> instead of running the build scripts to produce your own.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
81
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
82 <p>Here are the different types of output produced by the build:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
83
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
84 <h2>system-image-*.tar.bz2</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
85
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
86 <p>System images boot a complete linux system under an emulator. Each
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
87 system-image tarball contains a squashfs root filesystem image, a Linux kernel
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
88 configured to run under the emulator <a href=http://qemu.org>QEMU</a>,
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
89 and scripts to launch the virtual system under the emulator in various
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1040
diff changeset
90 configurations.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
91
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1040
diff changeset
92 <p>The steps to test boot a system image under QEMU are:</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
93 <ul>
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
94 <li>install QEMU</li>
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1040
diff changeset
95 <li>download the appropriate <a href=downloads/binaries>prebuilt binary tarball</a>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
96 for the target you're interested in</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
97 <li>extract it: <b>tar -xvjf system-image-$TARGET.tar.bz2</b></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
98 <li>cd into it: <b>cd system-image-$TARGET</b></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
99 <li>execute it: <b>./run-emulator.sh</b></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
100 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
101
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
102 <p>This boots the system image under the appropriate emulator, with
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
103 the emulated Linux's /dev/console hooked to stdin and stdout of the emulator
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
104 process. (I.E. the shell prompt the script gives you after the boot messages
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
105 scroll past is for a shell running inside the emulator. This lets you pipe
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
106 the output of other programs into the emulator, capture the emulator's
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
107 output with "tee", cut and paste in the terminal window, etc.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
108
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
109 <p>Type "cat /proc/cpuinfo" to confirm you're running in the emulator, then
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
110 play around and have fun. Type "exit" when done.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
111
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
112 <p>Inside a system image, you generally wget a source code package from a URL
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
113 and compile it. (You can even wget the Aboriginal Linux build scripts and
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
114 run them inside one of the system images to trivially prove the project
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
115 can rebuild itself.)</p>
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
116
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
117 <p>Inside QEMU you can access the host system's loopback interface using the
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
118 special address "10.0.2.2". The build control images use this to run
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
119 busybox's FTP server on the host's loopack address, allowing the system
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
120 image to upload its results to the host at the end of the build. You can
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
121 also run web servers and ssh servers on the host's loopback, and the system
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
122 image can connect to them.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
123
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
124 <h3>Extra space and speed</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
125
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
126 <p>The system images by themselves are fairly small (64 megabytes), and don't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
127 have a lot of scratch space for building or installing other packages. If a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
128 file named "<b>hdb.img</b>" exists in the current directory, run-emulator.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
129 will automatically designate it as a second virtual hard drive and attempt to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
130 mount the whole unpartitioned device on <b>/home</b> inside the emulator.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
131
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
132 <p>Some optional command line arguments to run-emulator.sh provide extra
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
133 space and extra speed for compiling more software:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
134
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
135 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
136 <li><p><b>--make-hdb $MEGABYTES</b> - if the hard drive image to mount on /home
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
137 doesn't already exist, create a sparse file of the indicated size and format
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
138 it ext3.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
139
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
140 <li><p><b>--with-hdb $FILENAME</b> - use specified $FILENAME from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
141 the host as the hard drive image to mount on the emulated system's /home
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
142 (instead of the default "hdb.img"). Fail if it doesn't exist, unless
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
143 --make-hdb was also specified.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
144
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
145 <li><p><b>--with-distcc $CC_PATH</b> - enable the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
146 <a href="#distcc_trick">distcc accelerator trick</a>. This option provides
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
147 the path to an appropriate cross compiler directory, so run-emulator.sh can
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
148 launch a distcc daemon on the host's loopback device configured to call that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
149 cross compiler, and configure the emulated system to call out to that cross
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
150 compiler through distcc.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
151 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
152
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
153 <p>Running an armv4l system image with the cross compiler
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
154 installed in the user's home directory, using a hard drive image in the user's
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
155 home directory (to be created with a size of 2 gigabytes if it doesn't already
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
156 exist) might look like:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
157
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
158 <blockquote><pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
159 <b>./run-emulator.sh --make-hdb 2048 --with-hdb ~/blah.img --with-distcc ~/cross-compiler-armv4l</b>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
160 </pre></blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
161
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
162 <h2>mini-native-*.tar.bz2</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
163
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
164 <p>These <a href=downloads/mini-native>tarballs</a> contain the same root
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
165 filesystem as the corresponding system images, just in an archive
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
166 instead of packaged into a filesystem image.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
167
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
168 <p>If you want to boot your own system image on real hardware instead of an
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
169 emulator, the appropriate mini-native tarball is a good starting point. If
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
170 all you want is a native uClibc development environment for your host, try:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
171
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
172 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
173 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
174 <b>chroot mini-native-x86_64 /usr/chroot-setup.sh</b>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
175 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
176 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
177
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
178 <p>The boot script /usr/qemu-setup.sh or /usr/chroot-setup.sh performs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
179 minimal setup for the appropriate environment, mounting /proc and /sys and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
180 such. It starts a single shell prompt, and automatically cleans up when that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
181 process exits.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
182
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
183 <p>If you're interested in building a more complex development environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
184 within this one (adding zlib and perl and such before building more complicated
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
185 packages), the best way to learn how is to read
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
186 <a href=http://www.linuxfromscratch.org/lfs/view/6.4/>Linux
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
187 From Scratch</a>.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
188
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
189 <p>Note that mini-native is just one potential filesystem layout; the FWL
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
190 build scripts have several other configurations available when you build from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
191 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
192
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
193 <h2>cross-compiler-*.tar.bz2</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
194
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
195 <p>The cross compilers created during the FWL build are relocatable C compilers
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
196 for each target platform. The primary reason for offering each cross compiler
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
197 as a downloadable binary is to implement the <a href="#distcc_trick">distcc
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
198 accelerator trick</a>. Using them to cross compile additional software is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
199 supported, but not recommended.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
200
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
201 <p>If you'd like to use one for something other than distcc, this documentation
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
202 mostly assumes you already know how. Briefly:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
203
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
204 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
205 <li>download the appropriate cross-compiler-$TARGET.tar.bz2</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
206 <li>extract it somewhere (doesn't matter where)</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
207 <li>add the resulting cross-compiler-$TARGET/bin subdirectory to your $PATH</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
208 <li>either use $TARGET-gcc as your compiler, or set your $CROSS_COMPILE prefix
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
209 to "$TARGET-" with a trailing dash.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
210 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
211
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
212 <p>Also, stock up on aspirin and clear a space to beat your head against; you'll
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
213 need both. See <a href="#why_cross_compiling_sucks">why cross compiling
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
214 sucks</a> for more details.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
215
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
216 <p>Note that although this cross compiler has g++, it doesn't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
217 have uClibc++ in its lib or include subdirectories, which is required to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
218 build most c++ programs. If you need extra libraries, it's up to you to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
219 cross-compile and install them into those directories.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
220
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
221 <a name="how_build_source"><h1>How do I build my own customized system images
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
222 from source code?</h1></a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
223
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
224 <p>To build your own root filesystem and system images from source code,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
225 download and run <a href=downloads>the FWL build scripts</a>. You'll
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
226 probably want to start with the most recent <a href=downloads>release
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
227 version</a>, although once you've got the hang of it you might want to follow
1324
abedce270c1e Update a couple more links.
Rob Landley <rob@landley.net>
parents: 1321
diff changeset
228 the <a href=/hg/aboriginal>development version</a>.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
229
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
230 <p>For a quick start, download the tarball, extract it, cd into it, and run
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
231 "<b>./build.sh</b>". This script takes one argument, which is the target to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
232 build for. Run it with no arguments to list available targets.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
233
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
234 <p>This should produce all the tarballs listed in the previous section in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
235 the "build" directory. To perform a clean build, "rm -rf build" and re-run
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
236 build.sh.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
237
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
238 <h2>How building from source works</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
239
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
240 <p>The build system is a series of shell scripts which download, compile,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
241 install, and use the appropriate source packages to generate a system
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
242 image. These shell scripts are designed to be easily read and modified,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
243 acting both as tools to perform a build and as documentation on how to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
244 build these packages.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
245
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
246 <p>The <b>build.sh</b> script is a simple wrapper which calls the following
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
247 other scripts in sequence:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
248 <ol>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
249 <li>download.sh</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
250 <li>host-tools.sh</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
251 <li>cross-compiler.sh $TARGET</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
252 <li>mini-native.sh $TARGET</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
253 <li>package-mini-native.sh $TARGET</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
254 </ol>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
255
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
256 <p>In theory, the stages are orthogonal. If you have an existing cross
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
257 compiler, you can add it to the $PATH and skip cross-compiler.sh. Or you
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
258 can use _just_ cross-compiler.sh to create a cross compiler, and then go build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
259 something else with it. The host-tools.sh stage can often be skipped
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
260 entirely.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
261
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
262 <h3>Build stages</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
263
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
264 <p>The following files control the individual stages of the build. Each
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
265 may be called individually, from in the top level directory of FWL:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
266
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
267 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
268 <li><p><b>download.sh</b> - Download source packages from the web.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
269
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
270 <p>This script does not take any arguments. It's a series of calls to a
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
271 download function (defined in sources/include.sh) that checks if an existing
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
272 copy of the tarball matching a defined $SHA1 sum exists in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
273 <b>sources/packages</b> directory, and if not uses wget to fetch it from the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
274 $URL (or else from a series of fallback mirrors). A blank value for $SHA1
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
275 will accept any file as correct, ignoring its contents.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
276
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
277 <p>After downloading all tarballs, the function <b>cleanup_oldfiles</b> deletes
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
278 any unused files from sources/packages (generally previous versions left over
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
279 after a package upgrade while using the development version of the FWL
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
280 build scripts).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
281
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
282 <p>Running this stage with the argument "--extract-all" will extract all
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
283 the tarballs at once, to populate the cache used by setupfor. (This is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
284 primarily used to avoid race conditions when building multiple architectures
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
285 in parallel with build-all-targets.sh. This is an esoteric internal
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
286 detail you can safely ignore if you're not doing that.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
287 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
288
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
289 <li><p><b>host-tools.sh</b> - Set up a known environment on the host</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
290
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
291 <p>This script does not take an arguments. In theory this is an optional step,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
292 and may be omitted, as the binaries produced by this script are not included in
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
293 any of the output tarballs.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
294
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
295 <p>This script populates the <b>build/host</b> directory with
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
296 host versions of the busybox and toybox command line tools (the same ones
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
297 that the target's eventual root filesystem will contain), plus symlinks to the
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
298 host's compiler toolchain (I.E. compiler, linker, assembler, and so on).</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
299
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
300 <p>This allows the calling scripts to trim the $PATH to point to just this
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
301 one directory, which serves several purposes:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
302
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
303 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
304
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
305 <li><p><b>Isolation</b> - This prevents the ./configure stages of the source
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
306 packages from finding and including unexpected dependencies on random things
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
307 installed on the host.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
308
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
309 <li><p><b>Portability</b> - Using a known set of command line utilities
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
310 insulates the build from variations in the host's Linux distribution (such as
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
311 Ubuntu's /bin/echo lacking suport for the -e option).</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
312
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
313 <li><p><b>Testing</b> - It ensures the resulting system can rebuild itself
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
314 under itself, since the initial build was done with the same tools we
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
315 install into the target's root filesystem. The initial build acts as a smoke
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
316 test of most of the packages used to create the resulting system, and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
317 restricting $PATH ensures that no necessary commands are missing. (Variation
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
318 can still show up between x86/arm/powerpc versions, of course.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
319
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
320 <p>It also moves most failures to the beginning. If anything is going to
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
321 break, it's usually the host-tools build. After that runs, we're mostly
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
322 in a known and tested state.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
323
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
324 <li><p><b>Dependency tracking</b> - If we don't explicitly know everything
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
325 we need to build ourselves in the first place, we can't be sure we added
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
326 it to the final system to get a self-hosting environment.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
327 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
328
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
329 <p>A secondary purpose of host-tools.sh is to build packages (such as distcc
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
330 and genext2fs) which might not be installed on the host system. Some of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
331 these aren't needed by build.sh but may be used by later run-emulator.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
332 invocations (such as the ./run-build-image.sh script).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
333
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
334 <p>Note that this script does not attempt to build qemu, due to the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
335 unreasonable requirement of installing gcc 3.x on the host. The FWL build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
336 scripts do not use qemu (except as an optional test at the end of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
337 cross-compiler.sh which is skipped if qemu is not available). You will need
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
338 to install qemu (or another emulator, or find real hardware) to use the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
339 resulting system images, but they should build just fine without it.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
340
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
341 <p>This stage is optional. You don't need to run this stage if you don't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
342 want to. If the build/host directory doesn't exist (or doesn't contain
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
343 a "busybox" executable), the build will use the host's original $PATH.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
344 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
345
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
346 <li><p><b>cross-compiler.sh</b> - Build a cross compiler for the target, for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
347 use by mini-native.sh and the distcc accelerator.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
348
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
349 <p>In order to build binaries for the target, the build must first create
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
350 a cross compiler to build those target binaries with. This script creates
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
351 that cross compiler. If you already have a cross compiler, you can
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
352 supply it here (the easy way is to create a build/cross-compiler-$TARGET/bin
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
353 directory and put "$TARGET-gcc" style symlinks in it) and skip this step.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
354
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
355 <p>This script takes one argument: the architecture to build for. It
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
356 produces a cross compiler that runs on the host system and produces binaries
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
357 that run on the target system. This cross compiler is created using the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
358 source packages binutils, gcc, uClibc, the Linux kernel headers, and a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
359 compiler wrapper to make the compiler relocatable.<</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
360
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
361 <p>The reason for the compiler wrapper is that by default, gcc hardwires
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
362 lots of absolute paths into itself, and thus only runs properly in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
363 directory it was built in. The compiler wrapper rewrites its command line
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
364 to prevent gcc from using its built-in (broken) path logic.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
365
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
366 <p>The build requires a cross-compiler even if the host and target system use
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
367 the same processor because the host and target may use different C libraries.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
368 If the host has glibc and the target uses uClibc, then the (dynamically linked)
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
369 target binaries the compiler produces won't run on the host. (Target binaries
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
370 that won't run on the host are what distinguishes cross-compiling from native
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
371 compiling. Different processors are just one reason for it: glibc vs uClibc
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
372 is another, ELF vs binflat or a.out executable format is a third...)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
373
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
374 <p>This script produces produces a working cross compiler in the build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
375 directory, and saves a tarball of it as "cross-compiler-$TARGET.tar.bz2"
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
376 for use outside the build system. This cross compiler is fully relocatable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
377 (because of the compiler wrapper), so any normal user can extract it into their
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
378 home directory, add cross-compiler-$TARGET/bin to their $PATH, and run
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
379 $TARGET-gcc to create target binaries.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
380 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
381
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
382 <li><p><b>mini-native.sh</b> - Use the cross compiler to create
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
383 a minimal native build environment for the target platform.<p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
384
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
385 <p>This script takes one argument: the architecture to build for.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
386
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
387 <p>This script uses the cross compiler found at
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
388 build/cross-compiler-$ARCH/bin (with $ARCH- prefixes) to build a root
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
389 filesystem for the target, as well as a target Linux kernel configured for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
390 use with qemu. A usable cross compiler is left in the build directory by
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
391 the cross-compiler.sh script, or you can install your own.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
392
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
393 <p>The basic root filesystem consists of busybox and uClibc. If the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
394 configuration variable NATIVE_TOOLCHAIN is set (this is enabled by
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
395 default), this script adds a native compiler to the target, consisting of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
396 linux kernel headers, gcc, binutils, make, and bash. It also adds distcc
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
397 to potentially distribute work to cross compilers living outside the emulator.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
398 This provides a minimal native development environment, which may be expanded
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
399 by building and installing more packages under the existing root filesystem.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
400 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
401
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
402 <li><p><b>package-mini-native.sh</b> - Create an ext2 filesystem image
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
403 of the native root filesystem.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
404
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
405 <p>This script takes one argument: the architecture to package.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
406
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
407 <p>This uses genext2fs to create an ext2 filesystem image from the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
408 build/mini-native-$ARCH directory left by running mini-native.sh, and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
409 creates a system-image-tarball containing the result. It first compiles
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
410 genext2fs and adds it to build/host if the host system hasn't already got a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
411 copy.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
412
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
413 <p>This script also generates a run-emulator.sh script to call the appropriate
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
414 emulator, using the architecture's configuration information.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
415 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
416
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
417 <li><p><b>run-from-build.sh</b> - Runs a system image you compiled from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
418 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
419
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
420 <p>Calls run-emulator.sh in the appropriate build/system-image-$TARGET
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
421 directory, with a 2 gigabyte <b>hdb.img</b> for /home and distcc connected
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
422 to build/cross-compiler/$TARGET. Between runs it calls e2fsck on the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
423 system image's root filesystem.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
424
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
425 <p>This is not technically a build stage, as it isn't called from build.sh,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
426 but it's offered as a convenience for users. It uses the existing
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
427 cross-compiler and system-image directories in build/ and doesn't mess
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
428 with the tarballs that were created from them.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
429 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
430 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
431
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
432 <p>The following generally aren't called directly, but are used by the rest of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
433 the build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
434
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
435 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
436 <li><p><b>config</b> - User definable configuration variables</li></p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
437
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
438 <p>This file contains environment variables which you can set to customize
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
439 the FWL build process. Setting any of these variables to a nonblank value
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
440 changes the build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
441
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
442 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
443 <li><p><b>NATIVE_TOOLCHAIN</b> - This tells mini-native.sh to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
444 include a compiler toolchain (binutils, gcc, bash, make, and distcc).
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
445 Without this, it builds a small uClibc/busybox system. This is the only
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
446 variable enabled by default in config.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
447
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
448 <p>Setting NATIVE_TOOLCHAIN="headers" will leave the libc and kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
449 header files in the appropriate include directory, for use by some other native
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
450 compiler. Building and installing additional tools (such as "make", or a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
451 compiler such as pcc, llvm/clang, or tinycc) then becomes your problem.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
452 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
453
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
454 <li><p><b>NATIVE_TOOLSDIR</b> - This tells mini-native.sh to change the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
455 directory layout to conform to a Linux From Scratch "intermediate" system, with
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
456 everything under a /tools directory. (This provides a cleaner environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
457 for creating a new completely customized system at the root level.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
458 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
459
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
460 <li><p><b>RECORD_COMMANDS</b> - Records all command lines used to build each
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
461 package.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
462
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
463 <p>This inserts a logging wrapper in the $PATH which logs the command lines
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
464 used by the build. Afterwards, the script
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
465 "sources/toys/report_recorded_commands.sh" can generate a big report on which
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
466 commands were used to build each package for each architecture. To get a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
467 single list of the command names used by everything, do:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
468
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
469 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
470 <p>echo $(find build -name "cmdlines.*" | xargs awk '{print $1}' | sort -u)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
471 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
472
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
473 <p>(Note: this will miss things which which call executables at absolute values
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
474 instead of checking $PATH, but the only interesting ones so far are the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
475 #!/bin/bash type lines at the start of shell scripts.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
476 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
477
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
478 <li><p><b>CROSS_BUILD_STATIC</b> - Tells cross-compiler.sh to statically link
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
479 all binaries in the cross compiler toolchain it creates.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
480
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
481 <p>The prebuilt binary versions in the download directory are statically linked
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
482 against uClibc, by building a mini-native environment and re-running the build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
483 under that with CROSS_BUILD_STATIC=1. The sources/build-all-targets.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
484 script can do this automatically with the "--use-static-host $TARGET"
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
485 argument. (Requires QEMU installed.)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
486
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
487 <li><p><b>PREFERRED_MIRROR</b> - Tells download.sh to try to download
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
488 packages from this URL first, before falling back to the normal mirror list.
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
489 For example, "PREFERRED_MIRROR=http://landley.net/aboriginal/mirror".</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
490
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
491 <li><p><b>USE_UNSTABLE</b> - Lists packages to build alternate "unstable"
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
492 versions for.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
493
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
494 <p>The value of this config entry is a comma separate list of packages.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
495
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
496 <p>Many packages in download.sh have an UNSTABLE= tag providing a URL to an
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
497 alternate version. Generally these link to newer versions, often unstable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
498 development versions, for testing purposes.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
499
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
500 <p>In addition to changing the download location, using alternate versions of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
501 packages prepends an "alt-" in front of the package name in various places
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
502 (such as the patches from the sources/patches directory and the configuration
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
503 files used from sources/targets). It changes the behavior of the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
504 "download" and "setupfor" shell functions.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
505 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
506
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
507 <li><p><b>USE_COLOR</b> - Color code the various build stages.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
508
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
509 <p>Enabling this provides a quick visual indicator of which build stage is in
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
510 progress.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
511
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
512 <p>This is disabled by default both because its utility is a matter of taste,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
513 and because finding a half-dozen different colors that work on both white and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
514 black backgrounds is hard, and gnome-terminal can't produce an actual black
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
515 background. (In its default palette, "black" is a fairly light grey.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
516 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
517 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
518 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
519
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
520 <li><p><b>sources/build-all-targets.sh</b> - Build all supported targets
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
521 at once.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
522
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
523 <p>This performs a similar function to build.sh, but for all targets instead
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
524 of just one. It can build targets in parallel with the --fork option, logs the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
525 output of the various build stages, and generates a README.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
526
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
527 <p>This script populates a second output directory, buildall, with its output.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
528 This is probably only of interest to FWL's developers.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
529 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
530 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
531
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
532 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
533 <a name="how_implemented"><h1>How is Firmware Linux implemented?</h1></a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
534
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
535 <h2>Directory layout</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
536
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
537 <p>The top level directory of FWL contains the user interface of FWL (scripts
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
538 the user is expected to call or edit), and the "sources" directory containing
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
539 code that isn't expected to be directly called by end users.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
540 Important directories under sources include:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
541
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
542 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
543 <li><p><b>sources/targets</b> - Configuration information for each target.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
544
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
545 <p>Adding a new target to FWL involves creating a new directory under here
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
546 (which determines the name of the target), and adding two miniconfig files
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
547 (for linux and uClibc), and a "details" file defining environment variables.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
548 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
549
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
550 <li><p><b>sources/packages</b> - Source tarballs for the packages to be built.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
551 This directory starts empty, and is populated by download.sh.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
552
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
553 <li><p><b>sources/native</b> - This directory hierarchy is copied into the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
554 target verbatim (under /usr). It contains the boot script and some sample
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
555 source code.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
556
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
557 <li><p><b>sources/toys</b> - Build utilities, mostly original code written for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
558 FWL. Not necessarily specific to this project, but can't be downloaded from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
559 somewhere else.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
560 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
561
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
562 <p>Output files from running the build scripts, and all temporary files, go
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
563 in the "build" subdirectory. This entire directory can be deleted between
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
564 builds.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
565
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
566 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
567 <li><p><b>build/sources</b> - cached copies of the extracted source tarballs,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
568 so setupfor can "cp -lfR" instead of having to re-extract and re-patch the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
569 source each time.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
570
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
571 <li><p><b>build/host</b> - Output of host-tools.sh. If this directory
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
572 exists and contains a "busybox" executable, include.sh will set the $PATH to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
573 point only to this directory.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
574
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
575 <li><p><b>build/temp-$TARGET</b> - Temporary directory for building each
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
576 target. Feel free to delete this between runs, it should be empty unless
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
577 a build broke, in which case it has the source tree that failed to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
578 build. (The temporary directory for host-tools.sh is "host-temp", in case
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
579 someday somebody creates a $TARGET named "host".)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
580
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
581 <li><p><b>build/cross-compiler-$TARGET</b> - Output directory for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
582 cross-compiler.sh. The corresponding cross-compiler tarball is just an
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
583 archive of this directory. Used by mini-native.sh.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
584
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
585 <li><p><b>build/mini-native-$TARGET</b> - Output directory for mini-native.sh.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
586 The corresponding mini-native tarball is just an archive of this directory.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
587 Used by package-mini-native.sh.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
588
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
589 <li><p><b>build/system-image-$TARGET</b> - Output directory for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
590 package-mini-native.sh. The corresponding system-image tarball is just an
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
591 archive of this directory. Used by run-from-build.sh.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
592 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
593
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
594 <h2>Shared infrastructure</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
595
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
596 <p>The top level file for the behind-the-scenes plumbing is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
597 <b>sources/include.sh</b>. This script is not run directly, but is instead
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
598 included from the other scripts. It does a bunch of things:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
599
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
600 <li><p>It parses the "config" file at the top directory, reading in the user
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
601 defined configuration variables. (You can also supply these as environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
602 variables, if you want to specify them for just one run.)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
603
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
604 <li><p>It sets several other environment variables, specifying things like the
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
605 $SOURCE and $BUILD directories, and detecting the number of $CPUS. Many
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
606 of these are set using the <b>export_if_blank</b> function, which keeps
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
607 any existing value of the variable, allowing them to be externally
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
608 overridden.</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
609
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
610 <li><p>It adjusts the $PATH. If build/host exists and contains a busybox
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
611 executable (meaning host-tools.sh did its thing already), $PATH is set to just
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
612 that directory. If build/wrapdir exists, that's used instead for command
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
613 line logging via sources/more/record-commands.sh.</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
614
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
615 <li><p>If host-tools.sh ran after record-commands.sh, it sets the $PATH to
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
616 point to the logging wrapper directory. ($WRAPPY_LOGPATH specifies where
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
617 the logging wrapper should write its log file, and $WRAPPY_REALPATH says where
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
618 to find the actual commands the logging wrapper hands off to.)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
619 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
620
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
621 <p>It also reads <b>sources/functions.sh</b>, which provides shell functions
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
622 used by the rest of the build, including:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
623
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
624 <ul>
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
625 <ul>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
626 <li><p><b>read_arch_dir</b> - parses the appropriate sources/targets
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
627 directory to read architecture information and set lots of environment
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
628 variables. It takes one argument, the architecture name to build. If
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
629 run with no arguments, it outputs all available architectures by listing
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
630 the subdirectories under sources/targets.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
631
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
632 <p>All the build stages except download.sh and host-tools.sh call read_arch_dir
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
633 with their first command line argument.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
634 </li>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
635
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
636 <li><p><b>download</b> - used by download.sh. Calls wget if necessary, uses
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
637 sha1sum to verify the files. Saves the results in the directory pointed to
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
638 by $SRCDIR (set to "packages" by sources/include.sh). Treat as a fancy call
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
639 to "wget".</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
640
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
641 <li><p><b>dienow</b> - abort the current script, exiting with an error message.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
642 (Can even exit from nested shell functions.) Treat as a fancy "exit".</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
643
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
644 <li><p><b>setupfor</b> - extract a source package (named in the first argument)
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
645 into a temporary directory (under $WORK), and change the current directory to
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
646 there. Treat as a fancy "tar -xvjf" followed by cd.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
647
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
648 <p>Source code is cached, meaning each package's source tarball is only
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
649 actually extracted and patched once (into build/packages) and the temporary
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
650 copies are directories full of hard links (or optionally symlinks) to the
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
651 cached source.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
652 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
653
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
654 <li><p><b>cleanup</b> - delete temporary copy of source code after build.
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
655 Treat as a fancy "rm -rf" (except that it remembers the working directory
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
656 from the last setupfor call, rather than requiring it to be specified on
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
657 the command line).</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
658
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
659 <p>If the exit code of the last command was nonzero,
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
660 it calls dienow instead of deleting the source code that didn't build
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
661 properly, to preserve the evidence of what went wrong.</p></li>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
662
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
663 <li><p><b>maybe_fork</b> - If the environment variable <b>FORK</b> is set, run
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
664 the first argument in the background. Otherwise, run it in the foreground.
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
665 (This is used with the <b>wait</b> command, which blocks until all background
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
666 jobs belonging to this shell have finished. If this shell has no background
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
667 processes wait returns immediately.)</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
668 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
669
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
670 <p>Most of what these shell functions do is optional. Most of it's there to
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
671 speed up and simplify the rest of the build, and perform error checking.
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
672 None of it should be very important to understanding how to build or install
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
673 any of the actual packages. It just abstracts away repetitive, uninteresting
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
674 bits.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
675
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
676 <h2>Downloading source code</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
677
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
678 <p>The FWL source distribution does not include any third party source
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
679 tarballs. Instead, these are downloaded by running download.sh, which calls
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
680 the shell function <b>download</b>, which calls wget as necessary. The
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
681 download.sh script contains a series of calls to the download function.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
682
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
683 <p>Only calls to the shell function "download" contain version information for
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
684 packages. The scripts that actually build the packages do not, they are as
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
685 version agnostic as possible.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
686
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
687 <p>The following environment variables control the behavior of download.sh,
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
688 and may be set before calling it:</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
689
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
690 <ul>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
691 <li><p><b>EXTRACT_ALL</b> - prepopulate the source cache.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
692
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
693 <p>If set, each call to the download function will extract and patch the
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
694 corresponding source tarball (into the sources/packages cache directory)
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
695 immediately after the download completes, instead of waiting for setupfor to
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
696 do it. (See "Extracting source code", below.)</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
697 </li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
698
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
699 <li><p><b>FORK</b> - Calls to download are usually wrapped in maybe_fork,
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
700 so if this is set they run in parallel.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
701 </li>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
702
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
703 <li><p><b>PREFERRED_MIRROR</b></p> - This contains the URL of a mirror site
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
704 to be checked _before_ downloading from the actual $URL specified in
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
705 download.sh.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
706
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
707 <p>This allows download.sh to fetch some or all of its packages from a local
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
708 mirror of the files, instead of going out to the net. Any files not found
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
709 in this mirror will be fetched from the standard URL, and the fallback mirrors
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
710 as necessary.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
711
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
712 <p>(Note: inside qemu the special address 10.0.2.2 passes through connections
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
713 to 127.0.0.1 on the host, so if you run a web server on your host's loopback
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
714 address you can pass source code into the emulator without going out
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
715 to an external network.)</p></li>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
716 </ul>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
717
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
718 <p>The following environment variables control each call to the
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
719 download function, and are set before each call:<p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
720
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
721 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
722 <li><p><b>URL</b> - The URL from which to download this source package
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
723 into the sources/packages directory.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
724
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
725 <p>In addition to specifying a web location, this URL determines the name of the
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
726 source package to fetch. If this source tarball cannot be fetched from this
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
727 location, the download function tries to download the file from a series of
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
728 fallback mirrors (stored in the variable MIRROR_LIST, set in include.sh).
1321
4c0a2018502c Clean up old references to impactlinux.com, add a FAQ explaining why that site went away, and start the long and winding process of redoing documentation.hmtl.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
729 The primary mirror is http://landley.net/aboriginal/mirror
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
730 which should have every source tarball used by the build.</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
731
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
732 <p>The package name is the filename at the end of URL minus any version
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
733 information and file type extensions, so "bash-2.04b.tar.bz2" becomes "bash".
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
734 The shell function "basename" uses a rather complicated regex to
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
735 extract the package name from a URL. This versionless package name is used
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
736 by things like setupfor, allowing the build scripts to mostly ignore the
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
737 versions of the packages they build.</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
738
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
739 <li><p><b>SHA1</b> - The sha1sum of the source tarball to fetch.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
740
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
741 <p>Used to confirm that the downloaded file is correct. If not, it tries
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
742 the next mirror in the list, or calls dienow if out of mirrors.</p>
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
743
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
744 <p>If this value is blank, the sha1sum calculated from the file will be
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
745 displayed but not verified. This means any file will be accepted as correct
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
746 as long as it exists with the right name, but the build won't be able to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
747 detect corrupted or truncated files.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
748
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
749 <p>When updating to a new version of a package, a common trick is to update
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
750 the URL and blank the SHA1, run ./download.sh to fetch the new file, cut and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
751 paste the SHA1 value displayed after the download to set the SHA1 variable,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
752 and then re-run ./download.sh to confirm they match.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
753
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
754 <li><p><b>UNSTABLE</b> - URL to an alternate version of the file, for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
755 testing purposes.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
756
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
757 <p>This version is only downloaded when USE_UNSTABLE contains the name of this
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
758 package in its package list. It doesn't fall back to check the mirror list,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
759 and is not affected by PREFERRED_MIRROR.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
760
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
761 <p>Unstable packages are saved as a tarball called "alt-$PACKAGE-0" plus the
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
762 file type extension. (Thus the name to save is based on the filename in the
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
763 normal $URL rather than on what the $UNSTABLE address points to, so even if
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
764 your UNSTABLE address ends with "snapshot.tgz" or "tip.tar.bz2", it will
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
765 still wind up somewhere the rest of the build can find it.)</p></li>
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
766
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
767 <li><p><b>RENAME</b> - regex to rename a downloaded file.</p>
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
768
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
769 <p>This is a "sed -r" extended regular expression with which to rename a file.
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
770 The "setupfor" function expects filenames in "$PACKAGE-$VERSION.$TYPE" format.
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
771 If a source package at $URL isn't named that way (such as squashfs not having
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
772 a dash between the package name and version), you can adjust it with this.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
773 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
774
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
775 <p>At the end of download.sh is a call to the shell function <b>cleanup_oldfiles</b>,
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
776 which deletes unused files. The include.sh snapshots the current time in
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
777 the variable $START_TIME, and download calls "touch" to update the timestamp on
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
778 each file it verifies the sha1sum of. Then cleanup_oldfiles deletes every
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
779 file from sources/packages with a date older than $START_TIME. (It does
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
780 not recurse into subdirectories.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
781
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
782 <p>Note that download updates the timestamp on stable packages when
1040
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
783 downloading corresponding unstable packages (and vice versa), so
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
784 cleanup_oldfiles won't delete them. In this special case they're not
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
785 considered "unused files", but it won't verify their integrity or fetch
b630081630a7 Serious upgrade of the "What is?" section.
Eric S. Raymond <esr@thyrsus.com>
parents: 881
diff changeset
786 them if they're not already there.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
787
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
788 <h2>Extracting source code</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
789
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
790 <p>The function "setupfor" extracts <b>sources/packages/$PACKAGENAME-*</b>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
791 tarballs. (If $PACKAGENAME is found in the comma separated $USE_UNSTABLE list,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
792 the build adds an "alt-" prefix to the package name.) This populates a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
793 corresponding directory under build/sources, and applies all the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
794 <b>sources/patches/$PACKAGENAME-*.patch</b> files in alphabetical order.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
795 (So if a package has multiple patches that need to be applied in a specific
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
796 order, name them something like "bash-001-dothingy.patch",
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
797 "bash-002-next.patch" to control this.)</p>
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
798
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
799 <p>The trailing "-" before filename wildcards prevents collisions between
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
800 things like "uClibc" and "uClibc++". Packages are allowed to contain dashes
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
801 (such as gcc-core), but cannot have a digit immediately after the dash.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
802
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
803 <p>FWL implements source caching. The first call to setupfor extracts the
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
804 package into build/sources, and then creates a directory of hard links in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
805 current target's build/temp-$TARGET directory with cp -lfR. Later setupfor
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
806 calls just create the directory of hard links from the existing source tree.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
807 (This is a hybrid approach between building "out of tree" and building
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
808 in-tree.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
809
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
810 <p>The <b>./download.sh --extract</b> option prepopulates the source cache,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
811 extracting and patching each source tarball. This is useful for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
812 scripts such as sources/build-all-targets.sh which perform multiple builds in
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
813 parallel.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
814
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
815 <p>The reason for keeping extracted source tarballs around is that extracting
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
816 and patching tarballs is a fairly expensive operation, which uses a significant
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
817 amount of disk space and doesn't parallelize well. (It tends to be disk
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
818 limited as much as CPU limited, so trying for more parallelism wouldn't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
819 necessarily help.) In addition, the same packages are repeatedly extracted:
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
820 the cross-compiler and mini-native stages use many of the same packages, and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
821 some packages (such as the Linux kernel) are extracted and removed repeatedly
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
822 to grab things like kernel headers separately from actually building a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
823 bootable kernel. (Also, different architectures build the exact same
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
824 packages, with the same set of patches. Even patches to fix a bug on a single
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
825 architecture are applied for all architectures; if this causes a problem, it's
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
826 not a mergeable patch capable of going upstream.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
827
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
828 <h2>Building host tools</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
829
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
830 <p>The host-tools.sh script sets up the host environment. Usually the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
831 host environment is already in a usable state, but this script explicitly
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
832 enumerates exactly what we need to build, and provides our own (known)
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
833 versions of everything except the host compiler toolchain in the directory
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
834 <b>build/host</b>. Once we've finished, the $PATH can be set to just that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
835 directory.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
836
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
837 <p>The build calls seven commands from the host compiler toolchain: ar, as,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
838 nm, cc, gcc, make, and ld. All those have to be in the $PATH, so host-tools.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
839 creates symlinks to those from the original $PATH.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
840
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
841 <p>Next host-tools.sh builds toybox for the "patch" command, because busybox
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
842 patch can't simple handle offsets and is thus extremely brittle in the face of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
843 new package versions. (This is different from "fuzz factor", which removes
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
844 context lines to find a place to insert a patch, and tends to break a lot.)
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
845 If USE_TOYBOX is enabled, a defconfig toybox is used and all commands are
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
846 installed.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
847
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
848 <p>Next host-tools builds a "defconfig" busybox and installs it into
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
849 build/host. This provides all the other commands the build needs.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
850
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
851 <h3>What's the minimum the build actually needs?</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
852
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
853 <p>When building a new system, environmental dependencies are a big issue.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
854 Figuring out what package needs what, and what order to build things in,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
855 is the hardest part of putting together a system.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
856
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
857 <p>Running the build without build/host calls lots of extra commands, including
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
858 perl, pod2man, flex, bison, info, m4, and so on. This is because the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
859 ./configure stages of the various packages detect optional functionality,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
860 and use it. One big reason to limit the build environment is to consistently
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
861 produce the same output files, no matter what's installed on the host.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
862
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
863 <p>The minimal list of commands needed to build a working system image is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
864 1) a working toolchain (ar, as, nm, cc, gcc, make, ld), 2) /bin/bash (and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
865 a symlink /bin/sh pointing to it), 3) the following command line utilities
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
866 in the $PATH:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
867
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
868 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
869 <p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
870 awk basename bzip2 cat chmod chown cmp cp cut date dd diff
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
871 dirname echo egrep env expr find grep gzip hostname id install ln ls mkdir
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
872 mktemp mv od patch pwd readlink rm rmdir sed sha1sum sleep sort tail tar
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
873 touch tr true uname uniq wc which whoami xargs yes
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
874 </p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
875 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
876
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
877 <p>These commands are supplied by current versions of busybox.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
878
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
879 <p>Bash has been the standard Linux shell since before the 0.0.1 release in
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
880 1991, and is installed by default on all Linux systems. (Ubuntu broke its
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
881 /bin/sh symlink to point to the Defective Annoying SHell, so many scripts call
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
882 #!/bin/bash explicitly now rather than relying on a broken symlink.) We
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
883 can't stop the build from relying on the host version of this tool; editing
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
884 $PATH has no effect on the #!/bin/bash lines of shell scripts.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
885
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
886 <p>The minimal set of commands necessary to build a system image was
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
887 determined experimentally, by running a build with $RECORD_COMMANDS and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
888 then removing commands from the list and checking the effect this had on
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
889 the build. (Note that the minimal set varies slightly from target to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
890 target.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
891
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
892 <p><b>$RECORD_COMMANDS</b> tells host-tools.sh to set up a logging wrapper
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
893 that intercepts each command line in the build and writes it to a log file, so
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
894 you can see what the build actually uses. (Note that when host-tools.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
895 sets up build/wrapper, it doesn't set up build/host, so the build still uses
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
896 the host system's original command line utilities instead of building busybox
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
897 versions. If you'd like to record the build using build/host commands,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
898 run host-too.sh without $RECORD_COMMANDS set and then run it again with
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
899 $RECORD_COMMANDS to set up the logging wrapper pointing to the busybox
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
900 tools.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
901
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
902 <p>The way $RECORD_COMMANDS works is by building a logging wrapper
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
903 (sources/toys/wrappy.c) and populating a directory (build/wrapper) with
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
904 symlinks to that logging wrapper for each command name in $PATH. When later
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
905 build stages run commands, the wrapper appends the command line to the log file
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
906 (specified in the environment variable $WRAPPY_LOGPATH, host-tools.sh sets
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
907 this to "$BUILD/cmdlines.$STAGE_NAME.$PACKAGE_NAME"), recording
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
908 each command run. The logging wrapper then searches $WRAPPY_REALPATH to find
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
909 the actual command to hand its command line off to.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
910
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
911 <h2>Building a cross compiler</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
912
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
913 <p>We cross compile so you don't have to. The point of this project is to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
914 make cross compiling go away, but you need to do some to get past it. So
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
915 let's get it over with.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
916
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
917 <p>The <b>cross-compiler.sh</b> script builds a cross compiler. Its output
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
918 goes into <b>build/cross-compiler-$TARGET</b> directory, which is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
919 deleted at the start of the build if it already exists, so re-running this
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
920 script always does a clean build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
921
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
922 <p>Creating a cross compiler is a five step process:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
923
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
924 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
925 <li><p><b>binutils</b> - Build assembler and linker for the target platform.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
926
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
927 <p>This package has no interesting dependencies, and thus can be the first
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
928 thing you build for a target.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
929 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
930
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
931 <li><p><b>gcc</b> - Build C/C++ compiler for the target platform.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
932
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
933 <p>This package needs binutils, and must be built after that. It does not
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
934 need a C library, so can be built before that.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
935
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
936 <p>The mini-native build doesn't require C++ support, but the build adds
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
937 gcc-g++ to the basic gcc-core and enables C++ support so the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
938 <a href="#distcc_trick">distcc accelerator trick</a> can speed up C++
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
939 builds.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
940
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
941 <p>We create an "xgcc" symlink pointing to the host compiler to force gcc
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
942 not to attempt to rebuild itself with itself. (It needed to be able to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
943 build xgcc with the host compiler, but doesn't trust the host compiler to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
944 build an actual binary to deploy. Note that this xgcc builds _host_ binaries,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
945 not target binaries.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
946 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
947
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
948 <li><p><b>compiler wrapper</b> - Install a wrapper around gcc to enforce sane
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
949 path logic.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
950
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
951 <p>This builds a wrapper for gcc from "sources/toys/gcc-uClibc.c". This
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
952 compiler wrapper rewrites the gcc command line to start with --nostdinc and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
953 --nostdlib, and then explicitly adds the correct header and library search
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
954 paths, and when linking adds the correct object files and libraries.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
955
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
956 <p>It needs to do this because gcc's path logic has been consistently broken
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
957 for about two decades now. (See <a href="#why_cross_compiling_sucks">why
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
958 cross compiling sucks</a> for more details.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
959
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
960 <p>The compiler hands off the new command line to $ARCH-rawgcc, so the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
961 old $ARCH-gcc gets renamed to that and the wrapper gets the old name.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
962
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
963 <p>To allow the compiler wrapper to easily find the headers and libraries,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
964 the build moves them to known locations. The system headers and libraries
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
965 go into "include" and "lib" directories at the same level as the "bin"
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
966 directory containing the wrapper script, and gcc's own headers and libraries
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
967 go into "gcc/include" and "gcc/lib". The wrapper then finds itself (using
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
968 argv[0] and if necessary searching the $PATH it inherits), and backs up one
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
969 level to find the headers and libraries it needs to add to the gcc path.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
970 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
971
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
972 <li><p><b>linux</b> - kernel headers.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
973
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
974 <p>This package doesn't have any prerequisites, but C libraries need it
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
975 to build themselves. (Kernel headers define the system call API for the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
976 Linux kernel.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
977 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
978
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
979 <li><p><b>uClibc</b> - uClibc (micro C library).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
980
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
981 <p>This package is target code that needs to be built with a cross compiler
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
982 (gcc and binutils), and also needs kernel headers. It requires all three of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
983 the other packages, and thus must be built last.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
984
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
985 <p>Note that we only build a standard C library. We don't build/install
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
986 a standard C++ library (uClibc++), because distcc doesn't need headers
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
987 or libraries in the cross compiler. Thus the cross compiler has enough
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
988 C++ support to be used from the native environment via distcc, but not
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
989 enough to cross compile C++ code on its own.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
990
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
991 <p>The compiler wrapper actually uses links to "libc.so", which is a linker
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
992 script pointing to libuClibc.so.0. We patch uClibc so it doesn't put absolute
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
993 paths into its libc.so; without them the linker searches the supplied library
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
994 search paths, and thus the compiler may be installed in an arbitrary
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
995 location.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
996 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
997 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
998
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
999 <p>Afterwards the build strips some of the binaries, tars up the result,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1000 and performs some quick sanity tests (building dynamic and static versions
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1001 of hello world. If the target configuration lists a version of QEMU to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1002 test individual binaries under on the host, it runs the static version
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1003 to make sure it outputs "Hello world".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1004 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1005
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1006 <h2>Building a minimal native development environment for the target system</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1007
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1008 <p>The <b>mini-native.sh</b> script uses the cross compiler from the previous
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1009 step to build a kernel and root filesystem for the target. The resulting
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1010 system should boot and run under an emulator, or on real target hardware.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1011
531
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1012 <p>If you really want to learn how to cross compile a target system, this
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1013 is the script you want to read, and possibly append your own packages to.
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1014 That said: please don't, and here's why:</p>
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1015
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1016 <p>Because cross-compiling is persnickety and difficult, we do as little of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1017 it as possible. This script should perform all the cross compiling anyone ever
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1018 needs to do. It uses the cross-compiler to generate the simplest possible
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1019 native build environment for the target which is capable of rebuilding itself
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1020 under itself.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1021
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1022 <p>Anything else that needs to be built for the target can then be built
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1023 natively, by running this kernel and root filesystem under an emulator and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1024 building new packages there, bootstrapping up to a full system if necessary.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1025 The emulator we use for this is QEMU. Producing a minimal build environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1026 powerful enough to boot and compile a complete Linux system requires seven
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1027 packages: the Linux kernel, binutils, gcc, uClibc, BusyBox, make, and bash.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1028 We build a few more than that, but those are optional extras.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1029
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1030 <p>This root filesystem can also be packaged using the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1031 <a href=http://www.linuxfromscratch.org/lfs>Linux From Scratch</a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1032 /tools directory approach, staying out of the way so the minimal build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1033 environment doesn't get mixed into the final system, by setting the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1034 $NATIVE_TOOLSDIR environment variable. If you don't know why you'd want
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1035 to do that, you probably don't want to.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1036
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1037 <p>In either configuration, the main target directory the build installs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1038 files into is held in the environment variable "$TOOLS". If $NATIVE_TOOLSDIR
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1039 is set this will be "/tools" in the new root filesystem, otherwise it'll
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1040 be "/usr".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1041
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1042 <p>The steps the script goes through are:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1043
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1044 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1045 <li><p><b>directory setup</b> - Create empty directories for the basic
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1046 filesystem layout.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1047
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1048 <p>If $NATIVE_TOOLSDIR is set, build script will create a Linux From Scratch
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1049 style intermediate system by moving the filesystem layout under /tools,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1050 which means skipping the top level directories and installing most files
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1051 into /tools instead of /usr. This also sets the variable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1052 $UCLIBC_DYNAMIC_LINKER to tell the compiler wrapper to create binaries that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1053 depend on shared libraries in /tools rather than the default
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1054 "/lib/ld-uClibc.so.0". (With the /tools layout, the qemu-setup.sh script can
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1055 recreate most of the top level directories at runtime, often as symlinks
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1056 into /tools.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1057 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1058
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1059 <li><p><b>Copy sources/native</b> - The most important thing here is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1060 the qemu-setup.sh script, but there's also example source code in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1061 src directory.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1062
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1063 <li><p><b>Linux kernel</b> - Build a kernel that can boot under QEMU.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1064
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1065 <p>We need kernel headers to build uClibc, so install those while we've got the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1066 kernel tarball extracted. (We could grab these files directly from the cross
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1067 compiler, but we rebuild from source to keep the layers cleanly separated.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1068
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1069 <p>The kernel build uses <b>sources/targets/$ARCH/miniconfig-linux</b>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1070 to configure the kernel for the appropriate QEMU target, and the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1071 $KERNEL_PATH variable to figure out which kernel image file to use.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1072
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1073 <li><p><b>uClibc</b> - Build standard C library.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1074
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1075 <p>The binaries in the target system are dynamically linked, so we need
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1076 shared libraries installed. Again, we could grab these files out of the cross
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1077 compiler, but we rebuild from source to keep the layers cleanly separated.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1078
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1079 <p>We unconditionally install the development files (headers and static
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1080 libraries), and delete them later if $NATIVE_TOOLCHAIN isn't set.</p>
531
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1081
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1082 <p>Right after installing the C library, we export the environment variable
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1083 $WRAPPER_TOPDIR which tells the compiler wrapper to links against the new
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1084 headers and shared libraries we've installed into the new root filesystem,
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1085 rather than the ones out of the cross compiler's include and lib
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1086 directories.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1087 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1088
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1089 <li><p><b>toybox</b> - Build optional command line utilities.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1090
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1091 <p>This isn't strictly required. If $USE_TOYBOX isn't set, this only
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1092 installs symlinks for the "patch" command and "oneit" commands. (The
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1093 oneit command is similar to init=/bin/sh, except it allows terminal control
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1094 to work and shuts the system down cleanly on exit. It's used by
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1095 qemu-setup.sh to provide a more forgiving command line.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1096
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1097 <p>If $USE_TOYBOX is set, this installs toybox versions of many commands
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1098 instead of the busybox versions. These tend to be simpler, more
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1099 straightforward implementations than the busybox versions. (Note: your author
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1100 is biased here.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1101 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1102
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1103 <li><p><b>busybox</b> - Build busybox command line utilities.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1104
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
1105 <p>This provides the bulk of the command line utilities for the new
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1106 system.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1107
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1108 <p>Once upon a time, "make defconfig" provided the largest sane configuration
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1109 in busybox, enabling every working command and feature that didn't have
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1110 undesirable side effects (such as debugging options) or require special
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1111 configuration to use (such as SELINUX). Unfortunately, over time this goal
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1112 was lost and make defconfig bit-rotted into a fairly random configuration.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1113
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1114 <p>To recapture the original "largest sane configuration" goal, the build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1115 starts with "<b>make allyesconfig</b>" and applies
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1116 <b>sources/trimconfig-busybox</b> to remove features that would otherwise
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1117 cause problems. The trimconfig file has comments in it if you're wondering
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1118 why specific features are disabled.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1119 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1120
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1121 <li><p><b>Check $NATIVE_TOOLCHAIN</b> - Build a native development toolchain
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1122 only if $NATIVE_TOOLCHAIN is set.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1123
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1124 <p>$NATIVE_TOOLCHAIN is the only configuration option set by default. You
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1125 can disable it in "config" if you want to build skeletal target system and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1126 add your own software to it by hand.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1127
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1128 <p>If it is enabled, the following happens:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1129 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1130 <li><p><b>binutils</b> - Build a native assembler and linker.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1131
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1132 <li><p><b>gcc and libsupc++</b> - Build a native C and C++ compiler.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1133
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1134 <p>This process is still a bit tangled. The fundamental reason for this
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1135 is that the gcc build process is pathologically misdesigned. (See
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1136 <a href="#gcc_sucks">what the hell is wrong with gcc</a> for a long
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1137 digression into the details.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1138
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1139 <p>The secondary reason is that libstdc++ is built into gcc, which makes as much
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1140 sense as building glibc into gcc. GCC's C++ support is not cleanly separated
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1141 into layers, so replacing their built-in libstdc++ with the much smaller
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1142 uClibc++ requires performing additional surgery on the gcc build process
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1143 to get it to stop being actively stupid. (For simplicity we punted on this
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1144 while building the cross compiler, but now we need to make it work.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1145
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1146 <p>So after beating gcc over the head with almost a dozen different environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1147 variables and a bunch of ./configure options to get it to cross compile like
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1148 a normal program, we then have to chdir into the <b>libsupc++</b> subdirectory
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1149 to build a static library which uClibc++ needs in order to interface properly
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1150 with the compiler. (It defines things like stack unwinding and the current
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1151 exception model, which the C++ library needs to know but which gcc doesn't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1152 cleanly export for external use.) Logically this step belongs with the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1153 uClibc++ build, but we have to export this information from the gcc source
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1154 directory because that's where it lives.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1155
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1156 <p>We also clean up after a bug where gcc uses multilib directories (such as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1157 /lib64) on some systems even when we explicitly told it we didn't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1158 want multilib. (This package isn't very good at taking "no" for an answer.)
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1159 And we create a "cc" symlink to gcc, because some packages use that as their
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1160 compiler and SUSv3 says we should have one.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1161 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1162
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1163 <li><p><b>compiler wrapper</b> - Wrap gcc, to control path logic.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1164
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1165 <p>The native build still installs the compiler wrapper
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1166 (from sources/toys/gcc-uClibc.c) to rewrite gcc's command line arguments
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1167 and bypass its built-in path logic. In theory native
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1168 compiling is less tricky and the final location we're installing the compiler
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1169 at is known at compile time, so we could just patch the compiler's source
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1170 code to check the right paths. But going there rapidly turns into a nightmare
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1171 of tangled historical scar tissue, and breaks in new and exciting ways
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1172 with each new gcc release. The only way to get gcc to use sane paths is to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1173 take path decisions out of its hands entirely.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1174
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1175 <p>This does the same header/library shuffling and symlink creation as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1176 the cross compiler did, but without a prefix on the symlink names this
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1177 time.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1178 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1179
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1180 <li><p><b>uClibc++</b> - Build micro standard c++ library.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1181
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1182 <p>C++ has its own standard library, and its own standard header files,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1183 without which the overloaded bit shift operators can't even perform I/O.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1184 The package uClibc++ provides much smaller and simpler versions of these
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1185 than the libstdc++-v3 metastasized through gcc-g++.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1186
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1187 <p>This package mostly builds out of the box, assuming the cross compiler has
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1188 minimal c++ support and you have the right pliers to extract libsupc++ from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1189 the gcc build. We start with the defconfig, switch off TLS and LONG_DOUBLE
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1190 support that uClibc doesn't currently provide, and blank the RUNTIME_PREFIX
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1191 so it installs where we tell it to. Then we shuffle the libraries around
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1192 so the compiler wrapper can find them and make symlinks from the generic
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1193 "libstdc++.{so,a}" names to the corresponding libuClibc++ files.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1194 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1195
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1196 <li><p><b>make</b> - Build make</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1197
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1198 <p>A toolchain doesn't do you much good without the "make" command. Fairly
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1199 straightforward to build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1200 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1201
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1202 <li><p><b>bash</b> - The standard Linux command shell.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1203
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1204 <p>Bash has been the standard Linux command shell since 1991, and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1205 lots of scripts explicitly say #!/bin/bash. In addition, bash extensions
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1206 like curly brace filename expansion are in common use.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1207
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1208 <p>Someday, busybox might provide a decent replacement for bash, but since
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1209 busybox has four different shells (lash, hush, msh, ash) which don't share a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1210 lot of code, development is fragmented and proceeds slowly. A bash replacement
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1211 will need to be callable as "#!/bin/bash" since debian pointed #!/bin/sh at the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1212 Defective Annoying SHell and greatly discouraged use of that symlink.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1213
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1214 <p>We intentionally build an older version of bash (2.04b) which is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1215 sufficient for our purposes, and much smaller and simpler than the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1216 current bash 3.x monsters. We have to hardwire a few things ./configure
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1217 entries because this version doesn't like cross compiling, and we do so
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1218 by supplying a config.cache file with the appropriate entries. It also doesn't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1219 work if you try to build in parallel, so we don't supply -j.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1220 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1221
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1222 <li><p><b>distcc</b> - command to distribute compiles across a network
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1223 cluster.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1224
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
1225 <p>We install this for <a href="#distcc_trick">the distcc accelerator
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1226 trick</a>. It's entirely optional.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1227
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1228 <p>We create a $TOOLS/distcc directory full of symlinks to distcc with the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1229 names of gcc, cc, g++, and c++. Inserting that directory at the start of the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1230 $PATH makes the build use distcc in place of the normal native compiler.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1231 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1232 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1233
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1234 <p>That's everything in the $NATIVE_TOOLCHAIN. The rest is minor cleanup
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1235 and packaging.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1236
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1237 <li><p><b>Build static and dynamic hello world binaries</b></p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1238
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1239 <p>These are installed into $TOOLS/bin as hello-dynamic and hello-static.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1240 These are debugging tools: If you can't boot the system to a shell prompt,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1241 try running hello-static as init to see if it runs and gives you output.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1242 If that works try hello-dynamic to see if shared libraries are loading.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1243
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1244 <li><p><b>Strip some binaries</b> to save space.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1245
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1246 <li><p><b>Create the mini-native tarball</b> - we're done.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1247 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1248
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1249 <p>In theory, you can add more packages to mini-native.sh, or run another
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1250 similar script to use the cross compiler to produce output into the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1251 mini-native directory. In practice, this is not recommended. Cross
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1252 compiling is an endless sinkhole of frustration, and the easiest way to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1253 deal with it is not to go there.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1254
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1255 <h2>Packaging up a system image to run under emulation</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1256
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1257 <p>The <b>package-mini-native.sh</b> script packages a system image for
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1258 use by QEMU. Its output goes into <b>build/system-image-$TARGET</b>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1259 directory, which is deleted at the start of the build if it already exists,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1260 so re-running this script always does a clean build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1261
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1262 <p>The steps here are:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1263
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1264 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1265 <li><p><b>use genext2fs</b> to package the output of mini-native.sh as an 64
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1266 megabyte ext2 image.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1267
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1268 <li><p><b>create run-emulator.sh</b> by appending an emulator invocation
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1269 command line to </b>sources/toys/run-emulator.sh</b>.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1270
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1271 <p>This calls a shell function "emulator_command" from the target architecture
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1272 definition, passing in the name of the ext2 image containing the root filesystem
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1273 and the kernel image to boot. A shell function "qemu_defaults" is defined
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1274 to let emulator_command grab logs of common boilerplate, such as kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1275 command line options. (In theory run_emulator is free to use a different
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1276 emulator, or even output a command to send the files to real hardware
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1277 through a network connection or jtag or some such.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1278
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1279 <p>The path for some or the run-emulator.sh kernel command line
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1280 arguments is also adjusted based on $NATIVE_TOOLSDIR.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1281 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1282
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1283 <li><p>For the powerpc architecture, ppc_rom.bin is copied from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1284 sources/toys. (This architecture needs a custom boot rom for qemu
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1285 to be able to boot a bzImage via -kernel.)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1286
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1287 <li><p>Tar up the result</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1288 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1289
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1290 <h2>Running on real hardware</a></h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1291
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1292 <p>To run a system on real hardware (not just under an emulator), you need to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1293 do several things. Dealing with myriad individual devices is beyond the scope
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1294 of this project, but the general theory is:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1295
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1296 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1297 <li><p>Figure out how to flash your device (often a jtag with openocd)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1298
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1299 <li><p>Configure and install a bootloader (uboot, apex, etc.)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1300
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1301 <li><p>Build and install a kernel targeted to your hardware (in the kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1302 source, see arch/$ARCH/configs for default .config files for various
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1303 boards)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1304
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1305 <li><p>Package and install the root filesystem appropriately for your system
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1306 (ext2, initramfs, jffs2).</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1307 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1308
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1309 <a name="distcc_trick"><h2>Speeding up emulated builds (the distcc accelerator trick)</h2></a>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1310
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1311 <p>Cross compiling is fast but unreliable. The ./configure stage is
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1312 designed wrong (it asks questions about the host system it's building
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1313 on, and thinks the answers apply to the target binary it's creating).
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1314
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1315 <p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1316
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1317 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1318
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1319 <a name="why"><h1>Why do things this way</h1></a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1320
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1321 <h1>UNDER DEVELOPMENT</h1>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1322
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1323 <p>This entire section is a dumping ground for historical information.
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1324 It's incomplete, lots of it's out of date, and it hasn't been integrated into
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1325 a coherent whole yet. What is here is in no obvious order.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1326
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1327 <a name="cross_compiling"><h2>Why cross compiling sucks</h2></a>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1328
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1329 <p>Cross compiling is fast but unreliable. Most builds go "./configure; make;
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1330 make install", but entire ./configure stage is designed wrong for cross
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1331 compiling: it asks questions about the host system it's building
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1332 on, and thinks the answers apply to the target binary it's creating.</p>
531
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1333
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1334 <p>Build processes often create temporary binaries which run during the
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1335 build (to generate header files, parse configuration information ala
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1336 kconfig, various "makedep" style dependency generators...). These builds
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1337 need two compilers, one for the host and one for the target, and need to
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1338 keep straight when to use each one.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1339
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1340 <p>Cross compilers leak host data, falling back to the host's headers and
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1341 libraries if they can't find the target files they need.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1342
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1343 <p>TODO: finish this.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1344
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1345 <a name="distcc_trick"><h2>Speeding up emulated builds (the distcc accelerator trick)</h2></a>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1346
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1347 <p>TODO: FILL THIS OUT</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1348
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1349 <h2>The basic theory</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1350
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1351 <p>The Linux From Scratch approach is to build a minimal intermediate system
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1352 with just enough packages to be able to compile stuff, chroot into that, and
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1353 build the final system from there.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1354
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1355 <p>This approach completely isolates the host from the
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1356 target, which means you should be able to run the FWL build under a wide
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1357 variety of Linux distributions, and since the final system is built with a
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1358 known set of tools you should get a consistent result. It also means you
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1359 could run a prebuilt system image under a different host operating system
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1360 entirely (such as MacOS X, or an arm version of linux on an x86-64 host)
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1361 as long as you have an appropriate emulator.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1362
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1363 <p>A minimal build environment consists of a compiler, command line tools,
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1364 and a C library. In theory you just need three packages:</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1365
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1366 <ul>
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1367 <li>A C compiler.</li>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1368 <li>BusyBox</li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1369 <li>A C library (uClibc)</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1370 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1371
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1372 <p>Unfortunately, that doesn't work yet.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1373
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1374 <h2>Some differences between theory and reality.</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1375
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1376 <p>We actually need seven packages (linux, uClibc, busybox, binutils, gcc,
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1377 make, and bash) to create a working build environment. We also add an optional
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1378 package for speed (distcc), and use two more (genext2fs and QEMU) to package
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1379 and run the result.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1380
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1381 <h3>Environmental dependencies.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1382
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1383 <p>Environmental dependencies are things that need to be installed before you
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1384 can build or run a given package. Lots of packages depend on things like zlib,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1385 SDL, texinfo, and all sorts of other strange things. (The GnuCash project
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1386 stalled years ago after it released a version with so many environmental
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1387 dependencies it was virtually impossible to build or install. Environmental
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1388 dependencies have a complexity cost, and are thus something to be
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1389 minimized.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1390
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1391 <p>A good build system will scan its environment to figure out what it has
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1392 available, and disable functionality that depends on anything that isn't.
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1393 (This is generally done with autoconf, which is disgusting but
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1394 suffers from a lack of alternatives.) That way, the complexity cost is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1395 optional: you can build a minimal version of the package if that's all you
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1396 need.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1397
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1398 <p>A really good build system can be told that the environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1399 it's building in and the environment the result will run in are different,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1400 so just because it finds zlib on the build system doesn't mean that the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1401 target system will have zlib installed on it. (And even if it does, it may not
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1402 be the same version. This is one of the big things that makes cross-compiling
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1403 such a pain. One big reason for statically linking programs is to eliminate
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1404 this kind of environmental dependency.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1405
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1406 <p>The Firmware Linux build process is structured the way it is to eliminate
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1407 as many environmental dependencies as possible. Some are unavoidable (such as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1408 C libraries needing kernel headers or gcc needing binutils), but the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1409 intermediate system is the minimal fully functional Linux development
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1410 environment we currently know how to build, and then we switch into that and
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1411 work our way back up from there by building more packages in the new
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1412 environment.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1413
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1414 <h3>Resolving environmental dependencies.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1415
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1416 <p><b>To build uClibc you need kernel headers</b> identifying the syscalls and
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1417 such it can make to the OS. We get them from the Linux kernel source tarball,
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1418 using the "make headers_install" infrastructure created by David Woodhouse.
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1419 This runs various scripts against the Linux kernel source code to sanitize
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1420 the kernel's own headers for use by userspace. (This was merged in 2.6.18-rc1,
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1421 and was more or less debugged by 2.6.19.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1422
702
a8854df93e15 Fix typo that left a tag unclosed.
Rob Landley <rob@landley.net>
parents: 655
diff changeset
1423 <p><b>We install bash</b> because the busybox shell situation is a mess.
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1424 Busybox has several different shell implementations which share little or no
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1425 code. (It's better now than it was a few years ago, but thanks to Ubuntu
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1426 breaking the #!/bin/sh symlink with the Defective Annoying SHell, many
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1427 scripts point explicitly at #!/bin/bash and BusyBox can't use that name for
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1428 any of its shells yet.)</p>
526
ad14395e1f0c Update, fix a couple dead links. The last 1/3 of the documentation still needs a major rewrite...
Rob Landley <rob@landley.net>
parents: 520
diff changeset
1429
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1430 <p><b>Most packages expect gcc</b>. The gnu compiler "toolchain" actually
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1431 consists of three packages <b>(binutils, gcc, and make)</b>. (The split
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1432 between binutils and gcc is for purely historical reasons, and you have
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1433 to match the right versions with each other or things break.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1434
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1435 <p>Adding an SUSv3
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1436 <a href=http://www.opengroup.org/onlinepubs/009695399/utilities/make.html>make</a>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1437 implementation to busybox or toybox isn't a major problem, but until a viable
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1438 GCC replacement emerges there's not much point.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1439
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1440 <p>None of the other compilers under development are a drop-in replacement for
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1441 gcc yet, especially for building the Linux kernel (which makes extensive use of
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1442 gcc extensions). <a href=http://www.intel.com/cd/software/products/asmo-na/eng/277618.htm>Intel's C Compiler</a>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1443 implemented the necessary gcc extensions to build the Linux kernel, but it's
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1444 a closed source package only supporting x86 and x86-64 targets. Since
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1445 the introduction of C99, the Linux kernel has replaced many of these gcc
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1446 extensions with equivalent C99 idioms, so in theory building the Linux kernel
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1447 with other compilers is now easier.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1448
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1449 <p>With the introduction of GPLv3, the Free Software Foundation has pissed off
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1450 enough people that work on an open source replacement for gcc is ongoing on
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1451 several fronts. The most promising is probably
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1452 <a href=http://pcc.ludd.ltu.se/>PCC</a>, which is
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1453 supported by what's left of the BSD community. Apple sponsors another
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1454 significant effort, <a href=http://clang.llvm.org/>LLVM/Clang</a>. Both are
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1455 worth watching.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1456
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1457 <p>Several others (Such as TinyCC and Open Watcom) once showed promise but have
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1458 been essentially moribund since about 2005, which is when compilers that only
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1459 ran on 32 bit hosts and supported C89 stopped being interesting. (A
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1460 significant amount of effort is required to retool an existing compiler to
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1461 cleanly run on an x86-64 host and support the full C99 feature set, let alone
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1462 produce output for the dozens of hardware platforms supported by Linux, or
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1463 produce similarly optimized binaries.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1464
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1465 <h2>Additional complications</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1466
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1467 <h3>Cross-compiling and avoiding root access</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1468
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1469 <p>Any time you create target binaries that won't run on the host system, you're
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1470 cross compiling. Even when both the host and target are on the same processor,
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1471 if they're sufficiently different that one can't run the other's binaries, then
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1472 you're cross-compiling. In our case, the host is usually running both a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1473 different C library and an older kernel version than the target, even when
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1474 it's the same processor.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1475
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1476 <p>We want to avoid requiring root access to build Firmware Linux. If the
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1477 build can run as a normal user, it's a lot more portable and a lot less likely
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1478 to muck up the host system if something goes wrong. This means we can't modify
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1479 the host's / directory (making anything that requires absolute paths
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1480 problematic). We also can't mknod, chown, chgrp, mount (for --bind, loopback,
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1481 tmpfs)...</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1482
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1483 <p>In addition, the gnu toolchain (gcc/binutils) is chock-full of hardwired
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1484 assumptions, such as what C library it's linking binaries against, where to look
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1485 for #included headers, where to look for libraries, the absolute path the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1486 compiler is installed at... Silliest of all, it assumes that if the host and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1487 target use the same processor, you're not cross-compiling (even if they have
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1488 a different C library and a different kernel, and even if you ./configure it
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1489 for cross-compiling it switches that back off because it knows better than
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1490 you do). This makes it very brittle, and it also tends to leak its assumptions
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1491 into the programs it builds. New versions may someday fix this, but for now we
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1492 have to hit it on the head repeatedly with a metal bar to get anything remotely
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1493 useful out of it, and run it in a separate filesystem (chroot environment) so
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1494 it can't reach out and grab the wrong headers or wrong libraries despite
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1495 everything we've told it.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1496
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1497 <p>The absolute paths problem affects target binaries because all dynamically
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1498 linked apps expect their shared library loader to live at an absolute path
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1499 (in this case /lib/ld-uClibc.so.0). This directory is only writeable by root,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1500 and even if we could install it there polluting the host like that is just
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1501 ugly.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1502
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1503 <p>The Firmware Linux build has to assume it's cross-compiling because the host
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1504 is generally running glibc, and the target is running uClibc, so the libraries
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1505 the target binaries need aren't installed on the host. Even if they're
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1506 statically linked (which also mitigates the absolute paths problem somewhat),
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1507 the target often has a newer kernel than the host, so the set of syscalls
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1508 uClibc makes (thinking it's talking to the new kernel, since that's what the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1509 ABI the kernel headers it was built against describe) may not be entirely
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1510 understood by the old kernel, leading to segfaults. (One of the reasons glibc
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1511 is larger than uClibc is it checks the kernel to see if it supports things
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1512 like long filenames or 32-bit device nodes before trying to use them. uClibc
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1513 should always work on a newer kernel than the one it was built to expect, but
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1514 not necessarily an older one.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1515
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1516 <h2>Ways to make it all work</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1517
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1518 <h3>Cross compiling vs native compiling under emulation</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1519
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1520 <p>Cross compiling is a pain. There are a lot of ways to get it to sort of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1521 kinda work for certain versions of certain packages built on certain versions
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1522 of certain distributions. But making it reliable or generally applicable is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1523 hard to do.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1524
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1525 <p>I wrote an <a href=/writing/docs/cross-compiling.html>introduction
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
1526 to cross-compiling</a> which explains the terminology, pluses and minuses,
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1527 and why you might want to do it. Keep in mind that I wrote that for a company
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1528 that specializes in cross-compiling. Personally, I consider cross-compiling
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1529 a necessary evil to be minimized, and that's how Firmware Linux is designed.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1530 We cross-compile just enough stuff to get a working native build environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1531 for the new platform, which we then run under emulation.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1532
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1533 <h3>Which emulator?</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1534
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1535 <p>The emulator Firmware Linux 0.8x used was User Mode Linux (here's a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1536 <a href=http://www.landley.net/writing/docs/UML.html>UML mini-howto</a> I wrote
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1537 while getting this to work). Since we already need the linux-kernel source
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1538 tarball anyway, building User Mode Linux from it was convenient and minimized
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1539 the number of packages we needed to build the minimal system.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1540
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1541 <p>The first stage of the build compiled a UML kernel and ran the rest of the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1542 build under that, using UML's hostfs to mount the parent's root filesystem as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1543 the root filesystem for the new UML kernel. This solved both the kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1544 version and the root access problems. The UML kernel was the new version, and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1545 supported all the new syscalls and ioctls and such that the uClibc was built to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1546 expect, translating them to calls to the host system's C library as necessary.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1547 Processes running under User Mode Linux had root access (at least as far as UML
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1548 was concerned), and although they couldn't write to the hostfs mounted root
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1549 partition, they could create an ext2 image file, loopback mount it, --bind
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1550 mount in directories from the hostfs partition to get the apps they needed,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1551 and chroot into it. Which is what the build did.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1552
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1553 <p>Current Firmware Linux has switched to a different emulator, QEMU, because
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1554 as long as we're we're cross-compiling anyway we might as well have the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1555 ability to cross-compile for non-x86 targets. We still build a new kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1556 to run the uClibc binaries with the new kernel ABI, we just build a bootable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1557 kernel and run it under QEMU.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1558
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1559 <p>The main difference with QEMU is a sharper dividing line between the host
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1560 system and the emulated target. Under UML we could switch to the emulated
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1561 system early and still run host binaries (via the hostfs mount). This meant
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1562 we could be much more relaxed about cross compiling, because we had one
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1563 environment that ran both types of binaries. But this doesn't work if we're
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1564 building an ARM, PPC, or x86-64 system on an x86 host.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1565
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1566 <p>Instead, we need to sequence more carefully. We build a cross-compiler,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1567 use that to cross-compile a minimal intermediate system from the seven packages
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1568 listed earlier, and build a kernel and QEMU. Then we run the kernel under QEMU
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1569 with the new intermediate system, and have it build the rest natively.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1570
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1571 <p>It's possible to use other emulators instead of QEMU, and I have a todo
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1572 item to look at armulator from uClinux. (I looked at another nommu system
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1573 simulator at Ottawa Linux Symposium, but after resolving the third unnecessary
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1574 environmental dependency and still not being able to get it to finish compiling
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1575 yet, I gave up. Armulator may be a patch against an obsolete version of gdb,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1576 but I could at least get it to build.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1577
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1578 <h2>Packaging</h2>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1579
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1580 <h2>Filesystem Layout</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1581
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1582 <p>Firmware Linux's directory hierarchy is a bit idiosyncratic: some redundant
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1583 directories have been merged, with symlinks from the standard positions
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1584 pointing to their new positions. On the bright side, this makes it easy to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1585 make the root partition read-only.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1586
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1587 <h3>Simplifying the $PATH.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1588
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1589 <p>The set "bin->usr/bin, sbin->usr/sbin, lib->usr/lib" all serve to consolidate
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1590 all the executables under /usr. This has a bunch of nice effects: making a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1591 a read-only run-from-CD filesystem easier to do, allowing du /usr to show
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1592 the whole system size, allowing everything outside of there to be mounted
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1593 noexec, and of course having just one place to look for everything. (Normal
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1594 executables are in /usr/bin. Root only executables are in /usr/sbin.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1595 Libraries are in /usr/lib.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1596
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1597 <p>For those of you wondering why /bin and /usr/sbin were split in the first
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1598 place, the answer is it's because Ken Thompson and Dennis Ritchie ran out
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1599 of space on the original 2.5 megabyte RK-05 disk pack their root partition
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1600 lived on in 1971, and leaked the OS into their second RK-05 disk pack where
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1601 the user home directories lived. When they got more disk space, they created
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1602 a new direct (/home) and moved all the user home directories there.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1603
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
1604 <p>The real reason we kept it is tradition. The excuse is that the root
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1605 partition contains early boot stuff and /usr may get mounted later, but these
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1606 days we use initial ramdisks (initrd and initramfs) to handle that sort of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1607 thing. The version skew issues of actually trying to mix and match different
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1608 versions of /lib/libc.so.* living on a local hard drive with a /usr/bin/*
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1609 from the network mount are not pretty.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1610
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
1611 <p>I.E. The separation is just a historical relic, and I've consolidated it in
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1612 the name of simplicity.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1613
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1614 <p>On a related note, there's no reason for "/opt". After the original Unix
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1615 leaked into /usr, Unix shipped out into the world in semi-standardized forms
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1616 (Version 7, System III, the Berkeley Software Distribution...) and sites that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1617 installed these wanted places to add their own packages to the system without
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1618 mixing their additions in with the base system. So they created "/usr/local"
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1619 and created a third instance of bin/sbin/lib and so on under there. Then
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1620 Linux distributors wanted a place to install optional packages, and they had
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1621 /bin, /usr/bin, and /usr/local/bin to choose from, but the problem with each
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1622 of those is that they were already in use and thus might be cluttered by who
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1623 knows what. So a new directory was created, /opt, for "optional" packages
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1624 like firefox or open office.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1625
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1626 <p>It's only a matter of time before somebody suggests /opt/local, and I'm
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1627 not humoring this. Executables for everybody go in /usr/bin, ones usable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1628 only by root go in /usr/sbin. There's no /usr/local or /opt. /bin and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1629 /sbin are symlinks to the corresponding /usr directories, but there's no
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1630 reason to put them in the $PATH.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1631
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1632 <h3>Consolidating writeable directories.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1633
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1634 <p>All the editable stuff has been moved under "var", starting with symlinking
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1635 tmp->var/tmp. Although /tmp is much less useful these days than it used to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1636 be, some things (like X) still love to stick things like named pipes in there.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1637 Long ago in the days of little hard drive space and even less ram, people made
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1638 extensive use of temporary files and they threw them in /tmp because ~home
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1639 had an ironclad quota. These days, putting anything in /tmp with a predictable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1640 filename is a security issue (symlink attacks, you can be made to overwrite
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1641 any arbitrary file you have access to). Most temporary files for things
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1642 like the printer or email migrated to /var/spool (where there are
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1643 persistent subdirectories with known ownership and permissions) or in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1644 user's home directory under something like "~/.kde".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1645
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1646 <p>The theoretical difference between /tmp and /var/tmp is that the contents
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1647 of /tmp should be deleted by the system init scripts on every
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1648 reboot, but the contents of /var/tmp may be preserved across reboots. Except
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1649 there's no guarantee that the contents of any temp directory won't be deleted.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1650 So any program that actually depends on the contents of /var/tmp being
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1651 preserved across a reboot is obviously broken, and there's no reason not to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1652 just symlink them together.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1653
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1654 <p>(I case it hasn't become apparent yet, there's 30 years of accumulated cruft
1341
d4eb237dcc6f Many typos, spotted by Alan Post.
Rob Landley <rob@landley.net>
parents: 1324
diff changeset
1655 in the standards, covering a lot of cases that don't apply outside of
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1656 supercomputing centers where 500 people share accounts on a mainframe that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1657 has a dedicated support staff. They serve no purpose on a laptop, let alone
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1658 an embedded system.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1659
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1660 <p>The corner case is /etc, which can be writeable (we symlink it to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1661 var/etc) or a read-only part of the / partition. It's really a question of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1662 whether you want to update configuration information and user accounts in a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1663 running system, or whether that stuff should be fixed before deploying.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1664 We're doing some cleanup, but leaving /etc writeable (as a symlink to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1665 /var/etc). Firmware Linux symlinks /etc/mtab->/proc/mounts, which
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1666 is required by modern stuff like shared subtrees. If you want a read-only
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1667 /etc, use "find /etc -type f | xargs ls -lt" to see what gets updated on the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1668 live system. Some specific cases are that /etc/adjtime was moved to /var
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1669 by LSB and /etc/resolv.conf should be a symlink somewhere writeable.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1670
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1671 <h3>The resulting mount points</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1672
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1673 <p>The result of all this is that a running system can have / be mounted read
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1674 only (with /usr living under that), /var can be ramfs or tmpfs with a tarball
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1675 extracted to initialize it on boot, /dev can be ramfs/tmpfs managed by udev or
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1676 mdev (with /dev/pts as devpts under that: note that /dev/shm naturally inherits
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1677 /dev's tmpfs and some things like User Mode Linux get upset if /dev/shm is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1678 mounted noexec), /proc can be procfs, /sys can bs sysfs. Optionally, /home
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1679 can be be an actual writeable filesystem on a hard drive or the network.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1680
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1681 <p>Remember to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1682 put root's home directory somewhere writeable (I.E. /root should move to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1683 either /var/root or /home/root, change the passwd entry to do this), and life
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1684 is good.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1685
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1686
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1687 <p>Firmware Linux is an embedded Linux distribution builder, which creates a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1688 bootable single file Linux system based on uClibc and BusyBox/toybox. It's
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1689 basically a shell script that builds a complete Linux system from source code
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1690 for an arbitrary target hardware platform.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1691
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1692 <p>The FWL script starts by building a cross-compiler for the appropriate
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1693 target. Then it cross-compiles a small Linux system for the target, which
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1694 is capable of acting as a native development environment when run on the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1695 appropriate hardware (or under an emulator such as QEMU). Finally the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1696 build script creates an ext2 root filesystem image, and packages it with
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1697 a kernel configured to boot under QEMU and shell scripts to invoke qemu
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1698 appropriately.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1699
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1700
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1701 <p>The FWL boot script for qemu (/tools/bin/qemu-setup.sh) populates /dev
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1702 from sysfs, sets up an emulated (masquerading) network (so you can wget
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1703 source packages or talk to <a href="#distcc_trick">distcc</a>), and creates
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1704 a few symlinks needed to test build normal software packages (such as making
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1705 /lib point to /tools/lib). It also mounts /dev/hdb (or /dev/sdb) on /home
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1706 if a second emulated drive is present.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1707
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1708 <p>For most platforms, exiting the command shell will exit the emulator.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1709 (Some, such as powerpc, don't support this yet. For those you have to kill
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1710 qemu from another window, or exit the xterm. I'm working on it.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1711
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1712 <p>To use this emulated system as a native build environment, see
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1713 <a href="#native_compiling">native compiling</a>.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1714
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1715
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1716 <a name="new_platform"><h1>Adding a new target platform</h1></a>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1717
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1718 <p>The differences between platforms are confined to a single directory,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1719 sources/targets. Each subdirectory under that contains all the configuration
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1720 information for a specific target platform FWL can produce system images
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1721 for. The same scripts build the same packages for each platform, differing
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1722 only in which configuration directory they pull data from.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1723
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1724 <p>Each target configuration directory has three interesting files:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1725
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1726 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1727 <li><p><b>details</b> - sets a bunch of environment variables</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1728 <li><p><b>miniconfig-uClibc</b> - configuration for uClibc.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1729 <li><p><b>miniconfig-linux</b> - configuration for the Linux kernel</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1730 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1731
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1732 <p>These configuration files are read and processed by the script
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1733 <b>include.sh</b>.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1734
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1735 <h2>Target name.</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1736
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1737 <p>The name of the target directory is saved in the variable "$ARCH", and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1738 used to form a "tuple" for gcc and binutils by appending "-unknown-linux" to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1739 the directory name. So the first thing to do is find out what platform name
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1740 gcc and binutils want for your target platform, and name your target directory
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1741 appropriately.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1742
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1743 <p>(Note: if your platform really can't use an "${ARCH}-unknown-linux" style
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1744 tuple, and instead needs a tuple like "bfin-elf", you can set the variable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1745 CROSS_TARGET in the "details" file to override the default value and feed
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1746 some other --target to gcc and binutils. You really shouldn't have to do
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
1747 this unless gcc doesn't yet fully support Linux on your platform, or unless
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
1748 you're doing multiple variants of the same target such as powerpc and ppc440.
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
1749 Try the default first, and fix it if necessary.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1750
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1751 <p>The name of the target directory is also used in the name of the various
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1752 directories generated during the build (temp-$ARCH, cross-compiler-$ARCH,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1753 and mini-native-$ARCH, all in the build/ directory), and as the prefix of the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1754 cross compiler binaries ($ARCH-gcc and friends).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1755
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1756 <h2>$ARCH/details</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1757
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1758 <p>The following environment variables may be set in the "<b>details</b>"
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1759 file:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1760
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1761 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1762 <li><p><b>CROSS_TARGET</b> - By default this is set to "${ARCH}-unknown-linux".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1763
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1764 <p>This is used by binutils and gcc. If your target really can't use that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1765 tuple name (perhaps needing a tuple like "bfin-elf" instead), you can set the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1766 variable CROSS_TARGET in the "details" file to override the default value and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1767 feed some other --target to gcc and binutils.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1768
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1769 <p>You usually shouldn't have to set this yourself unless gcc doesn't yet fully
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1770 support Linux on your platform. Try the default first, and fix it if
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1771 necessary.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1772 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1773
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1774 <li><p><b>KARCH</b> - architecture value for the Linux kernel (ARCH=$KARCH).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1775
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1776 <p>The Linux kernel uses different names for architectures than gcc or binutils
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1777 do. To see all your options, list the "arch" directory of the linux kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1778 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1779 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1780
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1781 <li><p><b>KERNEL_PATH</b> - Path in the linux kernel source tree where the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1782 bootable kernel image is generated.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1783
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1784 <p>This is the file saved out of the kernel build, to be fed to qemu's -kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1785 option. Usually "arch/${KARCH}/boot/zImage", but
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1786 sometimes bzImage or image in that directory, sometimes vmlinux in the top
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1787 level directory...</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1788 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1789
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1790 <li><p><b>GCC_FLAGS</b> - Any extra flags needed by gcc.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1791
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
1792 <p>Usually blank, but sometimes used to specify a floating point coprocessor,
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
1793 ABI, or --with-cpu.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1794 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1795
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1796 <li><p><b>BINUTILS_FLAGS</b> - Any extra flags needed by binutils.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1797
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1798 <p>Usually blank.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1799 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1800
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1801 <li><p><b>QEMU_TEST</b> - Optional emulator for sanity test.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1802
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1803 <p>At the end of the cross compiler build, a quick sanity
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1804 test builds static and dynamic "Hello world!" executables with the new cross
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1805 compiler. If QEMU_TEST isn't blank and a file qemu-$QEMU_TEST
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1806 exists in the $PATH, the cross compiler build script will then run qemu's
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1807 application emulation against the static version of "hello world" as an
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1808 additional sanity test, to make sure it runs on the target processor and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1809 outputs "Hello world!".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1810
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1811 <p>Leave it blank to skip this test.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1812 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1813
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1814 <li><p><b>emulator_command</b> - Shell function run to generate the actual
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1815 emulator invocation at the end of the run-$ARCH.sh shell script in the system
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1816 image tarball.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1817
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1818 <p>This is actually a shell function, not an environment variable. It's
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1819 called from package-mini-native.sh to output an emulator command line to
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1820 stdout (generally using "echo").<p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1821
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1822 <p>The function receives two arguments: $1 is the name of the ext2 image
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1823 containing the root filesystem, and $2 is the name of the kernel image.
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1824 The function can also call another shell function, <b>qemu_defaults</b>,
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1825 which is defined in package-mini-native.sh and which provides most of
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1826 the qemu command line. (If you use a different emulator, you don't have to
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1827 call this function, but if you use qemu it makes things a lot easier and
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1828 more consistent.) The qemu_command function outputs $ROOT and $CONSOLE
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1829 variables for its root= and console= kernel command line arguments, so
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1830 set those before calling it.</p>
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1831 </li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1832
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1833 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1834
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1835 <a name="miniconfig"><h2>Miniconfig files</h2></a>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1836
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1837 <p>The expanded .config files used to build both Linux and uClibc are copied
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1838 into the /usr/src directory of mini-native filesystems during the build,
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1839 and kept for future reference.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1840
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1841 <p>The Linux kernel and uClibc each need a configuration file to build.
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1842 Firmware Linux uses the "miniconfig" file format, which contains only the configuration
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1843 symbols a user would have to switch on in menuconfig if they started from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1844 allnoconfig.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1845
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1846 <p>To generate a miniconfig, first configure your kernel with menuconfig,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1847 then copy the resulting .config file to a temporary filename (such as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1848 "tempfile"). Then run the miniconfig.sh script in the sources/toys directory
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1849 with the temporary file name as your argument and with the environment variable
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1850 ARCH set to the $KARCH value in your new config file (and exported if
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1851 necessary). This should produce a new file, "mini.config", which is your
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1852 .config file converted to miniconfig format.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1853
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1854 <p>For example, to produce a miniconfig for a given platform:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1855 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1856 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1857 make ARCH=$KARCH menuconfig
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1858 mv .config tempfile
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1859 ARCH=$KARCH miniconfig.sh tempfile
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1860 ls -l mini.config
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1861 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1862 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1863
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1864 <p>To expand a mini.config back into a full .config file (to build a kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1865 by hand, or for further editing with menuconfig), you can go:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1866
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1867 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1868 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1869 make ARCH=$KARCH allnoconfig KCONFIG_ALLCONFIG=mini.config
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1870 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1871 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1872
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1873 <p>Remember to supply an actual value for $KARCH.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1874
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1875 <h2>$ARCH/miniconfig-linux</h2>
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1876 <p>This is the miniconfig file to build a Linux kernel for the appropriate
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1877 target. This is usually aimed at booting under QEMU, but if you'd like
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1878 to come up with your own configuration for actual target hardware, feel
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1879 free.</p>
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1880
635
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1881 <p>The starting point for kernel configs is generally one of the defconfig
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1882 files from the Linux kernel source code, usually at
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1883 "arch/$ARCH/configs/*_defconfig". Copy that to .config at the top of the
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1884 kernel source, run menuconfig to edit it, then shrink it into a miniconfig.</p>
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1885
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1886 <p>Kernels to run system images under qemu generally require the following
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1887 hardware: serial port (for /dev/console), hard drive (for hda and hdb images),
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1888 network card (for distcc), and a persistent realtime clock (make gets unhappy
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1889 if source files are newer than the current time). The ability to address
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1890 at least 512 megs of memory is also nice, although some targets (such as mips)
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1891 are limited to less than that by the hardware. The "qemu-system-$ARCH -M ?"
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1892 and "qemu-system-$ARCH -cpu ?" options may be informative here, also
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1893 the <a href=http://www.nongnu.org/qemu/qemu-doc.html#SEC60>QEMU System
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1894 emulator for non PC targets</a> documentation.</p>
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1895
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1896 <h2>$ARCH/miniconfig-uClibc</h2>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1897
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1898 <p>Just like the Linux kernel, uClibc needs a .config file to build, and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1899 so the Firmware Linux configuration file supplies a miniconfig. Note that
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1900 uClibc doesn't require an ARCH= value, because all its architecture information
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1901 is stored in the config file. Otherwise the procedure for creating and using
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1902 it is the same as for the Linux kernel, just with a different filename and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1903 contents.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1904
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1905 <p>Most of each miniconfig-uClibc is identical from platform to platform.
635
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1906 Usually only the "Target Architecture" changes (and occasionally an entry
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1907 or two out of Target Architecture Features and Options). At some point
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1908 in the future the rest of the uClibc configuration might be factored out into
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1909 a common file, but so far removing the duplication hasn't been worth the
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1910 extra complexity.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1911
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1912 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1913
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1914 <!--
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1915
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1916 <p>This root filesystem acts as a minimal native build environment for the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1917 target platform. This means it contains a compiler and associated build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1918 tools capable of building a complete new Linux system under itself. If you're
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1919 interested in building a more complex development environment within this one,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1920 see the <a href=http://www.linuxfromscratch.org/lfs/view/6.4/>Linux From
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1921 Scratch</a> project for ideas on how to bootstrap your way up (adding
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1922 zlip and perl and such before building more complicated packages).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1923
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1924 <p>Note that FWL can build a LFS "temporary system", but that the packaged
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1925 mini-native tarballs and system images are not configured that way.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1926
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1927 <p>The vast majority of the space taken up by this filesystem is the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1928 development toolchain and associated support files (mostly header files and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1929 libraries).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1930
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1931 <p>If you're doing anything fancy, you'll probably want to rebuild it from
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1932 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1933
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1934 GCC is bad at cross compiling.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1935
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1936 <p>A cross compiler reads input files and writes output files. So does a
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1937 docbook to PDF converter; this is nothing special. A program can take both
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1938 explicit and implicit input. Explicit input is listed on the command line,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1939 or perhaps piped into stdin. Implicit input in the case of the docbook->pdf
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1940 converter would include fonts and stylesheets, which might live at some
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1941 common path on the host, or be handed out by a server.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1942
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1943 <p>Compilers take implicit input from five places:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1944
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1945 compiler #includes
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1946 system library #includes
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1947 compiler libs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1948 system libs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1949
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1950
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1951 <p>In theory, someday busybox may provide a decent /bin/bash replacement,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1952 but unfortunately busybox shell development is terminally fragmented (between
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1953 lash, hush, msh, and ash, which do not share significant amounts of code),
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1954 so don't hold your breath.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1955
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1956 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1957 variables for invoking download
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1958 mirrors
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1959 --extract, setupfor, cacheing
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1960 why hard links instead of symlinks
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1961 Packages that modify distributed source files without breaking links: bad.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1962
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1963 CPUS, make -j (As much parallelism as possible; SMP increasing.)
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1964
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1965 Minimal native build environment, seven packages.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1966 Why bash?
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1967 Busybox ash buggy. Busybox has four shells, not one scalable shell.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1968 Older version of bash, smaller and simpler.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1969
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1970 sources/native
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1971 src
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1972 qemu-setup.sh/chroot-setup.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1973 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1974
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1975 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1976
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1977 <h2><a name="native_compiling">Native compiling under emulation</a></h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1978
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1979 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1980 Why do this?
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1981 the distcc trick
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1982 run-with-distcc.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1983 hdb for working space.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1984 run-with-home.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1985 Building on nfs sucks rocks.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1986 Building out of tree with cp -rs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1987
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1988 /tools (Linux From Scratch chapter 5).
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1989 qemu-setup.sh and the /lib symlink.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1990
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1991 Deficiencies in the current mini-native filesystem:
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1992 host-tools.sh, bzip2, coreutils, diffutils.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1993
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1994 Building glibc is your problem.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1995 It requires perl. Statically linking "hello world" is 400k. It's evil.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1996 Still, building it natively sucks less than trying to cross compile it.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1997 Pretty much follow the non-cross Linux From Scratch procedures.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1998
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1999 Building a distro:
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2000 Linux From Scratch.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2001 Gentoo embedded.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2002 Debian/ubuntu.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2003
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2004 anatomy_of_include
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2005 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2006
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2007 <h2><a name="customize">Customizing mini-native</a></h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2008
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2009 Adding packages (to the script, without the script)
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2010
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2011 build/temp-$ARCH
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2012 build/cross-compiler-$ARCH
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2013 build/mini-native-$ARCH
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2014 build/qemu-image-*.tar
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2015
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2016
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2017 <a name="gcc_sucks><h2>What the hell is wrong with GCC?</h2></a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2018
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2019 <p>First of all, gcc wants to build itself with itself. When you build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2020 gcc it wants to compile a temporary version of itself, and then build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2021 itself again with that temporary compiler, and then build itself a _third_
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2022 time with the second compiler.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2023
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2024 <h1>Packaging</h1>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2025
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2026 <p>The single file packaging combines a linux kernel, initramfs, squashfs
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2027 partition, and cryptographic signature.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2028
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2029 <p>In Linux 2.6, the kernel and initramfs are already combined into a single
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2030 file. At the start of this file is either the obsolete floppy boot sector
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2031 (just a stub in 2.6), or an ELF header which has 12 used bytes followed by 8
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2032 unused bytes. Either way, we can generally use the 4 bytes starting at offset
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2033 12 to store the original length of the kernel image, then append a squashfs
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2034 root partition to the file, followed by a whole-file cryptographic
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2035 signature.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2036
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2037 <p>Loading an ELF kernel (such as User Mode Linux or a non-x86 ELF kernel)
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2038 is controlled by the ELF segments, so the appended data is ignored.
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2039 (Note: don't strip the file or the appended data will be lost.) Loading an x86
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2040 bzImage kernel requires a modified boot loader that can be told the original
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2041 size of the kernel, rather than querying the current file length (which would
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2042 be too long). Hence the patch to Lilo allowing a "length=xxx" argument in the
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2043 config file.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2044
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2045 <p>Upon boot, the kernel runs the initramfs code which finds the firmware
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2046 file. In the case of User Mode Linux, the symlink /proc/self/exe points
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2047 to the path of the file. A bootable kernel needs a command line argument
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2048 of the form firmware=device:/path/to/file (it can lookup the device in
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2049 /sys/block and create a temporary device node to mount it with; this is
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2050 in expectation of dynamic major/minor happening sooner or later).
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2051 Once the file is found, /dev/loop0 is bound to it with an offset (losetup -o,
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2052 with a value extracted from the 4 bytes stored at offset 12 in the file), and
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2053 the resulting squashfs is used as the new root partition.</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2054
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2055 <p>The cryptographic signature can be verified on boot, but more importantly
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2056 it can be verified when upgrading the firmware. New firmware images can
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2057 be installed beside old firmware, and LILO can be updated with boot options
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2058 for both firmware, with a default pointing to the _old_ firmware. The
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2059 lilo -R option sets the command line for the next boot only, and that can
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2060 be used to boot into the new firmware. The new firmware can run whatever
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2061 self-diagnostic is desired before permanently changing the default. If the
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2062 new firmware doesn't boot (or fails its diagnostic), power cycle the machine
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2063 and the old firmware comes up. (Note that grub does not have an equivalent
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2064 for LILO's -R option; which would mean that if the new firmware doesn't run,
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2065 you have a brick.)</p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2066
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2067 -->
881
0da87d1ef528 Update the web page. Put the left-side nav bar back, move about page to "about.html" and make news.html the default index. Add architectures page. Note that IRC discussion is now on #edev.
Rob Landley <rob@landley.net>
parents: 830
diff changeset
2068
0da87d1ef528 Update the web page. Put the left-side nav bar back, move about page to "about.html" and make news.html the default index. Add architectures page. Note that IRC discussion is now on #edev.
Rob Landley <rob@landley.net>
parents: 830
diff changeset
2069 <!--#include file="footer.html" -->