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 1 "6 July 2010"
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
51 all these things are desired:
52 .LP
53 .RS
54 .TP
55 \(bu
56 perform a "make clobber" to clean up old binaries
57 .TP
58 \(bu
59 bringover from the identified parent gate/clone
60 .TP
61 \(bu
62 perform non-DEBUG and DEBUG builds
63 .TP
64 \(bu
65 list proto area files and compare with previous list
66 .TP
67 \(bu
68 copy updated proto area to parent
69 .TP
70 \(bu
71 list shared lib interface and compare with previous list
72 .TP
73 \(bu
74 perform a "make lint" of the kernel and report errors
75 .TP
76 \(bu
77 perform a "make check" to report hdrchk/cstyle errors
78 .TP
79 \(bu
80 report the presence of any core files
81 .TP
82 \(bu
83 check the ELF runtime attributes of all dynamic objects
84 .TP
85 \(bu
86 check for unreferenced files
87 .TP
88 \(bu
89 report on which proto area objects have changed (since the last build)
90 .TP
91 \(bu
92 report the total build time
93 .TP
94 \(bu
95 save a detailed log file for reference
96 .TP
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)
138 .TP
139 .B \-i
140 Do an incremental build, suppressing the "make clobber" that by
141 default removes all existing binaries and derived files. From the
142 command line, -i also suppresses the lint pass and the cstyle/hdrchk
143 pass
144 .TP
145 .B \-n
146 Suppress the bringover so that the build will start immediately with
147 current source code
148 .TP
149 .B \-p
150 Create packages for regular install
151 .TP
152 .B \-U
153 Update proto area in the parent workspace
154 .TP
155 .B \-u
156 Update the parent workspace with files generated by the build, as follows.
157 .RS
158 .TP
159 \(bu
160 Copy proto_list_${MACH} and friends to usr/src in the parent.
161 .TP
162 \(bu
163 When used with -f, build a usr/src/unrefmaster.out in
164 the parent by merging all the usr/src/unref-${MACH}.out files in the
165 parent.
166 .TP
167 \(bu
168 When used with -A or -r, copy the contents of the resulting
169 ELF-data.${MACH} directory to usr/src/ELF-data.${MACH} in the parent
170 workspace.
171 .RE
172 .TP
173 .B \-m
174 Send mail to $MAILTO at end of build
175 .TP
176 .B \-t
177 Build and use the tools in $SRC/tools (default setting).
178 .TP
179 .B \+t
180 Use the build tools in "$ONBLD_TOOLS/bin".
181
182 .LP
183 .B Code checking options
184 .TP 10
185 .B \-A
186 Check for ABI discrepancies in .so files.
187 It is only required for shared object developers when there is an
188 addition, deletion or change of interface in the .so files.
189 .TP
190 .B \-C
191 Check for cstyle/hdrchk errors
192 .TP
193 .B \-f
194 Check for unreferenced files. Since the full workspace must be built
195 in order to accurately identify unreferenced files, -f is ignored for
196 incremental (-i) builds, or builds that do not include -l, and -p.
197 .TP
198 .B \-r
199 Check the ELF runtime attributes of all dynamic objects
200 .TP
201 .B \-l
202 Do "make lint" in $LINTDIRS (default: $SRC n)
203 .TP
204 .B \-N
205 Do not run protocmp or checkpaths (note: this option is not
206 recommended, especially in conjunction with the \-p option)
207 .TP
208 .B \-w
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
211 are the last ones constructed as part of the build. As an example, if both
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
260 This is the workspace from which
261 .I nightly
262 will fetch sources to either populate or update your workspace;
263 it defaults to $CLONE_WS.
264 .RE
265 .LP
266 .B CLONE_WS
267 .RS 5
268 This is the workspace from which
269 .I nightly
270 will fetch sources by default. This is
271 often distinct from the parent, particularly if the parent is a gate.
272 .RE
273 .LP
274 .B SRC
275 .RS 5
276 Root of OS-Net source code, referenced by the Makefiles. It is
277 the starting point of build activity. It should be expressed
278 in terms of $CODEMGR_WS.
279 .RE
280 .LP
281 .B ROOT
282 .RS 5
283 Root of the proto area for the build. The makefiles direct
284 installation of build products to this area and
285 direct references to these files by builds of commands and other
286 targets. It should be expressed in terms of $CODEMGR_WS.
287 .LP
288 If $MULTI_PROTO is "no", $ROOT may contain a DEBUG or non-DEBUG
289 build. If $MULTI_PROTO is "yes", $ROOT contains the DEBUG build and
290 $ROOT-nd contains the non-DEBUG build.
291 .RE
292 .LP
293 .B TOOLS_ROOT
294 .RS 5
295 Root of the tools proto area for the build. The makefiles direct
296 installation of tools build products to this area. Unless \fB+t\fR
297 is part of $NIGHTLY_OPTIONS, these tools will be used during the
298 build.
299 .LP
300 As built by nightly, this will always contain non-DEBUG objects.
301 Therefore, this will always have a -nd suffix, regardless of
302 $MULTI_PROTO.
303 .RE
304 .LP
305 .B MACH
306 .RS 5
307 The instruction set architecture of the build machine as given
308 by \fIuname -p\fP, e.g. sparc, i386.
309 .RE
310 .LP
311 .B LOCKNAME
312 .RS 5
313 The name of the file used to lock out multiple runs of
314 .IR nightly .
315 This should generally be left to the default setting.
316 .RE
317 .LP
318 .B ATLOG
319 .RS 5
320 The location of the log directory maintained by
321 .IR nightly .
322 This should generally be left to the default setting.
323 .RE
324 .LP
325 .B LOGFILE
326 .RS 5
327 The name of the log file in the $ATLOG directory maintained by
328 .IR nightly .
329 This should generally be left to the default setting.
330 .RE
331 .LP
332 .B STAFFER
333 .RS 5
334 The non-root account to use on the build machine for the
335 bringover from the clone or parent workspace.
336 This may not be the same identify used by the SCM.
337 .RE
338 .LP
339 .B MAILTO
340 .RS 5
341 The address to be used to send completion e-mail at the end of
342 the build (for the \-m option).
343 .RE
344 .LP
345 .B MAILFROM
346 .RS 5
347 The address to be used for From: in the completion e-mail at the
348 end of the build (for the \-m option).
349 .RE
350 .LP
351 .B REF_PROTO_LIST
352 .RS 5
353 Name of file used with protocmp to compare proto area contents.
354 .RE
355 .LP
356 .B PARENT_ROOT
357 .RS 5
358 The parent root, which is the destination for copying the proto
359 area(s) when using the \-U option.
360 .RE
361 .LP
362 .B PARENT_TOOLS_ROOT
363 .RS 5
364 The parent tools root, which is the destination for copying the tools
365 proto area when using the \-U option.
366 .RE
367 .LP
368 .B RELEASE
369 .RS 5
370 The release version number to be used; e.g., 5.10.1 (Note: this is set
371 in Makefile.master and should not normally be overridden).
372 .RE
373 .LP
374 .B VERSION
375 .RS 5
376 The version text string to be used; e.g., "onnv:`date '+%Y-%m-%d'`".
377 .RE
378 .LP
379 .B RELEASE_DATE
380 .RS 5
381 The release date text to be used; e.g., October 2009. If not set in
382 your environment file, then this text defaults to the output from
383 $(LC_ALL=C date +"%B %Y"); e.g., "October 2009".
384 .RE
385 .LP
386 .B RELEASE_BUILD
387 .RS 5
388 Define this to build a release with a non-DEBUG kernel.
389 Generally, let
390 .I nightly
391 set this for you based on its options.
392 .RE
393 .LP
394 .B PKGARCHIVE
395 .RS 5
396 The destination for packages. This may be relative to
397 $CODEMGR_WS for private packages or relative to $PARENT_WS
398 if you have different workspaces for different architectures
399 but want one hierarchy of packages.
400 .RE
401 .LP
402 .B MAKEFLAGS
403 .RS 5
404 Set default flags to make; e.g., -k to build all targets regardless of errors.
405 .RE
406 .LP
407 .B UT_NO_USAGE_TRACKING
408 .RS 5
409 Disables usage reporting by listed Devpro tools. Otherwise it sends mail
410 to some Devpro machine every time the tools are used.
411 .RE
412 .LP
413 .B LINTDIRS
414 .RS 5
415 Directories to lint with the \-l option.
416 .RE
417 .LP
418 .B BUILD_TOOLS
419 .RS 5
420 BUILD_TOOLS is the root of all tools including the compilers; e.g.,
421 /ws/onnv-tools. It is used by the makefile system, but not nightly.
422 .RE
423 .LP
424 .B ONBLD_TOOLS
425 .RS 5
426 ONBLD_TOOLS is the root of all the tools that are part of SUNWonbld; e.g.,
427 /ws/onnv-tools/onbld. By default, it is derived from
428 .BR BUILD_TOOLS .
429 It is used by the makefile system, but not nightly.
430 .RE
431 .LP
432 .B SPRO_ROOT
433 .RS 5
434 The gate-defined default location for the Sun compilers, e.g.
435 /ws/onnv-tools/SUNWspro. By default, it is derived from
436 .BR BUILD_TOOLS .
437 It is used by the makefile system, but not nightly.
438 .RE
439 .LP
440 .B JAVA_ROOT
441 .RS 5
442 The location for the java compilers for the build, generally /usr/java.
443 .RE
444 .LP
445 .B OPTHOME
446 .RS 5
447 The gate-defined default location of things formerly in /opt; e.g.,
448 /ws/onnv-tools. This is used by nightly, but not the makefiles.
449 .RE
450 .LP
451 .B TEAMWARE
452 .RS 5
453 The gate-defined default location for the Teamware tools; e.g.,
454 /ws/onnv-tools/SUNWspro. By default, it is derived from
455 .BR OPTHOME .
456 This is used by nightly, but not the makefiles. There is no
457 corresponding variable for Mercurial or Subversion, which are assumed
458 to be installed in the default path.
459 .RE
460 .LP
461 .B ON_CLOSED_BINS
462 .RS 5
463 OpenSolaris builds do not contain the closed source tree. Instead,
464 the developer downloads a closed binaries tree and unpacks it.
465 .B ON_CLOSED_BINS
466 tells nightly
467 where to find these closed binaries, so that it can add them into the
468 build.
469 .RE
470 .LP
471 .B CHECK_PATHS
472 .RS 5
473 Normally, nightly runs the 'checkpaths' script to check for
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
515 .B PRE_BRINGOVER
516 .RS 5
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 (1)