" The contents of this file are subject to the terms of the
" Common Development and Distribution License (the "License").
" You may not use this file except in compliance with the License.
"
" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
" or http://www.opensolaris.org/os/licensing.
" See the License for the specific language governing permissions
" and limitations under the License.
"
" When distributing Covered Code, include this CDDL HEADER in each
" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
" If applicable, add the following below this CDDL HEADER, with the
" fields enclosed by brackets "[]" replaced with your own identifying
" information: Portions Copyright [yyyy] [name of copyright owner]
"
" CDDL HEADER END
"
"Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
"Copyright 2012 Joshua M. Clulow <josh@sysmgr.org>
"Copyright 2019 Peter Tribble.
"Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
"Copyright 2024 Bill Sommerfeld <sommerfeld@hamachi.org>
"
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 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)
compare the proto area with package manifests
lint the generated packages
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.
10 -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)
-L Do not run pkglint
-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 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
10 -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 -p.
-r Check the ELF runtime attributes of all dynamic objects
-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
10 -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
10 -V VERS set the build version string to VERS, overriding VERSION
10 -B WS Set BRINGOVER_WS from the command line.
10 -b BR Set BRINGOVER_BRANCH from the command line.
10 -d WS Set CODEMGR_WS from the command line.
Note that -B, -b, and -d set their respective variables before loading the env_file; settings in that file can override these options.
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
Pathname or URL of the workspace from which nightly will fetch sources to either populate or update your workspace; it defaults to $CLONE_WS.
BRINGOVER_SCM
Name of the underlying software configuration management system which nightly will use to fetch sources from remote URLs; it defaults to git .
BRINGOVER_BRANCH
This names the SCM branch which should be pulled into the build workspace. nightly will fetch the branch of this name in $BRINGOVER_WS and create or replace the branch of the same name in $CODEMGR_WS. Note that any local changes on $BRINGOVER_BRANCH will be unreferenced. If $BRINGOVER_WS is local, this defaults to the default branch.
BRINGOVER_REMOTE
This names the git remote in the build workspace which references $BRINGOVER_WS; it defaults to nightly_bringover_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.
CLONE_OPTIONS
Additional options passed to the SCM clone command when creating a new build workspace. For git workspaces, useful options can include --config and --reference . See git-clone (1) for more information.
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.
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.
JAVA_ROOT
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".
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.
If present, nightly executes this file just prior to executing the env file.
0 # grep NIGHTLY_OPTIONS myenv
NIGHTLY_OPTIONS="-ACrlapDmn"
export NIGHTLY_OPTIONS
# /opt/onbld/bin/nightly -i myenv
Accordingly, a best practice is to always use the n flag in NIGHTLY_OPTIONS in trees where you are actively making changes and only enable bringover for build-only workspaces intended to exactly mirror your development trees.
Committed changes discarded by git switch might be recoverable using the git reflog facility; see git-reflog (1) and git-switch (1) for more information.
When possible, the nightly script uses the --reference-if-able option to git clone which avoids fully populating the .git/objects directory in the build workspace, which saves space and significantly speeds workspace creation. This creates a persistent dependency on the contents of $BRINGOVER_WS workspace. Some git operations in the build workspace may fail if the referenced workspace is deleted, renamed, or otherwise rendered inaccessible, or if referenced objects in the parent workspace are released by a history-rewriting git operation like rebase or commit --amend and then deleted by a subsequent garbage collection. The linkage can be severed by using git repack as documented in the git-clone (1) manual page.