#
# README file for the lunar-iso generation code.
#

-- Goal

Most of this code was written to automate the generation of homogeneous
ISO images based on a fixed set of tools. The code should be as self-
sufficient as possible and generate as much of the binaries as possible
so porting to other platforms will be easy. Please keep this in mind if
you change the scripts and want to include binaries. This should be kept
to a minimum. Note that this code doesn't do cross builds and it requires a
Lunar host.

The ISO has been optimized to minimize the number of alien files. These
should always be as much as possible be provided by modules. The exception
are stored in template, and include several files which need to be filled
with something valid before you can start. Please take care of these files
and try your utter best to make sure you don't add files in the template
that really (really (really)) do not need to be in there.


-- Start

The Makefile should be able to do most of the ISO building automatically, but
there are a few steps that need to be taken:

 o Copy conf/config.in to conf/config
 o Configure the base parameters of the ISO in conf/config
 
The code tries to pollute the host system as little as it can. It will however
create a build cache for the bootstrap modules if it doesn't exist already.
Also it will download all the sources of core modules. Last it will install
cdrtools if mkisofs isn't found.

The build cache will be copied to cache/ and the sources of the core modules
will be copied to spool/.

The cache is used to bootstrap the ISO building. As first stage a few modules
are build. These modules are then copied to cache/. For the second stage
this cache is used to build all the core modules.


-- Building it

Run make to build the ISO. The default target will build the completely ISO.

Here's a brief explanation of the different make targets:

target			create BUILD/ directory

boostrap-lunar		use Lunar host to get the main modules into BUILD/
boostrap-base		populate BUILD/ directory with generic files
boostrap		populate BUILD/ directory

download-moonbase	download the moonbase, can be used for updating
moonbase-git		create moonbase package from local git
install-moonbase	extract the moonbase to BUILD/
download-lunar		use Lunar host to download all sources
download		download all sources

stage1-spool		copy spool/ to BUILD/
stage1-moonbase		fix the moonbase cache files
stage1-toolchain	build gcc, glibc and binutils
stage1-build		build the main modules
stage1-cache		copy stage1 to cache/
stage1			build stage1 and copy to cache/

stage2-target		create a clean BUILD/
stage2-base		populate BUILD/ directory with generic files
stage2-modules		populate BUILD/ with stage1 modules
stage2-spool		copy spool/ to BUILD/
stage2-extract-moonbase	extract the moonbase to BUILD/
stage2-moonbase		fix the moonbase cache files
stage2-toolchain	build stage2 gcc, glibc and binutils
stage2-build		build stage2 core modules
stage2			build stage2 from stage1

pack-base		create aaa_base.tar.bz2
pack			create packages of alien files

linux			build linux kernel
kernel			create kernel for the ISO and installation

lunar-installer		copy the installer to BUILD/
installer		install the insatller on the ISO

iso-target		clean stage2 markers
iso-modules		remove modules not needed on the ISO
iso-tools		check for mkisofs
iso-files		create config files for the ISO
iso-strip		strip all executables
iso-isolinux		copy isolinux files to BUILD/
iso			create the ISO from stage2

clean			wipes it all away

The Makefile itself contains no configurable items. Copy the template config
in the conf/ directory to conf/config and adjust the values as needed for
your needs.


--- Using git moonbase

The moonbase.tar.bz2 can be generated from a in-tree git clone. This clone is
located at moonbase-git/core. make moonbase-git will create this clone if it
doesn't exist, otherwise it will only update the moonbase.tar.bz2 in spool/.

To use the git moonbase run make moonbase-git first to create the clone. Next
make you modification by any means. Make sure to commit all modifications to
the active branch. Only committed changes will be in moonbase.tar.bz2. When
done making modifications run make moonbase-git to update the moonbase.tar.bz2
in spool/. This will make the ISO build start from the beginning when running
make iso.

To stop using the git moonbase run make download-moonbase. This will overwrite
the custom moonbase.tar.bz2 in spool/ with the current moonbase.tar.bz2 from
Lunar-Linux.


--- Tips and tricks

 o Removing BUILD/ will make start from the last finished stage redoing the
   next stages: bootstrap, stage1, stage2

 o Some build steps are not file based. These steps use markers. Most of them
   are placed in BUILD/ some are in spool/ and cache/. Removing such a marker
   can be used to redo that build step.