--- /dev/null	Tue Oct 30 04:01:32 2018
+++ new/tools/README.nightly	Tue Oct 30 04:01:32 2018
@@ -0,0 +1,356 @@
+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:
+
+
+	      •	     perform a "make clobber" to clean up old binaries
+
+	      •	     bringover from the	identified parent gate/clone
+
+	      •	     perform non-DEBUG and DEBUG builds
+
+	      •	     list proto	area files and compare with previous list
+
+	      •	     copy updated proto	area to	parent
+
+	      •	     list shared lib interface and compare with	previous list
+
+	      •	     perform a "make lint" of the kernel and report errors
+
+	      •	     perform a "make check" to report hdrchk/cstyle errors
+
+	      •	     report the	presence of any	core files
+
+	      •	     check the ELF runtime attributes of all dynamic objects
+
+	      •	     check for unreferenced files
+
+	      •	     report on which proto area	objects	have changed (since
+		     the last build)
+
+	      •	     report the	total build time
+
+	      •	     save a detailed log file for reference
+
+	      •	     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.
+
+		 •	Copy proto_list_${MACH}	and friends to usr/src in the
+			parent.
+
+		 •	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.
+
+		 •	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.
+
+       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.
+
+       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."
+
+       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
