Mercurial > hg > aboriginal

<html>
<!--#include file="header.html" -->
<title>Frequently Asked Questions</title>

<ul>
<li><p><a href=#where_start>Q: Where do I start?</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>
</ul>

<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
QEMU.</p>

<p>Most people want to do one of three things:</p>

<li><p>Download a prebuilt system image, boot it up under the emulator, and
compile stuff natively for a target.</p>

<p>Go <a href=screenshots>here</a> and download the appropriate
system-image-<b>$ARCH</b>.tar.bz2 for your $TARGET, extract it, cd into it,
and <b>./run-emulator.sh</b> to boot it under qemu.</p>

<p>Alternately, you can run the script <b>./development-environment.sh</b>,
which is a wrapper around run-emulator.sh that feeds QEMU extra options to add
memory (256 megs) and writeable disk space (a blank 2 gigabyte disk image
mounted on /home) to provide a more capable development environment.</p>

<p>The system images contain native compiler toolchains, but if you install
distccd on the host and add the appropriate cross compiler to your host's
$PATH, the ./run-emulator.sh script will detect this and set up the system
image to automatically use distcc to call out to the cross compiler through
the virtual network, speeding up native builds significantly.<p>
</li>

<li><p>Build your own cross compilers and system images from source, using
the build scripts.</p>

<p>Go to the <a href=downloads>downloads directory</a>, grab the most recent
release tarball, extract it, and run <b>./build.sh</b> to list
the available targets.  The run <b>./build.sh $TARGET</b> to compile
the one you like.  The results wind up in the "build" directory.</p>

<p>The build scripts are written in bash, and fairly extensively commented.
All the scripts at the top level are designed to be run directly, and
build.sh is just a wrapper script that calls them in order.  The less commonly
used scripts in <b>sources/more</b> are also designed to be run directly.</p>

<p>A large number of variables can be set to configure the build, either
by modifying the file "config" (which documents them all) or by exporting
them as environment variables.</p>

<p>To grab the latest development version of the build scripts out of the
source control system, go to the
<a href=http://impactlinux.com/hg/aboriginal>mercurial archive</a>.
If you don't want to install mercurial, you can grab a
<a href=http://impactlinux.com/hg/aboriginal/archive/tip.tar.bz2>tarball</a> of the current code at
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
"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=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>

<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
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
script attaches a 2 gigabyte ext2 image to /dev/hdb (which is mounted on
/home) so you always have writeable space to build stuff in, but that doesn't
let you modify the root filesystem on /dev/hda: you can't install packages
you build into /bin and such on a read-only root filesystem.</p>

<p>The "SYSIMAGE_TYPE" and "SYSIMAGE_HDA_MEGS" config entries let you change
the default system image type generated by the system-image.sh script.  You
can edit the file "config" or specify them as environment variables, ala:</p>

<blockquote><pre>
SYSIMAGE_TYPE=ext2 SYSIMAGE_HDA_MEGS=2048 ./build.sh $TARGET
</pre></blockquote>

<p>That creates a 2 gigabyte ext2 image, which you can boot into and install
packages natively under, using the "./run-from-build.sh $TARGET" script.
If you've already built a system image, you can repackage the existing root
filesystem by just running system-image.sh (instead of the whole build.sh).
As always, your new system image is created in the "build" subdirectory.</p>

<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>

<p>(You can also use the BUILD_RW_SYSTEM_IMAGE environment variable, which
tells build.sh to package the system image two ways, creating a
rw-system-image tarball with the above options.)</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>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>

<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
with a complaint that it couldn't find $PREREQUISITE, even though that's
installed on the host?  (For example, distcc and python.)</h2>

<p>Because you skipped the host-tools.sh step, and because installing a package
on the host isn't the same as installing it on the target.</p>

<p>Even though host-tools.sh is technically an optional step, your host has to
be carefully set up to work without it.</p>

<p>Not only does host-tools.sh add prerequisite packages your build requires,
it _removes_ everything else from the path that might change the behavior of
the build.  Without this, the ./configure stages of various packages will
detect that libtool exists, or that the host has Python or Perl installed,
and configure the packages to make use of things that the cross compiler's
headers and libraries don't have, and that the target root filesystem
may not have installed.</p>

<!--#include file="footer.html" -->
</html>
author	Rob Landley <rob@landley.net>
date	Mon, 26 Jul 2010 00:06:58 -0500
parents	25b47a72fd70
children	d413e255c812