You are not signed in. or register.

Community: OS/Net (ON)

2 Prerequisites

This chapter describes the hardware and software requirements for developing, building, and testing OpenSolaris. Most of these requirements can easily be met on any Solaris Express installation (other distributions may work as well). Depending on your interests, you may need to test your work with hardware or software which is not readily available to you. If this is the case, please ask your project leader for assistance. Sun and other companies and organizations sponsor various facilities which may be available to OpenSolaris community developers. If you are a project leader, please contact mailto:community underline liaison at opensolaris dot org for information about resources your project can use.

2.1 Hardware

This section details hardware requirements for developing and building OpenSolaris. Because some projects may have additional requirements (for example, driver development obviously requires the device in question), this information is intended to be a guide rather than a definitive set of rules. It is possible, for example, to develop on a system which cannot run any OpenSolaris-based distribution, transferring diffs or other work to a remote environment for building and testing. For purposes of this section, however, we will assume that your development and build systems will run Solaris or some other fully compatible OpenSolaris-based distribution.

2.1.1 Development Environment

The simplest set of requirements applies to a development environment: you need only have sufficient space to store the source tree and enough CPU and memory to run text editors and tools such as cscope. The current source tree occupies approximately 300MB without source code management metadata, so you should budget at least that amount of space for each tree you wish to store (about 1.9GB is required for a tree with a full set of SCCS metadata). Note that if you plan to build the tree on the same system, you will need additional space; see section 2.1.2 below.

In general, any computer which will run Solaris 10, Solaris Express, or another OpenSolaris-based distribution is adequate for this purpose. As of this writing, all SPARC systems with UltraSPARC-II or newer CPUs (that is, all CPUs which have faster clock rates than 200 MHz) are supported; the specific list of supported SPARC platforms for Solaris 10 can be found at http://docs.sun.com/source/817-6337-06/install-solaris.html. For i386 and amd64 systems, hardware support is somewhat more complex; you can find out more about x86 hardware compatibility at http://www.sun.com/bigadmin/hcl/. Be sure to check the latest release notes for Solaris for information about current and future hardware support; these notes can be found at http://docs.sun.com/.

Note that other OpenSolaris-based distributions may at times support a somewhat different set of hardware from the latest Solaris release or update; the latest information about hardware support can always be found in your vendor's release notes.

Table: Development system requirements

 ----------------------------------------------------------------
 CPU            Any supported CPU
 ----------------------------------------------------------------
 Memory         128MB recommended
 ----------------------------------------------------------------
 Swap           No requirement
 ----------------------------------------------------------------
 Storage        300MB to 1.9GB per copy of the source tree (*)
 ----------------------------------------------------------------

(*) The total size will vary depending on the type of source management you use. With no source management data, a built tree requires approximately 3.5GB; CVS and SCCS add 50MB or more, depending on the amount of revision history.

2.1.2 Build Environment

Building a large, complex piece of software such as ON or any other OpenSolaris consolidation is a memory-, compute-, and space-intensive process. Although it is possible to build OpenSolaris on almost any computer, it may take prohibitively long to do so on small configurations. It is especially important to have enough swap space if you will be using dmake to perform highly parallel builds. Inadequate swap will cause your build to fail. Following are the hardware requirements for a system on which you intend to build ON:

Table: Build system requirements

 ----------------------------------------------------------------
 CPU            300 MHz UltraSPARC or x86 CPU
                AMD Opteron or UltraSPARC-III recommended
 ----------------------------------------------------------------
 Memory         256MB minimum, 1GB recommended (+)
 ----------------------------------------------------------------
 Swap           1GB minimum, 2GB recommended (+)
 ----------------------------------------------------------------
 Storage        3.5 to 5GB per copy of the source tree (*) (**)
 ----------------------------------------------------------------

On a minimal build system as described above, expect a full build to take at least 14 hours. Incremental builds will take somewhat less time; a good rule of thumb is one-third of the full build time.

This table shows some approximate full build times for several representative systems. These are current as of 5 April 2006; as more code as added and the number of closed components decreases, build times will increase. Of course, the actual time to build will vary from system to system as well.

 System         CPU                     Memory          Time
 ----------------------------------------------------------------
 Ultra 2        2x300MHz UltraSPARC-II  512M            5h9m
 ----------------------------------------------------------------
 Generic        AMD Athlon64 3200       1GB             1h23m
 ----------------------------------------------------------------

The build system can take advantage of multiple CPUs or even distribute the work of compiling across multiple machines. See 4 Building OpenSolaris for more information about configuring parallel and distributed builds.

(+) If you use dmake(1) in parallel mode and run more than 4 jobs on the same machine, you may need additional memory and/or swap space.

(**) Compilers and tools are installed in /opt and will require an additional 300MB on x86 or 800MB on SPARC.

2.1.3 Test Environment

