How To Build OpenSolaris
2010-06-08

Building any operating system from scratch is usually a daunting task. OpenSolaris is no exception. There are lots of steps that can easily be overlooked and here I attempt to simplify the entire process step by step.

Note that this tutorial is not a replacement for the OpenSolaris ON Developer's Reference Guide. I highly suggest you follow my steps below in addition to reading the reference guide. Once you're familiar with what's involved this tutorial should prove to be a great reference.

*** FLAG DAYS ***

» All Flag Days and Heads Ups

» As of build 143 Perl 5.10 is required to build onnv. See the following heads up.

» As of build 144 the minimum onnv build system version increased to 137. See the following heads up.

*** ***

1. Uninstall any previously installed SunStudio package. Now download and install the proper compiler version as described here. You will need two compiler packages. At the time of this writing SunStudio 12 is needed for compiling and SunStudio 12u1 is needed for lint.

Install SunStudio 12 for the compiler:

# cd /opt
# mkdir SUNWspro
# cd SUNWspro
# gtar -jxvf sunstudio12-patched-ii-2009Sep-sol-x86.tar.bz2

Install SunStudio 12u1 for lint:

# cd /opt
# gtar -zxvf sunstudio12u1-patched-ii-2010Feb-sol-x86.tar.gz

2. Add the extra repo and install the developer package as initially described here. You'll have to register with Oracle here to proceed. Once you have registered and downloaded your SSL authority certificate you can add the extra repo:

# mkdir -m 0755 -p /var/pkg/ssl
# cp -i OpenSolaris_extras.key.pem /var/pkg/ssl
# cp -i OpenSolaris_extras.certificate.pem /var/pkg/ssl
# pkg set-authority -k /var/pkg/ssl/OpenSolaris_extras.key.pem \
                    -c /var/pkg/ssl/OpenSolaris_extras.certificate.pem \
                    -O https://pkg.sun.com/opensolaris/extra/ extra

3. Set your primary authority to the development repository:

# pkg set-authority -O http://pkg.opensolaris.org/dev opensolaris.org

4. Install the required packages for ON development:

# pkg install developer/opensolaris/osnet

5. In order to download the onnv sources mercurial must be installed:

# pkg install mercurial

6. Clone the onnv repo. The following clones the latest sources and puts it all under a directory named onnv:

# hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate onnv

If you want to build from a previous snapshot then you need to update your sources to a previous tag. This is done by downloading the latest sources and then updating to (mercurial terminology for making visible) a specified tag. Snapshot names can be found here.

# hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate onnv-b142
# cd onnv-b142
# hg update onnv_142

7. Download and unpack the latest on_closed and on_crypto binary packages. These contain the "binary distribution only" modules that are required for building the kernel. To make this step easy I created a script that will do this automatically:

# cd onnv
# osolbins current

Here is my osolbins script:

#!/bin/bash

if [[ -z $1 || -z $2 || ( $1 != "i386" && $1 != "sparc" ) ]]; then
  echo "ERROR: $0 [ i386 | sparc ] [ build ]"
  echo "  build = b134, b142, current, etc"
  exit
fi

MACH=$1
BLD=$2

CRYPTO="http://dlc.sun.com/osol/on/downloads/nightly-crypto"
CLOSED="http://dlc.sun.com/osol/on/downloads/$BLD"

function get_crypto()
{
   /bin/rm -f $1.$MACH.tar.bz2
   wget $CRYPTO/$1.$MACH.tar.bz2
}

function get_closed()
{
   /bin/rm -f $1.$MACH.tar.bz2
   wget $CLOSED/$1.$MACH.tar.bz2
}

get_crypto on-crypto-latest-nd
get_crypto on-crypto-latest

get_closed on-closed-bins-nd
get_closed on-closed-bins

gtar -jxvf on-closed-bins-nd.$MACH.tar.bz2
gtar -jxvf on-closed-bins.$MACH.tar.bz2

8. Create an environment file to use for building onnv. It is best to start with the default environment file and modify it as needed.

# cd onnv
# cp usr/src/tools/env/opensolaris.sh .

Edit the copied opensolaris.sh file and modify the following environment vars:

GATE=your_repo_dir
CODEMGR_WS=full_path_of_repo_dir
STAFFER=your_login_name
MAILTO=your_email_address
ON_CRYPTO_BINS=$CODEMGR_WS/on-crypto-latest.$MACH.tar.bz2

For example:

GATE=onnv
CODEMGR_WS=/work/$GATE
STAFFER=edavis
MAILTO=edavis@insanum.com
ON_CRYPTO_BINS=$CODEMGR_WS/on-crypto-latest.$MACH.tar.bz2

Finally add the following to the END of the opensolaris.sh file:

i386_LINT=/opt/sunstudio12.1/bin/lint; export i386_LINT
amd64_LINT=/opt/sunstudio12.1/bin/lint; export amd64_LINT
sparc_LINT=/opt/sunstudio12.1/bin/lint; export sparc_LINT
sparcv9_LINT=/opt/sunstudio12.1/bin/lint; export sparcv9_LINT

9. Install the onbld tools. These tools contain the scripts and programs needed to build and install onnv. Note that there is an onbld package that can be installed via IPS. Don't install that! Instead we have to build and use the tools that are based on the onnv snapshot. The onbld sources are found inside the cloned mercurial repository. These are guaranteed to work properly.

