Using the BeleniX Constructor

Many of you following the OpenSolaris distribution should have heard about the Distro Constructor toolkit that allows one to build the LiveCD distribution of OpenSolaris. The Distro Constructor has it’s roots in the Live Media Kit which in turn was a re-whack of the toolkit used to build BeleniX 0.4.4.

After OpenSolaris 2008.05 was released I decided to pick the Distro Constructor toolkit available at that time and re-whack it into the BeleniX Constructor. There are several differences in the way LiveCD ISO construction is done in BeleniX and in the OpenSolaris distro. Given the way Distro Constructor is evolving today these differences will increase going forward both at the architecural and feature level. These considerations necessitated creating and maintaining a separate distro construction toolkit for BeleniX’s requirements. One of the most important differences is the way the miniroot is constructed. in addition BeleniX still uses SVR4 packaging. The differences are sufficiently fundamental to make it well nigh impossible to use Distro Constructor customizations to accommodate BeleniX requirements without patching the former.

Today the BeleniX Constructor lives in an SVN repository here:

There is a README file in that directory that explains a bunch of things including various configuration settings. The top level directory structure and source code components is as follows:

packages Contains miscllaneous packages required for LiveCD at present this only has a Licensing package.
src Contains all the source code for BeleniX Constructor.

bootcd_skel Replacement customizations for existing files in the base OS. These are customizations needed for the LiveCD.
postrun_scripts Distro Constructor weirdness needed due to a combinaton of GNOME crappiness and IPS no-scripting limitation. Will be removed shortly.
archive_paths Pathname patterns that are not needed by LiveCD but needed in installed system. These are packed up tightly in a 7zip archive.
build_dist.bash Main script that orchestrates the entire build.
build_dist.lib Library of functions used by the above script.
dist.conf Empty config file with comments explaining various settings.
microroot_list Top-level pathname prefix list for including in the microroot.
mkrepo Script to pre-generate an SMF repository for the LiveCD.
pkg_retrieve_ips.lib Script that can populate an alternate root from an IPS repository.
pkg_retrieve_svr4.lib Script that can populate an alternate root from a directory containing needed SVR4 packages. The package list is in test_data/pkgs.txt. A perl script that can process a TOC-style SVR4 package Cluster. Explained later. A perl script to reverse a text file.
usr_microroot_files A short list of pathnames under /usr needed to be present in the microroot.
test_data Contains base configurations for the BeleniX Constructor.
tools A few tools used by constructor that are also useful by themselves.
usr A remnant from some changes in the earlier Distro Constructor. Will be removed shortly.

This is in essence a very high level view of the overall organization. Now if you wish to play with this utility can build custom LiveCDs, there are few steps:

  1. Check out the BeleniX Constructor tree: svn co belenix/trunk/apps/belenix_constructor
  2. Next you need to set aside space for storing the packages and distro construction area. At least 15GB of space is needed.
  3. Lets assume that you are storing all the packages in “/export/pkgs” and “/export/livecd” is your distro construction area.
  4. Now you need to download all the required packages listed in “belenix/trunk/apps/belenix_constructor/test_data/pkgs.txt”. That file is in a SVR4 cluster definition format. It is very simple to understand once you take a single look. All the packages are available from “”. The packages are compressed using 7Zip. So you’d have to extract them as well and convert from datastream format to filesystem format. This is essentially a small loop in a shell script and is left as an exercise for the reader. Of course I will work up a tinny script and post it in a subsequent blog entry. Obviously these packages have to go into “/export/pkgs”
  5. Now it is time to configure the Constructor:  cd belenix/trunk/apps/belenix_constructor/src; cp ../test_data/test1.conf .
  6. Edit test1.conf and setup the entries. The file is profusely commented and the settings are easy to understand. At the minimum you will have to set:
    • TEST_DATA – This should contain full path to the test_data directory referred to above.
    • DIST_MICROROOT_LIST – This contains full path to the belenix/src/belenix_constructor/src/microroot_list file. This is essentially a set of directories and patterns that are included in the ramdisk.
    • DIST_METACLUSTER – This defines the cluster name as specified in pkgs.txt. Leave this unchanged.
    • DIST_PROTO – This contains the full path to the proto or distro construction area. In our example this is “/export/livecd.
    • DIST_ID – Name of the distro
    • DIST_ISO – Full path to where the LiveCD ISO should be created. In our example this should be “/export/$DIST_ID.iso”
    • DIST_PKG_DIR – Directory where all our SVR4 packages are stored. In our example this is “/export/pkgs”
  7. Once configuration is done. You are ready to fire off a build thus: cd belenix/trunk/apps/belenix_constructor/src; ./build_dist.bash ./test1.conf

Obviously drop an email off to belenix_discuss __at_ opensolaris (_dot) org if you face problems.


One thought on “Using the BeleniX Constructor

  1. Martin

    Congrats, Moinak.
    I need to give it a try when I have more time.
    Maybe Brian Gupta, Al Hopper, myself and the rest of the Natamar team can donate the SPARC distro-changes plus the conary port (re-invented wheel, but:
    #0.) re-invented for a sane purpose / benefit ratio
    #1.) re-invented by others [ {==saved work}], only made work by us. If you read the Linux press, conary may have the potential to become *the* successor to rpm and else.

    p.s. I didn’t want to base my work directly on yours. I use my own Distro-generator (which was derived from Alan Coopersmith’s fox-gate Makefile system).
    What I do use from you is the /lib/svc/method/*live* SMF services (and their manifests), but not more. I wanted to build Natamar, rather than Nata-BeleniX. Otherwise I would not have released it on my own, but instead I would have asked to join your team. For the most part I didn’t use *any*constructor, just my keyboard and a hand-crafted process. The Natamar-DG is not ready, but we plan to set up hg or svn or git, too.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s