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