intro

# Welcome to the illumos developer's guide!

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.

## What is 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
releases of `UNIX` and `BSD`.



## Guide Layout

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.


  * Debugging

  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).


  * Integrating Changes

  This section covers best practices around testing, getting necessary review,
  and getting changes inside of the gate.


  * Getting Help

  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.


  * Appendix: Glossary

  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

## Conventions

The following section describes the current typographical conventions used
in this document.

### Commands

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:

```
#
```

### Manual Pages

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 `read()` function
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 `libsocket` library.

See the subsection [Manual Pages](anatomy.html#manual-pages) in the Components
section for more information about man pages, including the numbering scheme.