Chapter 1. Introduction

Welcome to OpenSolaris and the OS/Net (ON) consolidation!

This guide is intended to provide developers with comprehensive information about working with the ON consolidation. This chapter provides a brief overview of OpenSolaris and ON, and it 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 Getting Help 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 ON right now. Section 1.4 Conventions details the typographic conventions used in the rest of this guide.

The OpenSolaris code base is organized as several consolidations. Each consolidation is built as a unit and has its own conventions and processes. The ON consolidation covers the kernel, basic commands and daemons, system libraries, and system headers. Other consolidations include SFW, X, and OpenSolaris Desktop.

The OpenSolaris distribution is built from this code base. It and other distributions are available from http://opensolaris.org/os/downloads/.

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 webmaster@opensolaris.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 ON discussion at http://mail.opensolaris.org/mailman/listinfo/on-discuss.

You can always find the latest version of this document at http://opensolaris.org/os/community/on/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 ON, 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 Section 1.2 Getting Help to learn about the many resources available to the ON 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 Chapter 2 Prerequisites for more information about the requirements for installing, developing, and building parts of ON.

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.

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 ON. As of this writing, there are two distributions on which you can build ON: the OpenSolaris distribution, and Solaris Express.

Build machines are assumed to be running a recent build. For example, if you are building snv_99, your build machine should be running snv_97 or later. This means that your build machine may need to be running a prerelease (aka "preview" or "developer") build. This can be done by upgrading from a previous release or build, or by installing the prerelease build from scratch. Details will depend on which distribution you choose.

If you are unsure which distribution to install, the OpenSolaris distribution is generally easier to administer, and it receives more developer attention when there are problems. The chief advantage of Solaris Express is that it is produced for all builds. The OpenSolaris builds currently require more manual activity, so some builds are skipped, particularly right after an OpenSolaris release. Note, though, that this will likely change in the future, as we make the OpenSolaris builds more mechanical. And because Solaris Express will eventually be phased out, there may be a period where some builds are skipped for Solaris Express, too.

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 may 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 archives 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 suninstall to distinguish it from BFU and Cap-Eye-Install) and BFUing are documented here; all users and developers will need to install a binary distribution, while only developers interested in using the very latest ON bits or making significant modifications to core system components will need to read Section 1.3.4 Upgrading to the Latest ON 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. If your favorite distribution isn't mentioned here, please contribute a section explaining how to install it.

1.3.2.1 Installing the OpenSolaris Distribution

Installation of the OpenSolaris distribution is significantly simpler than it is for the Solaris Express distribution. Download the ISO image from http://opensolaris.org/os/downloads/ and burn it to a CD. This is a LiveCD image, so when you boot it, you'll have a usable desktop. When you're ready to install the distribution on your hard disk, start the installer via the desktop icon. The installer will ask a couple questions, then it will install the distribution on the hard disk.

Because of size limitations, not all the available packages are on the LiveCD. After the installer has finished and you have rebooted off the hard disk, you can use the Package Manager to install these packages from a network repository.

For more detailed installation instructions, follow the "Release Notes" link on the downloads page.

1.3.2.2 Updating the OpenSolaris Distribution

The OpenSolaris distribution provides command-line and GUI options for upgrading to the most recent build (or to a new release). The upgrade is done in a clone of the root filesystem, which means that it is easy to back out the upgrade if the new build is unusable for some reason.

As mentioned above, not every build is available as an OpenSolaris update. New OpenSolaris updates are announced on the mailing list indiana-discuss@opensolaris.org. Each announcement includes a pointer to the update, update instructions, and release notes for the build.

1.3.2.3 Installing 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).
See Section 2.1.1 Development Environment for size recommendations. 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 Section 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 Section 2.2 Operating Environment Packages for more information on software requirements.

1.3.2.4 Updating Solaris Express

