OpenSolaris

  subsites   code review   repo   packages   bugs   defect   polls   planet
You are not signed in. Sign in or register.

1 Introduction

Welcome to OpenSolaris!

This guide is intended to provide developers with comprehensive information about working with OpenSolaris tools and sources. This chapter provides a brief overview of what OpenSolaris is and provides pointers to additional information.

1.1 Overview

This chapter serves as an introduction both to OpenSolaris and to the guide itself. Because much of the information in the guide will change over time, we always recommend reading the latest version. Section 1.2 covers where you can find the current guide and other documents, and additional resources including answers to common questions, ways to contact other developers, and information about the sources. While we strongly recommend reading the parts of this guide that are relevant to your interests, it is not necessary in order to participate. See section 1.3 ``Quick Start'' for ways you can start working with OpenSolaris right now. Section 1.4 details the typographic conventions used in the rest of this guide.

This guide currently has a fairly strong focus on the OS and Networking (ON) consolidation. Expect similar information on other consolidations to be integrated here over time.

1.2 Getting Help

The OpenSolaris web site offers numerous ways to find answers to your questions. A set of technical and non-technical frequently asked questions is maintained at http://opensolaris.org/os/about/faq/. A larger and more in-depth set of technical documentation is maintained at http://opensolaris.org/os/community/documentation/.

If your question is not answered in the FAQs or in any of the documentation, or you don't know where to look, you can ask using the mailing lists of fora. There are many available; for a current list of discussions and to sign up, see http://opensolaris.org/os/discussions/.

If you are having difficulty using the OpenSolaris web site itself, please send a message to mailto:webmaster at opensolaris dot org. Note that this address should not be used for technical questions about OpenSolaris itself.

Finally, if you have any questions or comments about this document, please send a message to or join the OpenSolaris docs discussion at http://opensolaris.org/os/community/documentation/discussions/.

You can always find the latest version of this document at http://opensolaris.org/os/community/onnv/devref_toc.

1.3 Quick Start

This section bypasses most of the important material you'll find later in this document and makes a lot of assumptions about your development and build environment. The intent is to offer a set of step-by-step instructions that will help you begin development in less than an hour, even if you have no previous Solaris development experience. Although this procedure will work for most people, it cannot work for all. There are dozens of tools and utilities used in developing OpenSolaris, and most have at least a few options and arguments. This tremendous flexibility exists for a reason: each developer has unique needs. If you encounter difficulty in following these instructions, don't give up! Each instruction lists the relevant sections you can read to learn more about the commands and procedures used in that step. If all else fails, please see 1.2 Getting Help to learn about the many resources available to the OpenSolaris developer community.

1.3.1 Example Environment

The instructions in the remainder of section 1.3 cover building and installing on both x86 (32-bit only or 64-bit capable; there are no differences) and SPARC environments. They have been tested and verified to work. Because it is impossible to test on every imaginable hardware, software, and policy configuration, our testing was limited to the environments described here. While we expect these instructions will be broadly applicable, the more similar your environment is, the more likely you will be able to use them without modification.

1.3.1.1 x86 Environment

We assume that the entire system is dedicated to an OpenSolaris-based distribution, such as Solaris Express. Our test machine is a dual Intel Pentium 4 Xeon 2.8 GHz with hyperthreading enabled, 512MB memory, a standard ATA controller, and a Broadcom 57xx ethernet adapter. The machine has 2 40GB ATA disks, partitioned as follows:

Both c0d0p0 and c1d0p0 have a fdisk single partition which assigns the entire disk to Solaris.

 c0d0s0 contains a 35GB UFS filesystem mounted on /.
 c0d0s1 contains a 2GB swap space.
 c0d0s8 is a 1MB boot slice.
 c1d0s0 contains a 37GB UFS filesystem mounted on /aux0.

Your system does not need to be identical or even similar to this one in order for it to work; this configuration is merely an example of a supported system. Please see 2 Prerequisites for more information about the requirements for installing, developing, and building parts of OpenSolaris. Some consolidations may have additional requirements, so be sure to consult the latest release notes.

1.3.1.2 SPARC Environment

Our SPARC test environment is a Sun Fire V210 server with 2 1.0 GHz UltraSPARC-IIIi CPUs and 2 GB memory. The machine has two 36GB SCSI disks, partitioned as follows:

 c1t0d0s0 contains a 8GB UFS filesystem mounted on /.
 c1t0d0s1 contains a 4GB swap space.
 c1t0d0s3 contains a 22GB UFS filesystem mounted on /export1.
 c1t1d0s0 contains a 35GB UFS filesystem mounted on /export2.