The requirements for testing your changes will vary greatly. Some changes do not affect architecture-specific code at all and can simply be tested by building and running a test suite on any supported system of each architecture. For example, if you have added a new STREAMS module to the network stack, it is probably sufficient to build and test on one x86 system (test 32- and 64-bit kernels and user programs), and one SPARC system. In other cases, for example modifications to the x86 boot code, it will be necessary to test on the widest possible array of hardware to ensure you have not broken some obscure piece of functionality.

Some hardware variables you should consider testing include:

        - Architecture: i386, amd64, SPARC
        - Memory size: does your change work with 32MB?  With 32GB?
        - Multiprocessor versus uniprocessor
        - Graphical console versus serial console versus system LOM console
        - Diskless versus "normal" systems

Not all these variables will be applicable to your particular change, so you will need to consider, being as conservative as possible, what effects your changes could cause. In general, changes to core kernel code such as the VM subsystem or filesystem support require the broadest testing. Changes to add-on drivers or machine-specific code need only be tested on the relevant hardware in most cases. See Chapter 5 for more details.

Quite often you may want to make a change which you cannot completely test on the hardware available to you. If you find yourself in this situation, start by taking a look at the Testing Community. In addition, other OpenSolaris communities may be able to help provide you with access to hardware to test your changes.

2.2 Operating Environment Packages

The rest of this chapter discusses the software needed to build and package OpenSolaris. If you are only interested in looking at the sources, editing them, and sending your patches to others, you can skip this material; no special packages are required to view and edit the sources. We do recommend, however, that if you are installing Solaris for the first time on a system you plan to use for development, you install the ``Entire'' cluster (SUNWCall) because this will save you a good deal of time if you later decide you want to build OpenSolaris components. Other distributions may offer different installation options; consult your vendor's documentation.

We strongly recommend installing the ``Entire'' package cluster (SUNWCall) on all development, build, and test systems. Although systems with the Developer (SUNWCdev) package cluster installed may work, this configuration has not been tested and will not be evaluated or recommended. Additionally, you should obtain and install the SUNWonbld package, which contains prebuilt versions of the tools in usr/src/tools needed to build OpenSolaris components. If you prefer, you can instead use nightly(1) with the '-t' option to build these tools (see 4.2 Using nightly and bldenv) when building ON, but installing the package is recommended to avoid dependency problems and is required for other consolidations. SUNWonbld can be downloaded from http://opensolaris.org/os/downloads/on/. Finally, you will need to obtain and install the Sun Studio compilers, dmake, and other tools. You can obtain these tools from http://opensolaris.org/os/community/tools/sun_studio_tools/.

If you install and use a full installation (for example, Solaris or Solaris Express CDs or DVDs), you will have a complete matching set of programs, libraries, and kernel components. However, if you later upgrade the ON bits using a method such as BFU (see 5.3 Using BFU to Install ON) or Install (see 5.2 Using Cap-Eye-Install to Install Kernels), or want to build and copy in your own updated versions of a few files, you may need to install newer versions of one or more system packages first. When this happens, it is known as a Flag Day. You can find more information about Flag Days in 5.1.3 Flag Days and Other Hazards.

2.3 Obtaining and Installing Compilers

The compilers needed may depend on the consolidation you are building and the platform(s) on which you wish to build. Prior to build 19, an x86 build of ON used both the Sun One Studio 8 and GNU compilers by default. This is because 32-bit objects are built with cc and CC, while gcc is used for 64-bit objects. As of build 19, Sun Studio 10 compilers are used by default for all objects. And effective beginning in build 38, all ON builds on all platforms require both Sun Studio 10 and a recent version of gcc (from /usr/sfw in Solaris Express). Other consolidations may require slightly different compilers and/or compiler patches, so always check the latest release notes.

Because compilers used to build OpenSolaris may require special patches, links to current Studio compiler binaries will always be maintained at the OpenSolaris web site. Using other versions of compilers, assemblers, linkers, make(1), or dmake(1) is not supported and may fail to build or create binaries that do not function correctly. Therefore, you must use the compilers listed in your consolidation's release notes to ensure a successful build. From time to time the required tools will be updated; notices will be posted and newer versions made available as appropriate.

The only compilers that can be used to build the mainline OpenSolaris sources are the Sun Studio 10 tools available at http://opensolaris.org/os/community/tools/sun_studio_tools/ and the GNU Compiler Collection shipped with Solaris Express build 22 and later. If you wish to use gcc as your primary compiler (that is, if you wish the archives to contain objects built with gcc), see http://opensolaris.org/os/community/tools/gcc/. Regardless of the compiler you use, you will need a set of ON-specific build tools (onbld). You can find these tools for both SPARC and x86 platforms at http://opensolaris.org/os/downloads/on/.

The Studio 10 compilers can be installed in two ways: from an installed image, or as a complete product. The installed image is simply a compressed tar file containing many, but not all, of the contents of the Studio 10 product, with patches already applied and a valid license key. The contents are sufficient to build ON; you can learn more about exactly what's included at http://opensolaris.org/os/community/tools/sun_studio_tools/faqs/. The installed image will be extracted to opt/SUNWspro beneath the directory in which you extract it; if you extract it in the root directory as described below, which is recommended, it will install in the same location as the full product would. Please note that there is no way to apply additional patches to the installed image.

