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.