changeset 1234:d6e6c9ddf7f9

Yet more FAQ massaging.
author Rob Landley <rob@landley.net>
date Sun, 05 Sep 2010 00:02:21 -0500
parents a4734fc22a6d
children d169a2c6f410
files www/FAQ.html
diffstat 1 files changed, 160 insertions(+), 80 deletions(-) [+]
line wrap: on
line diff
--- a/www/FAQ.html	Sat Sep 04 17:55:54 2010 -0500
+++ b/www/FAQ.html	Sun Sep 05 00:02:21 2010 -0500
@@ -5,33 +5,43 @@
 <ul>
 <li><p><a href=#where_start>Q: Where do I start?</a></p></li>
 
+<li><p><a href=#building><h1>Building System Images</h1></a></p></li>
+<ul>
 <li><p><a href=#source_tour>Q: What's all this source code for?</a></p></li>
 
-<li><p><a href=#name_change>Q: Didn't this used to be called Firmware Linux?</a></p></li>
-
 <li><p><a href=#add_package>Q: How do I add $PACKAGE to my system image's root filesystem?</a></p></li>
 
-<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>
-
 <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>
 
 <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>
 
 <li><p><a href=#environment_sanitizing>Q: Why isn't the build listening to the environment variables I set?</p></li>
+</ul>
 
 <li><p><a href=#debugging><h1>Debugging questions</h1></a></p></li>
 
 <ul>
 <li><p><a href=#debug_logging>Q: How do I get better log output?</p></li>
+<li><p><a href=#debug_test>Q: How do I run my own build snippets without editing the build scripts?</a></p></li>
 <li><p><a href=#debug_source>Q: How do I play around with package source code?</p></li>
 <ul>
 <li><p><a href=#debug_package_cache>Q: What's the package cache for?</a></p></li>
 <li><p><a href=#debug_working_copies>Q: What are working copies for?</a></p></li>
 </ul>
 </ul>
+
+<li><p><a href=#other><h1>Other questions</h1></a></p></li>
+
+<ul>
+<li><p><a href=#name_change>Q: Didn't this used to be called Firmware Linux?</a></p></li>
+
+<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>
+
+<li><p><a href=#windows>Q: Do you care about windows?</a></p></li>
+</ul>
 </ul>
 
-<a name=where_start /><h2>Q: Where do I start?</h2>
+<hr /><a name=where_start /><h2>Q: Where do I start?</h2>
 
 <p>The project provides development and test environments for lots of different
 hardware platforms, based on busybox and uClibc and configured to run under
@@ -83,22 +93,33 @@
 any time.</p>
 </li>
 
-<ul>
 <li><p>Download a prebuilt cross compiler and cross-compile stuff with it.</p>
 
 <p>Go <a href=screenshots>here</a> and download the appropriate