Your system does not need to be identical or even similar to this one in order for it to work; this configuration is merely an example of a supported system. Please see 2 Prerequisites for more information about the requirements for installing, developing, and building OpenSolaris.

1.3.2 Installing a Binary Distribution

Before building your own source or installing the provided binary archives, you will have to install a complete OpenSolaris-based distribution. This is because you most likely will need drivers, packaging tools, and other components that aren't in the Operating System and Networking components released with OpenSolaris. As of this writing, the only distribution on which OpenSolaris binaries can be built or installed is Solaris Express, build 22 or newer.

If you are an ON developer and want to run the very latest bits or have made changes to the kernel or core libraries, you will also need to update your system to a set of binaries newer than the latest available build of your distribution. The process for doing this is called BFU and is described in detail below. The BFU process uses CPIO the archives manpage containing the binaries built from ON; you can download these archives at http://opensolaris.org/os/downloads/on/ or you can build them yourself (if you have made large changes to the system, you will be install those you built yourself). If your interest in making changes is limited to simple user-level applications, you can usually get by by building those applications individually and copying them over the system's existing binaries rather than BFUing.

Both parts of this process - the initial system install (sometimes referred to as the suninstall manpage to distinguish it from BFU and especially Install) and BFUing are documented here; all users and developers will need to perform the steps described in 1.3.2.1 Installing an OpenSolaris-based Distribution (Solaris Express), while only developers interested in using the very latest ON bits or making significant modifications to core system components will need to read 1.3.2.3 Upgrading to the Latest Bits.

As new distributions are created which can be used as a base for building and installing OpenSolaris bits, each will have its own section below similar to 1.3.2.1. If your favorite distribution isn't mentioned here, please contribute a section explaining how to install it.

1.3.2.1 Installing an OpenSolaris-based Distribution (Solaris Express)

The Solaris installation procedure is well documented at http://docs.sun.com/app/docs/coll/1236.1. While most of the default options presented in the interactive installation procedure are acceptable for creating a development or build system, you should take note of the following:

Locales are not needed.
You do not need to install any locales unless you need them for other reasons. Selecting the C (POSIX) locale as default is recommended.

Follow local policies,
Network configuration, time zone, use of IPv6 and Kerberos, name service, and other environment-specific parameters must be set according to local policy. OpenSolaris development is not directly affected by them.

Reserve space for sources (and optionally builds).
To install the sources, you will need at least 300MB of free space (more is recommended). If you also wish to build OpenON, you will need several GB. It is recommended that you create a separate local filesystem to store these sources and objects as well as user home directories and other standalone data if appropriate to your configuration; our example system mounts this filesystem at /aux0. See 2.1 Hardware for more detailed information.

Install the Entire Distribution package cluster.
If you do not have enough disk space to install the Entire Distribution, you will need to upgrade to a disk at least 9GB in size. You may also be able to install the Developer package metacluster instead, but this has not been tested and may not be sufficient to build successfully. See 2.2 Operating Environment Packages for more information on software requirements.

1.3.2.2 Installing Required Tools

There are two sets of tools required to build OpenON: compilers and ON-specific build tools. See 2.3 Obtaining and Installing Compilers and 2.4 Obtaining and Installing Custom Tools for detailed information. Here we assume you want to use the Studio 10 compiler (you cannot yet use Studio 11 to build OpenON). Note that many of the ON build tools are also used by other consolidations, including SFW and Network Storage (NWS).

Download the installed image (not the full product) into a scratch area, such as /var/tmp. The file is normally called sunstudio10-DATE.PLATFORM.tar.bz2. Before you start, be sure you have at least 900MB free in /opt. You can do this by examining the output of:

 $ df -klh /opt
 Filesystem             size   used  avail capacity  Mounted on
 /dev/dsk/c1t0d0s0      7.9G   3.8G   4.0G    50%    /

If the 'avail' field is 900M or larger, you have enough space to continue.

 $ su
 Password:
 # cd /opt
 # bzip2 -dc /var/tmp/sunstudio10-20050614.sparc.tar.bz2 | tar xf -

Note that your filename may differ slightly depending on your platform and future compiler releases.

Next, download the ON-specific build tools. This file is normally called SUNWonbld-DATE.PLATFORM.tar.bz2 and contains a SVR4 package. Assuming you downloaded it to /var/tmp, you'll now want to do:

 $ cd /var/tmp
 $ bzip2 -dc SUNWonbld-DATE.PLATFORM.tar.bz2 | tar xf -
 $ su
 Password:
 # pkgadd -d onbld SUNWonbld

Note that if you have installed a previous version of the tools, you will need to use pkgrm(1m) to remove them first.