There are two mechanisms for upgrading Solaris Express: Upgrade and Live Upgrade. The advantage of Live Upgrade is that the system remains usable while it is being upgraded, except for a final reboot into the new build. Live Upgrade does require additional disk space, though this isn't much of an isuse on modern hardware. A more serious problem is that Live Upgrade has been deprecated in favor of the technologies in the OpenSolaris distribution. Bugs, even serious ones, are unlikely to be fixed for Nevada.

See http://docs.sun.com/app/docs/coll/1236.1 for details on using Upgrade and Live Upgrade.

1.3.2.5 Installing Required Tools

There are two sets of tools required to build ON: compilers and ON-specific build tools. See Section 2.3 Obtaining and Installing Compilers and Section 2.4 Obtaining and Installing Custom Tools for detailed information.

Warning: ON switches to a new compiler release only after extensive testing. If you use a compiler other than the one(s) recommended in Section 2.3 Obtaining and Installing Compilers, there is a very good chance that you will run into problems. In particular, the "sunstudio" package in OpenSolaris is unlikely to be usable to build ON. Instead, you should grab a tarball of the tested, installed image.

Download the installed image (not the full product) into a scratch area, such as /var/tmp. The file is normally called something like sunstudio12-DATE.PLATFORM.tar.bz2. Before you start, be sure you have enough free space in /opt. The compiler tree takes 890MB for x86 and 1.4GB for SPARC.


$ su
Password:
# cd /opt/SUNWspro
# gzcat /var/tmp/sunstudio12-ii-20081010-sol-x86.tar.gz | 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 Section 1.3.4 Upgrading to the Latest ON Bits.

1.3.3 Building ON from Source

In this section we'll walk through a basic DEBUG build of the ON sources. For this walkthrough, we'll assume that you're using a snapshot tarball of the source code, rather than taking a snapshot directly from the gate. This is because the source tarball and matching closed binaries have had some testing prior to being posted for download.

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 on-src-DATE.tar.bz2 | tar xf -
$ bzip2 -dc on-closed-bins-DATE.PLATFORM.tar.bz2 | 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 Chapter 4 Building ON 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 Chapter 4 Building ON for more information on the build process and tools. Once you have successfully completed a build, see Chapter 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 Section 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 Section 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 opensolaris-help@opensolaris.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 Section 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.

Start a blog
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.
Fix a simple bug
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.
Enhance cstyle(1)
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 Section 7.2.1 Automated Style Tools for more information.
Clean up and modernize code
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 Section 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.
Simplify Install(1) usage
Improve Install(1)'s '-i' option to use official platform names in addition to code names when building kernel packages for specific platforms. See Section 5.2 Using Cap-Eye-Install to Install Kernels for more information.
Fix something that bothers you
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 request-sponsor@opensolaris.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.

1.5 Contributors

Many people have contributed to this document. This section contains a partial list of sources used in its compilation. If you are aware of additional sources, please add them here.

Note: Some references may be to SWAN-internal URLs. If this content is made public at a later time, these URLs should be updated. In all cases, however, the intent is to document sources as well as possible rather than provide a fully usable bibliography.

Adams, Jonathan; Bustos, David; Rhyason, Jeff. "Creating an Install Archive with Install." http://on-faq.eng.sun.com/onbld-serve/cache/94.html.

Unknown. "What are BFU Conflicts and How Do I Resolve Them?" http://on-faq.eng.sun.com/onbld-serve/cache/189.html

Unknown. "BFU." /ws/onnv-gate/public/bfu.README.

ARC Chairs, Interface Taxonomy. http://opensolaris.org/os/community/arc/policies/interface-taxonomy/.

Miscellaneous Sources:

/shared/ON/general_docs/keyword_info.txt, /shared/ON/general_docs/lint_tips.txt, usr/src/uts/README, usr/src/lib/README.Makefiles, /ws/onnv-gate/public/README

Ben Rockwood contributed much to early drafts of this document. Alan Burlison added the initial POD tags. Mike Sullivan, Mike Kupfer, John Beck, and Shanon Loveridge provided review comments.

last modified by kupfer on 2009/10/27 22:36

OpenSolaris

Top Menu