annotate www/FAQ.html @ 1228:8a88cae14011

Remove RW_SYSTEM_IMAGE option. The gentoo-stage1 build shows how to setup a writeable chroot, and the FAQ says how to build a writeable system image. I'm not shipping two different system iamges, then I'd have to explain it and it's not worth the confusion.
author Rob Landley <rob@landley.net>
date Tue, 24 Aug 2010 02:53:11 -0500
parents 39fda120621c
children d6e6c9ddf7f9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
1 <html>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
2 <!--#include file="header.html" -->
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
3 <title>Frequently Asked Questions</title>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
4
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
5 <ul>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
6 <li><p><a href=#where_start>Q: Where do I start?</a></p></li>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
7
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
8 <li><p><a href=#source_tour>Q: What's all this source code for?</a></p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
9
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
10 <li><p><a href=#name_change>Q: Didn't this used to be called Firmware Linux?</a></p></li>
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
11
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
12 <li><p><a href=#add_package>Q: How do I add $PACKAGE to my system image's root filesystem?</a></p></li>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
13
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
14 <li><p><a href=#ubuntu_mispackaged_qemu>Q: ./run-emulator.sh says qemu-system-mips isn't found, but I installed qemu. Why isn't this working?</a></p></li>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
15
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
16 <li><p><a href=#case_sensitive_patch>Q: I added my uClibc patch to sources/patches but it didn't do anything, what's wrong?</a></p></li>
896
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
17
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
18 <li><p><a href=#package_breaks>Q: Why did package build $NAME die because it couldn't find $PREREQUISITE, even though it's installed?</a></p></li>
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
19
1225
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
20 <li><p><a href=#environment_sanitizing>Q: Why isn't the build listening to the environment variables I set?</p></li>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
21
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
22 <li><p><a href=#debugging><h1>Debugging questions</h1></a></p></li>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
23
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
24 <ul>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
25 <li><p><a href=#debug_logging>Q: How do I get better log output?</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
26 <li><p><a href=#debug_source>Q: How do I play around with package source code?</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
27 <ul>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
28 <li><p><a href=#debug_package_cache>Q: What's the package cache for?</a></p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
29 <li><p><a href=#debug_working_copies>Q: What are working copies for?</a></p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
30 </ul>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
31 </ul>
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
32 </ul>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
33
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
34 <a name=where_start /><h2>Q: Where do I start?</h2>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
35
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
36 <p>The project provides development and test environments for lots of different
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
37 hardware platforms, based on busybox and uClibc and configured to run under
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
38 QEMU.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
39
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
40 <p>Most people want to do one of three things:</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
41
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
42 <li><p>Download a prebuilt system image, boot it up under the emulator, and
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
43 compile stuff natively for a target.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
44
901
777af6561b2c Fix FAQ links pointed out by by wangji.
Rob Landley <rob@landley.net>
parents: 896
diff changeset
45 <p>Go <a href=screenshots>here</a> and download the appropriate
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
46 system-image-<b>$ARCH</b>.tar.bz2 for your $TARGET, extract it, cd into it,
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
47 and <b>./run-emulator.sh</b> to boot it under qemu.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
48
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
49 <p>Alternately, you can run the script <b>./development-environment.sh</b>,
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
50 which is a wrapper around run-emulator.sh that feeds QEMU extra options to add
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
51 memory (256 megs) and writeable disk space (a blank 2 gigabyte disk image
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
52 mounted on /home) to provide a more capable development environment.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
53
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
54 <p>The system images contain native compiler toolchains, but if you install
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
55 distccd on the host and add the appropriate cross compiler to your host's
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
56 $PATH, the ./run-emulator.sh script will detect this and set up the system
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
57 image to automatically use distcc to call out to the cross compiler through
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
58 the virtual network, speeding up native builds significantly.<p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
59 </li>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
60
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
61 <li><p>Build your own cross compilers and system images from source, using
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
62 the build scripts.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
63
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
64 <p>Go to the <a href=downloads>downloads directory</a>, grab the most recent
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
65 release tarball, extract it, and run <b>./build.sh</b> to list
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
66 the available targets. The run <b>./build.sh $TARGET</b> to compile
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
67 the one you like. The results wind up in the "build" directory.</p>
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
68
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
69 <p>The build scripts are written in bash, and fairly extensively commented.
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
70 All the scripts at the top level are designed to be run directly, and
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
71 build.sh is just a wrapper script that calls them in order. The less commonly
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
72 used scripts in <b>sources/more</b> are also designed to be run directly.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
73
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
74 <p>A large number of variables can be set to configure the build, either
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
75 by modifying the file "config" (which documents them all) or by exporting
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
76 them as environment variables.</p>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
77
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
78 <p>To grab the latest development version of the build scripts out of the
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
79 source control system, go to the
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
80 <a href=http://impactlinux.com/hg/aboriginal>mercurial archive</a>.
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
81 If you don't want to install mercurial, you can grab a
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
82 <a href=http://impactlinux.com/hg/aboriginal/archive/tip.tar.bz2>tarball</a> of the current code at
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
83 any time.</p>
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
84 </li>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
85
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
86 <ul>
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
87 <li><p>Download a prebuilt cross compiler and cross-compile stuff with it.</p>
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
88
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
89 <p>Go <a href=screenshots>here</a> and download the appropriate
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
90 cross-compiler-<b>$TARGET</b>.tar.bz2 for your $TARGET, extract it, add its
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
91 "bin" directory to your $PATH, and use the appropriate $TARGET-cc and
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
92 $TARGET-ld and so on to compile your program. (The tool names have prefixes
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
93 so they can be in the same $PATH as your host's existing compiler.)</p>
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
94 </li>
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
95
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
96 </ul>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
97
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
98 <p>If all else fails, look at the pretty
901
777af6561b2c Fix FAQ links pointed out by by wangji.
Rob Landley <rob@landley.net>
parents: 896
diff changeset
99 <a href=screenshots>screenshots</a>.</p>
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
100
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
101 <a name=source_tour /><h2>Q: What's all this source code for?</h2>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
102
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
103 <p>A: The basic outline is:</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
104
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
105 <ul>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
106 <li><p><b>Top level</b> - The build stages. The file build.sh calls the rest of these scripts in order (but you can call 'em directly too), and the file config lists all the envirionment variables you can set to change the default behavior.</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
107
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
108 <li><p><b>sources</b> - Infrastructure files which you don't call directly.</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
109
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
110 <li><p><b>more</b> - Additional scripts you can call directly to do various things, but which aren't build stages. They have comments near the top describing what they do.</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
111
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
112 <li><p><b>build</b> - Directory generated output goes into. All the output of running a build winds up in here, and "rm -rf build" is essentially "make clean".</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
113
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
114 <li><p><b>packages</b> - Downloaded source packages. If you "rm -rf packages",
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
115 the script download.sh re-populates it by calling wget on various URLs.</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
116 </ul>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
117
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
118 <a name=name_change /><h2>Q: Didn't this used to be called Firmware Linux?</h2>
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
119
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
120 <p>A: Yup. The name changed shortly before the 1.0 release in 2010.</p>
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
121
1119
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
122 <p>The name "Aboriginal Linux" is based on a synonym for "native", as in
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
123 native compiling. It implies it's the first Linux on a new system, and also
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
124 that it can be replaced. It turns a system into something you can do
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
125 native development in, terraforming your environment so you can use it
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
126 to natively build your deployment environment (which may be something else
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
127 entirely).</p>
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
128
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
129 <p>Aboriginal Linux is cross compiled, but after it boots you shouldn't need
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
130 to do any more cross compiling. (Except optionally using the cross compiler
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
131 as a native building accelerator via distcc.) Hence our motto,
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
132 "We cross compile so you don't have to".</p>
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
133
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
134 <p>The old name didn't describe the project very well. (It also had tens
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
135 of millions of Google hits, most of which weren't this project.) If you're
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
136 really bored, there's a page on <a href=history.html>the history of the
25b47a72fd70 Update the FAQ with some reasons for the name change.
Rob Landley <rob@landley.net>
parents: 1050
diff changeset
137 project</a>.</p>
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
138
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
139 <a name=add_package /><h2>Q: How do I add $PACKAGE to my system image's root filesystem?</h2>
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
140
1050
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
141 <p>A: Use the rw-system-image instead of the system-image. This gives
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
142 you a writeable root filesystem with enough extra space to install your
333c8f799302 Update lots and lots of web pages for the project name change to Aboriginal Linux.
Rob Landley <rob@landley.net>
parents: 1030
diff changeset
143 package in.</p>
1030
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
144
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
145 <p>FWL builds squashfs images by default, and the prebuilt binary tarballs in
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
146 the downloads/binaries directory are built with the default values. Squashfs
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
147 is a read-only compressed filesystem, which means it's pretty durable (you
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
148 never need to fsck it), but also a bit limiting. The dev-environment.sh
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
149 script attaches a 2 gigabyte ext2 image to /dev/hdb (which is mounted on
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
150 /home) so you always have writeable space to build stuff in, but that doesn't
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
151 let you modify the root filesystem on /dev/hda: you can't install packages
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
152 you build into /bin and such on a read-only root filesystem.</p>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
153
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
154 <p>The "SYSIMAGE_TYPE" and "SYSIMAGE_HDA_MEGS" config entries let you change
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
155 the default system image type generated by the system-image.sh script. You
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
156 can edit the file "config" or specify them as environment variables, ala:</p>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
157
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
158 <blockquote><pre>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
159 SYSIMAGE_TYPE=ext2 SYSIMAGE_HDA_MEGS=2048 ./build.sh $TARGET
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
160 </pre></blockquote>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
161
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
162 <p>That creates a 2 gigabyte ext2 image, which you can boot into and install
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
163 packages natively under, using the "./run-from-build.sh $TARGET" script.
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
164 If you've already built a system image, you can repackage the existing root
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
165 filesystem by just running system-image.sh (instead of the whole build.sh).
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
166 As always, your new system image is created in the "build" subdirectory.</p>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
167
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
168 <p>Note: since this is a writeable image, you'll have to fsck it. You can
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
169 also use "tune2fs -j" to turn it into an ext3 image.</p>
81003c9f31cb Add a new FAQ: how to get a writeable root filesystem.
Rob Landley <rob@landley.net>
parents: 901
diff changeset
170
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
171 <a name=ubuntu_mispackaged_qemu /><h2>Q: ./run-emulator.sh says qemu-system-$TARGET isn't found, but I installed the qemu package and the executable "qemu" is there. Why isn't this working?</h2>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
172
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
173 <p>A: You're using Ubuntu, aren't you? You need to install
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
174 "qemu-kvm-extras" to get the non-x86 targets.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
175
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
176 <p>The Ubuntu developers have packaged qemu in an <strike>actively
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
177 misleading</strike> "interesting" way. They've confused the emulator QEMU
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
178 with the virtualizer KVM.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
179
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
180 <p>QEMU is an emulator that supports multiple hardware
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
181 targets, translating the target code into host code a page at a time. KVM
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
182 stands for Kernel Virtualization Module, a kernel module which allows newer x86
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
183 chips with support for the "VT" extension to run x86 code in a virtual
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
184 container.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
185
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
186 <p>The KVM project started life as a fork of QEMU (replacing QEMU's CPU
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
187 emulation with a kernel module providing VT virtualization support, but
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
188 using QEMU's device emulation for I/O), but KVM only ever offered a
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
189 small subset of the functionality of QEMU, and current versions of QEMU have
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
190 merged KVM support into the base package. (QEMU 0.11.0 can automatically
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
191 detect and use the KVM module as an accelerator, where appropriate.)</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
192
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
193 <p>It's a bit like the X11 project providing a "drm" module (for 3D acceleration
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
194 and such), which was integrated upstream into the Linux kernel. The Linux
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
195 kernel was never part of the X11 project, and vice versa, and pretending the
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
196 two projects were the same thing would be wrong.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
197
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
198 <p>That said, on Ubuntu the "qemu" package is an alias for "qemu-kvm", a
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
199 package which only supports i386 and x86_64 (because that's all KVM supports
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
200 when running on an x86 PC). In order to install the rest of qemu (support
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
201 for emulating arm, mips, powerpc, sh4, and so on), you need to install
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
202 the "qemu-kvm-extras" package (which despite the name has nothing whatsoever
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
203 to do with KVM).</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
204
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
205 <p>Support for non-x86 targets is part of the base package when you build QEMU
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
206 from source. If you ignore Ubuntu's packaging insanity and build QEMU
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
207 from source, you shouldn't have to worry about this strangely named
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
208 artificial split.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
209
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
210 <a name=case_sensitive_patch /><h2>Q: I added a uClibc patch to sources/patches but it didn't do anything, what's wrong?</h2>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
211
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
212 <p>The Linux filesystem is case sensitive, so the patch has to start with
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
213 "uClibc-" with a capital C.</p>
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
214
896
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
215 <a name=package_breaks /><h2>Q: Why did the $NAME package build die
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
216 with a complaint that it couldn't find $PREREQUISITE, even though that's
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
217 installed on the host? (For example, distcc and python.)</h2>
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
218
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
219 <p>Because you skipped the host-tools.sh step, and because installing a package
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
220 on the host isn't the same as installing it on the target.</p>
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
221
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
222 <p>Even though host-tools.sh is technically an optional step, your host has to
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
223 be carefully set up to work without it.</p>
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
224
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
225 <p>Not only does host-tools.sh add prerequisite packages your build requires,
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
226 it _removes_ everything else from the $PATH that might change the behavior of
896
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
227 the build. Without this, the ./configure stages of various packages will
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
228 detect that libtool exists, or that the host has Python or Perl installed,
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
229 and configure the packages to make use of things that the cross compiler's
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
230 headers and libraries don't have, and that the target root filesystem
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
231 may not have installed.</p>
edc150001472 New FAQ entry, comment updates.
Rob Landley <rob@landley.net>
parents: 889
diff changeset
232
1225
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
233 <a name=environment_sanitizing /><h2>Q: Why isn't the build listening to the environment variables I set?</h2>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
234
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
235 <p>Quick answer: export NO_SANITIZE_ENVIRONMENT=1.</p>
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
236
1225
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
237 <p>Long answer: you probably deleted the commented out variables from "config"
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
238 and then tried to set them on the command line. The environment sanitizing
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
239 logic has a whitelist of variables, but also looks at config to see what
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
240 variables are exported in there (whether they're commented out or not) and
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
241 lets those through from the environment as well. If you remove them from
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
242 config, it won't let them through from the environment.</p>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
243
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
244 <a name="debugging" /><h1>Debugging questions</h1>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
245
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
246 <a name="debug_logging" /><h2>Q: How do I get better log output from the build?</h2>
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
247
1191
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
248 <h3><b>Get a verbose, single-processor log of the build output.</b></h3>
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
249
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
250 <p>When something goes wrong, re-run your build with a couple extra variables,
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
251 and log the output with "tee":</p>
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
252
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
253 <blockquote><pre>BUILD_VERBOSE=1 CPUS=1 ./build.sh 2>&1 | tee out.txt</pre></blockquote>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
254
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
255 <p>The shell has a nice syntax for exporting variables just for a single
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
256 command, by putting the command to run after the assignment. Doing
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
257 that doesn't pollute your environment by leaving CPUS or BUILD_VERBOSE
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
258 exported, but it exports them just for the new "build.sh" process it
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
259 launches. And redirecting stderr to stdin and piping the result into "tee"
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
260 captures the output so you can examine it with less or vi.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
261
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
262 <p>BUILD_VERBOSE undoes the "pretty printing" of the linux kernel and uClibc,
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
263 and makes a few other build steps produce more explicit output.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
264
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
265 <p>CPUS controls the number of tasks make should run in parallel. The default
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
266 value is the number of processors on the system, times 1.5. (So a 4 processor
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
267 system runs 6 processes.) Making it single processor gives you much more
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
268 readable output, because a single-processor build stops more reliably at the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
269 point where it hit a problem, rather than at some random later point forcing
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
270 you to scroll back quite a ways to find the error. It also shouldn't
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
271 interleave the output of multiple parallel commands.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
272
1191
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
273 <h3><b>Use the command logging wrapper</b></h3>
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
274
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
275 <p>If you need more logging detail, run more/record-commands.sh, then re-run
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
276 the build and look at the output in build/logs.</p>
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
277
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
278 <p>The record-commands script sets up a wrapper which logs every command (and
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
279 all its arguments) run out of $PATH. It populates build/wrapdir with
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
280 symlinks for every command name currently in $PATH, all pointing to the
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
281 "wrappy" binary (built from sources/toys/wrappy.c). If you run record-commands
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
282 before running host-tools.sh it wraps the host $PATH, if you run it after
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
283 host-tools.sh it wraps the sanitized $PATH in build/host.</p>
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
284
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
285 <p>The wrappy binary depends on two environment variables (set up by
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
286 sources/include.sh): $WRAPPY_LOGPATH is an absolute path to the current
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
287 log file (updated by the "setupfor" function) and $OLDPATH is the $PATH to
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
288 exec the real command out of after appending the current command line to
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
289 the log.</p>
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
290
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
291 <p>The script "more/report-recorded-commands.sh" prints out a list of all
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
292 commands used by each build stage. (Comparing the host-tools version
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
293 to a run without host-tools can be instructive; that's the extra stuff
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
294 ./configure is picking up out of the host environment.)</p>
f66d99bb00f9 Write-up on the command logging wrapper.
Rob Landley <rob@landley.net>
parents: 1185
diff changeset
295
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
296 <a name=debug_source /><h2>Q: How do I play around with package source code?</p></h2>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
297
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
298 <p>The source code used by package builds lives in several directories, each
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
299 with a different purpose:</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
300
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
301 <ul>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
302 <li><p><b>packages</b> - vanilla upstream source tarballs (populated by download.sh).</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
303 <li><p><b>sources/patches</b> - local patches to apply to the vanilla packages.</li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
304 <li><p><b>build/packages</b> - the package cache, clean copies of the extracted and patched source.</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
305 <li><p><b>build/temp-$ARCH</b> - working copies of the source configured and built for the given architecture.</p></li>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
306 </ul>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
307
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
308 <h3><b>Downloading</b></h3>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
309
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
310 <p>The list of source URLs is in the script download.sh, along with a list
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
311 of mirrors to check if the original URL isn't available. Those URLs are
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
312 the only place that specifies version numbers for packages, so if you want
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
313 to switch versions just point to a new URL and re-run download.sh. (You can
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
314 set SHA1= blank for the first download, and it will output the sha1sum for
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
315 the file it downloads. Cut and paste that into the download script and
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
316 re-run to confirm.)</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
317
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
318 <h3><b>Extracting and patching</b></h3>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
319
1225
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
320 <p>Each script to build a package calls the shell function "setupfor"
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
321 before building the package, and "cleanup" afterwards. Conceptually,
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
322 "setupfor" extracts a tarball (from the "packages" directory),
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
323 patches it if necessary (applying all the files in "sources/patches" that
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
324 start with that package's name, which come from the aboriginal linux
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
325 repository), and cd's into the resulting directory. The function "cleanup"
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
326 does an "rm -rf" on that directory when you're done.</p>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
327
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
328 <p>In practice, the infrastructure behind the scenes caches the extracted
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
329 tarballs. This optimization saves disk space, CPU time, and I/O bandwidth,
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
330 speeding up builds considerably (especially when you do a lot of them in
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
331 parallel). This optimization is designed to be easily ignored, but
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
332 understanding the infrastructure can be useful for debugging.</p>
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
333
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
334 <p>There are two places to look for extracted source packages: the package
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
335 cache and the working copy. The <b>package cache</b> (in "build/packages")
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
336 contains clean copies of all the previously extracted source tarballs, with
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
337 patches already applied. Each <b>working copy</b> (in an architecture's
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
338 temporary directory, "build/temp-$ARCH") is a tree of hardlinks to the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
339 package cache that provides a directory in which to configure, build, and
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
340 install that package for a specific target.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
341
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
342 <p>The source in the package cache stays clean, can be re-used across multiple
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
343 builds, and is only used to create working copies. Working copies fill up
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
344 with temporary files from configure/make/install, and are normally deleted
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
345 after each successful build. If you want to look at clean source, you
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
346 want the package cache. If you want to look at the state of a failed
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
347 build to see how it was configured or re-run portions of it, you want the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
348 working copy.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
349
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
350 <a name=debug_package_cache /><h2>Q: What's the package cache for?</p></h2>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
351
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
352 <p>The package cache contains clean architecture-independent source code,
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
353 which you can edit, use to run modified builds and create patches, and easily
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
354 revert to its original condition. The package cache avoids re-extracting the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
355 same tarballs over and over, but also provides a place you can make temporary
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
356 modifications to that source behind the build system's back without having to
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
357 mess around with tarballs or patch files.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
358
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
359 <p>The setupfor function calls "extract_package" to populate the package
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
360 cache. First extract_package checks for an existing copy of the appropriate
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
361 source directory, and when it doesn't find one it extracts the source tarballs
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
362 from the "packages" directory, applies the appropriate patches from
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
363 "sources/patches/$PACKAGENAME-*.patch", and saves the results into its own
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
364 directory (named after the package) under "build/packages". (USE_UNSTABLE
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
365 packages work the same way, but insert an "alt-" prefix on the package
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
366 name.)</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
367
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
368 <p>When the package cache has an existing copy of the package, extract_package
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
369 checks the list of sha1sums in that copy's "sha1-for-source.txt" file against
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
370 the sha1sums for the tarball and for each of the patch files it needs to apply.
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
371 If the list matches, it uses the existing copy. If it doesn't match, it
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
372 deletes the existing copy out of the package cache, re-extracts the tarball,
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
373 and reapplies each patch to it.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
374
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
375 <p>This means if you can edit the copy under sources/patches all you like,
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
376 and as long as you don't modify sha1-for-source.txt, don't replace the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
377 tarball, or add/remove/edit any of the patches to apply to it, it
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
378 will re-use that source for subsequent builds. So go ahead and fill it
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
379 full of printf()s and test code, then when you want to go back to a clean
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
380 copy, delete the build/packages directory (either one package or the whole
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
381 thing) and let setupfor recreate it.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
382
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
383 <p>If you come up with changes you want to keep, you can create a patch from
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
384 the package cache this way:</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
385
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
386 <blockquote><pre>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
387 # Rename the modified package directory
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
388
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
389 cd $TOP
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
390 cd build/packages
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
391 mv $PACKAGE $PACKAGE.bak
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
392
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
393 # Extract a clean copy
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
394
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
395 cd $TOP
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
396 more/test.sh host extract_package $PACKAGE
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
397
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
398 # Diff the two and write out the patch to sources/patches
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
399
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
400 cd build/packages
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
401 diff -ruN $PACKAGE $PACKAGE.bak > ../../sources/patches/$PACKAGE-$NAME.patch
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
402 rm -rf $PACKAGE
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
403
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
404 # Run a clean test build
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
405
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
406 cd $TOP
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
407 rm -rf build/packages/$PACKAGE
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
408 ./build.sh $ARCH
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
409 </pre></blockquote>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
410
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
411 <p>Where $TOP is your top level Aboriginal Linux directory, $PACKAGE is the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
412 name of the package you're modifying, and $NAME is some unique name for your
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
413 patch. Don't forget to delete the $PACKAGE.bak directory to reclaim its disk
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
414 space when you're satisfied with your patch (or "rm -rf build/packages" to
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
415 zap the entire package cache, or just "rm -rf build" to clean
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
416 up all the temporary files).</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
417
1225
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
418 <p>If the environment variable EXTRACT_ALL is set, download.sh will
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
419 call extract_package on each package as soon as it confirms the tarball's
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
420 sha1sum. (The environment variable FORK makes each package download happen
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
421 in parallel, including the call to extract_package if any.) Prepopulating
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
422 the package cache this way is useful before running different architecture
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
423 builds in parallel, or when testing that new patches (added to the
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
424 sources/patches directory) apply correctly to the relevant package(s).</p>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
425
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
426 <p>This means you can do the following to get a freshly extracted and patched
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
427 clean copy of all packages:</p>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
428
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
429 <blockquote><pre>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
430 rm -rf build/packages
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
431 EXTRACT_ALL=1 ./download.sh
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
432 </pre></blockquote>
39fda120621c Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
Rob Landley <rob@landley.net>
parents: 1191
diff changeset
433
1185
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
434 <a name=debug_working_copies /><h2>Q: What are working copies for?</p></h2>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
435
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
436 <p>Working copies are target-specific copies of package source where builds
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
437 actually happen. The build scripts clone a fresh working copy for each build,
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
438 then run configure, make, and install commands in the new copy. They leave the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
439 aftermath of failed builds lying around for analysis; to keep the working
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
440 copies of successful builds around too, set the NO_CLEANUP environment
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
441 variable. If you want to cd into a source directory and re-run bits of a
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
442 previous build, use the working copy of a package's source. (You'll probably
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
443 have to add the appropriate cross compiler's bin directory to your $PATH, but
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
444 otherwise it'll usually just work.)</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
445
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
446 <p>Working copies of source packages are cloned from the package cache
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
447 by the the function "setupfor", which first calls extract_package to ensure the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
448 package cache is up to date, then creates a directory of hardlinks to the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
449 package cache via "cp -l" (or symlinks via "cp -s" if $SNAPSHOT_SYMLINK is
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
450 set).</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
451
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
452 <p>The working copies use hardlinks to avoid creating redundant copies of the
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
453 file contents, which would waste I/O bandwidth and eat lots of disk space
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
454 and disk cache memory. Using hardlinks instead of symlinks for the working
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
455 copies also saves inodes and dentry cache, since each symlink consumes an
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
456 inode, but that optimization requires that the package cache and working
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
457 copies be on the same filesystem.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
458
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
459 <p>Linking to the page cache instead of copying it doesn't cause problems
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
460 for most packages, because most methods of modifying files used by package
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
461 builds break hardlinks or symlinks by first creating a temporary copy with
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
462 the modifications, then deleting the original and moving the copy into its
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
463 place. Modifying files that are tracked by source control also creates
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
464 spurious noise for the package's developers. Occasionally a package will
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
465 make a mistake (such as zlib 1.2.5 shipping a Makefile which is
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
466 generated by configure, and modified in place), in which case the build
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
467 has to break the link itself. (Note that editing the working copies of
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
468 source files in build/temp-$ARCH can modify the cached copy if your editor
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
469 isn't configured to break hardlinks. Usually you edit the package cache
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
470 version and let setupfor create a new working copy.)</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
471
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
472 <p>If you want to search just the generated files and not the snapshot of
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
473 the source, use "find $PACKAGE -links 1". If you want to search just
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
474 the source files and not the generated files, that's what the package
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
475 cache is for.</p>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
476
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
477 <pre>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
478 TODO:
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
479 - more/test.sh ARCH build_section thingy
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
480 </pre>
d413e255c812 Add lots of debugging HOWTO information. More to come.
Rob Landley <rob@landley.net>
parents: 1119
diff changeset
481
889
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
482 <!--#include file="footer.html" -->
0947cffea3bd Add a FAQ.
Rob Landley <rob@landley.net>
parents:
diff changeset
483 </html>