Welcome to illumos! We're excited that you're interested in doing work on this project. This guide covers the basic workflow for developing illumos and then dives into specific detail on everything from the layout of the gate to several HOWTOs. Whether this is your first time working with illumos or you remember back when the code in the gate all referred to something called SunOS, this guide will help you in enhancing and fixing illumos.
illumos is a collection of software that forms the core of an Operating System. It includes the kernel, device drivers, core system libraries, and utilities. Conceptually, the illumos idea of "the operating system" lies between something like Linux (which is the kernel only; all of userspace is delivered by vendors in a "distribution") and the BSD family of operating systems, which are packaged as a complete unit (kernel, core libraries, userspace utilities, and even end-user software packages).
illumos is the home of many technologies including ZFS, DTrace, Zones, ctf,
FMA, and more. We pride ourselves on having a stable, highly observable, and
technologically different system. Finally, illumos has a proud engineering
heritage, tracing it roots back through Sun Microsystems to the original
This guide is broken into the following sections:
Basic illumos workflow
This section aims to get a new developer up and building illumos. It covers what to do from first clone through putback. If you're just getting started with illumos, this is where you should start.
illumos Guidelines and Principles
This section covers various core guidelines we have when working inside the illumos gate. It also goes into detail about several of the guiding engineering principles that have brought this project from its time at Sun through to today.
Source Tree Layout and Makefile System
This walks through the layout of the source tree. This covers where different components live and the general design of the illumos source tree as well as an introduction to the Makefile structure and top level targets in the tree.
Component Anatomy, Creating and Modifying Components
This sections covers working in specific components of the kernel. It first covers the anatomy of different libraries, commands, kernel modules, and device drivers. It then builds on top of this and discusses how to modify existing ones as well as how to create new ones. Makefiles, dealing with 3rd party source code, CTF data, and other issues that come up when building new components.
And then it all went terribly wrong -- processes core dumping and operating systems panicking. Don't panic! This section introduces you to tools and techniques for investigating such problems and help you along the road to root causing such issues. It also briefly discusses how to control the generation of such dumps as well as introducing system tools like mdb(1) and dtrace(1m).
This section covers best practices around testing, getting necessary review, and getting changes inside of the gate.
This section covers where to go with questions and how to get additional help on working with illumos, this document, or anything else that might come up.
This section provides a reference to acronyms and other terms that are used in this guide, and either unique to illumos (and related operating systems), or that may be unfamiliar to those who have not previously done UNIX systems development.
Appendix: Documentation License
The following section describes the current typographical conventions used in this document.
Fixed-width text beginning with a dollar sign indicates a shell command that should be run as a normal user:
Fixed-width text beginning with a hash mark indicates a shell command to be executed by the super-user's shell:
When you see text formatted as
name(number), that indicates a reference to
the command named
name in section
number of the manual. When they appear
in this developer's guide, there should be a hyperlink to the appropriate
manual page. For example, read(2) refers to the
in section 2 of the manual, while ctf(4) refers to the manual page on the CTF
file format, which is section 4. Manual sections may have a sub-descriptor
after the number: connect(3SOCKET) describes the
connect() function that
can be found in the
3SOCKET section of the manual; this section describes
functions that are a part of the
See the subsection Manual Pages in the Components section for more information about man pages, including the numbering scheme.