NIGHTLY(1ONBLD) illumos Build Tools NIGHTLY(1ONBLD)


NAME


nightly - build an OS-Net consolidation overnight

SYNOPSIS


nightly [-in] [-V VERS] <env_file>

DESCRIPTION


nightly, the mother of all build scripts, can bringover, build, archive,
package, error check, and generally do everything it takes to turn OS/Net
consolidation source code into useful stuff. It is customizable to
permit you to run anything from a simple build to all of the cross-
checking a gatekeeper needs. The advantage to using nightly is that you
build things correctly, consistently and automatically, with the best
practices; building with nightly can mean never having to say you're
sorry to your gatekeeper.

More specifically, nightly performs the following tasks, in order, if all
these things are desired:


+o perform a "make clobber" to clean up old binaries

+o bringover from the identified parent gate/clone

+o perform non-DEBUG and DEBUG builds

+o list proto area files and compare with previous list

+o copy updated proto area to parent

+o list shared lib interface and compare with previous list

+o perform a "make lint" of the kernel and report errors

+o perform a "make check" to report hdrchk/cstyle errors

+o report the presence of any core files

+o check the ELF runtime attributes of all dynamic objects

+o check for unreferenced files

+o report on which proto area objects have changed (since the
last build)

+o report the total build time

+o save a detailed log file for reference

+o mail the user a summary of the completed build

The actions of the script are almost completely determined by the
environment variables in the env file, the only necessary argument. Ths
only thing you really need to use nightly is an env file that does what
you want.

Like most of the other build tools in usr/src/tools, this script tends to
change on a fairly regular basis; do not expect to be able to build
OS/Net with a version of nightly significantly older than your source
tree. It has what is effectively a Consolidation Private relationship to
other build tools and with many parts of the OS/Net makefiles, although
it may also be used to build other consolidations.

NIGHTLY_OPTIONS
The environment variable NIGHTLY_OPTIONS controls the actions nightly
will take as it proceeds. The -i, -n, +t and -V options may also be used
from the command line to control the actions without editing your
environment file. The -i and -n options complete the build more quickly
by bypassing some actions. If NIGHTLY_OPTIONS is not set, then "-Bmt"
build options will be used.

Basic action options

-D Do a build with DEBUG on (non-DEBUG is built by default)

-F Do _not_ do a non-DEBUG build (use with -D to get just a DEBUG
build)

-M Do not run pmodes (safe file permission checker)

-i Do an incremental build, suppressing the "make clobber" that by
default removes all existing binaries and derived files. From
the command line, -i also suppresses the lint pass and the
cstyle/hdrchk pass

-n Suppress the bringover so that the build will start immediately
with current source code

-p Create packages for regular install

-U Update proto area in the parent workspace

-u Update the parent workspace with files generated by the build,
as follows.

+o Copy proto_list_${MACH} and friends to usr/src in the
parent.

+o When used with -f, build a usr/src/unrefmaster.out in
the parent by merging all the usr/src/unref-${MACH}.out
files in the parent.

+o When used with -A or -r, copy the contents of the
resulting ELF-data.${MACH} directory to usr/src/ELF-
data.${MACH} in the parent workspace.

-m Send mail to $MAILTO at end of build

-t Build and use the tools in $SRC/tools (default setting).

+t Use the build tools in "$ONBLD_TOOLS/bin".


Code checking options

-A Check for ABI discrepancies in .so files. It is only required
for shared object developers when there is an addition,
deletion or change of interface in the .so files.

-C Check for cstyle/hdrchk errors

-f Check for unreferenced files. Since the full workspace must be
built in order to accurately identify unreferenced files, -f is
ignored for incremental (-i) builds, or builds that do not
include -l, and -p.

-r Check the ELF runtime attributes of all dynamic objects

-l Do "make lint" in $LINTDIRS (default: $SRC n)

-N Do not run protocmp or checkpaths (note: this option is not
recommended, especially in conjunction with the -p option)

