Build/Install OpenSolaris (Part 1) at OpenSolaris.org

You are not signed in. or register.

Building and Installing OpenSolaris (Part 1)

Author:Rich Teer
June 2005

Introduction

This is the first of two articles in which we describe how to acquire and build the source code for OpenSolaris. The first article provides all the necessary background information (terminology, where to get the tools, and so on) and describes a basic compilation and installation, and the second article will describe a more complicated compilation and installation. While these articles were accurate at the time they were written, OpenSolaris is continually evolving. For the most recent details, please consult the ON Developers Reference.

These articles describe how to build and install OpenSolaris; they are not intended to be an "OpenSolaris developers' guide", so information beyond that which is required for building and installing OpenSolaris is not included. This should not be seen as a problem, however, because (as with most other large-scale open source projects) the number of active OpenSolaris developers who will need this knowledge is likely to be small compared to the number of people who will want to build it for their own edification.

These articles assume at least a passing familiarity with building major software projects and some C programming. It is unlikely that someone who is struggling to compile "Hello World" would be trying to compile OpenSolaris! However, we will otherwise assume no knowledge of building Solaris, and describe all the necessary steps.

Terminology

Before we can describe how to build OpenSolaris, we need to define a few terms. To keep this list as short as possible, we will describe only those that are directly relevant to building and installing OpenSolaris. The terms we describe here are a subset of those used by OpenSolaris developers. As the need arises, we will occasionally define new terms when we introduce them.

The first term we need to define is OpenSolaris itself. The OpenSolaris website, opensolaris.org/os/about/, contains the Sun-blessed, official definition, but for our purposes, OpenSolaris refers to the Solaris source code that has been released by Sun, and binaries built from that source code. Hence we can say that we have a copy of the OpenSolaris source code, or we are running OpenSolaris (the latter being built from the former). For the OpenSolaris launch, Sun does not plan to release their own "distribution" of OpenSolaris, but that does not preclude others from doing so (the author is aware of at least three distribution projects that will be built using OpenSolaris, not least of which is a port to the PowerPC platform).

One thing that OpenSolaris is definitely not is everything that ships on the Solaris DVD or CDs. At the time of this writing (June 2005), OpenSolaris consists of only the ON consolidation. A consolidation is a set of related software components that are developed and delivered together. In addition to ON, other examples of consolidations include the windowing system, Java Desktop System, and so on. ON is an abbreviation of "OS/Net" or "OS/Networking", and is the consolidation that contains the kernel, file systems, basic commands, some modules and drivers, daemons, header files, and libraries. (Incidentally, the contents of the Solaris DVDs and CDs shipped by Sun are collectively known as the WOS, or wad of stuff: it is the integration of all the consolidations that make up the Solaris product.)

Not all of the components that make up ON are currently available in source form, for reasons explained in opensolaris.org/os/about/no_source/. As time passes, most, if not all, of the closed sources will be replaced by open source code (i.e., code which is developed by Sun or contributed by the OpenSolaris community), but until that happens a set of pre-built binary objects are supplied to facilitate the building of OpenSolaris.

Because of its bleeding-edge nature, it is possible that installing our newly compiled version of OpenSolaris might brickify our machine, that is render it unbootable or otherwise unusable. Improper installation, or installing broken bits, can make our machine a "warm brick". The usual way to recover from this situation is to boot from some other media (that we know to be good).

One final pair of terms that we might encounter when dealing with OpenSolaris are Nevada and Tonic. Nevada is the internal name of the release of Solaris that will come after Solaris 10; OpenSolaris is based on the Solaris Nevada sources. (In other words, the OpenSolaris source code is not based on the First Customer Shipment (FCS) version of Solaris 10, but an evolution thereof.) Tonic is the internal name of the OpenSolaris project; as such, Sun employees and pilot program participants are likely to be the only people using this term.

Now that we've described some of the terminology we need to be cognizant of when working with OpenSolaris, let's take a look at the prerequisites necessary for us to actually build it.

Prerequisites

