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.

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.

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.

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 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 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 similar to 1.3.2.1. If your favorite distribution isn't mentioned here, please contribute a section explaining how to install it.

$ df -klh /opt
Filesystem             size   used  avail capacity  Mounted on
/dev/dsk/c1t0d0s0      7.9G   3.8G   4.0G    50%    /

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

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

First, Create an environment file to guide tools like nightly(1) and bldenv(1).

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.

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.

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 Building OpenSolaris for more information about configuring parallel and distributed builds.

(*) 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.

(+) 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.

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, please contact us via http://opensolaris.org/. The OpenSolaris community includes several organizations, including Sun, who may be able to provide you with access to additional hardware for the purpose of testing your changes.

$ 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.

$ 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.

You can obtain the tarballs for all released consolidations at http://opensolaris.org/os/downloads/. If you plan to build the source, and wish to produce complete installation sets, you may also need the closed binaries (if the consolidation of interest is not entirely open), which you can obtain from the same location. Be sure to obtain the appropriate binaries for your platform. Once you have done so, create your workspace as follows:

$ mkdir /path/to/workspace
$ cd /path/to/workspace
$ bzip2 -dc /path/to/tarball/on-src-<ver>.tar.bz2 | tar xf -
$ bzip2 -dc /path/to/tarball/on-bins-<ver>.{x86,sparc}.tar.gz | tar xf -

Initially, your workspace will have only one directory: usr. Once you have completed a build, you may have several additional directories, including archives, log, packages, and proto. We include here a diagram showing all these directories and their subdirectories. We also include the build subdirectories, which contain object files and are described in greater detail in subsections 2-4 below.

If you have done a nightly(1) build, you will also have a log directory at the top level. It will contain the complete output from the nightly(1) build process. See 4.2 Using nightly and bldenv for more information on nightly(1) and the log files it generates.

All sources are found under usr/src. This includes both the sources used to build the ON consolidation and sources for tools and other peripheral utilities needed to build but not shipped as part of Solaris. Because it includes only ON sources, it does not contain Java, the windowing system, or packaging and installation tools. Because of contractual obligations, it may not include all code from third-party hardware vendors. The usr/src directory has several subdirectories which are described here.

There are two basic strategies that can be used in the creation of object files and finished binaries (executables and libraries):

(a) place objects in a dedicated directory hierarchy parallel to the sources

(b) place objects in the same directories as the sources they are built from

ON actually uses each of these approaches in different parts of the tree. Strategy (a) must be used for all kernel code and many libraries, is preferred for new code, and will be described in detail here. There are several legacy variations on strategy (a) as well as instances in which strategy (b) is still used; the majority of these are in the cmd hierarchy. The entire uts hierarchy has been converted to strategy (a) as described below, and you will see this same approach used throughout much of the rest of the tree.

This discussion is intended to provide a step-by-step explanation of what targets exist and how they are built by the makefiles. I ignore the platform-specific module architecture because it is unlikely to be of significant interest except to hardware support engineers. The three main subtrees of interest are the kernel (uts), commands and daemons (cmd), and libraries (lib). The next three subsections cover these three subtrees in turn. There are also a handful of makefiles which apply to all builds:

This section describes in detail how make dependencies and rules are built up, and how each individual makefile contributes to the build process. Once you understand how the makefiles work, modifying existing build rules and creating new ones are mainly an exercise in copying existing files and making minor modifications to them. We begin with the kernel makefiles, then address the very similar command and library makefiles.

common/Makefile.files:ASY_OBJS +=      asy.o

MODULE          = asy
OBJECTS         = $(ASY_OBJS:%=$(OBJS_DIR)/%)

ALL_TARGET      = $(BINARY) $(SRC_CONFILE)

BINARY             = $(OBJS_DIR)/$(MODULE)

$(BINARY):              $(OBJECTS)
	$(LD) -r $(LDFLAGS) -o $@ $(OBJECTS)
	$(CTFMERGE_UNIQUIFY_AGAINST_GENUNIX)
	$(POST_PROCESS)
	$(ELFSIGN_MOD)

OBJECTS         = $(ASY_OBJS:%=$(OBJS_DIR)/%)

$(OBJS_DIR)/%.o:                $(UTSBASE)/common/io/%.c
	$(COMPILE.c) -o $@ $<
	$(CTFCONVERT_O)

KMODS +=	asy

all:	$(KMODS)

asy:	obj32/asy.o
	$(LD) -r $(LDFLAGS) -o $@ obj32/asy.o
	...

obj32/asy.o:	../../common/io/asy.c
	$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $@
	...

Most code in OpenSolaris is generic and platform- and ISA-independent; that is, it is portable code that can be compiled and run on any system for which a suitable compiler is available. However, even portable code must sometimes deal with specific attributes of the system on which it runs, or must be provided compiled for multiple supported architectures so that users can run or link with the architecture-specific version of their choosing.

There are two distinct situations in which multiple architecture-specific builds must be shipped: commands that, by their nature, must have visibility into the system's hardware characteristics, and libraries, which must be built separately for each architecture a developer may wish to target. Each case is discussed in its own subsection below.

install:        $(SUBDIRS)
	-$(RM) $(ROOTUSRSBINPROG)
	-$(LN) $(ISAEXEC) $(ROOTUSRSBINPROG)

PROG = dtrace
OBJS = dtrace.o

SRCS = $(OBJS:%.o=../%.c)

CFLAGS += $(CCVERBOSE)
CFLAGS64 += $(CCVERBOSE)
LDLIBS += -ldtrace -lproc

include ../Makefile.com

install: all $(ROOTUSRSBINPROG32)

ROOTUSRSBIN=    $(ROOT)/usr/sbin
ROOTUSRSBINPROG=$(PROG:%=$(ROOTUSRSBIN)/%)
ROOTUSRSBIN32=  $(ROOTUSRSBIN)/$(MACH32)
ROOTUSRSBINPROG32=      $(PROG:%=$(ROOTUSRSBIN32)/%)

$(ROOT)/usr/sbin/dtrace		-> $(ROOT)/usr/lib/isaexec
$(ROOT)/usr/sbin/$(MACH32)/dtrace	(our executable program)

yydebug := TARGET = yydebug
...
lint yydebug: $(SUBDIRS)

XRDIRS = common i386 sparc sparcv9
XRDEL = dt_lex.c dt_grammar.c Makefile*

DRTISRC = drti.c
DRTIOBJ = $(DRTISRC:%.c=%.o)

DLIBSRCS += \
	errno.d \
	io.d \
	procfs.d \
	regs.d \
	sched.d \
	signal.d \
	unistd.d
...
ROOTDLIBDIR = $(ROOT)/usr/lib/dtrace
ROOTDLIBDIR64 = $(ROOT)/usr/lib/dtrace/64
...
$(ROOTDLIBDIR):
	$(INS.dir)

$(ROOTDLIBDIR64): $(ROOTDLIBDIR)
	$(INS.dir)

$(ROOTDLIBDIR)/%.d: ../common/%.d
	$(INS.file)

$(ROOTDLIBDIR)/%.d: ../$(MACH)/%.d
	$(INS.file)

$(ROOTDLIBDIR)/%.d: %.d
	$(INS.file)

pics/%.o: ../$(MACH)/%.c 
	$(COMPILE.c) -o $@ $<
	$(POST_PROCESS_O)

pics/%.o: ../$(MACH)/%.s
	$(COMPILE.s) -o $@ $<
	$(POST_PROCESS_O)

%.o: ../common/%.c
	$(COMPILE.c) -o $@ $<
	$(POST_PROCESS_O)

ASFLAGS += -D_ASM -K PIC -P

MAPDIR = ../spec/sparc
include ../Makefile.com

SRCS += dt_asmsubr.s
OBJECTS += dt_asmsubr.o

install yydebug: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT) \
	$(ROOTDLIBS) $(ROOTDOBJS)

MAPDIR = ../spec/sparcv9
include ../Makefile.com
include ../../Makefile.lib.64

CPPFLAGS += -D_ELF64
...
install yydebug: all $(ROOTLIBS64) $(ROOTLINKS64) $(ROOTLINT64) \
	$(ROOTDLIBS) $(ROOTDOBJS64)

