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