-cross-compiler-<b>$TARGET</b>.tar.bz2 for your $TARGET, extract it, add its
+cross-compiler-$TARGET.tar.bz2 for your $TARGET, extract it, add its
 "bin" directory to your $PATH, and use the appropriate $TARGET-cc and
 $TARGET-ld and so on to compile your program.  (The tool names have prefixes
 so they can be in the same $PATH as your host's existing compiler.)</p>
 </li>
 
-</ul>
-
 <p>If all else fails, look at the pretty
 <a href=screenshots>screenshots</a>.</p>
 
-<a name=source_tour /><h2>Q: What's all this source code for?</h2>
+<hr /><a name=building />
+<h1>Building System Images</h1>
+
+<p>The build scripts compile the system images from source code.  Along
+the way, they create the cross compilers and root filesystem tarballs too.
+If you just want to use the prebuilt binary tarballs to mess around with
+native environments for various targets, you don't need to care about the
+build scripts.</p>
+
+<p>But if you want to understand how it all works, and how to reproduce it,
+then you do.</p>
+
+<p>Start by running (or reading) "build.sh", it calls everything else.</p>
+
+<hr /><a name=source_tour /><h2>Q: What's all this source code for?</h2>
 
 <p>A: The basic outline is:</p>
 
@@ -115,34 +136,13 @@
 the script download.sh re-populates it by calling wget on various URLs.</p></li>
 </ul>
 
-<a name=name_change /><h2>Q: Didn't this used to be called Firmware Linux?</h2>
+<hr /><a name=add_package /><h2>Q: How do I add $PACKAGE to my system image's root filesystem?</h2>
 
-<p>A: Yup.  The name changed shortly before the 1.0 release in 2010.</p>
+<p>A: Build an ext2 or ext3 formatted system image instead of squashfs, one
+with enough extra space to install your package in.</p>
 
-<p>The name "Aboriginal Linux" is based on a synonym for "native", as in
-native compiling.  It implies it's the first Linux on a new system, and also
-that it can be replaced.  It turns a system into something you can do
-native development in, terraforming your environment so you can use it
-to natively build your deployment environment (which may be something else
-entirely).</p>
-
-<p>Aboriginal Linux is cross compiled, but after it boots you shouldn't need
-to do any more cross compiling.  (Except optionally using the cross compiler
-as a native building accelerator via distcc.)  Hence our motto,
-"We cross compile so you don't have to".</p>
-
-<p>The old name didn't describe the project very well.  (It also had tens
-of millions of Google hits, most of which weren't this project.)  If you're
-really bored, there's a page on <a href=history.html>the history of the
-project</a>.</p>
-
-<a name=add_package /><h2>Q: How do I add $PACKAGE to my system image's root filesystem?</h2>
-
-<p>A: Use the rw-system-image instead of the system-image.  This gives
-you a writeable root filesystem with enough extra space to install your
-package in.</p>
-
-<p>FWL builds squashfs images by default, and the prebuilt binary tarballs in
+<p>Aboriginal Linux builds squashfs images by default, and the prebuilt binary
+tarballs in
 the downloads/binaries directory are built with the default values.  Squashfs
 is a read-only compressed filesystem, which means it's pretty durable (you
 never need to fsck it), but also a bit limiting.  The dev-environment.sh
@@ -168,51 +168,37 @@
 <p>Note: since this is a writeable image, you'll have to fsck it.  You can
 also use "tune2fs -j" to turn it into an ext3 image.</p>
 
-<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>
+<p>Alternately, you can boot from squashfs using the dev-environment.sh 
+script and copy it to a writeable chroot in the /home directory.  The
+gentoo-stage1 build in sources/native-builds does this like so:</p>
 
-<p>A: You're using Ubuntu, aren't you?  You need to install
-"qemu-kvm-extras" to get the non-x86 targets.</p>
+<blockquote><pre>
+mkdir gentoo-stage1
+find / -xdev | cpio -m -v -p /home/gentoo-stage1
 
-<p>The Ubuntu developers have packaged qemu in an <strike>actively
-misleading</strike> "interesting" way.  They've confused the emulator QEMU
-with the virtualizer KVM.</p>
+echo Restarting init script in chroot
 
-<p>QEMU is an emulator that supports multiple hardware
-targets, translating the target code into host code a page at a time.  KVM
-stands for Kernel Virtualization Module, a kernel module which allows newer x86
-chips with support for the "VT" extension to run x86 code in a virtual
-container.</p>
+for i in mnt proc sys dev
+do
+  mount --bind /$i gentoo-stage1/$i
+done
 
-<p>The KVM project started life as a fork of QEMU (replacing QEMU's CPU
-emulation with a kernel module providing VT virtualization support, but
-using QEMU's device emulation for I/O), but KVM only ever offered a
-small subset of the functionality of QEMU, and current versions of QEMU have
-merged KVM support into the base package.  (QEMU 0.11.0 can automatically
-detect and use the KVM module as an accelerator, where appropriate.)</p>
+chroot gentoo-stage1 /mnt/init
 
-<p>It's a bit like the X11 project providing a "drm" module (for 3D acceleration
-and such), which was integrated upstream into the Linux kernel.  The Linux
-kernel was never part of the X11 project, and vice versa, and pretending the
-two projects were the same thing would be wrong.</p>
+for i in mnt proc sys dev
+do
+  umount gentoo-stage1/$i
+done
 