Example: Installing Studio 10 compilers, installed image

Suppose you have downloaded the installed image into /var/tmp/sunstudio10-sparc.tar.bz2, and want to install it into /opt/SUNWspro (recommended). You could install as follows:

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

The complete product install has its own installer and a complete manual that includes installation instructions. See http://docs.sun.com/app/docs/doc/819-0485 for detailed installation instructions, including how to use the graphical and text installation methods. You will need to install the required patches before you can build OpenSolaris components if you use the full product; normally these are included with the product download. See http://opensolaris.org/os/community/tools/sun_studio_tools/ for more information on required patches. By default, the Studio 10 product installs into /opt/SUNWspro. You should not change this unless you have an existing installation of Sun Workshop/Forte/Studio that you need to preserve.

Example: Installing Studio 10 compilers, full product

Suppose you have downloaded the product into /var/tmp/sunstudio10-x86.tar, you wish to unpack it in /var/tmp/studio-install, and you received a license key 'ABC123'. You could install as follows:

 $ mkdir /var/tmp/studioinstall
 $ cd /var/tmp/studioinstall
 $ tar xf /var/tmp/sunstudio10-x86.tar
 $ su
 Password:
 # ./batch_installer -s ABC123
 ...
 # cd patches
 # patchadd -M . patchlist
 ...

The version of gcc needed is installed by default as part of Solaris Express builds 22 and later. If using a different distribution, consult your vendor's documentation to determine whether your version of gcc is sufficient.

2.4 Obtaining and Installing Custom Tools

In addition to the general development tools and compilers, a set of custom tools called ``onbld'' is also required. This includes scripts and programs that handle compiler and assembler compatibility, CTF data, ABI auditing, installation of ON bits, and more. Many of these utilities are platform-specific; therefore, we deliver a version of the SUNWonbld package for all supported platforms (currently x86 and SPARC). Note that these tools are built from sources in the usr/src/tools subdirectory of the ON source gate. Refer to the Tour of Your ON Workspace in section 3.2 for more information about location of the sources. If you have the sources available, you can get by without installing SUNWonbld; however, you may encounter dependency problems when bootstrapping your ON installation. You can obtain this package from http://opensolaris.org/os/downloads/on/. Be aware that certain versions of onbld may be required to build certain ranges of ON sources; if you need to work with an older version of the source, be sure to check the onbld version requirements for that version.

The ON-specific build tools are delivered as a SVR4 (pkgadd(1M)) package for each supported build machine architecture. The package installs into /opt/onbld.

Example: Installing the ON build tools

Suppose you have downloaded the build tools package into /var/tmp/SUNWonbld-20050613.tar.bz2 and you wish to install it. You could do so as follows:

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

2.5 Environment Variables

In order to use the source code management and build tools successfully, you will need to set several environment variables correctly. Most of these variables are either workspace-specific (see section 3.3.1) or build-specific (see section 4.1). However, in order to successfully use the installed tools, you will need to set your PATH environment variable correctly. This should normally be done as part of your login scripts so that it will be done automatically.

You can always get the latest information about recommend PATH components from the gate's public/README file. You can find a copy of this file at http://opensolaris.org/os/community/onnv/gate_info/README.

PATH is used by your shell and other programs to determine where to find programs. This functionality has nothing to do with OpenSolaris, but in order to find the various programs needed by the build tools, PATH requires several elements in addition to the standard system directories. In general, these are:

        /opt/SUNWspro/bin
        /opt/onbld/bin
        /opt/onbld/`uname -p`/bin

If you have installed your compilers or onbld tools in nonstandard locations (which is not recommended), you will need to modify these locations accordingly. Also, you must be certain to include /usr/ccs/bin in your PATH, and even more specifically, it must come before /usr/ucb if that directory is included in your PATH. As an example of putting all this together, a working PATH might look like:

        $ echo $PATH
        /usr/bin:/usr/sbin:/usr/ccs/bin:/usr/dt/bin:/usr/openwin/bin: \
            /opt/onbld/bin:/opt/onbld/bin/sparc:/opt/sfw/bin:/usr/sfw/bin

See the gate's public/README file for details.

Including /usr/ucb in your PATH is not recommended, and the build process does not require any programs located there. If you must include it for some other reason, be sure it is the last component. Otherwise, including /usr/ucb will cause your build to fail, especially if it is before /usr/sbin.

Note that the paths to some tools are explicitly set in usr/src/Makefile.master and other makefiles, so changing your PATH may not by itself have the effect you intend. Specifically, compiler paths are fixed. If you need to change this, you must override the make macros specifying the compiler locations. You can learn more about this in section 4.1.

In addition to PATH, you may find it helpful to add /opt/onbld/man and /opt/SUNWspro/man to your MANPATH. This will make it easier to read the manual pages associated with the many utilities discussed in this document. Alternately, you will need to add '-M /opt/onbld/man' or '-M /opt/SUNWspro/man' to your invocation of man(1) in order to view these pages.