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