At the risk of stating the obvious, the first thing we need to build OpenSolaris is a suitable machine: generally speaking, any computer that can run Solaris 10 is sufficient. This means that a machine with a 200 MHz or faster UltraSPARC-II or newer processor is required for SPARC builds. Due to the large variety of hardware, the requirements for x86 builds is a bit more complicated (when we say x86, unless we state otherwise, we mean both the 32-bit x86 platform as well as the 64-bit amd64 platform, which is sometimes referred to as x64 by marketing types). However, any reasonably recent hardware should be OK, provided it is on the Solaris x86 HCL (hardware compatibility list); the HCL can be found at www.sun.com/bigadmin/hcl/.

Presently, although both SPARC and x86 architectures are supported, cross-compilation is not (in other words, the platform we deploy OpenSolaris on must be the same as the one we use to build it). Building the OpenSolaris source tree is a fairly lengthy process, so a well specified machine is recommended (the author used an Acer Ferrari 3400 with 2 GB of RAM and a 7200 RPM hard drive for x86 builds, and an Ultra 60 with two 450 MHz processors and 2 GB of RAM for SPARC builds). At the time of writing, the machine we use must be running Solaris Express: Community Release (SXCR) Build 16 or later; the latest build of SXCR is strongly recommended, because it is likely that later versions of OpenSolaris will require later versions of SXCR as a minimum.

All this talk of Solaris, OpenSolaris, and Solaris Express can become confusing for new people, so we should take a minute or two to explain what these things are. First and foremost, Solaris is the branded product offering from Sun. A new version ships every two to three years, and updates are issued on an approximately quarterly basis. It is this version of the OS that should be used in production environments.

Solaris Express is monthly or so snapshots of the current development tree. The "best" build (i.e., most stable and least problematic) between the release date and the previous Solaris Express is the one that is released. Although it is reasonably well tested, it is important to remember that the code in Solaris Express is beta quality (i.e., has not been subjected to Sun's usual rigorous testing procedures), and should therefore not be used in production. That being said, Solaris Express is the easiest (and probably best) way to get access to new and improved Solaris features: for example, Solaris Express users were using what became Solaris 10 (including features like Zones and DTrace) for about two years before the FCS version was available. In the author's experience, Solaris Express is remarkably stable. Solaris Express builds trail the very latest Sun engineering builds by several versions (i.e., a month or two). As an example, at the time this article was written, Solaris Express was based on build 15 of Nevada, but build 16 was the current engineering version. (As we mentioned previously, there is also a Community Release of Solaris Express, which is released for every build. It receives less testing than the regular Solaris Express and is intended for OpenSolaris developers only, so should be deployed with suitable caution.)

As we alluded to previously, OpenSolaris is based on the current, bleeding edge, build of Solaris from Sun engineering. By its very nature, it has received less testing than Solaris Express, so tends to be a bit more challenging to work with and deploy. Definitely not for mission-critical production use!

Finally, we need sufficient disk space: about 90 MB is required for the source code, closed binaries, and tools, and each build tree needs at least 1.5 GB. With this in mind, we should have about 2 GB of free disk space for each tree that we intend to build. Doubtless, as more source code gets incorporated into OpenSolaris, the disk space requirements will increase.

Install a Binary Distribution of Solaris

As we mentioned previously, the machine on which we build OpenSolaris must be running a suitably recent version of Solaris Express or SXCR (or, indeed, a previous OpenSolaris build). Although the author has successfully built OpenSolaris on a machine with just the Developer cluster installed, Sun recommends that the Full cluster be installed.

Describing how to install Solaris is beyond the scope of these articles, and is well documented in Sun's Release and Installation collection, available from docs.sun.com.

Once we've satisfied the prerequisites (including installing a binary distribution of Solaris if necessary), we're ready to start downloading the various components and tools we need.

Download the Necessary Components

Before we download any of the OpenSolaris components and tools, we should create a directory in which we will work; this directory and its children is called a workspace. For the sake of these examples, we'll use a directory in our home directory called open_solaris as our base workspace. In this directory, we'll have a subdirectory for each build, named after the build contained therein (e.g., build-17). In each build directory, we'll have a build workspace that we'll call testws.

This will give us the following directory hierarchy:

$HOME/open_solaris Base directory

$HOME/open_solaris/build-17 Source and other bits for build 17

$HOME/open_solaris/build-n Source and other bits for build n

$HOME/open_solaris/build-n/testws Compilation workspace

There are a number of files we need to download into our "build" directory from the OpenSolaris web site (other sites will also probably offer the OpenSolaris components, but this article assumes the use of opensolaris.org). At the very least, we need the source code, the binaries built from closed source code, the ON build tools, the compiler and other tools. We should also download the release notes.

For the sake of this example, we'll assume that we want to compile build 17 of Nevada, and that we've already installed Solaris Express: Community Release build 16 (which is Nevada build 16). Because we're using build 17, our base workspace is $HOME/open_solaris/build-17; the files we download should be placed in there, and for the sake of brevity we'll refer to this directory as $OPEN_SOL in the following examples.

Install the Compiler and Other Tools

Having downloaded the necessary files, we need to install the compilers and ON build tools. The latter consists of programs and scripts that are specifically for use in building and installing OpenSolaris. The compiler and other Sun Studio tools are supplied as either a tar ball or a set of packages, while the ON build tools are supplied as a package. Note that in all of the following examples the filenames are representative of the actual ones, but they will likely be different to what we show here. For example, many of the filenames incorporate date stamps, which will obviously change from time to time.

First we'll add the ON build tools, by installing the package SUNWonbld:

#cd /tmp

# bzip2 -dc $OPEN_SOL/SUNWonbld-20050322.i386.tar.bz2 | tar xf -

# cd onbld

# pkgadd -d . SUNWonbld

# cd ..

For reasons of brevity, we've omitted the output from the pkgadd command. Also note that the actual filename of the ON build package will probably be different, as these tools are frequently updated to reflect the requirements of each build.

Next we install the tar install image of the Sun Studio compiler and other tools:

# cd /opt

# bzip2 -dc $OPEN_SOL/sunstudio10-20050613.x86.tar.bz2 | tar xf -

Having installed the compilers and tools, we to ensure that their directories are in our PATH, and create the directory in which we'll perform the actual build of OpenSolaris (note we do this as our own user rather than root, and we're back in $OPEN_SOL/build-n):