ROOTLIBDIR=     $(ROOT)/usr/lib
ROOTLIBDIR64=   $(ROOT)/usr/lib/$(MACH64)
...
ROOTLIBS=       $(LIBS:%=$(ROOTLIBDIR)/%)
ROOTLIBS64=     $(LIBS:%=$(ROOTLIBDIR64)/%)

The install target causes binaries and headers to be installed into a hierarchy called the prototype or proto area (see section 4.4.1 for more information on the prototype area's contents and purpose). The root of the proto area is defined by the environment variable ROOT. This variable is used in defining ROOT_MOD_DIR and USR_MOD_DIR in usr/src/uts/Makefile.uts:

ROOT_MOD_DIR               = $(ROOT)/kernel
USR_MOD_DIR                = $(ROOT)/usr/kernel

All modules are installed below one of these directories. The exact subdirectory used depends on the definition of ROOTMODULE in the module build directory, which is discussed below.

Additional files to be installed may be given by the INSTALL_TARGET definition in this makefile. For example, the asy makefile (usr/src/uts/intel/asy/Makefile) specifies:

INSTALL_TARGET  = $(BINARY) $(ROOTMODULE) $(ROOT_CONFFILE)

Since this is a common set of installation targets, let's look at how each component is derived.

$(BINARY) is simply the module itself; we've discussed its dependencies and rules in detail above. Including it here requires it to be fully built before any installation is attempted.

$(ROOTMODULE) is a name transform on the name of the module, relocating it into the prototype area. For example, usr/src/uts/intel/asy/Makefile defines:

ROOTMODULE      = $(ROOT_DRV_DIR)/$(MODULE)

ROOT_DRV_DIR requires a bit of additional explanation; it is one of many module installation subdirectories defined in Makefile.uts. Because the ending location of binary kernel modules depends on the machine type, specifically its 32 versus 64 bitness, there are really several definitions. First, the subdirectory definition for each 64-bit machine type:

SUBDIR64_sparc          = sparcv9
SUBDIR64_i386           = amd64
SUBDIR64                = $(SUBDIR64_$(MACH))

Next, the 32- and 64-bit installation directories for each type of module:

ROOT_KERN_DIR_32        = $(ROOT_MOD_DIR)
ROOT_DRV_DIR_32         = $(ROOT_MOD_DIR)/drv
ROOT_DTRACE_DIR_32      = $(ROOT_MOD_DIR)/dtrace
ROOT_EXEC_DIR_32        = $(ROOT_MOD_DIR)/exec
...

ROOT_KERN_DIR_64        = $(ROOT_MOD_DIR)/$(SUBDIR64)
ROOT_DRV_DIR_64         = $(ROOT_MOD_DIR)/drv/$(SUBDIR64)
ROOT_DTRACE_DIR_64      = $(ROOT_MOD_DIR)/dtrace/$(SUBDIR64)
ROOT_EXEC_DIR_64        = $(ROOT_MOD_DIR)/exec/$(SUBDIR64)
...

And finally the selection of either the 32- or 64-bit directory based on the actual bitness of this build:

ROOT_KERN_DIR           = $(ROOT_KERN_DIR_$(CLASS))
ROOT_DRV_DIR            = $(ROOT_DRV_DIR_$(CLASS))
ROOT_DTRACE_DIR         = $(ROOT_DTRACE_DIR_$(CLASS))
ROOT_EXEC_DIR           = $(ROOT_EXEC_DIR_$(CLASS))
...

There are similar definitions for USR_XXX_DIR based in $(ROOT)/usr/kernel. See usr/src/uts/Makefile.uts for the complete list of possible ROOT_ and USR_ installation directories.

The rules for installing files into each of these directories are given in usr/src/uts/Makefile.targ:

$(ROOT_MOD_DIR)/%:      $(OBJS_DIR)/% $(ROOT_MOD_DIR) FRC
	$(INS.file)

$(ROOT_DRV_DIR)/%:      $(OBJS_DIR)/% $(ROOT_DRV_DIR) FRC
	$(INS.file)
...

These rules install the file currently located in $(OBJS_DIR), described in detail above, into the appropriate directory in the proto area.

$(ROOT_CONFFILE) is the module's configuration file (most commonly used for drivers), transformed into the proto area. The CONFFILE variables are defined in usr/src/uts/Makefile.uts:

CONFFILE                = $(MODULE).conf
SRC_CONFFILE            = $(CONF_SRCDIR)/$(CONFFILE)
ROOT_CONFFILE_32        = $(ROOTMODULE).conf
ROOT_CONFFILE_64        = $(ROOTMODULE:%/$(SUBDIR64)/$(MODULE)=%/$(MODULE)).conf
ROOT_CONFFILE           = $(ROOT_CONFFILE_$(CLASS))

Each module's Makefile defines CONF_SRCDIR to specify the location of the configuration file that should be installed on this platform. The asy makefile defines:

CONF_SRCDIR     = $(UTSBASE)/common/io

which causes usr/src/uts/common/io/asy.conf to be installed in the proto area as /kernel/drv/asy.conf. Note that the configuration file installation directory does not depend on whether this is a 32- or 64-bit build.

Note that although it is confusing, installation targets are always named ROOTMODULE, ROOT_CONFFILE, and so on, even if they are actually installed into one of the USR_ directories. This simplifies the higher-level makefiles.

As we've seen, the sources are derived from $(XXX_OBJS) and the included rules. Now, here's the tricky part - finding where those sources are. The easiest way by far is to run make from the module's object directory and observe the compilation commands that are run. The path to each source file will be included in the output. This is the simplest and recommended way to find which source files are needed to build a module. However, if this does not work (perhaps the makefile itself is buggy) or if you want to gain greater understanding, the rest of this section describes logical processes for finding source files.

Since you know the basenames (they are simply the XXX_OBJS entries with .o replaced by .c) you can use a simple

$ find usr/src/uts -name asy.c

Suppose you find two source files with the same name - which is actually used? There are two ways to figure this out. The lazy way is to use make -d to show you the exact dependencies being used. Alternatively, you could reason it out, starting with the fact that not all source files are used on your platform (i.e., usr/src/uts/sparc/* is not used by x86 builds), and then looking at the specific order of the rules in each Makefile.rules. The more specific rules are listed first and take precedence over later rules (in fact they all add a dependency to the specific object file in question, but since the rules all use $<, only the first dependency is actually used).

Non-kernel source files are easier to locate, since the cmd and lib directories are generally organized with one subdirectory for each library or command, named accordingly. The major exceptions are cmd/sgs, which contains the entire binary tools subsystem, and cmd/cmd-inet, which contains most of the Berkeley networking commands and daemons as well as some additional network-related utilities, laid out in a BSD-style directory structure.

Some sources used to build the branded Solaris product are not included in OpenSolaris. There are two main reasons for this:

To accommodate fully functional builds even though some sources are missing, a set of closed binaries are available, and the build system has been modified to make use of them. The makefile variable CLOSED_BUILD controls whether the build system will use the prebuilt closed binaries or look for the closed sources.

CLOSED_BUILD is typically used in makefile lines that build up the list of modules or subdirectories that are to be built. Makefile lines that start with CLOSED_BUILD, e.g.,

$(CLOSED_BUILD)DCSUBDIRS += \
	$(CLOSED)/cmd/pax

are for use only when the closed sources are present.

Sometimes a separate closed module list is built up, rather than adding to the open module list. This approach is used extensively in the kernel, as in

$(CLOSED_BUILD)CLOSED_DRV_KMODS	+= chxge

Because this approach requires additional variables, the first approach is usually preferred. The second approach is used when the list needs to contain individual component names, rather than paths. For example, the kernel makefiles use the module names to construct a series of "-l" clauses for linting; that would be a lot messier if paths were used instead of module names.

You shouldn't normally need to set CLOSED_BUILD. Instead, bldenv(1) and nightly(1) set the environment variable CLOSED_IS_PRESENT, and the ON makefiles use this to set CLOSED_BUILD.

The kernel provides an additional challenge, which is that many makefile rules and declarations are practically the same for both the open and closed source trees. To avoid duplication of code, the common text was put in shared makefiles (e.g., Makefile.sun4u.shared). When used for open code, the makefile variable $(UTSTREE) is set to $(UTSBASE). For closed code, it is set to $(UTSCLOSED).

Once you have brought over a workspace, you must set up both the workspace itself and your environment before you can safely use it.

First, you must set your environment variables appropriately so that the build tools will work properly. This must be done once in any shell which will run commands that affect the workspace. Although there are numerous variables which must be set, nearly all of them are set by bldenv(1), which accepts a nightly-style environment file. For example, if your workspace's environment file is in /aux0/testws/opensolaris.sh, you would need to run the following command in each shell from which you will run commands that affect the workspace:

$ bldenv /aux0/testws/opensolaris.sh

It may be tempting to run this command from your shell initialization scripts; however, if you have more than one workspace, it can be inconvenient and even dangerous, as you may inadvertently perform an operation on the wrong workspace.

You can use any text editor you like to edit source files. Although choice of editor is a personal matter, not all editors are equal. In particular, there are two types of editor behavior which are certain to cause problems. First, some editors such as pico and nano wrap lines longer than 72 characters or so. While this is fine for documents, it causes havoc in source files. If you must use such an editor, be sure to turn off line wrapping; otherwise your diffs will include large quantities of noise and the resulting file may not compile. Second, some editors, especially on non-Unix systems which may have different conventions, will change newline characters from '\n' to something else. If you must edit sources on a foreign system, be absolutely certain your editor outputs Unix-style newlines. Source files containing foreign newline characters cannot be integrated into any OpenSolaris consolidation and may not compile.

When you edit source files, be sure that you are familiar with the style guide; see section 7.2 for more details. Once again, not all editors are equal: some may offer the ability to set parameters that will help you to write conformant code, while others may enforce fixed settings which conflict with our style. Regardless of your choice of editor, you will need to be sure that your code conforms to the style guidelines.

This section provides detailed, step-by-step instructions for common build-related tasks, such as adding or moving kernel modules and adding new libraries. You should also read the sections regarding makefile layout and operation to gain a better understanding of the overall build system.

FOOFS_OBJS +=	foovfs.o foovno.o

$(OBJS_DIR)/%.o:		$(UTSBASE)/common/fs/foofs/%.c
	$(COMPILE.c) -o $@ $<
	$(CTFCONVERT_O)

$(LINTS_DIR)/%.ln:		$(UTSBASE)/common/fs/foofs/%.c
	@($(LHEAD) $(LINT.c) $< $(LTAIL))

MODULE		= foofs
OBJECTS		= $(FOOFS_OBJS:%=$(OBJS_DIR)/%)
LINTS		= $(FOOFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
ROOTMODULE	= $(ROOT_FS_DIR)/$(MODULE)

MODSTUBS_DIR	 = $(OBJS_DIR)
$(MODSTUBS_O)	:= AS_CPPFLAGS += -DFOOFS_MODULE

CLEANFILES	+= $(MODSTUBS_O)

FS_KMODS	+= foofs

install_h: $(ROOTHDRS)

check: $(CHECKHDRS)

include ../Makefile.lib

POFILE =	  libfoo.po
MSGFILES =	  $(OBJECTS:%.o=%.i)

# ...

$(POFILE): $(MSGFILES)
		$(BUILDPO.msgfiles)

_msg: $(MSGDOMAINPOFILE)

include $(SRC)/Makefile.msg.targ

include ../Makefile.lib

SUBDIRS =	  $(MACH)

POFILE =	  libfoo.po
POFILES =	  $(SUBDIRS:%=%/_%.po)

_msg :=	  TARGET = _msg

# ...

$(POFILE): $(POFILES)
		$(BUILDPO.pofiles)

_msg: $(MSGDOMAINPOFILE)

include $(SRC)/Makefile.msg.targ

POFILE =	  _thissubdir.po
MSGFILES =	  $(OBJECTS:%.o=%.i)

$(POFILE):	  $(MSGFILES)
		  $(BUILDPO.msgfiles)

_msg:		  $(POFILE)

include $(SRC)/Makefile.msg.targ

include ../Makefile.lib

HDRS =		libinetutil.h
HDRDIR =	common
SUBDIRS =	$(MACH)
$(BUILD64)SUBDIRS += $(MACH64)

all :=		TARGET = all
clean :=	TARGET = clean
clobber :=	TARGET = clobber
install :=	TARGET = install
lint :=		TARGET = lint

.KEEP_STATE:

all clean clobber install: spec .WAIT $(SUBDIRS)

lint:		$(SUBDIRS)

install_h:	$(ROOTHDRS)

check:		$(CHECKHDRS)

$(SUBDIRS) spec: FRC
	@cd $@; pwd; $(MAKE) $(TARGET)

FRC:

include ../Makefile.targ

LIBRARY =	libinetutil.a
VERS =		.1
OBJECTS =	octet.o inetutil4.o ifspec.o

include ../../Makefile.lib
include ../../Makefile.rootfs

LIBS =		$(DYNLIB) $(LINTLIB)
SRCS =		$(COMDIR)/octet.c $(SRCDIR)/inetutil4.c \
		$(SRCDIR)/ifspec.c
$(LINTLIB):=	SRCS = $(SRCDIR)/$(LINTSRC)
LDLIBS +=	-lsocket -lc

SRCDIR =	../common
COMDIR =	$(SRC)/common/net/dhcp
MAPDIR =	../spec/$(TRANSMACH)
SPECMAPFILE =	$(MAPDIR)/mapfile

CFLAGS +=	$(CCVERBOSE)
CPPFLAGS +=	-I$(SRCDIR)

.KEEP_STATE:

all: $(LIBS)

lint: lintcheck

pics/%.o: $(COMDIR)/%.c
	$(COMPILE.c) -o $@ $<
	$(POST_PROCESS_O)

include ../../Makefile.targ

sparc/Makefile:

include ../Makefile.com

install: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT)

sparcv9/Makefile:

include ../Makefile.com
include ../../Makefile.lib.64

install: all $(ROOTLIBS64) $(ROOTLINKS64)

i386/Makefile:

include ../Makefile.com

install: all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT)

nightly(1) accepts a wide variety of options and flags that control its behavior. Many of these options control whether nightly(1) performs each of the many steps it can automate for you. These options may be specified in the environment file or on the command line; options specified on the command line take precedence. See nightly(1) for the complete list of currently accepted options and their effect on build behavior.

nightly(1) reads a file containing a set of environment definitions for the build. This file is a simple shell script, but normally just contains variable assignments. All variables described in section 2.5 Environment Variables and below in 4.2.3 Variables can be set in the nightly(1) environment file; however, common practice is to use the developer, or gatekeeper, or opensolaris environment files, as appropriate, and modify one of them to meet your needs. The name of the resulting environment file is then passed as the final argument to nightly(1). The sample environment files are available in usr/src/tools/env.

Although any environment variables can be set in a nightly(1) environment file, this section lists those which are used directly by nightly(1) to control its operation and which are commonly changed. The complete list of variables and options is found in nightly(1).

The install target causes binaries and headers to be installed into a hierarchy called the prototype or proto area. Since everything in the proto area is installed with its usual paths relative to the proto area root, a complete proto area looks like a full system install of the ON bits. However, a proto area can be constructed by arbitrary users, so the ownership and permissions of its contents will not match those in a live system. The root of the proto area is defined by the environment variable ROOT, which defaults to /proto. If you use bldenv(1) to set up your environment, ROOT defaults instead to ${CODEMGR_WS}/proto/root_${MACH}.

The proto area is useful if you need to copy specific files from the build into your live system. It is also compared with the parent's proto area and the packaging information by tools like protocmp and checkproto to verify that only the expected shipped files have changed as a result of your source changes.

protocmp does not include a man page. Its invocation is as follows:

protocmp [-gupGUPlmsLv] [-e <exception-list> ...] -d <protolist|pkg dir>
    [-d <protolist|pkg dir> ...] [<protolist|pkg dir>...]|<root>]

Where:

-g       : don't compare group
-u       : don't compare owner
-p       : don't compare permissions
-G       : set group
-U       : set owner
-P       : set permissions
-l       : don't compare link counts
-m       : don't compare major/minor numbers
-s       : don't compare symlink values
-d <protolist|pkg dir>:
           proto list or packaging to check
-e <file>: exceptions file
-L       : list filtered exceptions
-v       : verbose output

If any of the -[GUP] flags are given, then the final argument must be the proto root directory itself on which to set permissions according to the packaging data specified via -d options.

A protolist is a text file with information about each file in a proto area, one per line. The information includes: file type (plain, directory, link, etc.), full path, link target, permissions, owner uid, owner gid, i-number, number of links, and major and minor numbers. You can generate protolists with the protolist command, which does not include a man page. Its invocation is as follows:

$ protolist <protoroot>

where protoroot is the proto area root (normally $ROOT). Redirecting its output yields a file suitable for passing to protocmp via the -d option or as the final argument.

The last argument to protocmp always specifies either a protolist or proto area root to be checked or compared. If a -d option is given with a protolist file as its argument, the local proto area will be compared with the specified reference protolist and lists of files which are added, missing, or changed in the local proto area will be provided. If a -d option is given with a package definitions directory as its argument, the local proto area will be checked against the definitions provided by the package descriptions and information about discrepancies will be provided.

The exceptions file (-e) specifies which files in the proto area are not to be checked. This is important, since otherwise protocmp expects that any files installed in the proto area which are not part of any package represent a package definition error or spurious file in the proto area.

This comparison is automatically run as part of your nightly(1) build so long as the -N option is not included in your options. See nightly(1) and section 4.2 for more information on automating proto comparison as part of your automatic build.

As a shortcut to using protolist and protocmp, you can use the 'checkproto' command found in the SUNWonbld package. This utility does not include a man page, but has a simple invocation syntax:

$ checkproto [-X] <workspace>

The exception files and packaging information will be selected for you, and the necessary protolists will be generated automatically. Use of the -X option, as for nightly(1), will instruct checkproto to check the contents of the realmode subtree, which normally is not built.

You can find the sources for protolist, protocmp, and checkproto in usr/src/tools. The resulting binaries are included in the SUNWonbld package.

BFU archives are cpio-format archives (see cpio(1) and archives(4)) used by bfu(1) to install ON binaries into a live system. The actual process of using bfu(1) is described in greater detail in the man page and in section 5.3.

BFU archives are built by mkbfu, which does not include a man page. Its invocation is as follows:

$ mkbfu [-f filter] [-z] proto-dir archive-dir

The -f option allows you to specify a filter program which will be applied to the cpio archives. This is normally used to set the proper permissions on files in the archives, as discussed in greater detail below.

The -z option causes the cpio archives to be compressed with gzip(1). If both -f and -z are given, the compression will occur after the filter specified by -f is applied.

proto-dir is the proto area root described in section 4.4.1 and normally given by the ROOT environment variable.

archive-dir is the directory in which the archives should be created. If it does not exist it will be created for you.

However, 'mkbfu' is rarely used. Instead, 'makebfu' offers a much simpler alternative. It has no man page, but the invocation is simple:

$ makebfu [filename]

If an argument is given, it refers to an environment file suitable for nightly(1) or bldenv(1). Otherwise, 'makebfu' assumes that bldenv(1) or equivalent has already been used to set up the environment appropriately.

'makebfu' is a wrapper around 'mkbfu' that feeds package and environment information to 'cpiotranslate' to construct an appropriate filter for the archives. This filter's purpose is to set the correct mode, owner, and group on files in the archives. This is needed to allow builds run with ordinary user privileges to produce BFU archives with the correct metadata. Without root privileges, there is no way for the build user to set the permissions and ownership of files in the proto area, and without filtering, the cpio archives used by BFU would be owned by the build user and have potentially incorrect permissions. 'cpiotranslate' uses package definitions to correct both. See usr/src/tools/protocmp/cpiotranslate.c to learn how this works.

Each archive contains one subset of the proto area. Platform-specific directories are broken out into separate archives (this can simplify installing on some systems since only the necessary platform-specific files need to be installed), as are /, /lib, /sbin, and so on. The exact details of the files included in the archives can be found only by reading the latest version of mkbfu.

BFU archives are built automatically as part of your nightly(1) build if -a is included in your options. Also, if -z is included in your options, it will be passed through to mkbfu. See nightly(1) and section 4.2 for more information on automating BFU archive construction as part of your automatic build.

mkbfu and makebfu are Korn shell scripts included in the SUNWonbld package. Their sources are located in usr/src/tools/scripts.

cpiotranslate is a C program included in the SUNWonbld package. Its source is located in usr/src/tools/protocmp/cpiotranslate.c.

Ordinary SVR4 packages can be built from the files installed into the proto area (see section 4.4.1). This is done automatically by the main makefile's all and pkg_all targets (see usr/src/Makefile) as part of a successful build. The definitions located in usr/src/pkgdefs are used to build all packages; each subdirectory contains the package definitions and a makefile fragment used to build that package. Built packages are rooted in usr/src/packages and are in the standard format. See pkgmk(1) for more information on how packages are built.

Packages are built automatically as part of your nightly(1) build if -p is included in your options. See nightly(1) and section 4.2 for more information on automating package construction as part of your automatic build.

SVR4 packages are similar to those delivered by other operating systems; they contain the files to be installed, metadata about those files, scripts to perform tasks during installation and removal, and information about the package itself. Although the exact data formats used may differ, all the general concepts are the same. However, packages delivered by OpenSolaris tend to be coarser-grained than those that make up most GNU/Linux distributions. For example, SUNWcsu contains a large portion of the core system commands and kernel components; a typical GNU/Linux distribution might deliver equivalent functionality in ten or more different packages. Most OpenSolaris packages are separated based on the files' location, whether in the root filesystem or the /usr subdirectory. This is primarily to accommodate installation for diskless clients, which may have a shared /usr located on a file server. Distributions other than Solaris may package system components differently.

pkgmk(1) is part of the SUNWpkgcmdsu package. Its sources are not part of the ON consolidation.

Install (pronounced cap-eye-install) is used to update only the kernel and its associated modules on a specific system. It will place the new kernel in a nonstandard location and install only the platform-specific modules for your particular host. This allows you to test your changes without removing the normal kernel; if your new kernel does not boot or crashes, this makes recovery much easier.

BFU is used to update all ON bits, both kernel and userland. It is capable of updating some configuration files and is aware of the impact of the changes that have been made to ON. BFU is more thorough than Install, and takes longer. Also, unlike Install, the new kernel will be installed over the existing one, so if it does not work properly you may have to boot from alternate media to recover.

In some cases, you will need to install newer versions of one or more system packages before you will be able to use a new version of the ON bits. When this happens, it is known as a Flag Day. Flag Day notices will be posted at http://opensolaris.org/os/community/onnv/ and will include instructions for building and/or installing the newer software you will need. It should be noted that this installation procedure is not guaranteed to interoperate cleanly with the standard packaging tools such as pkgadd(1M). In particular, use of BFU (see section 4.1.4) or ad-hoc replacement of Solaris components means that those components can no longer be updated using Solaris packages. If this is of concern to you, we recommend that you utilize exclusively Solaris Express for managing your system package installation, and build and test only against the source tree current at the time of the latest Express build. You can

Although Install is useful for developers who have changed only kernel code, it is of limited value for others. In particular, if a recent flag day notice indicates that newer kernels are incompatible with existing userland libraries or commands, Install cannot be used to test the updated kernel until you have upgraded your userland via BFU or some other mechanism such as the regular installation or upgrade procedure.

Like bfu (see section 5.3), Install is rather closely attached to its particular release, so you should use the current version from the gate matching the release you are building. Normally this is in the public/bin subdirectory of the gate; however, for installations outside Sun it is located in /opt/onbld/bin.

It is critical that Install users install the correct set of platform-specific modules, especially on SPARC systems. Failure to do so can result in an unbootable system. See section 5.2.2 below for more information on how platform-specific modules relate to Install.

One major advantage of Install over BFU is the ability to keep your existing kernel in place so that you can still boot if the test kernel proves toxic. We strongly recommend that if you use Install to test kernels, you take advantage of this feature and use distinct locations (see the -G option described in section 5.2.1 above) for each new kernel you test. Otherwise, you will likely have to boot from alternate media to repair your system following the installation of a bad kernel.

Ordinarily, Install does not generate archives with implementation-specific modules. If these archives are installed onto a system which requires the missing modules, the system may fail to boot or work properly. If you do this, you will need to boot from a known-working kernel and correct the problem.

An example symptom of the problem (on an Enterprise 3500):

SunOS Release on81 Version jrhyason_[ws-vmstat]_05/15/01 64-bit
Copyright 1983-2001 Sun Microsystems, Inc.  All rights reserved.
DEBUG enabled
obpsym: symbolic debugging is available.
Read 297063 bytes from misc/forthdebug
  ====>  WARNING: consconfig: consconfig_util_openvp failed: err 6 vnode
 0x2803c80
  ====>  WARNING: consconfig: consconfig_util_link I_PLINK failed: error
 22
configuring IPv4 interfaces: hme0.
...

The console is gone!

To include the needed modules in your Install tarball, make sure to use

$ Install -i <implementation>

to include implementation-specific modules. But how do you know what sun4u implementation you need? First, obtain your machine's "official" implementation name from the output of 'uname -i'. Then, in usr/src/uts/sun4u, run "grep IMPLEMENTED_PLATFORM */Make*" to see a list of implementations and the corresponding platform name reported by uname(1).

In the example above, the E3500 reports:

$ uname -i
SUNW,Ultra-Enterprise

And we see from the grep output:

$ grep IMPLEMENTED_PLATFORM */Make*
...
sunfire/Makefile:IMPLEMENTED_PLATFORM   = SUNW,Ultra-Enterprise
...

In this case, the "-i sunfire" argument must be added to get the correct behavior.

Additionally, one of the easiest ways to get tripped up with Install wads comes from the fact that not all drivers are delivered by ON. This has been particularly noticeable with x86, but it also happens with SPARC, especially framebuffer drivers. One way to work around this is to do:

# cd /platform/{sun4u,i86pc}
# mkdir glomname
# (cd kernel; tar cf - .) | (cd glomname; tar xf -)

and then install the Install glom image. This will copy your existing drivers to the new kernel installation, ensuring that the drivers which are not part of ON (or OpenSolaris as a whole) are available when you reboot.

Although it saves time, BFU is not a panacea. This section contains information about BFU's drawbacks. You should carefully evaluate these drawbacks against the benefits and decide whether BFU is appropriate to your needs. In general, unless you are an active developer, we recommend that you do not use BFU.

BFU does not update package information. Therefore you will most likely be unable to install official Solaris patches or run a full system upgrade procedure on a system which has been BFU'd. The importance of this cannot be overemphasized: IF YOU BFU YOUR SYSTEM, DO NOT ATTEMPT TO USE "NORMAL" SYSTEM MANAGEMENT PROCEDURES TO UPDATE IT IN THE FUTURE. USE BFU OR REINSTALL.

BFU does not update non-ON packages, even if newer versions of those packages are required in order to successfully install or run the version of ON you are installing. You may need to update those packages before and/or after running BFU. To understand what package updates may be needed, consult http://opensolaris.org/os/community/onnv/ for the full list of flag days between the build you are currently running and the build you wish to BFU to. Each flag day notice will instruct you as to what package updates, if any, are needed, and whether they must be completed before or after BFUing. It is critical that you read, understand, and follow these instructions exactly before running BFU. If you fail to do so you will almost certain brickify your system. See section 5.1.3 for more information about flag days.

Although the core functionality of BFU consists of the simple activity of unpacking cpio(1) archives into the running system, it also performs numerous other tasks related to the update of your system. Many of these tasks are specific to particular changes that have been made in the sources over a period of years. If your system has unusual characteristics, these additional updates can fail, which may result in a nonfunctional system. Because these updates vary greatly, it is impossible to know in advance which updates could fail, or what failure modes are possible. Although such failures are rare, they can occur. If you use BFU, you should follow the development of ON to understand changes being made that could have an adverse effect on your system. If you have doubts as to how well BFU will update a particular aspect of your system following a major change to ON, read bfu(1) and consult with the engineers who made the change.

When bfu finishes, it invokes ksh with a limited PATH. The PATH contains programs which have been specially modified to work regardless of what changes the BFU archives may contain. You can use these programs to resolve conflicts (see section 5.3.2). In particular, "reboot" works, but "init 6" does not. You can exit from this protected environment if you want, but it is not advisable unless you are sure that there have not been any "flag days" (synchronized kernel/userland changes) since your last bfu.

Never BFU in a window; always use the system console. If BFU or the system crashes in midstream, or you use the window system and it crashes or hangs, your system will be in an inconsistent state. You may be unable to boot. Therefore, you should ensure that as much of the system as possible is quiescent before starting a BFU, and be sure you have a copy of suitable system software media handy to reinstall if necessary.

Never BFU a production system. Production systems should always be updated to approved releases using the supported upgrade mechanism.

Every machine has several configuration files which get modified from the default installation; bfu keeps a list of these. This list is known as the conflicts database.

BFU saves a copy of each configuration file it would overwrite under /bfu.child; likewise, it stores a copy of each such file from the cpio archives it is extracting under /bfu.parent, having moved the previous BFU's /bfu.parent (if any) to /bfu.ancestor. We refer to the files saved under those directories as the child, parent and ancestor respectively.

When the extraction is complete, BFU diffs the various versions of these configuration files and acts according to the following rules:

* If the file is unchanged (i.e., there is no difference between the child and the parent), there is nothing to do or report.

* If the file was accepted from the parent the previous run (i.e., the child is identical to the ancestor) then the parent is accepted automatically this time; such files are marked as "update:".

* If the file is the same as the beginning of the previous file, it is assumed that the user has added lines to the end (i.e., the child consists of the parent plus some added lines); the child version is restored; such files are marked as "restore:".

* If the file differs between the parent and the child, but the parent and ancestor are identical, then it is deemed an old conflict; such files are marked as "old:".

* Lastly, if the file differs between the parent and the child, and the parent and ancestor differ as well, then it is deemed a NEW conflict; such files are marked as "NEW:".

So now we know that a NEW conflict means a file which was already different from the default, where the default has been updated. To resolve this difference, whatever changes were introduced in the new build must be ported to the existing file on the system.

Although it is possible to blindly accept the parent, this will cause any customizations in the child to be lost. As it is very common for these files to have such customizations made automatically by class action scripts from non-ON packages, this is usually a mistake, which can lead to hours of lost productivity. Therefore, there are two forms of conflict resolution which are discussed in the following two sections. They are automatic and manual conflict resolution.

If you elect to resolve conflicts manually, or if the automatic tools are unable to resolve all conflicts, you will benefit from having a proper BFU baseline installation. To establish such a baseline, you should install BFU archives corresponding to your distribution immediately after installing it. It is strongly recommended that you begin this process only if your installation is sufficiently recent that such BFU archives are available. In particular, BFUing a system older than Solaris 11 build 16 will fail and may render your system unbootable.

When BFUing to the same build as your distribution include, you can ignore all conflicts, since your existing installed configuration files are known to work correctly for this build. You must then reboot before BFUing to a later build.

% diff /bfu.ancestor/$file /bfu.parent/$file

% diff $file /$file

% sort -k1,1 /etc/name_to_major | sort -uc -k1,1
% sort -k2n /etc/name_to_major | sort -uc -k2n

The contents of each zone are copied from the global zone when the zone is created. To ensure that all zones remain operational after BFUing, it is necessary to keep the zone contents consistent with those in the global zone. To do this, BFU will update each zone in turn once the global zone has been updated; however, because each zone may have configuration files that differ from the global zone's, each zone has its own BFU conflict management directories. Unfortunately, it is not possible to BFU only a single zone. BFU affects the entire system including all zones. If you want to test userspace changes in a zone, you will need to copy files from your proto area into that zone manually.

It is safest to shut down all zones before BFUing your system. This will ensure that dependencies which may be violated by the files being installed will not break a zone.

After BFUing a system with zones other than the global zone, you will need to first resolve conflicts in the global zone, then resolve conflicts in each remaining zone before rebooting the system. Resolving BFU conflicts in a zone works exactly the same way as for the global zone; however, in many cases it will not be necessary to manually merge the file contents. Instead you are likely to find that the file should be identical to that in the global zone, and you can simply copy it over. After resolving conflicts in all zones, you must reboot your system before rebooting any zone.

One of the attributes included in many Solaris man pages is "Interface Stability." The value of this attribute defines who may depend on the interface, and what expectations they may have for its future maintenance. The possible values and their explanations are described here; note that the Private levels will not appear in man pages shipped to customers.

In the absence of any evidence about an interface's stability level, certain assumptions must be made. Following the general rule "be strict in what you produce, and liberal in what you accept" would lead one to conclude that any documented interface is Stable, and undocumented interfaces are probably being used by others, but could be changed at any time without your knowledge (i.e. they are at once both Project Private and Unstable); as a consequence you should neither change the interface nor depend on its current implementation. If you need to depend on or change an undocumented interface whose stability level cannot be determined, you need to find that interface's owner, if any, and have the action approved by the relevant ARC. If the owner of the interface can be found, you will most likely want to promote the interface either to Open (public) status, or use one of the Contracted Private stability levels.

Following is a list of stability levels and their respective meanings. Additional information is available in the attributes(5) man page, including the precise public definitions of major, minor, and micro releases and additional information about Open interfaces.

Stability Level: Standard

----------------------------------------------------------------
Specification		Open
----------------------------------------------------------------
Incompatible Change	major release (X.0)
----------------------------------------------------------------
Compatible Change	minor release (x.Y)
----------------------------------------------------------------
ARC review of Specs	A precise reference is normally recorded
----------------------------------------------------------------
Examples	POSIX, ANSI-C, ABI, SCD, SVID, XPG, X11, DKI, VMEbus,
		Ethernet, NFS protocol, DPS
----------------------------------------------------------------

Most of these interfaces are defined by a formal standard, and controlled by a standards organization. Incompatible changes to these interfaces are rare.

This stability classification can also apply to interfaces that have been adopted (without a formal standard) by an "industry convention" (X/Open, MIT X-Consortium, OMG), or even by a single-source (Adobe's Display PostScript, Novell's NetWare Protocols, Legato's network backup protocols, Berkeley's sendmail) if we expect that the de facto standard is unlikely to change incompatibly.

If possible, there should still be a reference to a standard specification or reference system, although there may be cases where no such citation is possible. Customers are normally pointed to the same specification.

Support is only provided for specific version(s) of a standard, and support for a particular version does not guarantee that support will be provided for other versions. Sometimes bugs are corrected or interpretation is clarified in a standard; we may make incompatible changes to react to these, but will evaluate the impact of doing so and will announce a compatibility and migration strategy. (PSARC/1995/224's Advisory Information section provides guidelines for implementing a preliminary draft of a new standard.)

Some standards lack bindings to a specific programming language; if the project team chose names, numbers, extensions, or other implementation-specific details, they should be called out for architectural review.

Stability Level: Stable

----------------------------------------------------------------
Specification		Open
----------------------------------------------------------------
Incompatible Change	major release (X.0)
----------------------------------------------------------------
Compatible Change	minor release (x.Y)
----------------------------------------------------------------
ARC review of Specs	Yes
----------------------------------------------------------------
Examples		cc options, Sbus, XGL API; most bundled
			commands
----------------------------------------------------------------

We publish the specification of these interfaces, typically as manual pages or other product documentation. We also tell customers we will remain compatible with them.

The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release), without having to change or recompile the applications. Even at a major release, incompatible changes are expected to be rare, and to have strong justifications. Stable interfaces are sometimes proposed to be industry Standards, as was the case with ToolTalk (now an X/Open standard).

An ARC should review and archive the specification, and adequate customer documentation must also exist.

These are interfaces whose specification is generally controlled within OpenSolaris, and does not rely on externally delivered projects.

Stability Level: Evolving

----------------------------------------------------------------
Specification		Open
----------------------------------------------------------------
Incompatible Change	minor release (x.Y), with impact
			assessment
----------------------------------------------------------------
Compatible Change	minor release (x.Y)
----------------------------------------------------------------
ARC review of Specs	Yes
----------------------------------------------------------------
Examples		core and .il file formats, Solaris DDI &
			DGA; many GUIs, admin utils, config
			files, daemons; most of PAM
----------------------------------------------------------------

An Evolving interface is subject to incompatible change at a major or minor release, but we should expect to change an Evolving interface only carefully, and probably slowly. As the interface evolves, we will make reasonable efforts to ensure that all changes are source and binary compatible.

An ARC should review the interface specification (especially with respect to ability to absorb expected evolution compatibly). Adequate customer documentation should also exist. The intention of an Evolving interface is to enable ISV's to exploit new technology, and it should be expected that they will ship products that depend on these interfaces. As a result, any incompatible change to an Evolving interface requires an assessment of potential customer impact, and a notification and migration plan. Elements of such a plan might include:

* clearly setting customer expectations about the circumstances under which the interfaces might change.

* ensuring that all such changes are described in the release notes for the affected release.

* providing migration aids for binary compatibility and/or continued source development.

A project's intention to accept the risk of depending on an Evolving interface must be evaluated and explicitly approved by an ARC.

NOTE: It will often be the case that interfaces declared to be Evolving will later be reclassified as Stable or Standard. Nonetheless, foreseen promotion is not a necessary attribute of the Evolving taxonomy level. An interface could be classified Evolving and remain as such indefinitely.

Stability Level: Unstable

----------------------------------------------------------------
Specification		Open
----------------------------------------------------------------
Incompatible Change	minor release (x.Y)
----------------------------------------------------------------
Compatible Change	micro release (x.y.Z)
----------------------------------------------------------------
ARC review of Specs	Yes
----------------------------------------------------------------
Examples		SUNW* package abbreviations,
			some config utils
----------------------------------------------------------------

Unstable interfaces are experimental or transitional. They are typically used to give developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next.

The intention of an Unstable interface is that they be imported only by prototypes and by products on the same CD (or whatever release medium) as the interface implementation. A project's intention to import an Unstable interface should be discussed with the ARC early. The stability classification of the interface -- or a replacement interface -- might be raised. The opinion allowing any project to import an Unstable interface should explain why it is acceptable.

Any documentation for an Unstable interface must contain warnings that these interfaces are subject to change without warning and should not be used in unbundled products. In some situations, it may be appropriate to document Unstable interfaces in White Papers rather than in standard product documentation.

Given such caveats, customer impact need not be a factor when considering incompatible changes to an Unstable interface in a major or minor release. Nonetheless, when such changes are introduced, the changes should still be mentioned in the release notes for the affected release.

An ARC should review and archive the specification. Any proposed change to the interface must be ARC approved.

NOTE: If we choose to offer a draft standard implementation but state our intention to track the standard (or the portions we find technically sound or likely to be standardized), we set customer expectations for incompatible changes by classifying the interface Unstable. The interface should be reclassified Standard when standard is final. Such an intention could be encoded "Unstable->Standard".)

Stability Level: External

----------------------------------------------------------------
Specification		Open
----------------------------------------------------------------
Incompatible Change	micro release (x.y.z)
----------------------------------------------------------------
Compatible Change	micro release (x.y.z)
----------------------------------------------------------------
Arc review of Specs	A precise reference is normally recorded
----------------------------------------------------------------
Examples		OpenSSL
----------------------------------------------------------------

These interfaces are controlled by a body outside of OpenSolaris, but unlike Standard, it can not be asserted that an incompatible change to the interface would be exceedingly rare. In some cases it may not even be possible to clearly identify the controlling body. This classification is typically used for third-party open source components integrated wholesale into an OpenSolaris consolidation.

Use of the External interface stability level allows freeware interfaces provided by Sun to quickly track the fluid, external specification. In many cases, this is preferred to providing additional stability to the interface, as it tends to track the expectations of the community. However, External interfaces should adhere to OpenSolaris standards in at least the following areas:

* Security, Authentication * Manual Page Section Numbering * File System Semantics (/usr may be read-only, /var is where all significant run-time growth occurs, ...)

All External interfaces should be labeled as such in all associated documentation and the consequence of using such interfaces should be explained either as part of that documentation or by reference. Default search paths should not lead to External interfaces - the user should be required to take some simple, explicit action to access them.

Shipping incompatible change in a patch should be strongly avoided. It is not strictly prohibited for the following two reasons:

* Since we are not in explicit control of the changes, we can not guarantee with reasonable assurance that an unidentified incompatibility isn't present.

* A strong business case may exist for shipping a newer version as a patch if that newer version closes significant escalations.

In general, the intent of allowing change in a patch is to allow for change in Update Releases.

It should be noted that in some cases it will be preferable to apply a less fluid interface classification to an interface even if the controlling body is external to OpenSolaris. Use of the Unstable classification extends the stability commitment over micro/patch releases, allowing use of additional support models for software that depends upon these interfaces, at the potential cost of less frequent updates. However, care should be exercised because it will be difficult to differentiate External and Unstable as a classification for seemingly identical software. It is suggested to use External and behave (through contracts) as Unstable. Use of the Evolving classification promotes these interfaces to first class OpenSolaris interfaces, at the potential cost of diverging from the external specification. By using Evolving, we are essentially taking control of the interface, although it may liberally import from the external reference. Use of the Stable classification is not recommended.

Stability Level: Contracted External

This stability level is the same as External, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to place restrictions on how and when an interface may change if the normal rules for External do not satisfy the requirements of the consumer.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Obsolete

----------------------------------------------------------------
Specification		Open, along with warning of obsolescence
----------------------------------------------------------------
Incompatible Change	minor release (x.Y)
----------------------------------------------------------------
Compatible Change	By former classification, but unlikely
----------------------------------------------------------------
ARC review of Specs	Normally downgraded from a higher
			stability; ARC approval of interface or
			feature removal is also required.
----------------------------------------------------------------
Examples		RFS, System-V LP protocol
----------------------------------------------------------------

An interface that is "deprecated" and/or no longer in general use. An existing interface may be downgraded from some other status (such as Stable or Standard) to Obsolete to encourage customers to migrate from that interface before it will be removed (or incompatibly changed).

In addition to reclassifying the interface Obsolete and documenting the new classification in customer documentation, a pro-active program to communicate to customers the change in commitment must precede the incompatible change or removal in a minor release. For some interfaces, the ARC may find such a communication program appropriate before removing an interface, even at a major release.

The standard program to communicate a change in commitment requires:

1. Demonstration of support by the Steering Committee responsible for the deliverable(s) containing the interface. Such support can be demonstrated by a change to strategy document or resolutions taken in meetings and documented in the minutes.

2. One year's notice to the customer base and the Sun product development community of the intended obsolescence of the interface. This requirement ensures that no further commitments against the interface are created and gives those affected by future removal of the facility a chance to make alternative arrangements.

The year must elapse after the notice and prior to the delivery of a product that contains a change incompatible with the present status of the interface.

Acceptable means of customer notice includes letters to customers on support contracts, release notes or product documentation, or announcements to customer forums appropriate for the interface in question.

The notice of obsolescence is considered to be "public" information in that it is available freely to the customers. It is not intended that this require specific actions to "publish" the information, such as press releases or similar forms of publicity.

3. Where technically feasible, inclusion in the release where the interface is declared Obsolete of a warning mechanism if the interface is used. The mechanism should produce a message of the form "The application uses interface which has been declared obsolete and may not be present in versions of released after [event]. Please notify your support person. See in [reference] for more information." One suggested method is to use syslog(3), with a level of "LOG_WARNING". A method for turning off the warning message should also be provided. Common sense should apply in determining how often the warning should appear.

4. Information in the User Documentation that contains the following:

* An explanation of the meaning of Obsolete.

* An indication of the kinds of warning messages that may appear.

* A suggesting that the customer ask their support person to contact the vendor of any application that causes such a warning to appear.

* General instructions for turning off the warning messages.

* A list of the Obsolete interfaces contained in this release, the earliest that they may disappear, the kind of warning that might appear, and the method for disabling the warning.

Proposals to downgrade an interface through this mechanism must be approved by an ARC before "core" documentation may be altered to identify the interface as Obsolete. Release notes may warn of the possibility of removal with either ARC or Steering Committee approval. A warning that the interface *may* be removed in a future release could be included without ARC approval, but the ARC may not deem such notice alone as sufficient notification to customers to "start the 1-year clock".

A follow-on project to perform the actual feature removal in a forthcoming minor or major release after the timeout period expires, requires architectural approval to ensure that the requirements of the obsolescence policy have been met. Provided they have been met, approval will be straightforward.

Stability Level: Committed Private

----------------------------------------------------------------
Specification		Closed
----------------------------------------------------------------
Incompatible Change	major release (X.0)
----------------------------------------------------------------
Compatible Change	micro release (x.y.Z)
----------------------------------------------------------------
ARC review of Specs	Yes
----------------------------------------------------------------
Example			UFS media format,
			Calendar Manager RPC protocol
----------------------------------------------------------------

For some otherwise-private interfaces, we must maintain compatibility from release to release, in order to meet the customer's expectations for compatibility of the programs using these interfaces. However, we don't want customers to depend on these interfaces directly, and we don't want to directly expose these interfaces to customers. These interfaces are classified as Committed Private.

Our commitment is that a customer's "normal" use of system facilities should not allow them to see any incompatible changes to these interfaces. Since these interfaces typically span machines by being embodied in media or protocols (and since customers cannot upgrade all their machines simultaneously), these interfaces can't be changed with the freedom of a private interface. Yet, changes to the details of the interface can be dramatic, provided the commitment to the customer is maintained. In general, Committed Private interfaces should be versioned.

An ARC should review and archive the specification, and will at least assure that the interface can satisfy its purpose and support the evolution described in the previous paragraph. Any proposed change to or new dependency on the interface must be ARC approved.

Stability Level: Contracted Committed Private

This stability level is the same as Committed Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a Sun Partner.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Sun Private

----------------------------------------------------------------
Specification		Closed
----------------------------------------------------------------
Incompatible Change	minor release (x.Y)
----------------------------------------------------------------
Compatible Change	micro release (x.y.Z)
----------------------------------------------------------------
ARC review of Specs	Yes
----------------------------------------------------------------
Example		trap 40 (gethrtime)
----------------------------------------------------------------

These are interfaces which one consolidation depends on and another consolidation provides. Changes to these interfaces must be coordinated among all providers and users of the interface. Some internal kernel interfaces are Sun Private interfaces.

Interfaces are occasionally made Sun Private in order to gain some experience with them before opening them up to wider use as Unstable or Stable interfaces. Making such interfaces Consolidation Private would be preferable, however, as evolution is then far easier.

Sun Private interfaces are strongly discouraged. Coordinating changes to these interfaces within a consolidation is usually feasible, but coordinating changes among different consolidations released asynchronously is extremely difficult. Interface versioning is advised for Sun Private interfaces.

An ARC will review and archive these interfaces, with special attention to how the interface could evolve, if necessary. Any proposed change to the interface must be ARC approved.

Stability Level: Contracted Sun Private

This stability level is the same as Sun Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a partner.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Consolidation Private

----------------------------------------------------------------
Specification		Closed
----------------------------------------------------------------
Incompatible Change	micro release (x.y.Z) or "jumbo patch"
----------------------------------------------------------------
Compatible Change	micro release (x.y.Z) or "jumbo patch"
----------------------------------------------------------------
ARC review of Specs	Not necessary
----------------------------------------------------------------
Examples		libdeskset, kernel nameslists
----------------------------------------------------------------

These are interfaces internal to the consolidation that one piece of a consolidation depends on and another piece of the same consolidation provides. Changes to these interfaces must be coordinated among all providers and users of the interface. Many internal kernel interfaces are Consolidation Private interfaces.

Generally these are interfaces that have proven convenient for building the consolidation, but which change often enough that we're not willing to document them for external use nor to commit to their stability. libdeskset is an example of such an interface. Though the libkvm API is Public, the undocumented names that can be accessed through that interface are Consolidation or Project Private.

An ARC may review and archive these interfaces, or may leave the consolidation to monitor their own internal commitments. If a Consolidation Private interface is reviewed by the ARC, ask that ARC if they want to review later changes to that interface.

Importing the interface by any project outside the Consolidation would require negotiating a "contract" with the interface providers. An ARC must review and approve the classification change to Contracted Consolidation Private and the terms of the contract.

Stability Level: Contracted Consolidation Private

This stability level is the same as Consolidation Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a specific consumer in a different consolidation.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Project Private

----------------------------------------------------------------
Specification		Closed
----------------------------------------------------------------
Incompatible Change	micro release (x.y.Z)
----------------------------------------------------------------
Compatible Change	micro release (x.y.Z) or patch
----------------------------------------------------------------
ARC review of Specs	No
----------------------------------------------------------------
Examples		Metamucil ioctls, nfssys system call,
			uadmin cpu control functions
----------------------------------------------------------------

Project Private interfaces usually occur when a project must communicate between its components across a boundary in the system. For instance, Metamucil includes several new ioctls to perform operations on UFS filesystems. The Metamucil ufsdump program uses these ioctls. The ioctls are private interfaces since they are intended to be used only by the Metamucil product. If the Metamucil product needs to change these ioctls in the future, they can do so without coordinating with any other projects, since no other projects may use these ioctls. Likewise, the nfssys system call is used to communicate between the kernel- and user-level portions of NFS.

Project Private interfaces also occur in libraries where one module needs to call a private routine in another module in the same library.

Also, Project Private interfaces may be provisional or in transition. The uadmin cpu control functions are Project Private because they will change form before appearing as Standard interfaces, and in the meantime we don't want anyone depending on them.

Sadly, many kernel procedures are Project Private interfaces (instead of Internal interfaces) because they are visible to dynamically loaded kernel modules.

Once an interface is classified Project Private by an ARC, changes to that interface need not be ARC approved.

Any use of the interface from outside the project would involve negotiating a "contract" with the interface providers; an ARC must review and approve the classification change to Contracted Project Private and the terms of the contract.

Stability Level: Contracted Project Private

This stability level is the same as Project Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a specific consumer in a different consolidation.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Libraries delivered by ON contain symbol versioning information that limits the exposure of private interfaces and provides tracking of changes to public interfaces. This versioning information is embodied in the specfiles and mapfiles found under usr/src/lib/*/spec.

Two tools for checking many elements of the coding style are available as part of the ON tools. These tools are cstyle(1) for verifying compliance of C code with most style guidelines, and hdrchk(1) for checking the style of C and C++ headers. Note that these tools are not perfect; there are style mistakes that cannot be caught by any reasonable tool, and others that cannot be caught by the particular implementations. Improving the accuracy and completeness of these tools is an ongoing task and enhancements of all kinds are welcome.

All headers are expected to pass 'hdrchk'. All C files and headers are expected to pass 'cstyle -P -p'. These tools produce no output and exit with status code 0 if the file(s) checked meet the style requirements.

7.2.2 =head3 Style Examples

A few common examples of bad style which are not currently caught by the tools include:

* Mixing declaration of initialized and uninitialized variables on the same line; for example:

int a, b = 16, c = -4, d;

Instead, uninitialized variables may be declared one or more per line, and each initialized variable should be declared on its own line:

int a, d;
int b = 16;
int c = -4;

or

int a;
int b = 16;
int c = -4;
int d;

* Inconsistent use of acceptable styles. In the above example, two acceptable ways to declare variables are presented. Good style dictates that whichever is used by used everywhere within a file; however, the tools do not check for such consistency.

* Incorrect placement and use of braces around if/else constructs. The heuristic test for this is not run by default, and is not completely reliable. For simplicity's sake, here is the correct format for if/else in which both alternatives are compound statements:

if (x != SOME_CONSTANT) {
	do_stuff();
	return (x);
} else {
	do_other_stuff();
	x = OTHER_CONSTANT;
}

If neither alternative is a compound statement, use:

if (x != SOME_CONSTANT)
	do_stuff();
else
	do_other_stuff();

Finally, if only one alternative is a compound statement, both alternatives should have braces, formatted as shown:

if (x != SOME_CONSTANT) {
	do_stuff();
	return (x);
} else {
	do_other_stuff();
}

Note the placement of braces; they should surround an "else" and only the closing brace should be on a line by itself.

* Use of comments associated with conditional compilation directives. It is good style to include trailing comments after #else and #endif directives describing the condition it references; for example:

#ifdef __FOO
...
#else	/* !__FOO */
...
#endif	/* !__FOO */

The style tools do not check for the presence, usefulness, or correctness of these trailing comments, but you should normally include them, especially if the intervening code blocks are lengthy or the tests are part of a complicated set of nested preprocessor conditionals.

* Incorrect guards in header files. Guard names should be derived from the header name, but hdrchk does not check this. For example, a header installed in <sys/scsi/foo_impl.h> should have a guard as follows:

#ifndef _SYS_SCSI_FOO_IMPL_H
#define _SYS_SCSI_FOO_IMPL_H
...
#endif /* _SYS_SCSI_FOO_IMPL_H */

However, hdrchk verifies neither the actual guard token name nor the comment following #endif.

* Comment style is only partially checked. For example, the correct style for block comments is:

/*
 * Some comment here.
 * More here.
 */

cstyle(1) can detect some common errors, such as enclosing the entire block comment in a box of asterisks or other characters. However, it cannot detect all such errors; for example:

/*
   Some comment here.
   We conserve asterisks even though it's harder to read.
   Our comment is nonconforming.
 */

Correct indentation of comments is also unchecked; block and single-line comments within functions should be indented at the same level as the code they document. Trailing comments should be aligned with other trailing comments in related code. None of these style guidelines is checked by the tools.

It probably goes without saying that the contents of comments aren't checked in any way. Please, be sure to follow the comment content guidelines in the style guide.

cstyle(1) and hdrchk(1) will, in addition to several code-formatting guidelines, verify compliance with SCCS keyword and copyright requirements. All files must be under SCCS control, and each must have a set of keywords near the top (see the prototypes for the exact order of file contents). In general, the keywords should have the following format in C files and headers:

@PRAGMA_IDENT_EXP@

Note that this string actually contains several embedded tabs; showing these tabs as \t, the keywords look like:

@PRAGMA_IDENT@

Files which are not C (or C++) implementations or headers should dispense with the "pragma" portion and just use #ident as follows:

@IDENT@

In addition, each file must contain a statement of copyright at the very top. The acceptable text and formats for these copyrights are shown in the example files in usr/src/prototypes. When a source file is significantly updated, the year or range of years in the copyright should be replaced with just the current year at the time of modification. Significant updates do not include formatting changes. However, if you prefer not to think about whether your change constitutes a significant update or if you don't trust your judgment, erring on the side of always updating the year is acceptable. Since the prototypes assume that Sun is always the sole copyright holder, you will need to change the copyright statement slightly; for example, if a file initially contains:

/*
 * Copyright (c) 1992-1998 by Sun Microsystems, Inc.
 * All rights reserved.
 */

you should replace this notice with:

/*
 * Copyright 2005 Sun Microsystems, Inc.
 * All rights reserved.  Use is subject to license terms.
 */

and, if you are a contributor not employed by Sun, you should also add:

/*
 * Copyright 2005 J. Random Hacker
 * All rights reserved.  Use is subject to license terms.
 */

or a similar statement of your copyright. Do not combine copyright notices, and do not remove the existing copyright notices unless specifically instructed to do so.

Before submitting any changes for code review prior to inclusion in OpenSolaris, you should self-review your code for stylistic correctness (as well as semantic correctness!). Running the cstyle(1) and/or hdrchk(1) tools is part of this process, but you should also be familiar with the entire style guide so that you will be able to use correct style even in elements that the tools do not check. All new code must be cstyle- and, if applicable, hdrchk-clean. If you are modifying existing code which does not conform to the style guide, your changes should be conformant, and at worst your changes should not increase the number of cstyle or hdrchk warnings.