1 NIGHTLY(1ONBLD)               illumos Build Tools              NIGHTLY(1ONBLD)
   2 
   3 
   4 
   5 NAME
   6        nightly - build an OS-Net consolidation overnight
   7 
   8 SYNOPSIS
   9        nightly [-in] [-V VERS] <env_file>
  10 
  11 DESCRIPTION
  12        nightly, the mother of all build scripts, can bringover, build,
  13        archive, package, error check, and generally do everything it takes to
  14        turn OS/Net consolidation source code into useful stuff.  It is
  15        customizable to permit you to run anything from a simple build to all
  16        of the cross-checking a gatekeeper needs.  The advantage to using
  17        nightly is that you build things correctly, consistently and
  18        automatically, with the best practices; building with nightly can mean
  19        never having to say you're sorry to your gatekeeper.
  20 
  21        More specifically, nightly performs the following tasks, in order, if
  22        all these things are desired:
  23 
  24 
  25               o      perform a "make clobber" to clean up old binaries
  26 
  27               o      bringover from the identified parent gate/clone
  28 
  29               o      perform non-DEBUG and DEBUG builds
  30 
  31               o      list proto area files and compare with previous list
  32 
  33               o      copy updated proto area to parent
  34 
  35               o      list shared lib interface and compare with previous list
  36 
  37               o      perform a "make lint" of the kernel and report errors
  38 
  39               o      perform a "make check" to report hdrchk/cstyle errors
  40 
  41               o      report the presence of any core files
  42 
  43               o      check the ELF runtime attributes of all dynamic objects
  44 
  45               o      check for unreferenced files
  46 
  47               o      report on which proto area objects have changed (since
  48                      the last build)
  49 
  50               o      report the total build time
  51 
  52               o      save a detailed log file for reference
  53 
  54               o      mail the user a summary of the completed build
  55 
  56        The actions of the script are almost completely determined by the
  57        environment variables in the env file, the only necessary argument.
  58        Ths only thing you really need to use nightly is an env file that does
  59        what you want.
  60 
  61        Like most of the other build tools in usr/src/tools, this script tends
  62        to change on a fairly regular basis; do not expect to be able to build
  63        OS/Net with a version of nightly significantly older than your source
  64        tree.  It has what is effectively a Consolidation Private relationship
  65        to other build tools and with many parts of the OS/Net makefiles,
  66        although it may also be used to build other consolidations.
  67 
  68 NIGHTLY_OPTIONS
  69        The environment variable NIGHTLY_OPTIONS controls the actions nightly
  70        will take as it proceeds.  The -i, -n, +t and -V options may also be
  71        used from the command line to control the actions without editing your
  72        environment file.  The -i and -n options complete the build more
  73        quickly by bypassing some actions. If NIGHTLY_OPTIONS is not set, then
  74        "-Bmt" build options will be used.
  75 
  76        Basic action options
  77 
  78        -D        Do a build with DEBUG on (non-DEBUG is built by default)
  79 
  80        -F        Do _not_ do a non-DEBUG build (use with -D to get just a
  81                  DEBUG build)
  82 
  83        -M        Do not run pmodes (safe file permission checker)
  84 
  85        -i        Do an incremental build, suppressing the "make clobber" that
  86                  by default removes all existing binaries and derived files.
  87                  From the command line, -i also suppresses the lint pass and
  88                  the cstyle/hdrchk pass
  89 
  90        -n        Suppress the bringover so that the build will start
  91                  immediately with current source code
  92 
  93        -p        Create packages for regular install
  94 
  95        -U        Update proto area in the parent workspace
  96 
  97        -u        Update the parent workspace with files generated by the
  98                  build, as follows.
  99 
 100               o         Copy proto_list_${MACH} and friends to usr/src in the
 101                         parent.
 102 
 103               o         When used with -f, build a usr/src/unrefmaster.out in
 104                         the parent by merging all the
 105                         usr/src/unref-${MACH}.out files in the parent.
 106 
 107               o         When used with -A or -r, copy the contents of the
 108                         resulting ELF-data.${MACH} directory to usr/src/ELF-
 109                         data.${MACH} in the parent workspace.
 110 
 111        -m        Send mail to $MAILTO at end of build
 112 
 113        -t        Build and use the tools in $SRC/tools (default setting).
 114 
 115        +t        Use the build tools in "$ONBLD_TOOLS/bin".
 116 
 117 
 118        Code checking options
 119 
 120        -A        Check for ABI discrepancies in .so files.  It is only
 121                  required for shared object developers when there is an
 122                  addition, deletion or change of interface in the .so files.
 123 
 124        -C        Check for cstyle/hdrchk errors
 125 
 126        -f        Check for unreferenced files.  Since the full workspace must
 127                  be built in order to accurately identify unreferenced files,
 128                  -f is ignored for incremental (-i) builds, or builds that do
 129                  not include -l, and -p.
 130 
 131        -r        Check the ELF runtime attributes of all dynamic objects
 132 
 133        -l        Do "make lint" in $LINTDIRS (default: $SRC n)
 134 
 135        -N        Do not run protocmp or checkpaths (note: this option is not
 136                  recommended, especially in conjunction with the -p option)
 137 
 138        -w        Report which proto area objects differ between this and the
 139                  last build.  See wsdiff(1ONBLD) for details. Note that the
 140                  proto areas used for comparison are the last ones constructed
 141                  as part of the build. As an example, if both a non-debug and
 142                  debug build are performed (in that order), then the debug
 143                  proto area will be used for comparison (which might not be
 144                  what you want).
 145 
 146        Groups of options
 147 
 148        -G        Gate keeper default group of options (-u)
 149 
 150        -I        Integration engineer default group of options (-mpu)
 151 
 152        -R        Default group of options for building a release (-mp)
 153 
 154 
 155        Miscellaneous options
 156 
 157        -V VERS   set the build version string to VERS, overriding VERSION
 158 
 159 
 160 ENVIRONMENT VARIABLES
 161        Here is a list of prominent environment variables that nightly
 162        references and the meaning of each variable.  CODEMGR_WS
 163             The root of your workspace, including whatever metadata is kept by
 164             the source code management system.  This is the workspace in which
 165             the build will be done.
 166 
 167        PARENT_WS
 168             The root of the workspace that is the parent of the one being
 169             built.  This is particularly relevant for configurations with a
 170             main workspace and build workspaces underneath it; see the -u and
 171             -U options as well as the PKGARCHIVE environment variable, for
 172             more information.
 173 
 174        BRINGOVER_WS
 175             This is the workspace from which nightly will fetch sources to
 176             either populate or update your workspace; it defaults to
 177             $CLONE_WS.
 178 
 179        CLONE_WS
 180             This is the workspace from which nightly will fetch sources by
 181             default.  This is often distinct from the parent, particularly if
 182             the parent is a gate.
 183 
 184        SRC
 185             Root of OS-Net source code, referenced by the Makefiles.  It is
 186             the starting point of build activity.  It should be expressed in
 187             terms of $CODEMGR_WS.
 188 
 189        ROOT
 190             Root of the proto area for the build.  The makefiles direct
 191             installation of build products to this area and direct references
 192             to these files by builds of commands and other targets.  It should
 193             be expressed in terms of $CODEMGR_WS.
 194 
 195             If $MULTI_PROTO is "no", $ROOT may contain a DEBUG or non-DEBUG
 196             build.  If $MULTI_PROTO is "yes", $ROOT contains the DEBUG build
 197             and $ROOT-nd contains the non-DEBUG build.
 198 
 199        TOOLS_ROOT
 200             Root of the tools proto area for the build.  The makefiles direct
 201             installation of tools build products to this area.  Unless +t is
 202             part of $NIGHTLY_OPTIONS, these tools will be used during the
 203             build.
 204 
 205             As built by nightly, this will always contain non-DEBUG objects.
 206             Therefore, this will always have a -nd suffix, regardless of
 207             $MULTI_PROTO.
 208 
 209        MACH
 210             The instruction set architecture of the build machine as given by
 211             uname -p, e.g. sparc, i386.
 212 
 213        LOCKNAME
 214             The name of the file used to lock out multiple runs of nightly.
 215             This should generally be left to the default setting.
 216 
 217        ATLOG
 218             The location of the log directory maintained by nightly.  This
 219             should generally be left to the default setting.
 220 
 221        LOGFILE
 222             The name of the log file in the $ATLOG directory maintained by
 223             nightly.  This should generally be left to the default setting.
 224 
 225        STAFFER
 226             The non-root account to use on the build machine for the bringover
 227             from the clone or parent workspace.  This may not be the same
 228             identify used by the SCM.
 229 
 230        MAILTO
 231             The address to be used to send completion e-mail at the end of the
 232             build (for the -m option).
 233 
 234        MAILFROM
 235             The address to be used for From: in the completion e-mail at the
 236             end of the build (for the -m option).
 237 
 238        REF_PROTO_LIST
 239             Name of file used with protocmp to compare proto area contents.
 240 
 241        PARENT_ROOT
 242             The parent root, which is the destination for copying the proto
 243             area(s) when using the -U option.
 244 
 245        PARENT_TOOLS_ROOT
 246             The parent tools root, which is the destination for copying the
 247             tools proto area when using the -U option.
 248 
 249        RELEASE
 250             The release version number to be used; e.g., 5.10.1 (Note: this is
 251             set in Makefile.master and should not normally be overridden).
 252 
 253        VERSION
 254             The version text string to be used; e.g., "onnv:`date
 255             '+%Y-%m-%d'`".
 256 
 257        RELEASE_DATE
 258             The release date text to be used; e.g., October 2009. If not set
 259             in your environment file, then this text defaults to the output
 260             from $(LC_ALL=C date +"%B %Y"); e.g., "October 2009".
 261 
 262        RELEASE_BUILD
 263             Define this to build a release with a non-DEBUG kernel.
 264             Generally, let nightly set this for you based on its options.
 265 
 266        PKGARCHIVE
 267             The destination for packages.  This may be relative to $CODEMGR_WS
 268             for private packages or relative to $PARENT_WS if you have
 269             different workspaces for different architectures but want one
 270             hierarchy of packages.
 271 
 272        MAKEFLAGS
 273             Set default flags to make; e.g., -k to build all targets
 274             regardless of errors.
 275 
 276        UT_NO_USAGE_TRACKING
 277             Disables usage reporting by listed Devpro tools. Otherwise it
 278             sends mail to some Devpro machine every time the tools are used.
 279 
 280        LINTDIRS
 281             Directories to lint with the -l option.
 282 
 283        BUILD_TOOLS
 284             BUILD_TOOLS is the root of all tools including the compilers;
 285             e.g., /ws/onnv-tools.  It is used by the makefile system, but not
 286             nightly.
 287 
 288        ONBLD_TOOLS
 289             ONBLD_TOOLS is the root of all the tools that are part of
 290             SUNWonbld; e.g., /ws/onnv-tools/onbld.  By default, it is derived
 291             from BUILD_TOOLS.  It is used by the makefile system, but not
 292             nightly.
 293 
 294        SPRO_ROOT
 295             The gate-defined default location for the Sun compilers, e.g.
 296             /ws/onnv-tools/SUNWspro.  By default, it is derived from
 297             BUILD_TOOLS.  It is used by the makefile system, but not nightly.
 298 
 299        JAVA_ROOT
 300             The location for the java compilers for the build, generally
 301             /usr/java.
 302 
 303        OPTHOME
 304             The gate-defined default location of things formerly in /opt;
 305             e.g., /ws/onnv-tools.  This is used by nightly, but not the
 306             makefiles.
 307 
 308        TEAMWARE
 309             The gate-defined default location for the Teamware tools; e.g.,
 310             /ws/onnv-tools/SUNWspro.  By default, it is derived from OPTHOME.
 311             This is used by nightly, but not the makefiles.  There is no
 312             corresponding variable for Mercurial or Subversion, which are
 313             assumed to be installed in the default path.
 314 
 315        ON_CLOSED_BINS
 316             OpenSolaris builds do not contain the closed source tree.
 317             Instead, the developer downloads a closed binaries tree and
 318             unpacks it.  ON_CLOSED_BINS tells nightly where to find these
 319             closed binaries, so that it can add them into the build.
 320 
 321        CHECK_PATHS
 322             Normally, nightly runs the 'checkpaths' script to check for
 323             discrepancies among the files that list paths to other files, such
 324             as exception lists and req.flg.  Set this flag to 'n' to disable
 325             this check, which appears in the nightly output as "Check lists of
 326             files."
 327 
 328        CHECK_DMAKE
 329             Nightly validates that the version of dmake encountered is known
 330             to be safe to use.  Set this flag to 'n' to disable this test,
 331             allowing any version of dmake to be used.
 332 
 333        MULTI_PROTO
 334             If "no" (the default), nightly will reuse $ROOT for both the DEBUG
 335             and non-DEBUG builds.  If "yes", the DEBUG build will go in $ROOT
 336             and the non-DEBUG build will go in $ROOT-nd.  Other values will be
 337             treated as "no".
 338 
 339 NIGHTLY HOOK ENVIRONMENT VARIABLES
 340        Several optional environment variables may specify commands to run at
 341        various points during the build.  Commands specified in the hook
 342        variable will be run in a subshell; command output will be appended to
 343        the mail message and log file.  If the hook exits with a non-zero
 344        status, the build is aborted immediately.  Environment variables
 345        defined in the environment file will be available.
 346 
 347        SYS_PRE_NIGHTLY
 348             Run just after the workspace lock is acquired.  This is reserved
 349             for per-build-machine customizations and should be set only in
 350             /etc/nightly.conf
 351 
 352        PRE_NIGHTLY
 353             Run just after SYS_PRE_NIGHTLY.
 354 
 355        PRE_BRINGOVER
 356             Run just before bringover is started; not run if no bringover is
 357             done.
 358 
 359        POST_BRINGOVER
 360             Run just after bringover completes; not run if no bringover is
 361             done.
 362 
 363        POST_NIGHTLY
 364             Run after the build completes, with the return status of nightly -
 365             one of "Completed", "Interrupted", or "Failed" - available in the
 366             environment variable NIGHTLY_STATUS.
 367 
 368        SYS_POST_NIGHTLY
 369             This is reserved for per-build-machine customizations, and runs
 370             immedately after POST_NIGHTLY.
 371 
 372 FILES
 373             /etc/nightly.conf
 374 
 375        If present, nightly executes this file just prior to executing the env
 376        file.
 377 
 378 EXAMPLES
 379        Start with the example file in usr/src/tools/env/developer.sh (or
 380        gatekeeper.sh), copy to myenv and make your changes.
 381 
 382        # grep NIGHTLY_OPTIONS myenv
 383        NIGHTLY_OPTIONS="-ACrlapDm"
 384        export NIGHTLY_OPTIONS
 385        # /opt/onbld/bin/nightly -i myenv
 386 
 387 SEE ALSO
 388        bldenv(1ONBLD)
 389 
 390 
 391 
 392                                January 28, 2014                NIGHTLY(1ONBLD)