This document will help prepare you to build the source code for illumos. It assumes some familiarity with development on Unix-like systems.

You need an illumos-based operating system to build illumos (cross-compilation is not supported). If you don't have one installed, the quickest way to get started is to download and install OpenIndiana from openindiana.org/download, possibly into a virtual machine (compilation performance may suffer, but it is functional). Some other distributions support self-hosting, including compilation of illumos-gate, as well. If you have an existing system with OpenSolaris installed, see Updating OpenSolaris.

Note: All commands in this guide assume you run them as an unprivileged user. sudo will be prepended to commands which need additional privileges; on some systems pfexec can be used instead, if your user has the correct RBAC profiles. The generic commands below use a $USER variable to define the current (unprivileged) user account's name which will ultimately be used to compile the project. If you are not using a stock shell or have manipulated the $USER variable in your environment at a site, system, or user level, you are responsible for diagnosing and addressing any consequences.

Note: VirtualBox has proven unfit for purpose in building from source (builds can take days instead of hours) and running debug kernels (systems have problems with clock discipline and are slow or become unresponsive). If you're interested in developing for illumos, consider running on bare metal or using an alternative virtualization product (KVM, VMware, Xen).

Update (2013-06-28): Some users have reported reasonable build times with recent (>= 4.2) versions of VirtualBox on recent Apple hardware. It is as yet unknown what specifically changed to resolve the issue, but presently it appears that recent VirtualBox may be more feasible. Until we know the specifics, consider VirtualBox unsuitable or experimental at best. More testing welcome! This only applies to building illumos, and not running debug kernels.


Installing required packages

You need to install these packages in order to build illumos:

sudo pkg install -v \
 pkg:/data/docbook \
 pkg:/developer/astdev \
 pkg:/developer/build/make \
 pkg:/developer/build/onbld \
 pkg:/developer/illumos-gcc \
 pkg:/developer/gnu-binutils \
 pkg:/developer/opensolaris/osnet \
 pkg:/developer/java/jdk \
 pkg:/developer/lexer/flex \
 pkg:/developer/object-file \
 pkg:/developer/parser/bison \
 pkg:/developer/versioning/mercurial \
 pkg:/developer/versioning/git \
 pkg:/developer/library/lint \
 pkg:/library/glib2 \
 pkg:/library/libxml2 \
 pkg:/library/libxslt \
 pkg:/library/nspr/header-nspr \
 pkg:/library/perl-5/xml-parser \
 pkg:/library/security/trousers \
 pkg:/print/cups \
 pkg:/print/filter/ghostscript \
 pkg:/runtime/perl-510 \
 pkg:/runtime/perl-510/extra \
 pkg:/runtime/perl-510/module/sun-solaris \
 pkg:/system/library/math/header-math \
 pkg:/system/library/install \
 pkg:/system/library/dbus \
 pkg:/system/library/libdbus \
 pkg:/system/library/libdbus-glib \
 pkg:/system/library/mozilla-nss/header-nss \
 pkg:/system/header \
 pkg:/system/management/product-registry \
 pkg:/system/management/snmp/net-snmp \
 pkg:/text/gnu-gettext \
 pkg:/library/python-2/python-extra-26 \
 pkg:/web/server/apache-13

Installing compilers

The source code was traditionally built using Sun's closed-source compiler suite, which was named Sun Studio at the time of the illumos fork.  We now build illumos with GCC, but you will still need some tools from Sun Studio and those are available as packages in the legacy OpenSolaris repository.

GCC

The primary version of GCC necessary for development and integration 4.4.4 (4.4.4-il-3) should have been installed on your system when you installed the prerequisites above.  If for some reason that didn't happen (old build system, or the like), tarballs are available as described in the initial heads-up notice  2012-06-15 Illumos will now build with GCC 4.4.4 + patches.

Note that the compiler for building illumos-gate installs into /opt/gcc/4.4.4 and is not available in the default PATH for building application programs. You can add PATH="/opt/gcc/4.4.4/bin:$PATH"; export PATH to your profile to reference this compiler, or install one of the other GCC builds, destined as the current default compiler for application programs (versions ranging from 3.4.3 to 4.6.x, see pkg info -r '*gcc*' for details du-jour).

Unfortunately, Sun Studio dmake (Distributed Make) and lint are currently required even for GCC-only builds. We currently deliver Lint libraries built using the closed Sun Studio version of lint.  The lint from the unpatched (but redistributable) version of Sun Studio 12.1 in the opensolaris.org repository can be used, regardless of its utility for actually checking the software.

Run:

sudo pkg set-publisher -g http://pkg.openindiana.org/legacy opensolaris.org
sudo pkg install pkg:/developer/sunstudio12u1

