This tool can be used to create a Live CD/DVD or a Live USB image from a
given list of packages.

The script retrieves the list of packages from the specified IPS repository
server, prepares the X86 microroot, does additional processing for
creating a bootable live CD, and then creates an ISO that can be
burned into a CD/DVD.  The script can also convert
the ISO into a USB image that is suitable for writing to a USB drive.

The following is a high-level description of the steps the Distribution
Constructor completes in order to create a bootable live CD. 

The Constructor...

1) Loads your configuration file.

2) Populates the proto area with the list of packages specified.

3) Populates the microroot with the list of packages specified for the
   microroot.

4) Completes special setup for the Live CD.  This setup is done in the
   livemedia_processing() function in src/build_dist.lib. 

   The preparations includes running all the postinstall scripts
   to setup GNOME; setting up the font cache; preloading the SMF repository;
   creating symlinks between the microroot and the proto area;
   and finally creating a boot archive with all the files installed into
   the microroot.

5) Invoke mkisofs to build a bootable iso image containing the
   entire contents of our proto directory. Grub's eltorito stage2 bootloader
   is used, that enables booting directly off a CD/DVD. We violate the ISO9660
   specs somewhat to accomodate file properties essential for a proper Unix
   file/directory layout.


Pre-requisites to using the BeleniX Constructor:
------------------------------------------------
- To use this kit, you need to have root access to the system on which the
resulting image are to be created.

- The system on which you are using the kit must be a x86 system running
  Solaris Nevada build 71 or above.  Sparc is not supported at this time.

- You need to have access to a package repository.

Usage:
------

To create a Live CD/DVD or USB image, invoke the "build_dist.bash"
script with your configuration file as an argument.  For example:
        # ./build_dist.bash test1.conf


Configuration file:
-------------------

The configuration file is used to specify different parameters used
for creating the image.  The "dist.conf" file is a skeleton file
containing all the parameters.  You can make a copy of this file,
and fill in your values.  

To view a sample file, see test_data/test1.conf.

The following parameters are required:

DIST_PKG_LIST: 
        Full path to a file containing list of packages to be
        included in distribution.  The list of package names
        should be one per line in the file.  test_data/pkg.txt
        is the file used for creating the Slim CD prototype.

DIST_MICROROOT_LIST:
        Full path to a file containing list of packages to be included
        in microroot.  The list of package names should be one per line in
        the file.  test_data/microroot_pkgs.txt is the file used
        for creating the Slim CD prototype.

DIST_PKG_SERVER:
        Name of the IPS server containing the packages.  Note:
        in this prototype release, we only support specifying
        one IPS server.

DIST_PROTO:
        The proto directory where the filesystem hierarchy for
        the distribution is created.  If this directory does not
        currently exist, it will be created.  If this directory
        exists, and there's content in it, all contents will be removed.

DIST_ISO:
        The full path to the ISO file to be created.  If this file
        already exists, it will be overwritten with the new file.

DIST_ID:
        Name of this image.

DIST_ISO_SORT:
        Sort list for the /usr file system on the CD.  This is used
        for optimizing the run time of the CD.  test_data/iso.sort
        is the file used for the Slim CD prototype release.

The following parameters are optional:

DIST_USB:
        The full path to the USB file for the USB image
        If this value is not specified, the USB image will not be
        created.  If the USB file exists, it will be overwritten
        with the new file.

QUIT_ON_PKG_FAILURES:
        Acceptible values are yes or no. Yes means that if the
        package adds fail, the entire build is aborted. No means that if
        the package add fail, continue on. The default value is no. 

DIST_ADDITIONAL_MOD: 
        If additional changes need to be made to the image before the image
        is created, these changes can be passed into the Distro Constructor
        code as an archive.

        The archive must contain at least one script with the
        name "post-process".  If no script with the name
        "post-process" is found in the root of the
        archive, the archive will be ignored.

--------------------------------------------------------
Brief Overview of the structure of the source code:
--------------------------------------------------------

The source code for the BeleniX Constructor toolkit for the Beta
release is a collection of scripts.  This is a modification of the
work that is being done in the Distribution Constructor Project
http://www.opensolaris.org/os/project/caiman/Constructor/

which is in turn derived from the original work done in BeleniX
and the Live Media project!
See http://opensolaris.org/os/project/livemedia/


src:
----

The src directory contains all the code used to create the ISO image.

build_dist.bash:
        Main script
build_dist.lib:
        Supporting functions for the main script.
pkg_retrieve.lib:
        Functions for installing packages from the IPS repository.
dist.conf:
        Skeleton configuration file.  Make a copy of this file and fill it
        out to specify your own configuration.
mkrepo:
        Pre-registers SMF services for the Live CD.
generic_live.xml:
        Used by "mkrepo" script above.
usr_microroot_file:
        List of files for the /usr directory for the microroot.  This file
        is a "hack" for the prototype.  In order to reduce the size of the
        microroot, only files that are critical for the Live CD during boot
        are included.  
postrun_scripts:
        This directory contains some SVR4 postinstall scripts that do
        postrun.  Since IPS doesn't support postinstall scripts, and the
        postrun command depends on some SVR4 information,  this setup is
        a "hack".  This "hack" is necessary to run all
        the postinstall scripts needed to setup GNOME.
        
test_data/
-----------

pkgs.txt:
        List of packages used for creating the Live CD prototype.
microroot_list
        List of files/directories/rules for including stuff into the
        microroot for the Live CD.
test1.conf:
        sample configuration file.
iso.sort:
        This is used for optimizing the run time of the CD for the
        Slim CD prototype.

tools/
------
usbgen:
        Generates a USB file that is suitable for USB drives based on an ISO.

usbcopy:
        Copies the file generated by usbgen to your USB drive.
        
proc_slist.pl:
proc_tracedata:
        Used for generating the iso.sort file.

listusb:
        A binary used by usbgen.

extract_postrun:
        A convenience script that extracts all the postinstall scripts
        from SVR4 packages that contain postrun calls.