moved to comments below
While there are many different good OSes and distributions based on common illumos kernel and contributing to its development, the OpenIndiana project remains about the most generic distribution as a most-direct ideological descendant of the OpenSolaris project, and is dubbed the reference distribution. In fact, some OpenIndiana projects are being renamed into illumos namespace these days, while the illumos project will soon use the development, organizational and building processes developed for OpenIndiana. The two projects also share some infrastructure and some of the developers.
This page aims to outline the procedure (a rough outline here with links to detailed pages in the two projects' Wikis) for newcomers to prepare a build environment, get the sources and start building illumos kernel (OS/Net consolidation) and OpenIndiana userland programs, and, hopefully, ultimately fix some bugs, code new features and contribute to the public projects.
When the fixes get upstream from individual projects (including every user's personal tinkering), everybody wins!
Prepare the Build Environment
“If you want to make an apple pie from scratch, you must first create the universe.”
-- Dr. Carl Sagan (American Astronomer, Writer and Scientist, 1934-1996)
illumos is a self-hosting effort. In order to build it, you need to install an illumos-based OS, such as OpenIndiana.
- Go to http://openindiana.org/download/ and get the current distribution image of whatever type suits you best.
The installation media is a LiveCD or a LiveUSB image of an installer (one installer with graphics desktop, another with text-mode and SSH only); there is also an Automated Installer for advanced (usually networked) setups.
NOTE that you'll likely also need internet access to install further required packages and local zones.
- Install the distro to your building machine, see Installing OpenIndiana for a reference procedure if you're new to this.
NOTE 1: There are many other ways to install (Open)Solaris-based OSes, if you're experienced and brave enough (see for example posts about Automated Installer and Networked Installation, Advanced Manual installation of OpenIndiana from LiveCD media, Experimental installation with split ROOT dataset hierarchy); however, simple standard installations work well enough and are much easier for your peers give advice on – should you need help in troubleshooting something.
NOTE 2: If you decide to use a VM environment for builds and/or tests, beware that VirtualBox has proven too slow for many developers (as of those versions that they have tested), and illumos builds took days instead of hours. It may work for you – please report if so.
- (optional) If you have free internet traffic, and plan to do many experiments, you might want to set up a mirror of OS package repositories, so that your further installations (including installs of local zones) would be local to your LAN networking.
This optional step is described in Mirroring OpenIndiana (page is being rewritten as of April 2012) and somewhat in Automated Installer and Networked Installation, and would require considerable disk space and download traffic (about 3Gb for "current" OpenIndiana packages, and 55Gb for optional "legacy" packages; few of the latter may be needed – if at all).
After some successful builds, you'll likely be running repositories of your own compiled software – that's what a successful
When your installed host OS is up and running, it is advised to create a "local zone" dedicated for builds, so as not to pollute your host's main operating environment ("global zone"). The procedure to prepare a build zone is outlined here: Building in zones.
Local zones are a lightweight virtualization technology, one of many goodies introduced by Sun Solaris 10 and OpenSolaris – a separate operating environment which runs within your host OS and has a separate set of installed software, so that the builds and subsequent tests have little impact on your main host OS, or on other local zones. Using ZFS, it is easy to snapshot the zone's filesystems, and roll back in case of major mishaps.
Being an operating environment, a local zone may have a networking setup of its own – but a dedicated IP address number from your LAN is not required. The local zone may be NATed by its global zone using etherstubs and other virtual networking components, or it may have no networking at all – but repository cloning and other networked operations would have to be run from the global zone then.
Get the Sources and Build Stuff
make world" or "
-- an innocent question like that can start a holy war elsewhere...
Source codes of illumos and OpenIndiana, as well as some other related projects, are published as "repositories" with Git (
git) and Mercurial (
hg) source-code management systems. Public copies of these repositories are hosted on a number of servers, including
hg.openindiana.org, BitBucket and GitHub; their contents are maintained by corresponding project admins with commit privileges.
Developers working with the projects' source codes clone the projects' public repositories, then they create "workspaces" as instances of their private repository, and compile the code in their workspace.
Also, when the public project moves ahead, the developer's local repository and workspace needs to be updated (or even merged) with the public changes.
People start by compiling a copy of the current public sources, but when they ultimately change some code and fix something, they would report and contribute these changes as described in the next sections.
- If you'd like to play with the illumos kernel
illumos-gate, see How To Build illumos and How To Build Components. These pages detail the setup of ZFS datasets, compilers and environment scripts needed to build the kernel, as well as running the build procedure and installing the built illumos core packages as a new boot environment on your build host or another test system. The main page also describes how to configure and run the package repository server to install your newly built kernel onto a different machine.
NOTE: The page as of now documents building of illumos in the global zone (host OS); it may soon be tested for procedural compatibility with local zones and updated accordingly.
- If you'd like to play with the OpenIndiana userland programs
illumos-userland(mostly – third-party software integrated with illumos/OpenIndiana and not part of the OS core), see Building with illumos-userland for instructions of compiler setup, getting the sources and running the build procedure and installing the results to test. Its several child pages detail the process; in particular, see Contribution Process for more details on forking your own source-code repository. See also the
docdirectory in the checked-out source code repository.
- There is also an OI-SFE ("Spec Files Extra") project for more open-source software to get packaged under Solaris and derived operating systems, including an extra repository of some software known to be patent-encumbered and of limited legal usability in certain countries:
- Your building adventures would usually create (or update) your IPS repository of packages with pieces of software. If you want to make a unitary distribution from that, there is an utility called the Distribution Constructor (it takes care of making the ISO and USB images).
NOTE: the Distro Constructor is known to work only from the global zone.
While using the OS you can stumble upon things that are inconvenient, missing or even outright don't work in your software and hardware environment. Even the small things matter, such as missing entries in man-pages, uninformative error messages returned by programs, and such.
Even if you intend to fix that problem yourself, the proper procedure starts with checking if the problem is not already known, and making sure the problem gets known. You can do that via the bug tracker (needed for contributions down the road) and/or via mailing lists (for open discussion of options, as well as to find out if somebody works on that/related/similar problem already, or can do that quest faster/better/more eagerly than you); probably both paths should be followed.
If you propose a new feature, you can post an RFE (Request For Enhancement or Feature) in the illumos bugtracker; if you think something is broken – you should post a Bug.
Note that some bugs can get rejected by the bugtracker maintainers – either because they duplicate another bug, or because the work described is deemed to be out of scope for the project (near-term or at all), and existing developers won't commit to fixing it. In the latter case, if the feature is still important for you and you would fix it yourself (or find someone who would), you're welcome to revisit the closed bug and assign it to yourself, ultimately integrating the fix as discussed below.
There are many categories (see the list of sub-projects at https://www.illumos.org/projects/ before posting), including these for illumos kernel and userland, OpenIndiana distribution, and integration of third-party software into common repositories or the distribution itself:
It may also be correct to bring attention to your proposals in corresponding Mailing Lists (see above).
There are some recommended procedures to gather information on more serious Bugs which cause program or OS crashes (kernel or program core files and an overview analysis of them) – which can greatly help developers figure out what went wrong:
"LGTM" or "+1"
-- a good response to good submissions
When you're comfortable with the building environment and it works for you, you may feel the urge to fix something in the OS, or add to it. When that works, you may want (and are encouraged) to contribute your changes to parent projects.
The process is described in more detail in pages like these:
- illumos Contribution Process: How To Contribute
- OpenIndiana Contribution Process: Contribution Process
The general procedure includes:
- marking the problem and your involvement in it via the bugtracker for a certain project, so that the problem you are fixing has a name and an issue number (check if a matching issue already exists and is perhaps being worked on by somebody else).
If you do intend to solve it yourself – assign the bug to yourself; in part, this helps avoid situations where bugs important to you are discarded (closed) by bugtracker admins as being "too vague" or "out of scope" for existing core developers;
- cloning the source code repository;
- developing a solution;
- testing that the solution works and a full compilation of the repository is "clean" (no warnings and complaints from involved compilers and other utilities);
- committing the changes to your repository and including the bugtracker issue number and name in the commit comment;
- preparing a patch report for public review (for
illumos-gatethat is automated by the webrev program; for BitBucket projects like
illumos-userlandthere is a button to calculate differences between your and original repositories);
- notify the corresponding mailing list about your fix and have some reviewers look at your changes, perhaps repairing the drawbacks they find;
- when your fixes are "LGTM"ed (looks good to me) or "+1"ed by several reviewers, request to integrate (RTI) your changes into the common public repositories via the mailing lists.
Thanks, now you are officially one of our heroes, and your name is recorded for posterity! Keep it going!