Sun Studio compilers

If you wish to build with Sun Studio, you need specifically patched versions of both Studio 12 (used to compile) and 12.1 (used for lint) to get consistent results. These are no longer distributed by Oracle and can not be legally found in the open Internet. If you do not have access to these versions, skip this section and use GCC.

illumos-gate does not build correctly with Sun Studio versions released after 12.0. Reportedly using a newer version of the compiler will produce a system containing grave, data-corrupting bugs.  Patched compilers were previously available from Sun Microsystems, however not licensed for redistribution. After a recent Oracle site reorganization, the necessary compilers are no longer available.

If you have the patched versions of both Sun Studio 12 and 12.1, they should be installed in /opt/SUNWspro (Studio 12), and /opt/SUNWspro/sunstudio12.1 (Studio 12.1), respectively. Pay attention, the Studio 12.1 location is different from how it was in OpenSolaris, i.e. it's not /opt/sunstudio12.1.

The meta-procedure for cleaning up optionally prepackaged Sun Studio installations and installing the ones you require for building illumos (assuming your stashed Sun Studio 12 distribution archives are now pre-copied to /tmp) is as follows:

sudo pkg uninstall \
    pkg:/developer/sunstudio12u1 \
    pkg:/developer/sunstudioexpress \
    pkg:/sunstudioexpress \
    pkg:/ss-dev

sudo mkdir -p /opt/SUNWspro
cd /opt/SUNWspro
sudo tar xjf /tmp/sunstudio12-patched-ii-2009Sep-sol-x86.tar.bz2
sudo tar xzf /tmp/sunstudio12u1-patched-ii-2010Feb-sol-x86.tar.gz

The first archive contains the product component sub-directories directly at the top-level, and the second has similar sub-directories under the top-level sunstudio12.1 as its children. Thus you receive the structure outlined above.

You can check if you have the correct versions installed as follows. All of the following tests must succeed and return these specific product/patch versions:

$ /opt/SUNWspro/bin/cc -V
cc: Sun C 5.9 SunOS_i386 Patch 124868-10 2009/04/30
usage: cc ...

$ /opt/SUNWspro/sunstudio12.1/bin/cc -V
cc: Sun C 5.10 SunOS_i386 Patch 142363-03 2009/12/03
usage: cc ...

$ /opt/SUNWspro/sunstudio12.1/bin/lint -V
lint: Sun C 5.10 SunOS_i386 Patch 142363-03 2009/12/03
usage: lint ...

You must then adjust your nightly(1) environment file (i.e. by adding a line in illumos.sh) to specify that Studio should be used as the default compiler, by adding:

export __SUNC="";

Building illumos

Preparing the source-code directory

You can use any location, but for the purposes of this guide, we will assume that you have a directory /code owned by your user ID, which you are using to obtain source and build.

For a less naive example, see the Build datasets page and some more industrious details on Managing multiple workspaces and Working on several bugs at once.

Getting the source

You may use the Git or Mercurial source code management systems to retrieve the illumos source code. Both tools will be able to retrieve the same history. Ensure about 6 gigabytes of free space for the source and binaries combined.

Note that currently the origin of illumos-gate development is the GitHub repository (or its easily created forks) used by one or another distribution, such as OpenIndiana Hipster; some other distros, like OpenIndiana Dev releases, still use Mercurial as the main repository but may migrate to Git in the future.

Getting the source with Git

The repository is available from GitHub using the Git source code control system.

The Git repository URI is: git://github.com/illumos/illumos-gate.git

Or, if the Git protocol is firewalled at your site: https://github.com/illumos/illumos-gate.git

The illumos-gate source can then be cloned using:

cd /code
git clone git://github.com/illumos/illumos-gate.git

Getting the source with Mercurial (hg)

illumos.org hosts a Mercurial repository containing the illumos source code.

The Mercurial illumos-gate URI is:

Additional Mercurial mirrors:

Mercurial pulls a complete replica (clone) of the repository, including all history, from a remote source, and then updates a working copy of the files from this clone. The working copy is the files you may edit and compile. You may update the working copy from any versions of files in the repository history.

When cloning an external source code repository, Mercurial starts by creating a new directory, and fails if one already exists and is not empty. The directory may be a mountpoint for an empty ZFS dataset. Mercurial creates a .hg directory under this to store the repository history. After the history has been fully populated, a working copy of the files is deposited in the parent directory.

The following example creates a clone of the "Mercurial repository" ssh://anonhg@hg.illumos.org/illumos-gate containing the illumos source code under /code; this will create a sub-directory illumos-gate under that.

cd /code
hg clone ssh://anonhg@hg.illumos.org/illumos-gate
Updating the source with Mercurial

