Depend on fai >=3.2, implement the suite handling for conffiles, update docs, improve...

[grml-live.git] / docs / grml-live.txt

diff --git a/docs/grml-live.txt b/docs/grml-live.txt
index 9bb6948..52b7d2d 100644 (file)
--- a/docs/grml-live.txt
+++ b/docs/grml-live.txt
@@ -3,43 +3,51 @@ grml-live(8)
 
 Name
 ----
 
 Name
 ----

-grml-live - build process script for generating a (grml based) Linux Live-ISO
+
+grml-live - build framework for generating a grml and Debian based Linux Live
+system (CD/ISO)

 
 Synopsis
 --------
 
 Synopsis
 --------

+

 grml-live [-c <classe[s]>] [-t <target_directory>] [-F] [-h|--help]
 
 *******************************************************************************
 grml-live [-c <classe[s]>] [-t <target_directory>] [-F] [-h|--help]
 
 *******************************************************************************

-Important! grml-live is under heavy construction, your feedback is highly
+Important! grml-live is under heavy construction, though your feedback is highly

 appreciated.  This document is growing as requested. If you have questions which
 appreciated.  This document is growing as requested. If you have questions which

-aren't answered by this document yet please let me (mika@grml.org) know!
+aren't answered by this document yet please let me know: <mika@grml.org>!

 *******************************************************************************
 
 Description
 -----------
 
 *******************************************************************************
 
 Description
 -----------
 

-grml-live provides the build system for creating (a grml based) live-cd. The
-build system is based on link:http://www.informatik.uni-koeln.de/fai/[FAI]
-(Fully Automatic Installation).
+grml-live provides the build system for creating a grml and Debian based Linux
+live-cd. The build system is based on
+link:http://www.informatik.uni-koeln.de/fai/[FAI] (Fully Automatic
+Installation). grml-live uses the "fai dirinstall" feature to generate a chroot
+system based on the class concept of FAI (see later section for further details)
+and provides all the details to be able to generate a full-featured ISO. It does
+not use all the FAI features by default though and you don't have to know FAI to
+be able to use it.

 
 

-FAI uses a class based system. This gives you the flexibility to choose the
+The use of FAI behind the curtains gives you the flexibility to choose the

 packages you would like to include on your very own Linux live-cd without having
 to deal with all the details of a build process.
 
 packages you would like to include on your very own Linux live-cd without having
 to deal with all the details of a build process.
 

-CAUTION: grml-live does not use /etc/fai for configuration but instead provides
-and uses /etc/grml/fai. This ensures that it does not clash with default FAI
-configuration and packages, so you can use grml-live and FAI completely
-independent!
+CAUTION: grml-live does **not** use /etc/fai for configuration but instead
+provides and uses /etc/grml/fai. This ensures that it does not clash with
+default FAI configuration and packages, so you can use grml-live and FAI
+completely independent at the same time!

 
 [NOTE]
 
 [NOTE]

+

 Please notice that you should have a fast network connection as all the Debian
 packages will be installed via network. If you want to use a local mirror
 Please notice that you should have a fast network connection as all the Debian
 packages will be installed via network. If you want to use a local mirror

-(strongly recommended!) checkout
-mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror)
-debmirro(1) and reprepro(1) (check out
-/usr/share/doc/grml-live/examples/reprepro/ for a sample configuration).
-To avoid downloading of the base system check out FAI's
-NFSROOT (check docs for ../fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz).
+(strongly recommended!) checkout mkdebmirror (see
+/usr/share/doc/grml-live/examples/mkdebmirror), debmirror(1), reprepro(1) (see
+/usr/share/doc/grml-live/examples/reprepro/ for a sample configuration) and
+approx(8). To avoid downloading of the base system check out FAI's NFSROOT (check
+docs for ../fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz).

 
 Options
 -------
 
 Options
 -------


@@ -50,27 +58,45 @@ Specify the CLASSES to be used for building the ISO via fai.  By default only
 the classes GRMLBASE and I386 are assumed, resulting in a small base system
 (being about ~150MB ISO size).
 
 the classes GRMLBASE and I386 are assumed, resulting in a small base system
 (being about ~150MB ISO size).
 

+  -s **SUITE**::
+
+Specify the Debian suite you want to use for your live-system.  Defaults to
+"etch"; support values are: etch, lenny, sid, stable, testing, unstable.
+

   -t **TARGET_DIRECTORY**::
 
   -t **TARGET_DIRECTORY**::
 

-Output directory of the build process of FAI - being the chroot
-used for building the ISO.
+Main output directory of the build process of FAI.  Three directories are
+created inside the target directory, being: grml_cd/ - where the files for
+creating the ISO are located (including the compressed squashfs file),
+grml_chroot/ - the generated chroot system and grml_isos/ - where the resulting
+ISO is stored.

 
   -F::
 
 
   -F::
 