$ export PATH=/opt/onbld/bin:/opt/SUNWspro/bin:$PATH

$ mkdir testws

Modifying our login script to contain the appropriate PATH is a good idea.

Unpack the Source Code and Closed Binaries

The next step is to unpack the closed binaries and source code:

$ cd testws

$ bzip2 -dc ../opensolaris-closed-bins-20050322.i386.tar.bz2 | tar xf -

$ bzip2 -dc ../opensolaris-src-20050322.tar.bz2 | tar xf -

Build the OpenSolaris Code

We are nearly ready to build the OpenSolaris source code! A script is used to prepare the build environment; this script sets numerous environment variables, which we must customize to suit our environment. We'll make a local copy and modify it:

$ cp usr/src/tools/env/opensolaris.sh .

$ chmod 644 opensolaris.sh

We edit opensolaris.sh, changing the definitions of the GATE, CODEMGR_WS,STAFFER, and VERSION environment variables as required. We'll leave them at their default values, except for STAFFER, CODEMGR_WS and VERSION, which we'll change to "rich", "/home/rich/open_solaris/build-17/$GATE" and "OpenSolaris_build-17" respectively (obviously the value of CODEMGR_WS should be modified as appropriate).

Finally,the nightly script is used to perform the actual build (note that nightly builds everything, not just the kernel):

$ nightly opensolaris.sh

