Prerequisites

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.1.1 Development Environment
  • 2.1.2 Build Environment
  • 2.1.3 Test Environment
• 2.2 Operating Environment Packages
• 2.3 Obtaining and Installing Compilers
• 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 a 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.

 Since you installed the OpenSolaris distribution, Section 1.3.2.1 explained how to install the additional packages that are needed to build ON.

2.3 Obtaining and Installing Compilers

 Building ON requires both Sun Studio 12 and gcc, as well as the Sun Studio 12u1 lint. 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 was included in developer/opensolaris/osnet, and should be sufficient. Using other versions of compilers, assemblers, linkers, make(1), or dmake(1) is not supported and may either 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/.

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/bin/`uname -p`

 If you have installed your compilers 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.