-Force execution and do not display summary of configuration details.
+Force execution and do not prompt for / display summary of configuration
+details.

 
 

-  -h|--help::
+  -h::

 
 Display short usage information and exit.
 
 
 Display short usage information and exit.
 

+  -v::
+
+Increase verbosity in the build process.
+

 How to get your own live-cd - the easy, fast and simple way
 -----------------------------------------------------------
 
 How to get your own live-cd - the easy, fast and simple way
 -----------------------------------------------------------
 

-To get a small, Debian-stable and grml based live-cd using /dev/shm/
+To get a small, Debian-stable and grml based live-cd using /grml/grml-live

 as build and output directory:
 
   # grml-live
 
 as build and output directory:
 
   # grml-live
 

+To get a small Debian-unstable and grml-small based live-cd using
+/home/mika/grml-live as build and output directory:
+
+  # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
+

 [NOTE]
 
 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
 [NOTE]
 
 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually


@@ -80,6 +106,22 @@ But please be aware of the fact that rebooting your system will result in an
 empty /dev/shm, so please another directory for $CHROOT_TARGET, $BUILD_TARGET
 and $ISO_TARGET if you plan to create more persistent output. :)
 
 empty /dev/shm, so please another directory for $CHROOT_TARGET, $BUILD_TARGET
 and $ISO_TARGET if you plan to create more persistent output. :)
 

+Features
+--------
+
+* create a grml-/Debian-based Linux Live-CD with one single command
+
+* class based concept, providing a maximum of flexibility
+
+* supports integration of own hooks, scripts and configuration
+
+* supports use and integration of own Software and/or Kernels via use of Debian
+repositories
+
+* native support of FAI features
+
+* multi-arch support (work in progress)
+

 The class concept
 -----------------
 
 The class concept
 -----------------
 


@@ -213,38 +255,56 @@ as possiblbe)
 Known TODOs
 -----------
 
 Known TODOs
 -----------
 

-* do not use /dev/shm/ als default target directory (which one do we want to use
-instead?)
+* document the available classes in more detail
+
+* make sure $TARGET is mounted rw,suid,dev
+
+* write a step-by-step guide **how** to adjust **what** at **which** place

 
 * add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
 that are arch specific so we have a clean package list in all classes)
 
 * support different grml-flavours through classes right out-of-the-box (being:
 
 * add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
 that are arch specific so we have a clean package list in all classes)
 
 * support different grml-flavours through classes right out-of-the-box (being:

-grml, grml64, grml-small for at least x86, amd64 and ppc)
+grml, grml64, grml-small (done) for at least x86, amd64 and ppc)

 
 

-* support setting grml-live configuration on the command line to provide
-different flavours using the commandline only
+* support signed apt repositories (currently it's deactivated via FAI's
+FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)

 
 

-* really support signed apt repositories (currently it's deactivated via fai's
-dirinstall for some packages)
+* explain (and provide configuration for) use of NFSROOT

 
 

-* explain (and provide configuration for) the use of NFSROOT
+* support setting stuff like ISO name, version,... on-the-fly (especially for
+stuff inside boot/isolinux/*)

 
 

-* support setting stuff like ISO name, version,... (especially for stuff inside
-x86_files/boot/isolinux)
-
-* support "final builds" (including stuff like md5sums)
-
-* use hooks of FAI as far as possible in all grml-live scripts
+* support "final builds" (including stuff like generating md5sums, gpg,... -
+create something like grml_release including all the details about the build
+like dpkg selection, logs,...)

 
 * the grml-live class(es) should send output as used inside FAI as well (so it's
 not as verbose unless you specify it, make it configurable)
 
 
 * the grml-live class(es) should send output as used inside FAI as well (so it's
 not as verbose unless you specify it, make it configurable)
 

-* provide possibility for cleanup of all created build directories
+* provide possibility for cleanup of all created build directories and
+a smart summary of the buildprocess (including "took ... minutes/seconds to
+build...)
+
+* support hooks to allow further customisation of the build process
+
+Debian package
+--------------
+
+Debian packages will be available through the grml-repository at
+link:http://deb.grml.org/[http://deb.grml.org/] as soon as the grml-team
+considers grml-live as stable enough. In the meantime just build the package on
+your own:
+
+  hg clone http://hg.grml.org/grml-live
+  cd grml-live
+  debuild -us -uc

 
 

-* support hooks to further allow customisation of the build process
+Source
+------

 
 

-* support nocolor-option for /etc/grml/fai/grml/grml_cleanup_chroot
+The source of grml-live is available at
+link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]

 
 Bugs
 ----
 
 Bugs
 ----