This step can take a while, so now would be a good time to find something else to do (on the author's 2 GHz Ferrari 3400 laptop, this step takes about 90 minutes to complete). When the build completes, three log files can be found in the directory log/log.mmdd (where mm is the month and dd is the day), called mail_msg, nightly.log, and proto_list_i386 (or similar). The first of these contains a copy of the email that is sent to $STAFFER upon completion, and contains a summary of the build. The second file contains a verbose log of the build process, and the last file is a prototype list which can be used to create packages (the details of which are beyond the scope of this article).

If the mail_msg file contains no errors, we no our build was successful. If it wasn't, we can examine nightly.log to determine the reason.

Installing OpenSolaris (Part One)

Assuming all is well, we can install our newly compiled bits. Because installing new bits (specifically, the kernel or critical libraries and applications) can result in brickification, we'll use the Install (pronounced "cap eye install") utility. This utility creates a tar ball of the newly-built kernel, that we can install alongside the existing one (testing on a machine other than the build one is highly recommended). Note that Install does not install the new userland bits; only the new kernel and modules are installed. Because the Install procedure does not overwrite the currently installed kernel, the risk of brickification is mitigated.

Become root and change to the workspace directory we're using (i.e., what we have previously called $OPEN_SOL). Make sure that the tools and compilers that live in /opt/onbld/bin and /opt/SUNWspro/bin are in root's PATH (or just use the commands' full path name).

The first thing we need to do is make sure that all the required environment variables are set to the correct values, by running the bldenv script:

# bldenv opensolaris.sh

The next step creates the Install tar ball, and, on the assumption that we're testing on the same machine we build on, installs it:

# Install -k i86pc -G kernel-17

# cd /

# tar xf /tmp/Install.root/Install.i86pc.tar

The -k flag for the Install command informs it what kernel architecture we're Installing, and the -G flag specifies the glomname. The latter is the name of the subdirectory in /platform/<arch> that the new kernel will go into, so in our case they will go into /platform/i86pc/kernel-17 (on SPARC this would currently be /platform/sun4u/kernel-17). If we don't specify a glomname, our newly-compiled kernel will overwrite the current one. If this leads to brickification, our only recourse is to recover by booting from alternative media.

On x86 there's one more task we must perform before booting our new kernel: once the tar ball has been extracted, we must add the name of our new kernel directory to the file /boot/solaris/filelist.ramdisk. This step doesn't apply if we're installing on the SPARC platform, because it doesn't use the GRUB boot loader.

The only thing left to do is booting using the new kernel:

# reboot -- kernel-17/amd64/unix

This example assumes the use of a 64-bit amd64 machine; for 64-bit SPARC use kernel-17/sparcv9/unix and for 32-bit x86 use kernel-17/unix.

If all goes well, the booting banner should display the string we put into the VERSION variable in opensolaris.sh:

rich@orac3559# uname -a

SunOS orac 5.11 OpenSolaris_build-17 i86pc i386 i86pc

Some machines may not be able to boot in this manner due to missing device drivers that are not supplied as part of OpenSolaris. In this event, we can try to work around this by copying the modules and drivers supplied by the base OS install into our test directory, installing the new bits on top.

Here's how we would do this:

# cd /platform/i86pc

# rm -fr kernel-17/*

# (cd kernel; tar cf - .) | (cd kernel-17; tar xf -)

# cd $OPEN_SOL

# Install -k i86pc -G kernel-17

# cd /

# tar xf /tmp/Install.root/Install.i86pc.tar

# reboot -- kernel-17/amd64/unix

If we want to install more than just the new kernel, we must use a process called BFU, which we will describe in another article. BFUing is not for the feint of heart, and is recommended only for developers who absolutely must have the latest bleeding edge bits.

Summary

In this article we defined some of the terminology we'll encounter when dealing with OpenSolaris. We also described how to obtain the source code and other bits necessary to compile it, and finally, we described the steps necessary to perform a simple compilation and installation of OpenSolaris. These steps are:

Obtain the source code, closed binaries, compilers and build tools from www.opensolaris.org or one of its mirrors.
Install the ON build tools and Sun Studio compilers into /opt and add their directories to our PATH.
Unpack the source and closed binaries tar balls.
Copy and edit the opensolaris.sh script.
Build the source code using the nightly script.
Install the resulting new kernel using the Install script.
Reboot using the new kernel.

Recommended Reading

The opensolaris.org web site contains several documents, including the OpenSolaris Developer's Reference. Also, be sure to check out details regarding the OpenSolaris Tools Community site and specifically the Sun Studio download site at /os/community/tools/sun_studio_tools/. The author's book, Solaris Systems Programming [Teer 2005], is essential for readers wishing to work with the userland OpenSolaris code, andSolaris Internals [Mauro and McDougall 2001] by Jim Mauro and Richard McDougall should be on every OpenSolaris kernel hacker's bookshelf. The community blogs at www.opensolaris.org/os/blogs/ are another great source of information.

[Mauro and McDougall 2001]: Solaris Internals, ISBN 0-13-022496-0. See www.solarisinternals.com/ for more details.

[Teer 2005]: Solaris Systems Programming, ISBN 0-201-75039-2. See www.rite-group.com/rich/ssp/ for more details.