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!
“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.
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.
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.
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.
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.
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:
The general procedure includes:
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);
Thanks, now you are officially one of our heroes, and your name is recorded for posterity! Keep it going!