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