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 "Jan 28, 2014"
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 .LP
29 .SH DESCRIPTION
30 .IX "OS-Net build tools" "nightly" "" "\fBnightly\fP"
31 .LP
32 .I nightly,
33 the mother of all build scripts,
34 can bringover, build, archive, package, error check, and
35 generally do everything it takes to
36 turn OS/Net consolidation source code into useful stuff.
37 It is customizable to permit you to run anything from a
38 simple build to all of the cross-checking a gatekeeper
39 needs. The advantage to using
40 .I nightly
41 is that you build things correctly, consistently and
42 automatically, with the best practices; building with
43 .I nightly
44 can mean never having to say you're sorry to your
45 gatekeeper.
46 .LP
47 More
48 specifically,
49 .I nightly
50 performs the following tasks, in order, if
97 \(bu
98 mail the user a summary of the completed build
99 .RE
100 .LP
101 The actions of the script are almost completely determined by
102 the environment variables in the
103 .I env
104 file, the only necessary argument. Ths only thing you really
105 need to use
106 .I nightly
107 is an
108 .I env
109 file that does what you want.
110 .LP
111 Like most of the other build tools in usr/src/tools, this script tends
112 to change on a fairly regular basis; do not expect to be able to build
113 OS/Net with a version of nightly significantly older than your source
114 tree. It has what is effectively a Consolidation Private relationship
115 to other build tools and with many parts of the OS/Net makefiles,
116 although it may also be used to build other consolidations.
117 .LP
118 .SH NIGHTLY_OPTIONS
119 The environment variable NIGHTLY_OPTIONS controls the actions
120 .I nightly
121 will take as it proceeds.
122 The -i, -n, +t and -V options may also be used from the command
123 line to control the actions without editing your environment file.
124 The -i and -n options complete the build more quickly by bypassing
125 some actions. If NIGHTLY_OPTIONS is not set, then "-Bmt" build
126 options will be used.
127
128 .B Basic action options
129 .TP 10
130 .B \-D
131 Do a build with DEBUG on (non-DEBUG is built by default)
132 .TP
133 .B \-F
134 Do _not_ do a non-DEBUG build (use with -D to get just a DEBUG build)
135 .TP
136 .B \-M
137 Do not run pmodes (safe file permission checker)
212 a non-debug and debug build are performed (in that order), then the debug
213 proto area will be used for comparison (which might not be what you want).
214 .LP
215 .B Groups of options
216 .TP 10
217 .B \-G
218 Gate keeper default group of options (-u)
219 .TP
220 .B \-I
221 Integration engineer default group of options (-mpu)
222 .TP
223 .B \-R
224 Default group of options for building a release (-mp)
225
226 .LP
227 .B Miscellaneous options
228 .TP 10
229 .B \-V VERS
230 set the build version string to VERS, overriding VERSION
231
232 .LP
233 .SH ENVIRONMENT VARIABLES
234 .LP
235 Here is a list of prominent environment variables that
236 .I nightly
237 references and the meaning of each variable.
238 .LP
239 .RE
240 .B CODEMGR_WS
241 .RS 5
242 The root of your workspace, including whatever metadata is kept by
243 the source code management system. This is the workspace in which the
244 build will be done.
245 .RE
246 .LP
247 .B PARENT_WS
248 .RS 5
249 The root of the workspace that is the parent of the
250 one being built. This is particularly relevant for configurations
251 with a main
252 workspace and build workspaces underneath it; see the
253 \-u and \-U
254 options as well as the PKGARCHIVE environment variable, for more
255 information.
256 .RE
257 .LP
258 .B BRINGOVER_WS
259 .RS 5
474 discrepancies among the files that list paths to other files, such as
475 exception lists and req.flg. Set this flag to 'n' to disable this
476 check, which appears in the nightly output as "Check lists of files."
477 .RE
478 .LP
479 .B CHECK_DMAKE
480 .RS 5
481 Nightly validates that the version of dmake encountered is known to be
482 safe to use. Set this flag to 'n' to disable this test, allowing any
483 version of dmake to be used.
484 .RE
485 .LP
486 .B MULTI_PROTO
487 .RS 5
488 If "no" (the default),
489 .I nightly
490 will reuse $ROOT for both the DEBUG and non-DEBUG builds. If "yes",
491 the DEBUG build will go in $ROOT and the non-DEBUG build will go in
492 $ROOT-nd. Other values will be treated as "no".
493 .RE
494 .LP
495 .SH NIGHTLY HOOK ENVIRONMENT VARIABLES
496 .LP
497 Several optional environment variables may specify commands to run at
498 various points during the build. Commands specified in the hook
499 variable will be run in a subshell; command output will be appended to
500 the mail message and log file. If the hook exits with a non-zero
501 status, the build is aborted immediately. Environment variables
502 defined in the environment file will be available.
503 .LP
504 .B SYS_PRE_NIGHTLY
505 .RS 5
506 Run just after the workspace lock is acquired. This is reserved for
507 per-build-machine customizations and should be set only in /etc/nightly.conf
508 .RE
509 .LP
510 .B PRE_NIGHTLY
511 .RS 5
512 Run just after SYS_PRE_NIGHTLY.
513 .RE
514 .LP
517 Run just before bringover is started; not run if no bringover is done.
518 .RE
519 .LP
520 .B POST_BRINGOVER
521 .RS 5
522 Run just after bringover completes; not run if no bringover is done.
523 .RE
524 .LP
525 .B POST_NIGHTLY
526 .RS 5
527 Run after the build completes, with the return status of nightly - one
528 of "Completed", "Interrupted", or "Failed" - available in the
529 environment variable NIGHTLY_STATUS.
530 .RE
531 .LP
532 .B SYS_POST_NIGHTLY
533 .RS 5
534 This is reserved for per-build-machine customizations, and runs
535 immedately after POST_NIGHTLY.
536 .RE
537 .LP
538 .SH FILES
539 .LP
540 .RS 5
541 /etc/nightly.conf
542 .RE
543 .LP
544 If present, nightly executes this file just prior to executing the
545 .I env
546 file.
547 .SH EXAMPLES
548 .LP
549 Start with the example file in usr/src/tools/env/developer.sh
550 (or gatekeeper.sh), copy to myenv and make your changes.
551 .LP
552 .PD 0
553 # grep NIGHTLY_OPTIONS myenv
554 .LP
555 NIGHTLY_OPTIONS="-ACrlapDm"
556 .LP
557 export NIGHTLY_OPTIONS
558 .LP
559 # /opt/onbld/bin/nightly -i myenv
560 .PD
561 .LP
562 .SH SEE ALSO
563 .BR bldenv (1ONBLD)
|
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 "Jan 28, 2014"
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
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)
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
468 discrepancies among the files that list paths to other files, such as
469 exception lists and req.flg. Set this flag to 'n' to disable this
470 check, which appears in the nightly output as "Check lists of files."
471 .RE
472 .LP
473 .B CHECK_DMAKE
474 .RS 5
475 Nightly validates that the version of dmake encountered is known to be
476 safe to use. Set this flag to 'n' to disable this test, allowing any
477 version of dmake to be used.
478 .RE
479 .LP
480 .B MULTI_PROTO
481 .RS 5
482 If "no" (the default),
483 .I nightly
484 will reuse $ROOT for both the DEBUG and non-DEBUG builds. If "yes",
485 the DEBUG build will go in $ROOT and the non-DEBUG build will go in
486 $ROOT-nd. Other values will be treated as "no".
487 .RE
488 .SH NIGHTLY HOOK ENVIRONMENT VARIABLES
489 .LP
490 Several optional environment variables may specify commands to run at
491 various points during the build. Commands specified in the hook
492 variable will be run in a subshell; command output will be appended to
493 the mail message and log file. If the hook exits with a non-zero
494 status, the build is aborted immediately. Environment variables
495 defined in the environment file will be available.
496 .LP
497 .B SYS_PRE_NIGHTLY
498 .RS 5
499 Run just after the workspace lock is acquired. This is reserved for
500 per-build-machine customizations and should be set only in /etc/nightly.conf
501 .RE
502 .LP
503 .B PRE_NIGHTLY
504 .RS 5
505 Run just after SYS_PRE_NIGHTLY.
506 .RE
507 .LP
510 Run just before bringover is started; not run if no bringover is done.
511 .RE
512 .LP
513 .B POST_BRINGOVER
514 .RS 5
515 Run just after bringover completes; not run if no bringover is done.
516 .RE
517 .LP
518 .B POST_NIGHTLY
519 .RS 5
520 Run after the build completes, with the return status of nightly - one
521 of "Completed", "Interrupted", or "Failed" - available in the
522 environment variable NIGHTLY_STATUS.
523 .RE
524 .LP
525 .B SYS_POST_NIGHTLY
526 .RS 5
527 This is reserved for per-build-machine customizations, and runs
528 immedately after POST_NIGHTLY.
529 .RE
530 .SH FILES
531 .LP
532 .RS 5
533 /etc/nightly.conf
534 .RE
535 .LP
536 If present, nightly executes this file just prior to executing the
537 .I env
538 file.
539 .SH EXAMPLES
540 .LP
541 Start with the example file in usr/src/tools/env/developer.sh
542 (or gatekeeper.sh), copy to myenv and make your changes.
543 .LP
544 .PD 0
545 # grep NIGHTLY_OPTIONS myenv
546 .LP
547 NIGHTLY_OPTIONS="-ACrlapDm"
548 .LP
549 export NIGHTLY_OPTIONS
550 .LP
551 # /opt/onbld/bin/nightly -i myenv
552 .PD
553 .SH SEE ALSO
554 .BR bldenv (1ONBLD)
|