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