Chapter 2. Prerequisites
This chapter describes the hardware and software requirements for developing, building, and testing ON. Most of these requirements can easily be met on any OpenSolaris or 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 community_liaison@opensolaris.org for information about resources your project can use.
- 2.1 Hardware
- 2.2 Operating Environment Packages
- 2.3 Obtaining and Installing Compilers
- 2.4 Obtaining and Installing Custom Tools
- 2.5 Environment Variables
2.1 Hardware
This section details hardware requirements for developing and building ON. 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 OpenSolaris, 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 550MB without source code management metadata, so you should budget at least that amount of space for each tree you wish to store. About 800MB is required for a Mercurial repository (source plus 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 OpenSolaris, Solaris Express, Solaris 10, 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/chapterHPG.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 1GB recommended ---------------------------------------------------------------- Swap No requirement ---------------------------------------------------------------- Storage 550MB to 800MB per copy of the source tree (*) ----------------------------------------------------------------
(*) The total size will vary depending on whether you are using source tarballs or Mercurial. A built tree requires approximately 4.5GB.
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 ON 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 UltraSPARC or x86 CPU UltraSPARC-III (or better) recommended AMD Opteron or Intel Core 2 Duo recommended ---------------------------------------------------------------- Memory 512MB minimum, 2-4GB recommended (+) ---------------------------------------------------------------- Swap 1GB minimum, 2GB recommended (+) ---------------------------------------------------------------- Storage 4.5GB per copy of the source tree (*) ----------------------------------------------------------------
(+) 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 890MB on x86 or 1.4GB on SPARC.
Expect a full build to run anywhere from a couple hours to overnight, depending on the CPU and memory in the build system. Incremental builds will take somewhat less time; a good rule of thumb is one-third of the full build time.
The build system can take advantage of multiple CPUs or even distribute the work of compiling across multiple machines. See 4 Building ON for more information about configuring parallel and distributed builds.
Note that the build system is assumed to be running a build that is no older than 2 builds back. For example, if you are building snv_99, your build machine should be running snv_97 or later. See Section 1.3.2 Installing a Binary Distribution for information on installing an appropriate build.
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 ON. 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.
If you have installed the OpenSolaris distribution, consult http://opensolaris.org/os/project/indiana/building_on/ for information on what is needed to build ON. The rest of this section discusses the packages that you'll need if you have installed Solaris Express.
2.2.1 Packages to Install from Solaris Express
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 ON components. If you prefer, you can instead use nightly(1) with the '-t' option to build these tools (see Section 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 Section 5.3 Using BFU to Install ON) or Install (see Section 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 Section 5.1.3 Flag Days and Other Hazards.
2.3 Obtaining and Installing Compilers
Building ON requires both Sun Studio 12 and gcc. Because the compilers may require special patches, links to current Studio compiler binaries will always be maintained at the OpenSolaris web site: http://opensolaris.org/os/community/tools/sun_studio_tools/. For gcc, a recent version from OpenSolaris or Solaris Express should be sufficient. 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. In particular, the "sunstudio" package in OpenSolaris is not supported for building ON. From time to time the required tools will be updated; notices will be posted and newer versions made available as appropriate.
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 12 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 12 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/. If you extract it as described in the example 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.
The complete product install has its own installer and a complete manual that includes installation instructions. Because it is significantly easier to install the prebuilt tarball (e.g., it already contains any necessary patches), we will not discuss the complete product install further.
Example 1: Installing Studio compilers, installed image
Suppose you have downloaded the installed image into /var/tmp/sunstudio12-ii-20081010-sol-sparc.tar.gz, and want to install it into /opt/SUNWspro (recommended). You could install as follows:
$ su Password: # cd /opt/SUNWspro # gzcat /var/tmp/sunstudio12-ii-20081010-sol-sparc.tar.gz | tar xf -
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 3: 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.
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.