Once you have installed your distribution, the compilers, and ON-specific build tools, you're ready to build from source or install from binaries. If you're building from source, continue on to the next section. Otherwise, skip ahead to 1.3.4 Upgrading to the Latest ON Bits.

1.3.3 Building ON from Source

1.3.3.1 Creating a Source Workspace

Suppose you are using /aux0/testws as your workspace.

First, cd to /aux0/testws and unpack the sources and closed binaries, e.g.,

 $ mkdir /aux0/testws
 $ cd /aux0/testws
 $ bzip2 -dc opensolaris-src-DATE.tar.bz2 | tar xf -
 $ bzip2 -dc opensolaris-closed-bins-DATE.PLATFORM.tar.gz | tar xf -

The sources will unpack into usr/src and the binaries will unpack into closed/root_PLATFORM (i.e., closed/root_i386 or closed/root_sparc).

1.3.3.2 Performing a Basic Build

First, Create an environment file to guide tools like nightly(1) and bldenv(1).

  • Copy in the template environment file
    • Copy /aux0/testws/usr/src/tools/env/opensolaris.sh to /aux0/testws. It doesn't have to go in /aux0/testws, but that's a convenient place to put it. Nor do you have to keep the name opensolaris.sh, but that's the name we'll use in these notes. 
     $ cp /aux0/testws/usr/src/tools/env/opensolaris.sh /aux0/testws

  • Make required changes
    • First, add /opt/onbld/bin to your PATH environment variable. You may wish to make this change permanent by editing your .login or .profile files (as appropriate for your shell).

    Then, using your favorite text editor, make the following changes to opensolaris.sh:

    Change GATE to the name of the top-level directory (e.g., testws).

    Change CODEMGR_WS to the top-level path (e.g., /aux0/testws).

    Change STAFFER to your login.

  • (optional) Customize VERSION.
    • VERSION is the string that ``uname -v'' will print.

Then, To build a complete set of BFU archives, cd to /aux0/testws, utter

 $ nightly ./opensolaris.sh &

and find something else to work on for a few hours. You can monitor the build's progress using ptree(1). nightly(1) will send mail to $MAILTO when it has finished. The mail will have an overview of the build results. A copy of the mail text and a more detailed log file will be available in the workspace (e.g., /aux0/testws/log/log.MMDD/nightly.log, where MMDD is the build date). The log file is also available (in a slightly different location) during the build; to monitor the progress of your build in real time, you can do:

 $ tail -f /aux0/testws/log/nightly.log

The location of the log is controlled by the LOGFILE and ATLOG variables; see nightly(1) for more details.

If your build fails, you can correct the problem, then use the '-i' option to nightly to run an incremental build, bypassing the initial clobber. See the nightly(1) manual and 4 Building OpenSolaris for more information.

To build a specific component, first use bldenv(1) to set up various environment variables, then cd to the subtree that you want to build. For example:

 $ cd /aux0/testws
 $ bldenv ./opensolaris.sh
 [status information from bldenv]
 $ cd usr/src/cmd/vi
 $ dmake all

To build the kernel, run dmake(1) from usr/src/uts.

See 4 Building OpenSolaris for more information on the build process and tools. Once you have successfully completed a build, see 5 Installing and Testing ON for more information on what to do with it.

1.3.4 Upgrading to the Latest ON Bits

WARNING! The steps described in this section are optional for advanced developers only and are not required to view and edit the sources. Performing this process unnecessarily will result in reduced system manageability and exposes you to the greater risks associated with the use of development software. If in doubt, SKIP THIS STEP. See 5.3 Using BFU to Install ON for more details on the risks and benefits of this process.

If you wish to build one or more OpenSolaris consolidations, you may in some cases be required to update all or part of your system's software before doing so. Such requirements are listed for each build in the relevant consolidation's release notes; in most cases your existing installation will be sufficient to build and use the latest sources. In general, it is both safer and more effective to use the official suninstall, upgrade, or LiveUpgrade process to install a more recent Solaris Express build than to use the BFU process; the official upgrade upgrades all of your system software, while BFU upgrades only a few parts. Unless you need to use the very latest ON bits, you should skip this step.

Before proceeding, please read 5.3 Using BFU to Install ON in its entirety. The remainder of this section provides an example usage of bfu(1), but you must understand how BFU works, what BFU conflicts are, and how to resolve them before you can successfully use BFU. It's impossible to overemphasize this: You almost certainly want to let acr(1) resolve conflicts for you. Resolving conflicts by hand can be difficult, time-consuming, and error-prone. Errors in conflict resolution will often leave your machine in a nonworking state. We assume here that you will be resolving conflicts automatically.

