annotate www/documentation.html @ 977:8d6fe8ad822d

Comment tweak.
author Rob Landley <rob@landley.net>
date Sat, 06 Feb 2010 17:57:15 -0600
parents 0da87d1ef528
children b630081630a7
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
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
3 <h1>Documentation for Firmware Linux</h1>
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 <p>Note, this documentation is currently under construction. This is three
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
6 files concatenated together, with their contents in the process of being
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
7 reorganized and rewritten. Some of it's up to date, some isn't.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
8
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
9 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
10 <li><a href="#what_is_it">What is Firmware Linux?</a></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
11 <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
12 <li><a href="#how_build_source">How do I build my own customized system images from source code?</a></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
13 <li><a href="#how_implemented">How is Firmware Linux implemented?</a></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
14 <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
15 <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
16 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
17
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
18 <hr />
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
19 <a name="what_is_it"><h1>What is Firmware Linux?</h1></a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
20
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
21 <p>Firmware Linux is an embedded Linux build system, designed to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
22 replace cross compiling with native compiling under emulation. It provides
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
23 an easy way to get started with embedded development, building your own code
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
24 against uClibc, and testing it on non-x86 hardware platforms.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
25
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
26 <p>This documentation uses the name "Firmware Linux' (or abbreviation "FWL") to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
27 refer to the <a href=downloads>build system</a>, and calls the output of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
28 the build a "<a href=downloads/binaries/system-image>system image</a>".
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
29 The build system is implemented as a series of bash scripts and configuration
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
30 files which compile a Linux development system for the specified target and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
31 package it into a bootable binary image.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
32
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
33 <p>These system images provide a simple native Linux development
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
34 environment for a target, built from seven source packages: busybox, uClibc,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
35 gcc, binutils, make, bash, and the Linux kernel. This is the smallest
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
36 environment that can rebuild itself entirely from source code, and thus the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
37 minimum a host system must cross compile in order to create a fully independent
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
38 native development environment for a target.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
39
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
40 <p>Booting a development system image under an emulator such as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
41 <a href=http://bellard.org/qemu/>QEMU</a> allows fully
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
42 native builds for supported target platforms to be performed on cheap and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
43 powerful commodity PC hardware. Building and installing additional packages
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
44 (zlib, bison, openssl...) within a system image can provide an arbitrarily
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
45 complex native development environment, without resorting to any additional
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
46 cross compiling.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
47
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
48 <p>FWL currently includes full support for arm, mips, powerpc, x86 and x86-64
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
49 targets, and partial support for sh4, mips, and sparc. The goal for the FWL
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
50 1.0 release is to support every target QEMU can emulate in "system" mode.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
51
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
52 <p>Firmware Linux is licensed under GPL version 2. Its component packages are
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
53 licensed under their respective licenses (mostly GPL and LGPL).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
54
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
55 <h2>Optional extra complexity</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
56
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
57 <p>Intermediate stages of the build (such as the cross compiler and the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
58 unpackaged root filesystem directory) may also be useful to Linux developers,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
59 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
60
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
61 <p>By default the build cross-compiles some optional extra packages (toybox,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
62 distcc, uClibc++) and preinstalls them into the target filesystem. This is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
63 just a convenience; these packages build and install natively within the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
64 minimal development system image just fine.<!-- TODO: experimentally confirm
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
65 that, make it configurable, add genext2fs and strace to the list? -->)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
66
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
67 <hr />
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
68 <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
69
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
70 <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
71 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
72 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
73
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
74 <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
75
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
76 <h2>system-image-*.tar.bz2</h2>
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>System images boot a complete linux system under an emulator. Each
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
79 system-image tarball contains an ext2 root filesystem image, a Linux kernel
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
80 configured to run under the emulator <a href=http://bellard.org/qemu/>QEMU</a>,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
81 and a run-emulator.sh script.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
82
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
83 <p>The steps to test boot a system image under qemu 0.9.1 are:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
84 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
85 <li>install QEMU 0.9.1 or later</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
86 <li>download the appropriate <a href=downloads/image>prebuilt binary tarball</a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
87 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
88 <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
89 <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
90 <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
91 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
92
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
93 <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
94 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
95 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
96 scroll past is for a shell running inside the emulator. This lets you pipe
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
97 the output of other programs into the emulator, and capture the emulator's
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
98 output.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
99
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
100 <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
101 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
102
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
103 <p>Inside a system image, you generally wget source code from some URL and
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
104 compile it. (For example, you can wget the FWL build, extract it, and run it
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
105 inside one of its own system images to trivially prove it can rebuild itself.)
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
106 If you run a web server on your host's loopback interface, you an access it
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
107 inside QEMU using the special address "10.0.2.2". Example build scripts
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
108 are available in the /usr/src directory.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
109
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
110 <h3>Extra space and speed</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
111
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
112 <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
113 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
114 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
115 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
116 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
117
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
118 <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
119 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
120
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
121 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
122 <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
123 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
124 it ext3.</p></li>
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 <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
127 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
128 (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
129 --make-hdb was also specified.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
130
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
131 <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
132 <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
133 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
134 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
135 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
136 compiler through distcc.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
137 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
138
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
139 <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
140 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
141 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
142 exist) might look like:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
143
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
144 <blockquote><pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
145 <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
146 </pre></blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
147
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
148 <h2>mini-native-*.tar.bz2</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
149
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
150 <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
151 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
152 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
153
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
154 <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
155 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
156 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
157
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
158 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
159 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
160 <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
161 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
162 </blockquote>
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>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
165 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
166 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
167 process exits.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
168
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
169 <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
170 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
171 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
172 <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
173 From Scratch</a>.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
174
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
175 <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
176 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
177 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
178
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
179 <h2>cross-compiler-*.tar.bz2</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
180
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
181 <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
182 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
183 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
184 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
185 supported, but not recommended.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
186
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
187 <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
188 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
189
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
190 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
191 <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
192 <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
193 <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
194 <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
195 to "$TARGET-" with a trailing dash.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
196 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
197
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
198 <p>Also, stock up on asprin and clear a space to beat your head against; you'll
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
199 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
200 sucks</a> for more details.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
201
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
202 <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
203 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
204 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
205 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
206
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
207 <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
208 from source code?</h1></a>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
209
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
210 <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
211 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
212 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
213 version</a>, although once you've got the hang of it you might want to follow
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
214 the <a href=/hg/firmware>development version</a>.</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>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
217 "<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
218 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
219
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
220 <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
221 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
222 build.sh.</p>
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 <h2>How building from source works</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
225
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
226 <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
227 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
228 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
229 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
230 build these packages.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
231
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
232 <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
233 other scripts in sequence:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
234 <ol>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
235 <li>download.sh</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
236 <li>host-tools.sh</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
237 <li>cross-compiler.sh $TARGET</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
238 <li>mini-native.sh $TARGET</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
239 <li>package-mini-native.sh $TARGET</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
240 </ol>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
241
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
242 <p>In theory, the stages are othogonal. If you have an existing cross
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
243 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
244 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
245 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
246 entirely.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
247
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
248 <h3>Build stages</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
249
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
250 <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
251 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
252
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
253 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
254 <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
255
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
256 <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
257 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
258 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
259 <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
260 $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
261 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
262
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
263 <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
264 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
265 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
266 build scripts).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
267
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
268 <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
269 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
270 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
271 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
272 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
273 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
274
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
275 <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
276
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
277 <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
278 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
279 any of the output tarballs.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
280
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
281 <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
282 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
283 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
284 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
285
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
286 <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
287 one directory, which serves several purposes:</p>
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 <ul>
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 <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
292 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
293 installed on the host.</p></li>
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 <li><p><b>Portability</b> - Using a known set of command line utilities
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
296 insulates the build from variations in the host's Linux distribtion (such as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
297 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
298
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
299 <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
300 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
301 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
302 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
303 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
304 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
305
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
306 <p>It also moves most failures to the beginning. If anything's going to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
307 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
308 in a known and tested state.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
309
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
310 <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
311 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
312 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
313 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
314
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
315 <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
316 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
317 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
318 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
319
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
320 <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
321 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
322 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
323 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
324 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
325 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
326
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
327 <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
328 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
329 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
330 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
331
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
332 <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
333 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
334
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
335 <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
336 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
337 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
338 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
339 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
340
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
341 <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
342 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
343 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
344 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
345 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
346
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
347 <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
348 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
349 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
350 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
351
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
352 <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
353 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
354 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
355 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
356 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
357 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
358 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
359
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
360 <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
361 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
362 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
363 (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
364 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
365 $TARGET-gcc to create target binaries.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
366 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
367
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
368 <li><p><b>mini-native.sh</b> - Use the cross compiler to create
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
369 a minimal native build environment for the target platfrom.<p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
370
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
371 <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
372
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
373 <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
374 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
375 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
376 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
377 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
378
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
379 <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
380 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
381 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
382 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
383 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
384 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
385 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
386 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
387
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
388 <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
389 of the native root filesystem.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
390
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
391 <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
392
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
393 <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
394 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
395 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
396 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
397 copy.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
398
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
399 <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
400 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
401 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
402
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
403 <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
404 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
405
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
406 <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
407 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
408 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
409 system image's root filesystem.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
410
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
411 <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
412 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
413 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
414 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
415 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
416 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
417
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
418 <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
419 the build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
420
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
421 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
422 <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
423
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
424 <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
425 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
426 changes the build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
427
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
428 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
429 <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
430 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
431 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
432 variable enabled by default in config.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
433
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
434 <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
435 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
436 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
437 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
438 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
439
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
440 <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
441 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
442 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
443 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
444 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
445
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
446 <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
447 package.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
448
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
449 <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
450 used by the build. Afterwards, the script
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
451 "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
452 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
453 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
454
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
455 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
456 <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
457 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
458
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
459 <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
460 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
461 #!/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
462 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
463
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
464 <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
465 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
466
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
467 <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
468 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
469 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
470 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
471 argument. (Requires QEMU installed.)</p></li>
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 <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
474 packages from this URL first, before falling back to the normal mirror list.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
475 For example, "PREFERRED_MIRROR=http://impactlinux.com/fwl/mirror".</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
476
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
477 <li><p><b>USE_TOYBOX</b> - Tells the host-tools.sh and mini-native.sh to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
478 install the <a href=http://impactlinux.com/code/toybox>toybox</a> implementation
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
479 of commands (where available) instead of the busybox versions. This is an
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
480 alternate (simpler) implementation of many commands.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
481
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
482 <p>Currently FWL always uses the toybox "patch" command, because the busybox
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
483 version can't apply patches at offsets.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
484 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
485
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
486 <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
487 versions for.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
488
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
489 <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
490
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
491 <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
492 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
493 development versions, for testing purposes.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
494
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
495 <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
496 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
497 (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
498 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
499 "download" and "setupfor" shell functions.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
500 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
501
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
502 <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
503
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
504 <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
505 progress.</p>
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 <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
508 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
509 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
510 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
511 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
512 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
513 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
514
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
515 <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
516 at once.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
517
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
518 <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
519 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
520 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
521
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
522 <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
523 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
524 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
525 </ul>
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 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
528 <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
529
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
530 <h2>Directory layout</h2>
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 <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
533 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
534 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
535 Important directories under sources include:</p>
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 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
538 <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
539
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
540 <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
541 (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
542 (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
543 </li>
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 <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
546 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
547
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
548 <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
549 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
550 source code.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
551
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
552 <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
553 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
554 somewhere else.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
555 </ul>
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 <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
558 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
559 builds.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
560
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
561 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
562 <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
563 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
564 source each time.</p></li>
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 <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
567 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
568 point only to this directory.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
569
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
570 <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
571 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
572 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
573 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
574 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
575
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
576 <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
577 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
578 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
579
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
580 <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
581 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
582 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
583
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
584 <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
585 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
586 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
587 </ul>
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 <h2>Shared infrastructure</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
590
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
591 <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
592 <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
593 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
594
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
595 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
596 <li><p>Its command line argument is the architecture to build.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
597 If run with no arguments, it outputs all available architectures by
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
598 listing the subdirectories under sources/targets. (The special environment
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
599 variable $NO_ARCH tells it to skip that part; this is used by download.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
600 and host-tools.sh which are architecture independent.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
601 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
602
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
603 <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
604 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
605 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
606
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
607 <li><p>It sets several other environment variables, specifying things like the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
608 $SOURCE and $BUILD directories, and detecting the number of $CPUS.</p></li>
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
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
612 that directory.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
613
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
614 <li><p>If host-tools.sh ran with $RECORD_COMMANDS, it sets the $PATH to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
615 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
616 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
617 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
618 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
619
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
620 <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
621 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
622
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
623 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
624 <li><p><b>download</b> - Used by download.sh. Calls wget if necessary, uses
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
625 sha1sum to verify the files. Treat as a fancy call to "wget".</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
626
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
627 <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
628 (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
629
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
630 <li><p><b>setupfor</b> - extract a source package (named in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
631 first argument) into a temporary directory, and change the current directory
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
632 to there. Treat as a fancy "tar -xvjf" followed by cd.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
633
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
634 <p>Source code is cached, meaning each package's source tarball is only
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
635 actually extracted and patched once (into build/sources) and the temporary
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
636 copies are directories full of hard links to the cached source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
637 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
638
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
639 <li><p><b>cleanup</b> - delete temporary copy of source code after build.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
640 Treat as a fancy "rm -rf". (If the exit code of the last command was nonzero,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
641 it calls dienow instead of deleting the source code that didn't build
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
642 properly, to preserve the evidence of what went wrong.)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
643 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
644
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
645 <p>Most of what include.sh does is optional. A lot of it's there to speed up
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
646 and simplify the rest of the build. (You don't really need to call "make -j"
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
647 for parallel bilds, and can re-extract and re-patch source code each time
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
648 you need it rather than cacheing the extracted version.) Most of the rest is
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
649 error checking, from "dienow" to the sha1sum checking in "download".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
650
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
651 <p>None of this should be important to understanding how to build or install
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
652 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
653 bits.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
654
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
655 <h2>Downloading source code</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
656
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
657 <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
658 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
659 the shell function <b>download</b>, which calls wget as necessary. The
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
660 download.sh script is just a series of calls to the download function.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
661
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
662 <p>The first thing download.sh does is check for the --extract option,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
663 and if present set the environment variable EXTRACT_ALL, which tells
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
664 each call to the download function to call the extract shell function on
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
665 the appropriate tarball to prepopulate the source cache. (See "Extracting
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
666 source code", below.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
667
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
668 <p>Each call to the download function is controlled by the following
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
669 <b>environment variables</b>:<p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
670
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
671 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
672 <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
673 into the sources/packages directory.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
674
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
675 <p>In addition to specifying a web location, this URL specifies the name of the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
676 source package to fetch. If this source tarball cannot be fetched from this
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
677 location, download tries to download the file from a series of fallback mirrors,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
678 most importantly http://impactlinux.com/firmware/mirror which should have every
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
679 source tarball used by the build.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
680
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
681 <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
682 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
683 The shell function "basename" uses a rather complicated regex to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
684 extract the package name from a URL. The package name is used by things
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
685 like setupfor, allowing the build scripts to mostly ignore the versions of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
686 the packages they build.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
687
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
688 <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
689
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
690 <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
691 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
692 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
693 detect corrupted or truncated files.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
694
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
695 <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
696 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
697 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
698 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
699
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
700 <li><p><b>PREFERRED_MIRROR</b></p> - This contains the URL of a mirror site
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
701 to be checked _before_ downloading from the actual $URL specified in
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
702 download.sh.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
703
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
704 <p>This allows download.sh to fetch some or all of its packages from a local
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
705 mirror of the files, instead of going out to the net. Any files not found
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
706 in this mirror will be fetched from the standard URL, and the fallback mirrors
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
707 as necessary.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
708
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
709 <p>(Note: inside qemu the special address 10.0.2.2 passes through connections
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
710 to 127.0.0.1 on the host, so if you run a web server on hour host's loopback
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
711 address you can easily pass source code into the emulator without going out
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
712 to an external network.)</p></li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
713
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
714 <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
715 testing purposes.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
716
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
717 <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
718 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
719 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
720
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
721 <p>Unstable packages are saved as a tarball called "alt-$PACKAGE-0" plus the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
722 file type extension, so the name to save is based on the filename in the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
723 normal $URL rather than on what the $UNSTABLE address points to. (So even if
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
724 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
725 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
726
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
727 <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
728
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
729 <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
730 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
731 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
732 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
733 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
734
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
735 <p>At the end of download.sh is a call to the shell function cleanup_oldfiles,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
736 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
737 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
738 each file it verifies the sha1sum of. Then cleanup_oldfiles deletes every
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
739 file from sources/packages with a date older than $START_TIME.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
740
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
741 <p>Note that download updates the timestamp on stable packages when
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
742 downloading corresponding unstable stable packages, so cleanup_oldfiles
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
743 won't delete them. In this special case they're not considered "unused
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
744 files", but it won't verify their integrity or fetch them if they're not
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
745 already there. If a package is not in the USE_UNSTABLE list, download.sh won't
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
746 update the timestamp on unstable source tarballs, leaving them marked as
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
747 unused and thus deleted by cleanup_oldfiles.</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 <h2>Extracting source code</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
750
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
751 <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
752 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
753 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
754 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
755 <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
756 (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
757 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
758 "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
759
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
760 <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
761 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
762 (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
763
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
764 <p>FWL implements source cacheing. The first call to setupfor extracts the
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
765 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
766 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
767 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
768 (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
769 in-tree.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
770
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
771 <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
772 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
773 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
774 parallel.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
775
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
776 <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
777 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
778 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
779 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
780 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
781 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
782 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
783 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
784 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
785 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
786 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
787 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
788
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
789 <h2>Building host tools</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
790
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
791 <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
792 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
793 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
794 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
795 <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
796 directory.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
797
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
798 <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
799 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
800 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
801
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
802 <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
803 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
804 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
805 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
806 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
807 installed.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
808
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
809 <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
810 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
811
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
812 <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
813
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
814 <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
815 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
816 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
817
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
818 <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
819 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
820 ./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
821 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
822 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
823
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
824 <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
825 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
826 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
827 in the $PATH:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
828
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
829 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
830 <p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
831 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
832 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
833 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
834 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
835 </p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
836 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
837
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
838 <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
839
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
840 <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
841 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
842 /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
843 #!/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
844 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
845 $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
846
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
847 <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
848 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
849 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
850 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
851 target.)</p>
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><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
854 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
855 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
856 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
857 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
858 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
859 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
860 $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
861 tools.)</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 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
864 (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
865 symlinks to that logging wrapper for each command name in $PATH. When later
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
866 build stages run commands, the wraper appends the command line to the log file
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
867 (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
868 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
869 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
870 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
871
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
872 <h2>Building a cross compiler</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
873
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
874 <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
875 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
876 let's get it over with.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
877
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
878 <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
879 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
880 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
881 script always does a clean build.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
882
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
883 <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
884
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
885 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
886 <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
887
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
888 <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
889 thing you build for a target.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
890 </li>
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 <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
893
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
894 <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
895 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
896
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
897 <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
898 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
899 <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
900 builds.</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>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
903 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
904 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
905 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
906 not target binaries.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
907 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
908
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
909 <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
910 path logic.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
911
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
912 <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
913 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
914 --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
915 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
916
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
917 <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
918 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
919 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
920
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
921 <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
922 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
923
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
924 <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
925 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
926 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
927 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
928 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
929 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
930 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
931 </li>
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 <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
934
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
935 <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
936 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
937 Linux kernel.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
938 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
939
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
940 <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
941
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
942 <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
943 (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
944 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
945
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
946 <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
947 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
948 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
949 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
950 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
951
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
952 <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
953 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
954 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
955 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
956 location.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
957 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
958 </ul>
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>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
961 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
962 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
963 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
964 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
965 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
966
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
967 <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
968
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
969 <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
970 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
971 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
972
531
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
973 <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
974 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
975 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
976
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
977 <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
978 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
979 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
980 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
981 under itself.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
982
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
983 <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
984 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
985 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
986 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
987 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
988 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
989 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
990
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
991 <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
992 <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
993 /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
994 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
995 $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
996 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
997
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
998 <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
999 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
1000 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
1001 be "/usr".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1002
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1003 <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
1004
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1005 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1006 <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
1007 filesystem layout.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1008
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1009 <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
1010 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
1011 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
1012 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
1013 $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
1014 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
1015 "/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
1016 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
1017 into /tools.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1018 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1019
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1020 <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
1021 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
1022 src directory.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1023
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1024 <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
1025
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1026 <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
1027 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
1028 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
1029
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1030 <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
1031 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
1032 $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
1033
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1034 <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
1035
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1036 <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
1037 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
1038 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
1039
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1040 <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
1041 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
1042
4828f4597ede Documentation tweak talking about mini-native, and warning that the last
Rob Landley <rob@landley.net>
parents: 526
diff changeset
1043 <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
1044 $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
1045 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
1046 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
1047 directories.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1048 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1049
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1050 <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
1051
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1052 <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
1053 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
1054 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
1055 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
1056 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
1057
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1058 <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
1059 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
1060 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
1061 is biased here.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1062 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1063
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1064 <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
1065
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1066 <p>This provides the bulk of the command line utlities for the new
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1067 system.</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>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
1070 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
1071 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
1072 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
1073 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
1074
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1075 <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
1076 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
1077 <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
1078 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
1079 why specific features are disabled.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1080 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1081
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1082 <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
1083 only if $NATIVE_TOOLCHAIN is set.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1084
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1085 <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
1086 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
1087 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
1088
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1089 <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
1090 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1091 <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
1092
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1093 <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
1094
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1095 <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
1096 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
1097 <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
1098 digression into the details.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1099
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1100 <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
1101 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
1102 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
1103 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
1104 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
1105 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
1106
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1107 <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
1108 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
1109 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
1110 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
1111 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
1112 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
1113 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
1114 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
1115 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
1116
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1117 <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
1118 /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
1119 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
1120 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
1121 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
1122 </li>
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 <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
1125
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1126 <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
1127 (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
1128 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
1129 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
1130 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
1131 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
1132 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
1133 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
1134 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
1135
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1136 <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
1137 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
1138 time.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1139 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1140
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1141 <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
1142
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1143 <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
1144 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
1145 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
1146 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
1147
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1148 <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
1149 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
1150 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
1151 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
1152 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
1153 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
1154 "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
1155 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1156
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1157 <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
1158
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1159 <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
1160 straightforward to build.</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>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
1164
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1165 <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
1166 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
1167 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
1168
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1169 <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
1170 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
1171 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
1172 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
1173 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
1174
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1175 <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
1176 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
1177 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
1178 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
1179 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
1180 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
1181 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1182
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1183 <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
1184 cluster.</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1185
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1186 <p>We install this for <a href="#distcc_trick">the distc accelerator
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1187 trick</a>. It's entirely optional.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1188
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1189 <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
1190 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
1191 $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
1192 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1193 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1194
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1195 <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
1196 and packaging.</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 <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
1199
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1200 <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
1201 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
1202 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
1203 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
1204
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1205 <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
1206
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1207 <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
1208 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1209
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1210 <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
1211 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
1212 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
1213 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
1214 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
1215
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1216 <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
1217
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1218 <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
1219 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
1220 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
1221 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
1222
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1223 <p>The steps here are:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1224
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1225 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1226 <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
1227 megabyte ext2 image.</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1228
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1229 <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
1230 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
1231
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1232 <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
1233 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
1234 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
1235 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
1236 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
1237 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
1238 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
1239
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1240 <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
1241 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
1242 </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>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
1245 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
1246 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
1247
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1248 <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
1249 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1250
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1251 <h2>Running on real hardware</a></h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1252
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1253 <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
1254 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
1255 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
1256
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1257 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1258 <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
1259
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1260 <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
1261
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1262 <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
1263 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
1264 boards)</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1265
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1266 <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
1267 (ext2, initramfs, jffs2).</p></li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1268 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1269
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1270 <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
1271
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1272 <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
1273 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
1274 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
1275
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1276 <p>
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1277
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1278 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1279
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1280 <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
1281
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1282 <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
1283
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1284 <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
1285 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
1286 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
1287
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1288 <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
1289
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1290 <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
1291 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
1292 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
1293 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
1294
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1295 <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
1296 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
1297 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
1298 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
1299 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
1300
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1301 <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
1302 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
1303
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1304 <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
1305
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1306 <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
1307
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1308 <p>TODO: FILL THIS OUT</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1309
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1310 <h2>The basic theory</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1311
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1312 <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
1313 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
1314 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
1315
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1316 <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
1317 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
1318 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
1319 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
1320 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
1321 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
1322 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
1323
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1324 <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
1325 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
1326
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1327 <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
1328 <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
1329 <li>BusyBox</li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1330 <li>A C library (uClibc)</li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1331 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1332
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1333 <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
1334
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1335 <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
1336
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1337 <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
1338 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
1339 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
1340 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
1341
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1342 <h3>Environmental dependencies.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1343
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1344 <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
1345 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
1346 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
1347 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
1348 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
1349 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
1350 minimized.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1351
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1352 <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
1353 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
1354 (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
1355 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
1356 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
1357 need.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1358
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1359 <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
1360 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
1361 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
1362 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
1363 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
1364 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
1365 this kind of environmental dependency.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1366
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1367 <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
1368 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
1369 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
1370 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
1371 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
1372 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
1373 environment.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1374
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1375 <h3>Resolving environmental dependencies.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1376
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1377 <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
1378 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
1379 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
1380 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
1381 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
1382 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
1383
702
a8854df93e15 Fix typo that left a tag unclosed.
Rob Landley <rob@landley.net>
parents: 655
diff changeset
1384 <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
1385 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
1386 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
1387 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
1388 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
1389 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
1390
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1391 <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
1392 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
1393 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
1394 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
1395
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1396 <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
1397 <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
1398 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
1399 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
1400
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1401 <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
1402 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
1403 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
1404 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
1405 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
1406 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
1407 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
1408 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
1409
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 <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
1411 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
1412 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
1413 <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
1414 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
1415 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
1416 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
1417
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1418 <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
1419 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
1420 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
1421 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
1422 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
1423 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
1424 produce similarly optimized binaries.)</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1425
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1426 <h2>Additional complications</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1427
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1428 <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
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>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
1431 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
1432 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
1433 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
1434 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
1435 it's the same processor.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1436
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1437 <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
1438 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
1439 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
1440 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
1441 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
1442 tmpfs)...</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1443
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1444 <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
1445 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
1446 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
1447 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
1448 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
1449 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
1450 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
1451 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
1452 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
1453 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
1454 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
1455 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
1456 everything we've told it.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1457
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1458 <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
1459 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
1460 (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
1461 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
1462 ugly.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1463
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1464 <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
1465 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
1466 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
1467 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
1468 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
1469 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
1470 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
1471 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
1472 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
1473 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
1474 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
1475 not necessarily an older one.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1476
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1477 <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
1478
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1479 <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
1480
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1481 <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
1482 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
1483 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
1484 hard to do.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1485
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1486 <p>I wrote an <a href=/writing/docs/cross-compiling.html>introduction
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1487 to cross-compiling</a> which explains the terminology, plusses and minuses,
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1488 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
1489 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
1490 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
1491 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
1492 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
1493
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1494 <h3>Which emulator?</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1495
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1496 <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
1497 <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
1498 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
1499 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
1500 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
1501
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1502 <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
1503 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
1504 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
1505 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
1506 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
1507 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
1508 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
1509 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
1510 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
1511 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
1512 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
1513
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1514 <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
1515 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
1516 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
1517 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
1518 kernel and run it under QEMU.</p>
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>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
1521 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
1522 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
1523 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
1524 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
1525 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
1526
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1527 <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
1528 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
1529 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
1530 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
1531
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1532 <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
1533 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
1534 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
1535 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
1536 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
1537 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
1538
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1539 <h2>Packaging</h2>
518
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 <h2>Filesystem Layout</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1542
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1543 <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
1544 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
1545 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
1546 make the root partition read-only.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1547
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1548 <h3>Simplifying the $PATH.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1549
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1550 <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
1551 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
1552 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
1553 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
1554 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
1555 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
1556 Libraries are in /usr/lib.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1557
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1558 <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
1559 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
1560 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
1561 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
1562 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
1563 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
1564
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1565 <p>The real reason we kept it is tradition. The execuse is that the root
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1566 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
1567 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
1568 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
1569 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
1570 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
1571
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1572 <p>I.E. The seperation is just a historical relic, and I've consolidated it in
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1573 the name of simplicity.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1574
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1575 <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
1576 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
1577 (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
1578 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
1579 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
1580 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
1581 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
1582 /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
1583 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
1584 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
1585 like firefox or open office.</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 <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
1588 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
1589 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
1590 /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
1591 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
1592
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1593 <h3>Consolidating writeable directories.</h3>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1594
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1595 <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
1596 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
1597 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
1598 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
1599 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
1600 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
1601 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
1602 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
1603 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
1604 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
1605 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
1606
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1607 <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
1608 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
1609 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
1610 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
1611 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
1612 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
1613 just symlink them together.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1614
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1615 <p>(I case it hasn't become apparent yet, there's 30 years of accumulated cruft
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1616 in the standards, convering a lot of cases that don't apply outside of
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1617 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
1618 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
1619 an embedded system.)</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1620
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1621 <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
1622 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
1623 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
1624 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
1625 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
1626 /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
1627 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
1628 /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
1629 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
1630 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
1631
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1632 <h3>The resulting mount points</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>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
1635 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
1636 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
1637 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
1638 /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
1639 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
1640 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
1641
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1642 <p>Remember to
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1643 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
1644 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
1645 is good.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1646
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1647
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1648 <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
1649 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
1650 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
1651 for an arbitrary target hardware platform.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1652
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1653 <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
1654 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
1655 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
1656 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
1657 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
1658 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
1659 appropriately.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1660
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1661
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1662 <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
1663 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
1664 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
1665 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
1666 /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
1667 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
1668
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1669 <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
1670 (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
1671 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
1672
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1673 <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
1674 <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
1675
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1676
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1677 <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
1678
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1679 <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
1680 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
1681 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
1682 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
1683 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
1684
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1685 <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
1686
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1687 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1688 <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
1689 <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
1690 <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
1691 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1692
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1693 <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
1694 <b>include.sh</b>.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1695
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1696 <h2>Target name.</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1697
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1698 <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
1699 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
1700 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
1701 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
1702 appropriately.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1703
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1704 <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
1705 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
1706 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
1707 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
1708 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
1709 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
1710 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
1711
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1712 <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
1713 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
1714 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
1715 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
1716
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1717 <h2>$ARCH/details</h2>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1718
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1719 <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
1720 file:</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1721
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1722 <ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1723 <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
1724
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1725 <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
1726 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
1727 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
1728 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
1729
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1730 <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
1731 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
1732 necessary.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1733 </li>
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 <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
1736
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1737 <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
1738 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
1739 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1740 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1741
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1742 <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
1743 bootable kernel image is generated.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1744
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1745 <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
1746 option. Usually "arch/${KARCH}/boot/zImage", but
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1747 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
1748 level directory...</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1749 </li>
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 <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
1752
655
62a727f52a18 Update docs to mention download RENAME option.
Rob Landley <rob@landley.net>
parents: 635
diff changeset
1753 <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
1754 ABI, or --with-cpu.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1755 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1756
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1757 <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
1758
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1759 <p>Usually blank.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1760 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1761
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1762 <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
1763
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1764 <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
1765 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
1766 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
1767 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
1768 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
1769 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
1770 outputs "Hello world!".</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1771
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1772 <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
1773 </li>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1774
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1775 <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
1776 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
1777 image tarball.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1778
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1779 <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
1780 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
1781 stdout (generally using "echo").<p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1782
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1783 <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
1784 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
1785 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
1786 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
1787 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
1788 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
1789 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
1790 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
1791 set those before calling it.</p>
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1792 </li>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1793
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1794 </ul>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1795
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1796 <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
1797
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1798 <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
1799 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
1800 and kept for future reference.</p>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1801
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1802 <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
1803 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
1804 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
1805 allnoconfig.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1806
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1807 <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
1808 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
1809 "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
1810 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
1811 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
1812 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
1813 .config file converted to miniconfig format.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1814
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1815 <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
1816 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1817 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1818 make ARCH=$KARCH menuconfig
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1819 mv .config tempfile
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1820 ARCH=$KARCH miniconfig.sh tempfile
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1821 ls -l mini.config
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1822 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1823 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1824
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1825 <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
1826 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
1827
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1828 <blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1829 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1830 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
1831 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1832 </blockquote>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1833
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1834 <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
1835
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1836 <h2>$ARCH/miniconfig-linux</h2>
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1837 <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
1838 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
1839 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
1840 free.</p>
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1841
635
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1842 <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
1843 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
1844 "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
1845 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
1846
c796d3ebf179 Fluff out docs a bit (miniconfig: what hardware does qemu need?)
Rob Landley <rob@landley.net>
parents: 584
diff changeset
1847 <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
1848 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
1849 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
1850 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
1851 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
1852 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
1853 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
1854 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
1855 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
1856
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1857 <h2>$ARCH/miniconfig-uClibc</h2>
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1858
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1859 <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
1860 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
1861 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
1862 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
1863 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
1864 contents.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1865
520
16adbffb58b0 More documentation tweaks, adding a new target section.
Rob Landley <rob@landley.net>
parents: 518
diff changeset
1866 <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
1867 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
1868 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
1869 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
1870 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
1871 extra complexity.</p>
518
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 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1874
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1875 <!--
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1876
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1877 <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
1878 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
1879 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
1880 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
1881 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
1882 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
1883 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
1884
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1885 <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
1886 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
1887
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1888 <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
1889 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
1890 libraries).</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1891
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1892 <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
1893 source.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1894
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1895 GCC is bad at cross compiling.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1896
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1897 <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
1898 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
1899 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
1900 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
1901 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
1902 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
1903
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1904 <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
1905
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1906 compiler #includes
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1907 system library #includes
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1908 compiler libs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1909 system libs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1910
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 <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
1913 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
1914 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
1915 so don't hold your breath.</p>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1916
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1917 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1918 variables for invoking download
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1919 mirrors
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1920 --extract, setupfor, cacheing
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1921 why hard links instead of symlinks
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1922 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
1923
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1924 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
1925
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1926 Minimal native build environment, seven packages.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1927 Why bash?
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1928 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
1929 Older version of bash, smaller and simpler.
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 sources/native
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1932 src
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1933 qemu-setup.sh/chroot-setup.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1934 </pre>
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 <hr>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1937
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1938 <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
1939
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1940 <pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1941 Why do this?
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1942 the distcc trick
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1943 run-with-distcc.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1944 hdb for working space.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1945 run-with-home.sh
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1946 Building on nfs sucks rocks.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1947 Building out of tree with cp -rs
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1948
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1949 /tools (Linux From Scratch chapter 5).
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1950 qemu-setup.sh and the /lib symlink.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1951
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1952 Deficiencies in the current mini-native filesystem:
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1953 host-tools.sh, bzip2, coreutils, diffutils.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1954
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1955 Building glibc is your problem.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1956 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
1957 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
1958 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
1959
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1960 Building a distro:
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1961 Linux From Scratch.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1962 Gentoo embedded.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1963 Debian/ubuntu.
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 anatomy_of_include
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1966 </pre>
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1967
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1968 <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
1969
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1970 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
1971
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1972 build/temp-$ARCH
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1973 build/cross-compiler-$ARCH
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1974 build/mini-native-$ARCH
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1975 build/qemu-image-*.tar
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
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1978 <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
1979
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1980 <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
1981 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
1982 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
1983 time with the second compiler.
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
1984
584
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1985 <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
1986
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1987 <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
1988 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
1989
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1990 <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
1991 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
1992 (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
1993 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
1994 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
1995 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
1996 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
1997
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
1998 <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
1999 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
2000 (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
2001 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
2002 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
2003 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
2004 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
2005
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2006 <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
2007 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
2008 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
2009 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
2010 /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
2011 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
2012 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
2013 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
2014 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
2015
26a5ac0c01ce Random update to docs I did a while ago, need to do more.
Rob Landley <rob@landley.net>
parents: 531
diff changeset
2016 <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
2017 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
2018 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
2019 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
2020 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
2021 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
2022 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
2023 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
2024 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
2025 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
2026 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
2027
518
f109c324cca4 Massive documentation rewrite. Not quite finished, but better.
Rob Landley <rob@landley.net>
parents:
diff changeset
2028 -->
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
2029
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
2030 <!--#include file="footer.html" -->