-<p>That said, on Ubuntu the "qemu" package is an alias for "qemu-kvm", a
-package which only supports i386 and x86_64 (because that's all KVM supports
-when running on an x86 PC).  In order to install the rest of qemu (support
-for emulating arm, mips, powerpc, sh4, and so on), you need to install
-the "qemu-kvm-extras" package (which despite the name has nothing whatsoever
-to do with KVM).</p>
+tar cvjf gentoo-stage1.tar.bz2 gentoo-stage1
+</pre></blockquote>
 
-<p>Support for non-x86 targets is part of the base package when you build QEMU
-from source.  If you ignore Ubuntu's packaging insanity and build QEMU
-from source, you shouldn't have to worry about this strangely named
-artificial split.</p>
-
-<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>
+<hr /><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>
 
 <p>The Linux filesystem is case sensitive, so the patch has to start with
 "uClibc-" with a capital C.</p>
 
-<a name=package_breaks /><h2>Q: Why did the $NAME package build die
+<hr /><a name=package_breaks /><h2>Q: Why did the $NAME package build die
 with a complaint that it couldn't find $PREREQUISITE, even though that's
 installed on the host?  (For example, distcc and python.)</h2>
 
@@ -230,7 +216,7 @@
 headers and libraries don't have, and that the target root filesystem
 may not have installed.</p>
 
-<a name=environment_sanitizing /><h2>Q: Why isn't the build listening to the environment variables I set?</h2>
+<hr /><a name=environment_sanitizing /><h2>Q: Why isn't the build listening to the environment variables I set?</h2>
 
 <p>Quick answer: export NO_SANITIZE_ENVIRONMENT=1.</p>
 
@@ -241,9 +227,9 @@
 lets those through from the environment as well.  If you remove them from
 config, it won't let them through from the environment.</p>
 
-<a name="debugging" /><h1>Debugging questions</h1>
+<hr /><a name="debugging" /><h1>Debugging questions</h1>
 
-<a name="debug_logging" /><h2>Q: How do I get better log output from the build?</h2>
+<hr /><a name="debug_logging" /><h2>Q: How do I get better log output from the build?</h2>
 
 <h3><b>Get a verbose, single-processor log of the build output.</b></h3>
 
@@ -293,7 +279,28 @@
 to a run without host-tools can be instructive; that's the extra stuff
 ./configure is picking up out of the host environment.)</p>
 
-<a name=debug_source /><h2>Q: How do I play around with package source code?</p></h2>
+<hr /><a name=debug_test /><h2>Q: How do I run my own build snippets without editing the build scripts?</p></h2>
+
+<p>A: Use the more/test.sh script</p>
+
+<p>The more/test.sh script's first argument is the target to build for, and
+the rest of its arguments are a command line to run as if building for that
+target.  It sets up the same context for building for an $ARCH the scripts use
+(adds the appropriate cross compiler to the $PATH if it's been build, sets
+all the shell functions and environment variables, and so on), and then runs
+the rest of the command line in that context.</p>
+
+<p>Examples:</p>
+<blockquote><pre>
+  more/test.sh armv5l build_section busybox
+  more/test.sh mips getconfig linux
+</pre></blockquote>
+
+<p>You can also write your own script and source sources/include.sh and
+call read_arch_dir yourself at the top of it, but that's pretty much all
+test.sh does.</p>
+
+<hr /><a name=debug_source /><h2>Q: How do I play around with package source code?</p></h2>
 
 <p>The source code used by package builds lives in several directories, each
 with a different purpose:</p>
@@ -347,7 +354,7 @@
 build to see how it was configured or re-run portions of it, you want the
 working copy.</p>
 
-<a name=debug_package_cache /><h2>Q: What's the package cache for?</p></h2>
+<hr /><a name=debug_package_cache /><h2>Q: What's the package cache for?</p></h2>
 
 <p>The package cache contains clean architecture-independent source code,
 which you can edit, use to run modified builds and create patches, and easily
@@ -431,7 +438,7 @@
   EXTRACT_ALL=1 ./download.sh
 </pre></blockquote>
 
-<a name=debug_working_copies /><h2>Q: What are working copies for?</p></h2>
+<hr /><a name=debug_working_copies /><h2>Q: What are working copies for?</p></h2>
 
 <p>Working copies are target-specific copies of package source where builds
 actually happen.  The build scripts clone a fresh working copy for each build,
