Mercurial > hg > aboriginal
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> - -<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> +<hr /><a name=add_package /><h2>Q: How do I add $PACKAGE to my system image's root filesystem?</h2> -<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>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 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>A: You're using Ubuntu, aren't you? You need to install -"qemu-kvm-extras" to get the non-x86 targets.</p> +<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>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> +<blockquote><pre> +mkdir gentoo-stage1 +find / -xdev | cpio -m -v -p /home/gentoo-stage1 -<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> +echo Restarting init script in chroot -<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> +for i in mnt proc sys dev +do + mount --bind /$i gentoo-stage1/$i +done -<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> +chroot gentoo-stage1 /mnt/init -<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> +for i in mnt proc sys dev +do + umount gentoo-stage1/$i +done -<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> +tar cvjf gentoo-stage1.tar.bz2 gentoo-stage1 +</pre></blockquote> -<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>