-w Report which proto area objects differ between this and the
last build. See wsdiff(1ONBLD) for details. Note that the
proto areas used for comparison are the last ones constructed
as part of the build. As an example, if both a non-debug and
debug build are performed (in that order), then the debug proto
area will be used for comparison (which might not be what you
want).

Groups of options

-G Gate keeper default group of options (-u)

-I Integration engineer default group of options (-mpu)

-R Default group of options for building a release (-mp)


Miscellaneous options

-V VERS set the build version string to VERS, overriding VERSION


ENVIRONMENT VARIABLES


Here is a list of prominent environment variables that nightly references
and the meaning of each variable. CODEMGR_WS
The root of your workspace, including whatever metadata is kept by
the source code management system. This is the workspace in which
the build will be done.

PARENT_WS
The root of the workspace that is the parent of the one being built.
This is particularly relevant for configurations with a main
workspace and build workspaces underneath it; see the -u and -U
options as well as the PKGARCHIVE environment variable, for more
information.

BRINGOVER_WS
This is the workspace from which nightly will fetch sources to
either populate or update your workspace; it defaults to $CLONE_WS.

CLONE_WS
This is the workspace from which nightly will fetch sources by
default. This is often distinct from the parent, particularly if
the parent is a gate.

SRC
Root of OS-Net source code, referenced by the Makefiles. It is the
starting point of build activity. It should be expressed in terms
of $CODEMGR_WS.

ROOT
Root of the proto area for the build. The makefiles direct
installation of build products to this area and direct references to
these files by builds of commands and other targets. It should be
expressed in terms of $CODEMGR_WS.

If $MULTI_PROTO is "no", $ROOT may contain a DEBUG or non-DEBUG
build. If $MULTI_PROTO is "yes", $ROOT contains the DEBUG build and
$ROOT-nd contains the non-DEBUG build.

TOOLS_ROOT
Root of the tools proto area for the build. The makefiles direct
installation of tools build products to this area. Unless +t is
part of $NIGHTLY_OPTIONS, these tools will be used during the build.

As built by nightly, this will always contain non-DEBUG objects.
Therefore, this will always have a -nd suffix, regardless of
$MULTI_PROTO.

MACH
The instruction set architecture of the build machine as given by
uname -p, e.g. sparc, i386.

LOCKNAME
The name of the file used to lock out multiple runs of nightly.
This should generally be left to the default setting.

ATLOG
The location of the log directory maintained by nightly. This
should generally be left to the default setting.

LOGFILE
The name of the log file in the $ATLOG directory maintained by
nightly. This should generally be left to the default setting.

STAFFER
The non-root account to use on the build machine for the bringover
from the clone or parent workspace. This may not be the same
identify used by the SCM.

MAILTO
The address to be used to send completion e-mail at the end of the
build (for the -m option).

MAILFROM
The address to be used for From: in the completion e-mail at the end
of the build (for the -m option).

REF_PROTO_LIST
Name of file used with protocmp to compare proto area contents.

PARENT_ROOT
The parent root, which is the destination for copying the proto
area(s) when using the -U option.

PARENT_TOOLS_ROOT
The parent tools root, which is the destination for copying the
tools proto area when using the -U option.

RELEASE
The release version number to be used; e.g., 5.10.1 (Note: this is
set in Makefile.master and should not normally be overridden).

VERSION
The version text string to be used; e.g., "onnv:`date '+%Y-%m-%d'`".

RELEASE_DATE
The release date text to be used; e.g., October 2009. If not set in
your environment file, then this text defaults to the output from
$(LC_ALL=C date +"%B %Y"); e.g., "October 2009".

RELEASE_BUILD
Define this to build a release with a non-DEBUG kernel. Generally,
let nightly set this for you based on its options.

PKGARCHIVE
The destination for packages. This may be relative to $CODEMGR_WS
for private packages or relative to $PARENT_WS if you have different
workspaces for different architectures but want one hierarchy of
packages.

MAKEFLAGS
Set default flags to make; e.g., -k to build all targets regardless
of errors.

