Mercurial > hg > aboriginal
changeset 1826:1ba206595781 draft
Update build-stages.html documentation.
author | Rob Landley <rob@landley.net> |
---|---|
date | Wed, 09 Dec 2015 15:28:51 -0600 |
parents | 2dd2e648c2ae |
children | c7b90f8d1b80 |
files | www/about.html www/build-stages.html |
diffstat | 2 files changed, 68 insertions(+), 54 deletions(-) [+] |
line wrap: on
line diff
--- a/www/about.html Wed Dec 09 15:00:30 2015 -0600 +++ b/www/about.html Wed Dec 09 15:28:51 2015 -0600 @@ -41,6 +41,7 @@ from busybox, uClibc, and gcc/binutils to toybox, musl-libc, and lvm/lld.)</p> +<a name="sysimage_use"> <h2>Using system images.</h2> <p>Each system image tarball contains a wrapper script <b>./run-emulator.sh</b>
--- a/www/build-stages.html Wed Dec 09 15:00:30 2015 -0600 +++ b/www/build-stages.html Wed Dec 09 15:28:51 2015 -0600 @@ -18,18 +18,19 @@ <h2>Overview</h2> -<p>The build runs the following stages, in order:</p> +<p><b>build.sh</b> runs the following stages, in order:</p> <ul> -<li><b>download.sh</b> - Download source packages used by the rest of the build.</li> -<li><b>host-tools.sh</b> - Build prerequisites host needs to run remaining stages.</li> -<li><b>simple-cross-compiler.sh</b> - Build cross compiler for selected target architecture.</li> -<li><b>[</b>cross-compiler.sh<b>]</b> - optionally produce a more portable -cross compiler (not needed by rest of build, but <a href=bin/>released as -a tarball</a>).</li> -<li><b>native-compiler.sh</b> - Build native compiler to install/run on target.</li> -<li><b>root-filesystem.sh</b> - Build simple initramfs filesystem, just enough to boot to a shell prompt.</li> -<li><b>system-image.sh</b> - Build bootable linux kernel and package together filesystem image and kernel with scripts to launch them under an emulator.</li> +<li><p><b>download.sh</b> - Download source packages used by the rest of the build.</p></li> +<li><p><b>host-tools.sh</b> - Build prerequisites host needs to run remaining stages.</p></li> +<li><p><b>simple-cross-compiler.sh</b> - Build cross compiler for selected target architecture.</p></li> +<li><p><b>[</b>cross-compiler.sh<b>]</b> - optionally produce a more portable +cross compiler which can be <a href=bin/>packaged as a tarball</a> for use +elsewhere. This stage is skipped unless CROSS_COMPILER_HOST is set (usually +to i686 or x86_64).</p></li> +<li><p><b>root-filesystem.sh</b> - Build simple initramfs filesystem, just enough to boot to a shell prompt.</p></li> +<li><p><b>native-compiler.sh</b> - Build native compiler to install/run on target.</p></li> +<li><p><b>system-image.sh</b> - Build bootable linux kernel and package together filesystem image and kernel with scripts to launch them under an emulator.</p></li> </ul> <p>The top level wrapper script <b>build.sh</b> runs the above stages in order, @@ -55,7 +56,7 @@ <p>None of these scripts need to be run as root -- an explicit design goal of Aboriginal Linux is that root access on the host is never required.</p> -<h2>Build stages</h2> +<h2>Files</h2> <p>The files in the top level directory of the Aboriginal Linux source are:</p> @@ -124,8 +125,8 @@ place are the same ones the scripts install into the target root filesystem.</p> <p>This script populates the "build/host" directory, which is automatically -<p>used by later stages if it exists. It is not target specific, and only -<p>needs to be run once when building multiple architectures.</p> +used by later stages if it exists. It is not target specific, and only +needs to be run once when building multiple architectures.</p> </blockquote> </li> @@ -159,9 +160,24 @@ 32 bit code. If you run "./cross-comiler.sh $TARGET" manually without setting CROSS_COMPILER_HOST, it defaults to i686.)</p> -<p>This compiler is statically linked against uClibc, for maximum +<p>This compiler is statically linked against musl-libc, for maximum portability. (You can set BUILD_STATIC=none to dynamically link instead, -but then have to install uClibc's shared libraries on the host.)</p> +but then have to install musl's shared libraries on the host.)</p> +</blockquote> +</li> + +<li><b>root-filesystem.sh $TARGET</b> + +<blockquote> +<p>Creates a root filesystem (with uCLibc, BusyBox, and an init script) +which contains just enough infrastructure to boot up to a shell prompt. +By default this is packaged as an initramfs, see SYSIMAGE_TYPE in config +to see other available filesystem types.</p> + +<p>This creates empty directories, copies the skeleton files from +sources/root-filesystem, builds toybox, and finally adds the contents +of the directory $MY_OVERLAY points to (if any). On appropriate hardware +(or with an appropriate emulator), you should be able to chroot into this.</p> </blockquote> </li> @@ -181,55 +197,52 @@ </blockquote> </li> -<li><b>root-filesystem.sh $TARGET</b> - -<blockquote> -<p>Creates a root filesystem (with uCLibc, BusyBox, and an init script) -which contains just enough infrastructure to boot up to a shell prompt. -By default this is packaged as an initramfs, see SYSIMAGE_TYPE in config -to see other available filesystem types.</p> - -<p>This creates empty directories, copies the skeleton files from -sources/root-filesystem, adds the contents of the directory $ROOT_OVERLAY -points to (if any), and builds toybox.</p> -<p> -<p>The config variable ROOT_OVERLAY can add arbitrary files to this stage.</p> -</blockquote> -</li> - <li><b>system-image.sh $TARGET</b> <blockquote> -<p>Packages up the root-filesystem (usually as a cpio.gz for initramfs), -builds a linux kernel (generally configured -for use with QEMU), and adds emulator launch scripts.</p> +<p>This does three things:</p> +<ul> +<li><p>Packages up the root-filesystem (the default is cpio.gz for initramfs, +see SYSIMAGE_TYPE in config for alternatives) and the native-compiler +(as a squashfs).</p></li> +<li><p>Adds emulator launch scripts (usually for QEMU), see the +<a href=<about.html#sysimage_use>About page</a> for details.</p></li> +<li><p>Builds a linux kernel, generally configured for use with QEMU).</p></li> -<p>The kernel configuration combines the sources/baseconfig-linux settings +<p>The <b>mini.config</b> file is the kernel configuration in +<a href=http://landley.net/aboriginal/FAQ.html#miniconfig>miniconfig</a> +format (I.E. start from 'allnoconfig' and list the symbols you'd need to +switch on in menuconfig, allowing that to resolve dependencies as it goes). +It's created by combining the sources/baseconfig-linux settings (which are the same for each $TARGET) with the target-specific LINUX_CONFIG -entries from sources/targets/$TARGET. This configuration mechanism -(<a href=http://landley.net/aboriginal/FAQ.html#miniconfig>miniconfig</a>) -essentially starts with "allnoconfig" and then switches on each mentioned -symbol, resolving dependencies as it goes, just as if you opened up menuconfig -and set that list of symbols by hand.</p> - -<p>You can also build your own kernel outside of this build system, using -the root-filesystem directory as your initramfs source.</p> - -<p>For more information on system images and launch scripts, see the -<a href=prebuilt-binaries.html>the binary docs</a></p> +entries from sources/targets/$TARGET. This gives you a starting point +to build your own kernel and package up root-filoesystem in your own way +if you want to bypass the system-image.sh stage.</p> </blockquote> </li> </ul> -<p>The sources/more directory contains additional scripts the user can run, -but which are not called from build.sh. This directory contains the external -user interfaces the user can call directly which are not build stages. -See more/README in the Aboriginal source code for details.</p> +<p>The <b>sources/</b> directory contains infrastructure, defining variables +and shell functions used by the rest of the build. Most prominently, the +the shell functions "<b>setupfor</b>" prepares a temporary copy of +the source (extract and patch the relevant source tarballs and cd into the +directory), and the shell function "<b>cleanup</b>" deletes that temporary copy +when finished. (The actual implementation has +<a href=FAQ.html#debug_source>some optimizations</a> you can usually ignore.) +The function "<b>build_section</b>" does both and calls a build script from +sources/sections in between (see sources/sections/README for details).</p> -<p>The native-build.sh script in each system-image, and the -more/native-build-from-build.sh script, use <a href=control-images>build +<p>The <b>sources/targets/</b> directory contains all target-specific +information. Each target has a single file defining all target-specific +information, and adding a target just means adding a file to this directory.</p> + +<p>The <b>more/</b> directory contains all the additional scripts the user may +want to run directly, but which aren't build stages.</p> + +<p>The <b>more/native-build-from-build.sh</b> script (which calls the +native-build.sh script in a system-image) uses <a href=control-images>build control images</a>, externally supplied filesystem images (usually squashfs) -the system image's init script automatically mounts on /mnt. If the file -/mnt/init exists (I.E. an executable "init" script at the top of the +which the system image's init script automatically mount on /mnt. Then if the +file /mnt/init exists (I.E. an executable "init" script at the top of the build control image), the system image init script will run that file instead of dropping to a shell prompt. This allows arbitrary automated behavior out of the newly booted image, operating on supplied data.</p>