# HG changeset patch # User Rob Landley # Date 1283662941 18000 # Node ID d6e6c9ddf7f9b076c93dfd4072a218876c63582a # Parent a4734fc22a6d73bc83a9ebae3714605743e8cf75 Yet more FAQ massaging. diff -r a4734fc22a6d -r d6e6c9ddf7f9 www/FAQ.html --- 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 @@ -

Q: Where do I start?

+

Q: Where do I start?

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.

- -

If all else fails, look at the pretty screenshots.

-

Q: What's all this source code for?

+
 +

Building System Images

+ +

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.

+ +

But if you want to understand how it all works, and how to reproduce it, +then you do.

+ +

Start by running (or reading) "build.sh", it calls everything else.

+ +

Q: What's all this source code for?

A: The basic outline is:

@@ -115,34 +136,13 @@ the script download.sh re-populates it by calling wget on various URLs.

-

Q: Didn't this used to be called Firmware Linux?

- -

A: Yup. The name changed shortly before the 1.0 release in 2010.

- -

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

+

Q: How do I add $PACKAGE to my system image's root filesystem?

-

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

+

A: Build an ext2 or ext3 formatted system image instead of squashfs, one +with enough extra space to install your package in.

-

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 the history of the -project.

- -

Q: How do I add $PACKAGE to my system image's root filesystem?

- -

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.

- -

FWL builds squashfs images by default, and the prebuilt binary tarballs in +

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

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.

-

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?

- -

A: You're using Ubuntu, aren't you? You need to install -"qemu-kvm-extras" to get the non-x86 targets.

+

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:

-

The Ubuntu developers have packaged qemu in an actively -misleading "interesting" way. They've confused the emulator QEMU -with the virtualizer KVM.

+
+mkdir gentoo-stage1
+find / -xdev | cpio -m -v -p /home/gentoo-stage1
 
-
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.

+echo Restarting init script in chroot
 
-
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.)

+for i in mnt proc sys dev
+do
+  mount --bind /$i gentoo-stage1/$i
+done
 
-
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.

+chroot gentoo-stage1 /mnt/init
 
-
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).

+for i in mnt proc sys dev
+do
+  umount gentoo-stage1/$i
+done
 
-
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.

+tar cvjf gentoo-stage1.tar.bz2 gentoo-stage1
+
-

Q: I added a uClibc patch to sources/patches but it didn't do anything, what's wrong?

+

Q: I added a uClibc patch to sources/patches but it didn't do anything, what's wrong?

The Linux filesystem is case sensitive, so the patch has to start with "uClibc-" with a capital C.

-

Q: Why did the $NAME package build die +

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

@@ -230,7 +216,7 @@ headers and libraries don't have, and that the target root filesystem may not have installed.

-

Q: Why isn't the build listening to the environment variables I set?

+

Q: Why isn't the build listening to the environment variables I set?

Quick answer: export NO_SANITIZE_ENVIRONMENT=1.

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

-

Debugging questions

+

Debugging questions

-

Q: How do I get better log output from the build?

+

Q: How do I get better log output from the build?

Get a verbose, single-processor log of the build output.

@@ -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.)

-

Q: How do I play around with package source code?

+

Q: How do I run my own build snippets without editing the build scripts?

+ +

A: Use the more/test.sh script

+ +

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.

+ +

Examples:

+
+  more/test.sh armv5l build_section busybox
+  more/test.sh mips getconfig linux
+
+ +

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.

+ +

Q: How do I play around with package source code?

The source code used by package builds lives in several directories, each with a different purpose:

@@ -347,7 +354,7 @@ build to see how it was configured or re-run portions of it, you want the working copy.

-

Q: What's the package cache for?

+

Q: What's the package cache for?

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 -

Q: What are working copies for?

+

Q: What are working copies for?

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.

-
-TODO:
-  - more/test.sh ARCH build_section thingy
-
+

Q: Didn't this used to be called Firmware Linux?

+ +

A: Yup. The name changed shortly before the 1.0 release in 2010.

+ +

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

+ +

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

+ +

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 the history of the +project.

+ +

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?

+ +

A: You're using Ubuntu, aren't you? You need to install +"qemu-kvm-extras" to get the non-x86 targets.

+ +

The Ubuntu developers have packaged qemu in an actively +misleading "interesting" way. They've confused the emulator QEMU +with the virtualizer KVM.

+ +

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.

+ +

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

+ +

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.

+ +

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

+ +

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.

+ +

Q: Do you care about windows?

+ +

A: Not really, but this +guy does. 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.

+ +

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.

+ +