@@ -474,10 +481,83 @@
 the source files and not the generated files, that's what the package
 cache is for.</p>
 
-<pre>
-TODO:
-  - more/test.sh ARCH build_section thingy
-</pre>
+<hr /><a name=name_change /><h2>Q: Didn't this used to be called Firmware Linux?</h2>
+
+<p>A: Yup.  The name changed shortly before the 1.0 release in 2010.</p>
+
+<p>The name "Aboriginal Linux" is based on a synonym for "native", as in
+native compiling.  It implies it's the first Linux on a new system, and also
+that it can be replaced.  It turns a system into something you can do
+native development in, terraforming your environment so you can use it
+to natively build your deployment environment (which may be something else
+entirely).</p>
+
+<p>Aboriginal Linux is cross compiled, but after it boots you shouldn't need
+to do any more cross compiling.  (Except optionally using the cross compiler
+as a native building accelerator via distcc.)  Hence our motto,
+"We cross compile so you don't have to".</p>
+
+<p>The old name didn't describe the project very well.  (It also had tens
+of millions of Google hits, most of which weren't this project.)  If you're
+really bored, there's a page on <a href=history.html>the history of the
+project</a>.</p>
+
+<hr /><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>
+
+<p>A: You're using Ubuntu, aren't you?  You need to install
+"qemu-kvm-extras" to get the non-x86 targets.</p>
+
+<p>The Ubuntu developers have packaged qemu in an <strike>actively
+misleading</strike> "interesting" way.  They've confused the emulator QEMU
+with the virtualizer KVM.</p>
+
+<p>QEMU is an emulator that supports multiple hardware
+targets, translating the target code into host code a page at a time.  KVM
+stands for Kernel Virtualization Module, a kernel module which allows newer x86
+chips with support for the "VT" extension to run x86 code in a virtual
+container.</p>
+
+<p>The KVM project started life as a fork of QEMU (replacing QEMU's CPU
+emulation with a kernel module providing VT virtualization support, but
+using QEMU's device emulation for I/O), but KVM only ever offered a
+small subset of the functionality of QEMU, and current versions of QEMU have
+merged KVM support into the base package.  (QEMU 0.11.0 can automatically
+detect and use the KVM module as an accelerator, where appropriate.)</p>
+
+<p>It's a bit like the X11 project providing a "drm" module (for 3D acceleration
+and such), which was integrated upstream into the Linux kernel.  The Linux
+kernel was never part of the X11 project, and vice versa, and pretending the
+two projects were the same thing would be wrong.</p>
+
+<p>That said, on Ubuntu the "qemu" package is an alias for "qemu-kvm", a
+package which only supports i386 and x86_64 (because that's all KVM supports
+when running on an x86 PC).  In order to install the rest of qemu (support
+for emulating arm, mips, powerpc, sh4, and so on), you need to install
+the "qemu-kvm-extras" package (which despite the name has nothing whatsoever
+to do with KVM).</p>
+
+<p>Support for non-x86 targets is part of the base package when you build QEMU
+from source.  If you ignore Ubuntu's packaging insanity and build QEMU
+from source, you shouldn't have to worry about this strangely named
+artificial split.</p>
+
+<hr /><a name=windows /><h2>Q: Do you care about windows?</h2>
+
+<p>A: Not really, but <a href=http://www.davereyn.co.uk/download.htm>this
+guy does</a>.  You can download his prebuilt binary QEMU versions for Windows,
+and launch the various prebuilt binary Linux system images under them for
+each target.  Then if you want to rebuild the system images from source, or
+build more software for a given target, you can do so natively within a
+system image.</p>
+
+<p>If you want to cross compile from Cygwin or mingw or something, you're on
+your own.  Emulating a Linux system (thereby bypassing Windows entirely) is
+fairly straightforward, assuming somebody else has already done the work of
+porting the emulator.  Trying to make Windows run posix apps is an unnatural
+act involving ceremonial headgear and animal sacrifice just to get it to
+fail the same way twice.</p>
+
+
 
 <!--#include file="footer.html" -->
 </html>