UT_NO_USAGE_TRACKING
Disables usage reporting by listed Devpro tools. Otherwise it sends
mail to some Devpro machine every time the tools are used.

LINTDIRS
Directories to lint with the -l option.

BUILD_TOOLS
BUILD_TOOLS is the root of all tools including the compilers; e.g.,
/ws/onnv-tools. It is used by the makefile system, but not nightly.

ONBLD_TOOLS
ONBLD_TOOLS is the root of all the tools that are part of SUNWonbld;
e.g., /ws/onnv-tools/onbld. By default, it is derived from
BUILD_TOOLS. It is used by the makefile system, but not nightly.

SPRO_ROOT
The gate-defined default location for the Sun compilers, e.g.
/ws/onnv-tools/SUNWspro. By default, it is derived from
BUILD_TOOLS. It is used by the makefile system, but not nightly.

JAVA_ROOT
The location for the java compilers for the build, generally
/usr/java.

OPTHOME
The gate-defined default location of things formerly in /opt; e.g.,
/ws/onnv-tools. This is used by nightly, but not the makefiles.

TEAMWARE
The gate-defined default location for the Teamware tools; e.g.,
/ws/onnv-tools/SUNWspro. By default, it is derived from OPTHOME.
This is used by nightly, but not the makefiles. There is no
corresponding variable for Mercurial or Subversion, which are
assumed to be installed in the default path.

ON_CLOSED_BINS
OpenSolaris builds do not contain the closed source tree. Instead,
the developer downloads a closed binaries tree and unpacks it.
ON_CLOSED_BINS tells nightly where to find these closed binaries, so
that it can add them into the build.

CHECK_PATHS
Normally, nightly runs the 'checkpaths' script to check for
discrepancies among the files that list paths to other files, such
as exception lists and req.flg. Set this flag to 'n' to disable
this check, which appears in the nightly output as "Check lists of
files."

CHECK_DMAKE
Nightly validates that the version of dmake encountered is known to
be safe to use. Set this flag to 'n' to disable this test, allowing
any version of dmake to be used.

MULTI_PROTO
If "no" (the default), nightly will reuse $ROOT for both the DEBUG
and non-DEBUG builds. If "yes", the DEBUG build will go in $ROOT
and the non-DEBUG build will go in $ROOT-nd. Other values will be
treated as "no".

NIGHTLY HOOK ENVIRONMENT VARIABLES


Several optional environment variables may specify commands to run at
various points during the build. Commands specified in the hook variable
will be run in a subshell; command output will be appended to the mail
message and log file. If the hook exits with a non-zero status, the
build is aborted immediately. Environment variables defined in the
environment file will be available.

SYS_PRE_NIGHTLY
Run just after the workspace lock is acquired. This is reserved for
per-build-machine customizations and should be set only in
/etc/nightly.conf

PRE_NIGHTLY
Run just after SYS_PRE_NIGHTLY.

PRE_BRINGOVER
Run just before bringover is started; not run if no bringover is
done.

POST_BRINGOVER
Run just after bringover completes; not run if no bringover is done.

POST_NIGHTLY
Run after the build completes, with the return status of nightly -
one of "Completed", "Interrupted", or "Failed" - available in the
environment variable NIGHTLY_STATUS.

SYS_POST_NIGHTLY
This is reserved for per-build-machine customizations, and runs
immedately after POST_NIGHTLY.

FILES


/etc/nightly.conf

If present, nightly executes this file just prior to executing the env
file.

EXAMPLES


Start with the example file in usr/src/tools/env/developer.sh (or
gatekeeper.sh), copy to myenv and make your changes.

# grep NIGHTLY_OPTIONS myenv
NIGHTLY_OPTIONS="-ACrlapDm"
export NIGHTLY_OPTIONS
# /opt/onbld/bin/nightly -i myenv

SEE ALSO


bldenv(1ONBLD)


January 28, 2014 NIGHTLY(1ONBLD)