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