If you want to get latest version of illumos-gate merged with your private development code, you need to hg pull new changes into your clone and hg update the working copy. This can be done in one command as hg pull -u. If you have committed changes prior to updating, you may be wish to hg merge them with the new changes.

For more details see: http://mercurial.selenic.com/wiki/FAQ.

There is also a simple script to update the repository.

Getting closed binaries

There are still closed components in illumos that have not yet been replaced. You must get the latest closed binaries from Sun/Oracle, since illumos currently needs those in order to build:

cd /code/illumos-gate
wget -c \
  http://dlc.sun.com/osol/on/downloads/20100817/on-closed-bins.i386.tar.bz2 \
  http://dlc.sun.com/osol/on/downloads/20100817/on-closed-bins-nd.i386.tar.bz2
tar xjvpf on-closed-bins.i386.tar.bz2
tar xjvpf on-closed-bins-nd.i386.tar.bz2

Note that if you had a crypto tarball from an earlier build, do not use it here, as it is no longer required to build illumos. You should remove it from your tree if already present.

According to the gcc-4.4.4-il heads-up note, the kernel modules among the closed binaries might need some fixup for proper compilation. According to several developers, however, they've never needed to do this in practice. Just in case you are trying to build some older branch of illumos which might require this modification and inexplicably breaks without it, the steps are outlined below in the troubleshooting section.

Preparing the build environment

General build configuration

The build is configured using a shell script with environment variables, a template for this file is included:

cp usr/src/tools/env/illumos.sh .
vi illumos.sh       # or your favourite editor instead of @vi@

The settings we are going to focus on for now are the following:

ImportantONNV_BUILDNUM specifies the build number which is used in packaging. If you intend to upgrade a system whose build number is greater than the one in illumos-gate (currently 148), such as OpenIndiana, you need to specify this to allow upgrades until issue #1118 is addressed. Run:

pkg info osnet-incorporation | grep Branch:

If you see, for example, "Branch: 0.151.1", you must choose a number greater than the part after the leading "0.". For example, add

export ONNV_BUILDNUM=152

to the illumos.sh script.

Building with only GCC-4.4.4-il (i.e. without using Sun Studio at all)

If you are building with solely GCC 4.4.4 (i.e. you do NOT wish to use Sun Studio at all), you must append these lines to the end of illumos.sh:

# The following are added to build without Sun Studio
export CW_NO_SHADOW=1
export ONLY_LINT_DEFS=-I${SPRO_ROOT}/sunstudio12.1/prod/include/lint
export __GNUC=""
#unset __SUNC

This should suffice for compilation of modern illumos-gate sources executed on a modern distribution. Older branches (circa 2012) might need some more setup which, along with explanation of the options, can be found below in the troubleshooting section.

We understand that the required version of Sun Studio is no longer publicly available and will accept contributions that were tested only with GCC.

 

Starting the build

You are now ready to start the illumos build.

Since this process may take up to several hours depending on your system (reference build times are in a chart below), it may be wise to start the build job in a VNC session, GNU Screen (screen), or tmux. The screen program can be installed with the pkg:/terminal/screen package.

Run the following command to start the full build:

cd /code/illumos-gate
cp usr/src/tools/scripts/nightly.sh .
chmod +x nightly.sh
time ./nightly.sh illumos.sh

Note that the command does not give any progress output. You can instead follow the log file at log/nightly.log, which is updated (slowly) during the build process. In another terminal, run:

tail -f /code/illumos-gate/log/nightly.log

To only track the running build for warnings and errors you might instead run:

tail -F /code/illumos-gate/log/nightly.log | gegrep -A5 -B5 '(error|warning).*: '

After the build is complete, the nightly.log file and some other generated logs are moved into a uniquely named subdirectory log/log.$TIMESTAMP/ (i.e. /code/illumos-gate/log/log.2012-04-20.04\:17/ ).

A dry overview of the build progress (hopefully small – about 2KB in size – with no errors) is saved in log/log.$TIMESTAMP/mail_msg file intended for mailing to the build administrator after the build completes (this automation is out of the scope of the nightly.sh script). If you do receive any errors in the mail_msg report file, you can grep the error lines in the larger nightly.log file.

Performing an incremental build

If you've made changes after completing a nightly build, you can perform an incremental build without discarding the already built files.

cd /code/illumos-gate
./nightly.sh -i illumos.sh

To make this the default, edit illumos.sh and add the character i to NIGHTLY_OPTIONS.
Before submitting a patch, we request that you perform a full, non-incremental build including the lint stage.

Building specific components, and other info

Installing built software

Installing the nightly build on local machine with onu script

