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.
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.
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 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.
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 Prerequisites for more information about the requirements for installing, developing, and building OpenSolaris.
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 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 especially ???) 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 ???.
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.
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.
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.
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).
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 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 Building OpenSolaris for more information on the build process and tools. Once you have successfully completed a build, see Installing and Testing ON for more information on what to do with it.
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:[email protected] 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.
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
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
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)
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
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
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
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:[email protected] 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.