Build the onbld tools:

# cd onnv
# ksh93 usr/src/tools/scripts/bldenv.sh opensolaris.sh \
        "cd usr/src/tools && dmake install && cd .. && dmake setup"

Now install the newly built onbld tools:

# cp -r usr/src/tools/proto/root_i386-nd/opt/onbld /opt

Make sure to have /opt/onbld/bin in your PATH.

10. We are now ready to build. The nightly script that comes with onbld takes care of all the dirty work:

# cd onnv
# ksh93 /opt/onbld/bin/nightly ./opensolaris.sh

If you want to watch what the going on then run the following in a different terminal/shell:

# cd onnv
# tail -f log/nightly.log

Note that the -i argument to nightly tells it to do an incremental build. Without it nightly does a full clobber/clean of existing objects and rebuilds from scratch.

If you have any problems up to this point I highly suggest consulting one of the OpenSolaris mailing lists. Namely the osol-discuss list.

11. Install the new bits using the onu script that comes with onbld.

# cd onnv
# /opt/onbld/bin/onu -Ov -d `pwd`/packages/i386/nightly \
                         -t nightly-`date +'%Y-%m-%d'`

onu clones the current boot environment (beadm) and only updates the packages that were previously installed in the environment. If, after you reboot into the new environment, you need to install additional packages you'll have to make the build bits repo available again. onu can do this for you:

# cd onnv
# /opt/onbld/bin/onu -O -r -d `pwd`/packages/i386/nightly

12. That's it! If you've reached this step then congrats. I hope this tutorial helped!

» Optional past here...

13. After you have successfully built OpenSolaris you might want to package up the binaries for installation on another system without having to rebuild again from scratch. I've created a script that will do this automatically. This script creates a zip file containing the specific onbld tools and the onnv installation bits used by onu. The following would create a file named onnv.zip which can be used on another system.

# cd onnv
# osolbits onnv

Here is my osolbits script:

#!/bin/bash

if [[ -z $1 ]]; then
  echo "ERROR: $0 [ build_name ]"
  exit
fi

if [[ -d $1 ]]; then
  echo "ERROR: $1 already exists"
  exit
fi

mkdir $1

cd $1
ln -s ../packages/i386/nightly nightly
ln -s ../usr/src/tools/proto/root_i386-nd/opt/onbld onbld
cd ..

gtar -zchvf $1.tgz $1

cd $1
rm nightly onbld
cd ..

rmdir $1

After copying the zip file to another system run the following to perform the upgrade. If you have a previous version of onbld installed either uninstall it or rename /opt/onbld to something else.

# gtar -zxvpf onnv.tgz
# cp -r onnv/onbld /opt
# /opt/onbld/bin/onu -O -d `pwd`/onnv/nightly -t b140
# beadm list
# reboot

Notice the -p passed to gtar. This is required else onu will fail.

Here is an example of what to expect from onu during the upgrade. This output is from when I updated a system from build 134 to 140 using a prepackaged zip named b140.zip.

# /opt/onbld/bin/onu -O -d `pwd`/b140/nightly -t b140
[28/May/2010:10:20:47] ENGINE Listening for SIGHUP.
[28/May/2010:10:20:47] ENGINE Listening for SIGTERM.
[28/May/2010:10:20:47] ENGINE Listening for SIGUSR1.
[28/May/2010:10:20:47] ENGINE Bus STARTING
[28/May/2010:10:20:47] ENGINE Started monitor thread '_TimeoutMonitor'.
[28/May/2010:10:20:48] ENGINE Serving on 0.0.0.0:13000
[28/May/2010:10:20:48] ENGINE Bus STARTED
[28/May/2010:10:20:48] INDEX Updating search indices
PHASE                                        ACTIONS
Removal Phase                                  54/54 
[28/May/2010:10:21:08] INDEX Search indexes updated and available.
DOWNLOAD                                  PKGS       FILES    XFER (MB)
Completed                              240/240   4105/4105  127.2/127.2

PHASE                                        ACTIONS
Removal Phase                              1898/1898 
Install Phase                              2273/2273 
Update Phase                               6965/6965 
b140 has been updated successfully
[28/May/2010:10:24:13] ENGINE Caught signal SIGTERM.
[28/May/2010:10:24:13] ENGINE Bus STOPPING
[28/May/2010:10:24:13] ENGINE HTTP Server cherrypy._cpwsgi_server.CPWSGIServer(('0.0.0.0', 13000)) shut down
[28/May/2010:10:24:13] ENGINE Stopped thread '_TimeoutMonitor'.
[28/May/2010:10:24:13] ENGINE Bus STOPPED
[28/May/2010:10:24:13] ENGINE Bus EXITING
[28/May/2010:10:24:13] ENGINE Bus EXITED
[28/May/2010:10:24:13] ENGINE Waiting for child threads to terminate...

# beadm list
BE            Active Mountpoint      Space  Policy Created          
--            ------ ----------      -----  ------ -------          
b140          R      /tmp/onu.jDaGwc 11.85G static 2010-05-28 10:20 
opensolaris-2 N      /               7.39M  static 2010-05-28 09:12