The build process will generate updated packages. Depending on the NIGHTLY_OPTIONS variable in illumos.sh script, the packages will be written either to $PWD/packages/i386/nightly (with debug, the typical default) or to $PWD/packages/i386/nightly-nd (without debug). Therefore there are two possible commands to install the software you you just built. You need choose the proper onu command, typically the first one listed below.

Typical install: you can install with onu for debug builds (the default, with 'F' and 'D' characters in NIGHTLY_OPTIONS variable in illumos.sh):

$ sudo ./usr/src/tools/scripts/onu \
    -t nightly-`date +%Y-%m-%d` -d $PWD/packages/i386/nightly

The non-typical installs are detailed in the following pages:

Possible problems

In any case, if you have build errors or other "inconsistencies", it would be wise to revise the mail_msg logfile that can contain short error descriptions, and grep for those errors in the longer nightly.log file. If that doesn't help, you should also recreate the build in a "clean lab" environment, which may be set up as a local zone according to the Building in zones instructions and rule out the local environment's influence (conflicting libraries and binaries, perhaps from your own earlier builds, come to mind first).

Localization bugs #167 and #168

illumos has entirely different localization infrastructure from Solaris, so your existing system locales will not work.

The English locales for illumos are in pkg:/locale/en (NOT pkg:/system/locale/en), and if you wish to use them, you'll need to install that package after you reboot. Likewise, other locales are in pkg:/locale/<language code> where <language code> is a two letter ISO 639-1 code, except for zh_cn/zh_hk/zh_mo/zh_sg/zh_tw.

If your locale is not installed, it will cause problems with software which behaves badly if setlocale() fails. This includes, at least, time-slider and svcs(1M). The pkg(5) commands print a warning, but function normally.

If this is a problem, you can  "export LANG=C LC_ALL=C" as a workaround, and change the LANG setting in/etc/default/init to 'C' (and reboot) to make the change permanent.

Package repository (path /code/illumos-gate/packages/i386/nightly/repo.redist) is not created and onu script fails

This error has happened to me whenever I ran the default checkout and full-build procedure outlined above (in VirtualBox VMs); I don't yet know why (possibly due to a wrong setup of my SunStudio compiler stack, as was later discovered).
However, rerunning with an incremental build has created the package repository correctly (as well as full builds with proper SunStudio setup):

./nightly.sh -i illumos.sh

Fixing the closed binaries for GCC-4.4.4-il

According to 2012-06-15 Illumos will now build with GCC 4.4.4 + patches the closed binaries should be fixed for compilation of illumos-gate with the newer gcc-4.4.4-il compiler. However, several developers stated that they've never needed to do this for current versions of illumos-gate (as of March 2014).

Just in case, the command to run is:

cd /code/illumos-gate && \
   cd closed && find . -type f | grep '/kernel/' | grep -v '\.conf' | \
   while read F; do echo "=== $F" && mcs -d -n .SUNW_ctf "$F"; done

Ensuring a build with only GCC-4.4.4-il for older branches of illumos

Current illumos-gate (as of March 2014) should compile cleanly with GCC with the simplified instructions above. However, some earlier versions of the gate needed more configuration steps to compile properly, and the settings below shouldn't break anything for the newer source code as well (wink)

If you are building with solely GCC 4.4.4 (i.e. you do NOT wish to use Sun Studio at all), you must append these lines to the end of illumos.sh:

# The following are added to build without Sun Studio
export CW_NO_SHADOW=1
export ONLY_LINT_DEFS=-I${SPRO_ROOT}/sunstudio12.1/prod/include/lint
# The following select the proper version of GCC
__GNUC=""; __GNUC4=""; export __GNUC __GNUC4
GCC_ROOT=/opt/gcc/4.4.4; export GCC_ROOT
CW_GCC_DIR=${GCC_ROOT}/bin; export CW_GCC_DIR

Explanation of these settings:

The last two lines make sure the patched version of GCC-4.4.4 is used (the default gcc version shipped with e.g. earlier OpenIndiana, gcc-3.4.3, is not suitable for building illumos), as described here.

If you are trying to build with GCC 4.4.4 and your build fails because of some invalid GCC warning options, try setting the variables GCC_ROOT and CW_GCC_DIR as shown above and described here.

While recently rebuilding a historical 2012 version of illumos-gate with GCC-4.4.4-only setup per instructions above, I've still got Sun Studio errors in my mail_msg file like:

< cw: error: couldn't run /opt/SUNWspro/bin/CC (No such file or directory) 
< cw: error: couldn't run /opt/SUNWspro/bin/cc (No such file or directory) 

 or more frightening:

< ln: cannot access /code/illumos-gate/proto/root_i386/usr/lib/isaexec 

 However, the files in proto/ and packages/ were created successfully. So... even error reports may need manual verification before panic and frantic fixes (wink)

Build times