First, download the BFU archives for your system architecture from http://opensolaris.org/os/downloads/on/. Then, unpack the archives into a temporary directory of your choice. In this example, we will use /var/tmp/bfu to store the archives and LATEST to be the build you want to install.

 # mkdir /var/tmp/bfu
 # cd /var/tmp/bfu
 # bzip2 -dc /path/to/opensolaris-bfu-LATEST.sparc.tar.bz2 | tar xf -

This will create the directory and /var/tmp/bfu/archives-LATEST/sparc. In it will be a set of CPIO archives; these are used by bfu(1) to overwrite your system binaries. Next, exit the window system, log in on the console as root, and issue the command:

 # /opt/onbld/bin/bfu /var/tmp/bfu/archives-LATEST/sparc

You may see warnings about upgrading non-ON packages; if you have not already done so, you will need to upgrade these before you can safely use BFU. If BFU fails because it tries to upgrade a package that is not available, please check the release notes for your build for information on the cause and solution to the problem. If you don't find what you need, send a message to mailto:opensolaris dash help at opensolaris dot org describing the messages and the circumstances.

After BFU completes, you must resolve conflicts in configuration files The BFU will complete, and if successful will leave you with some warnings and a bfu# prompt. YOU ARE NOT DONE! You must now resolve conflicts and reboot:

 bfu# acr

If acr fails or prints out warnings or errors, you will need to resolve conflicts manually before rebooting. See <5.3 Using BFU to Install ON> for full details. Otherwise, reboot:

 bfu# reboot

As your system comes up, note the new kernel version. The ON bits on your system have been upgraded.

1.3.5 Mini-Projects

These activities are intended to help developers gain familiarity with the OpenSolaris tools and environment while at the same time making useful contributions toward meeting their own needs and those of the community. We hope that by engaging in some of these mini-projects, new developers will be exposed to OpenSolaris from a variety of directions and will find inspiration for new improvements in the large body of existing work. The project suggestions are roughly ordered from simplest to most complex; less experienced developers should find the first several projects to be a good introduction to OpenSolaris, while more experienced developers may wish to take on some of the more challenging tasks. Of course, all of these are only suggestions; you are always free to work on any part of the system you wish. We ask only that you utilize the mailing lists to coordinate your activities with others to reduce duplication of effort.

  1. Start a blog
    2. Many developers keep notes, bookmarks, pointers to useful documentation, and other historical materials in a notebook or journal. As you become more familiar with OpenSolaris, your notes and experiences along the way will be valuable to you and to others in the community. You can create your own blog at any of a number of free blogging sites. Suggestions for topics include any observations you make, difficulties you encounter, or ideas you dream up for improving OpenSolaris. Writing about your ideas and experiences in your blog forms a focal point for wider community involvement and discussion, filing of bugs or RFEs, or the creation of a new development project.

  2. Fix a simple bug
    3. Many bugs we track in OpenSolaris are low-priority issues that have remained unfixed over a long period of time; they are not especially difficult to fix, and their effects tend to be annoying rather than catastrophic. We have also identified bugs which are easily fixed with the 'oss-bite-size' keyword, so that new developers can obtain up to date starting points.

    You can view information about these bugs and search for bite-sized bugs at http://bugs.opensolaris.org.

  3. Enhance cstyle(1)
    4. Improve the automated C/C++ style checking tools cstyle(1) and hdrchk(1) to implement more of the style guide requirements. For example, cstyle(1) could be improved to detect poor declarations of initialized variables. See 7.2.1 Automated Style Tools for more information.

  4. Clean up and modernize code
    5. Make more commands and libraries lint-clean. Although the entire kernel (uts/...) lints without warnings, many commands and libraries are excluded from linting because they contain lint errors. Correcting these errors is usually not difficult; start by enabling lint (see 3.3.3 Modifying the ON Build System) and re-linting the command or library in question. In some cases it may be difficult or impossible to fix a particular lint error, and that error must be disabled instead. You can discuss such situations on the relevant mailing list.

  5. Simplify Install(1) usage
    6. Improve Install(1)'s '-i' option to use official platform names in addition to code names when building kernel packages for specific platforms. See 5.2 Using Cap-Eye-Install to Install Kernels for more information.

  6. Fix something that bothers you
    7. Search for and fix a bug in a program you use frequently, or that you have noticed yourself. You can search for bugs at http://bugs.opensolaris.org. Many bugs may already be undergoing fixes, so you should avoid duplication of effort by mailing mailto:request dash sponsor at opensolaris dot org when you start working on a bug fix. The sponsors make sure nobody else is working on the bug, and help you make sure you follow the right process to get your fix integrated.

1.4 Conventions

The typographic conventions for this document are not yet finalized. As the document grows and improves it will eventually be typeset in multiple formats, and each will have specific conventions. Information about those conventions goes here.