Print this page
8564 developer/build/onbld shouldn't require ghostscript
Reviewed by: Alexander Pyhalov <apyhalov@gmail.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/webrev.1onbld
+++ new/usr/src/tools/scripts/webrev.1onbld
1 1 .\"
2 2 .\" CDDL HEADER START
3 3 .\"
4 4 .\" The contents of this file are subject to the terms of the
5 5 .\" Common Development and Distribution License (the "License").
6 6 .\" You may not use this file except in compliance with the License.
7 7 .\"
8 8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 9 .\" or http://www.opensolaris.org/os/licensing.
10 10 .\" See the License for the specific language governing permissions
11 11 .\" and limitations under the License.
12 12 .\"
13 13 .\" When distributing Covered Code, include this CDDL HEADER in each
|
↓ open down ↓ |
13 lines elided |
↑ open up ↑ |
14 14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 15 .\" If applicable, add the following below this CDDL HEADER, with the
16 16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 18 .\"
19 19 .\" CDDL HEADER END
20 20 .\"
21 21 .\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
22 22 .\" Use is subject to license terms.
23 23 .\"
24 +.\" Copyright 2019 Joyent, Inc.
24 25 .\"
25 -.TH WEBREV 1ONBLD "Mar 27, 2016"
26 +.TH WEBREV 1ONBLD "Aug 2, 2019"
26 27 .SH NAME
27 28 webrev \- Generate HTML codereview materials
28 29 .SH SYNOPSIS
29 30 .B webrev
30 31 [
31 32 .I common-options
32 33 ]
33 34
34 35 .B webrev
35 36 [
36 37 .I common-options
37 38 ]
38 39 .I file-list-file
39 40 |
40 41 .I -
41 42
42 43 .B webrev
43 44 [
44 45 .I common-options
45 46 ]
46 47 .B -w
47 48 .I wx-file
48 49
49 50 .SH DESCRIPTION
50 51 .B webrev
51 52 builds a set of HTML files suitable for performing code review of
52 53 source changes in a web browser.
53 54 It supports Git and Subversion repositories.
54 55 At its most basic, usage is:
55 56 .nf
56 57 $ webrev
57 58 .fi
58 59
|
↓ open down ↓ |
23 lines elided |
↑ open up ↑ |
59 60 In which case \fBwebrev\fR attempts to figure out the list of files
60 61 for review. If that fails, or if more control
61 62 over the set of files is needed, a \fIfile list\fR may be specified.
62 63 \fBwebrev\fR also attempts to deduce a
63 64 .I basis for comparison
64 65 (interchangeably called the \fIparent\fR, but see SCM INTERACTIONS below).
65 66 A basis for comparison is needed in order to determine the differences
66 67 introduced by the code changes under review.
67 68
68 69 By default, \fBwebrev\fR creates a \fIwebrev\fR directory in the
69 -workspace directory that contains the generated HTML files, a generated
70 -PDF review, and a patch representing the changes. It also places a
71 -copy of the file list in that directory, and of both the old and new
72 -raw files in the \fB$webrev_root/raw_files\fR directory.
70 +workspace directory that contains the generated HTML files, and a patch
71 +representing the changes. It also places a copy of the file list in
72 +that directory, and of both the old and new raw files in the
73 +\fB$webrev_root/raw_files\fR directory.
73 74 To output the webrev somewhere other than the default location, use the
74 75 \fI-o <outdir>\fR option, or set the \fBWDIR\fR environment variable.
75 76 For example:
76 77 .nf
77 78 $ webrev -o ~/public_html/myreview/
78 79 .fi
79 80 .PP
80 81 In the index file, each file is listed on a line with a link to the
81 82 relevant review materials. Comments for each change will be included
82 83 automatically. Cross references to bug (or other information) tracking
83 84 databases in the comments will become hyperlinks in the associated web
84 85 interface, according to the rules in CROSS REFERENCING below.
85 86
86 87 As a review aid, content may be added to the \fIindex\fR file in two ways.
87 88 First, the author may manually edit the file (for example by including
88 89 text that explains the changes in front of the links for each file).
89 90 Note that if webrev is run again, manual edits will be lost. Second,
90 91 if a file named \fIwebrev-info\fR is present at the root of the workspace,
91 92 it will be automatically included in the \fIindex\fR file. To include a
92 93 different file, see the \fI-i\fR option.
93 94
94 95 For each file in the file list, \fBwebrev\fR compares the file with the
95 96 version in the basis for comparison (i.e. the parent workspace) and
96 97 generates a variety of HTML renderings of the differences between
97 98 the two files; which of these renderings to use is largely a matter
98 99 of personal preference. Additional, webrev emits a patch, the old
99 100 and new versions of the file, and a "raw" copy of the file which is
100 101 suitable for download. For files which express differences, source
|
↓ open down ↓ |
18 lines elided |
↑ open up ↑ |
101 102 is formatted according to the following color coding:
102 103 .IP
103 104 .nf
104 105 unchanged : black
105 106 removed : brown
106 107 changed : blue
107 108 new : bold blue
108 109 .fi
109 110
110 111 .SH SCM INTERACTIONS
111 -.PP
112 112 .B webrev
113 113 attempts to interact with the source code management system currently in use.
114 114 .B webrev
115 115 needs to be able locate the code under review (i.e. the workspace) and
116 116 the basis for comparison (i.e. the parent). The method for doing so
117 117 depends upon the SCM in use, which
118 118 .B webrev
119 119 will also attempt to auto-discover. In all cases,
120 120 .B webrev
121 121 must either discover the list of files which have changed, or else this list
122 122 must be manually specified, either in "webrev file list" format or in "wx"
123 123 format.
124 124 See FILE LIST for more details.
125 125 .PP
126 126 In all cases, if the user has activated the workspace with the
127 127 .BR ws (1ONBLD)
128 128 or
129 129 .BR bldenv (1ONBLD)
130 130 commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
131 131 \fBCODEMGR_WS\fR environment variables to identify parent and child
132 132 workspaces respectively.
133 133 To manually specify the basis for comparison, use the -p option or
134 134 specify the \fBCODEMGR_PARENT\fR variable in either the file list or
135 135 the environment.
136 136
137 137 .SS Discovering the SCM in use.
138 138 .B webrev
139 139 makes use of
140 140 .BR which_scm (1ONBLD)
141 141 to determine the SCM in use for a given workspace.
142 142
143 143 .SS Git
144 144 In the case of Git \fBwebrev\fR will attempt to use the output from the
145 145 .BR git (1)
146 146 "git rev-parse --git-dir" command to identify the workspace root, and will
147 147 attempt to use the remote branch which the current branch is tracking as the
148 148 parent, if none is specified 'origin/master' will be used.
149 149
150 150 The parent specified when using git is, in all cases, a git 'tree-ish' and
151 151 never an actual git repository, remote or otherwise. Anything specifiable to
152 152 git as a tree-ish should, similarly, be specifiable as a parent for webrev.
153 153 This includes branches, explicit revisions, reflog entries, etc. See
154 154 .BR git-rev-parse (1)
|
↓ open down ↓ |
33 lines elided |
↑ open up ↑ |
155 155
156 156 .SS Subversion
157 157 In the case of Subversion \fBwebrev\fR will attempt to use the output
158 158 from the
159 159 .BR svn (1)
160 160 "svn info" to find the workspace root and subversion repository URL.
161 161 .PP
162 162 The file list will be created from the output of the "svn status" command.
163 163
164 164 .SH CROSS REFERENCING
165 -.PP
166 165 After extracting comments (see FILE LIST below),
167 166 .B webrev
168 167 will translate cross references into hyperlinks. By default, information
169 168 about available information tracking systems can be found in
170 169 /opt/onbld/etc/its.reg, and the specification of a local domain and
171 170 selection and prioritization of systems
172 171 in /opt/onbld/etc/its.conf. These file formats are self documenting. Also
173 172 see the -I and -C options below.
174 173 .SH OPTIONS
175 174 .TP 10
176 175 .BI "-c " revision
177 176 Generate webrev for single commit specified by \fIrevision\fR (git only).
|
↓ open down ↓ |
2 lines elided |
↑ open up ↑ |
178 177 .TP 10
179 178 .BI "-C " priority-file
180 179 In addition to the system default and an optional user-supplied ~/.its.conf,
181 180 use the specified file to specify a local domain list and prioritize the list
182 181 of information tracking systems to be searched automatically when resolving cross
183 182 references.
184 183 .TP 10
185 184 .BI "-D"
186 185 Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
187 186 default remote directory for removal is the same as workspace/repository
188 -basename. Remote target can be overriden using -t option. If combined with
187 +basename. Remote target can be overridden using -t option. If combined with
189 188 -U the deletion will be performed first. Also, if used together with -U
190 189 and the removal fails, no upload is done. Without -U option no webrev will
191 190 be generated, just like if -n option was used. The deletion is done by
192 191 moving the webrev to special directory in user's home directory. It is
193 192 expected that the remote host periodically runs a script which deletes
194 193 the contents of this directory. See the ENVIRONMENT VARIABLES section for
195 194 more details about this directory.
196 195 .TP 10
197 196 .BI "-h " head-revision
198 197 Specify the explicit head to generate webrev from (git only).
199 198 .TP 10
|
↓ open down ↓ |
1 lines elided |
↑ open up ↑ |
200 199 .BI "-I " information-file
201 200 Use the specified file to seed the list of information tracking systems.
202 201 .TP 10
203 202 .BI "-i " include-file
204 203 Include the specified file into the index.html file which is generated
205 204 as part of the webrev. This allows a snippet of XHTML to be added by
206 205 the webrev author. User content is contained by a <div> tag and
207 206 the markup should validate as XHTML 1.0 Transitional.
208 207 .TP 10
209 208 .BI "-N"
210 -Suppress all comments from all output forms html, txt and pdf.
209 +Suppress all comments from all output forms.
211 210 .TP 10
212 211 .BI "-n"
213 212 Do not generate webrev. Useful whenever only upload is needed.
214 213 .TP 10
215 214 .B -O
216 215 Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
217 216 are generated using the EXTERNAL_URL field from the specified its.reg entry,
218 217 instead of the default INTERNAL_URL_domain field, and sources which appear in
219 218 \fIusr/closed\fR are automatically elided from the review.
220 219 .TP 10
221 220 .BI "-o " output-dir
222 221 Place output from running the script in the directory specified. If
223 222 specified, this option takes precedence over the WDIR environment variable.
224 223 .TP 10
225 224 .BI "-p " basis-of-comparison
226 225 Specify a basis of comparison meaningful for the SCM currently in use.
227 226 See SCM INTERACTIONS and INCREMENTAL REVIEWS.
228 227 .TP 10
229 228 .BI "-t " target
230 229 Upload target. Specified in form of URI identifier. For SCP/SFTP it is
231 230 \fIssh://user@remote_host:remote_dir\fR and for rsync it is
232 231 \fIrsync://user@remote_host:remote_dir\fR. This option can override the
233 232 -o option if the URI is fully specified. The target is relative to
234 233 the top level directory of the default sftp/rsync directory tree.
235 234 .TP 10
236 235 .BI "-U"
|
↓ open down ↓ |
16 lines elided |
↑ open up ↑ |
237 236 Upload the webrev. Default remote host is \fIcr.opensolaris.org\fR.
238 237 Default transport is rsync. If it fails, fallback to SCP/SFTP transport
239 238 is done.
240 239 .TP 10
241 240 .BI "-w " wx-file
242 241 Extract the file list from the wx "active" file specified. 'wx' uses
243 242 this mode when invoking webrev. The list is assumed to be in the
244 243 format expected by the \fIwx\fR package. See FILE LIST, below.
245 244
246 245 .SH FILE LIST
247 -.PP
248 246 .B Webrev
249 247 needs to be told or to discover which files have changed in a
250 248 given workspace. By default,
251 249 .B webrev
252 250 will attempt to autodetect the
253 251 list of changed files by first consulting
254 252 .BR wx "(1)."
255 253 If this information is not available, webrev tries to consult the SCM (Source
256 254 Code Manager) currently in use. If that fails, the user must intervene by
257 255 specifying either a file list or additional options specific to the SCM in use.
258 256
259 257 .SS Webrev Format
260 258 A webrev formatted file list contains a list of all the files to
261 259 be included in the review with paths relative to the workspace
262 260 directory, e.g.
263 261 .IP
264 262 .nf
265 263 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
266 264 usr/src/uts/common/fs/nfs/nfs_export.c
267 265 usr/src/cmd/fs.d/nfs/mountd/mountd.c
268 266 .fi
269 267 .PP
270 268 Include the paths of any files added, deleted, or modified.
271 269 You can keep this list of files in the webrev directory
272 270 that webrev creates in the workspace directory
273 271 (CODEMGR_WS).
274 272
275 273 If CODEMGR_WS is not set, it may be specified as an environment variable
276 274 within the file list, e.g.
277 275 .IP
278 276 .nf
279 277 \f(CWCODEMGR_WS=/home/brent/myws
280 278 usr/src/uts/common/fs/nfs/nfs_subr.c
281 279 usr/src/uts/common/fs/nfs/nfs_export.c
282 280 usr/src/cmd/fs.d/nfs/mountd/mountd.c
283 281 .fi
284 282 .PP
285 283 To compare the workspace against one other than the parent (see also
286 284 the -p option), include a CODEMGR_PARENT line in the file list, like:
287 285 .IP
288 286 .nf
289 287 \f(CWCODEMGR_WS=/home/brent/myws
290 288 CODEMGR_PARENT=/ws/onnv-gate
291 289 usr/src/uts/common/fs/nfs/nfs_subr.c
292 290 usr/src/uts/common/fs/nfs/nfs_export.c
293 291 usr/src/cmd/fs.d/nfs/mountd/mountd.c
294 292 .fi
295 293 .PP
296 294 Finally, run webrev with the name of the file containing the file list as an
297 295 argument, e.g.
298 296 .nf
299 297 $ webrev file.list
300 298 .fi
301 299 .PP
302 300 If "-" is supplied as the name of the file, then stdin will be used.
303 301
304 302 .SS wx Format
305 303 If the \fI-w\fR flag is specified then \fBwebrev\fR
306 304 will assume the file list is in the format expected by the "wx" package:
307 305 pathname lines alternating with SCCS comment lines separated by blank
308 306 lines, e.g.
309 307 .IP
310 308 .nf
311 309 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
312 310
313 311 1206578 Fix spelling error in comment
314 312
315 313 usr/src/uts/common/fs/nfs/nfs_export.c
316 314
317 315 4039272 cstyle fixes
318 316
319 317 usr/src/cmd/fs.d/nfs/mountd/mountd.c
320 318
321 319 1927634 mountd daemon doesn't handle expletives
322 320 .fi
323 321
324 322 .SH INCREMENTAL REVIEWS
325 323 When conducting multiple rounds of code review, it may be desirable to
326 324 generate a webrev which represents the delta between reviews. In this
327 325 case, set the parent workspace to the path to the old webrev:
328 326
329 327 .IP
330 328 .nf
331 329 \f(CW$ webrev -o ~/public_html/myreview-rd2/ \\
332 330 -p ~/public_html/myreview/
333 331 .fi
334 332
335 333 .SH ENVIRONMENT VARIABLES
336 334 The following environment variables allow for customization of \fBwebrev\fR:
337 335
338 336 .PP
339 337 \fBCDIFFCMD\fR and \fBUDIFFCMD\fR are used when generating Cdiffs and Udiffs
340 338 respectively; their default values are "diff -b -C 5" and "diff -b -U
341 339 5". To generate diffs with more (or less) than 5 lines of context or
342 340 with more (or less) strict whitespace handling, set one or both of
343 341 these variables in the user environment accordingly.
344 342
345 343 \fBWDIR\fR sets the output directory. It is functionally equivalent to
346 344 the \fI-o\fR option.
347 345
348 346 \fBWDIFF\fR specifies the command used to generate Wdiffs. Wdiff generates a
349 347 full unified context listing with line numbers where unchanged
350 348 sections of code may be expanded and collapsed. It also provides a
351 349 "split" feature that shows the same file in two HTML frames one above the
352 350 other. The default path for this script is
353 351 /ws/onnv-gate/public/bin/wdiff but WDIFF may be set to customize this
354 352 to use a more convenient location.
355 353
356 354 \fBWEBREV_TRASH_DIR\fR specifies alternative location of trash directory
357 355 for remote webrev deletion using the \fI-D\fR option. The directory is
358 356 relative to the top level directory of the default sftp/rsync directory tree.
359 357 The default value of this directory is ".trash".
360 358
361 359 .SH UPLOADING WEBREVS
362 360 A webrev can be uploaded to remote site using the -U option. To simply
363 361 generate new webrev and upload it to the default remote host use the following
364 362 command:
365 363 .IP
366 364 .nf
367 365 \f(CW$ webrev -U
368 366 .fi
369 367 .PP
370 368 This will generate the webrev to local directory named 'webrev' and upload it
371 369 to remote host with remote directory name equal to local workspace/repository
372 370 name. To change both local and remote directory name, -U can be combined with
373 371 -o option. The following command will store the webrev to local directory named
374 372 "foo.onnv" and upload it to the remote host with the same directory name:
375 373 .IP
376 374 .nf
377 375 \f(CW$ webrev -U -o $CODEMGR_WS/foo.onnv
378 376 .fi
379 377 .PP
380 378 If there is a need for manual change of the webrev before uploading,
381 379 -U can be combined with -n option so that first command will just generate
382 380 the webrev and the second command will upload it without generating it again:
383 381 .IP
384 382 .nf
385 383 \f(CW$ webrev
386 384 \f(CW$ webrev -n -U
387 385 .fi
388 386 .PP
389 387 For custom remote targets, -t option allows to specify all components:
390 388 .IP
391 389 .nf
392 390 \f(CW$ webrev -U -t \\
393 391 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
394 392 .fi
395 393 .PP
396 394 If the remote path is specified as absolute, \fBwebrev\fR will assume all the
397 395 directories are already created. If the path is relative, \fBwebrev\fR will
398 396 try to create all needed directories. This only works with SCP/SFTP transport.
399 397 .PP
400 398 By default, rsync transport will use SSH for transferring the data to remote
401 399 site. To specify custom username, use entry in SSH client configuration file,
402 400 for example:
403 401 .IP
404 402 .nf
405 403 \f(CWHost cr.opensolaris.org
406 404 Hostname cr.opensolaris.org
407 405 User vkotal
408 406 .fi
409 407
410 408 .SH DELETING WEBREVS
411 409 When deleting a webrev directory on remote site which has a different name
412 410 than the basename of local repository it is necessary to specify the output
413 411 option:
414 412 .IP
415 413 .nf
416 414 \f(CW$ webrev -Do webrev-foo.onnv
417 415 .fi
418 416 .PP
419 417 Otherwise \fBwebrev\fR will attempt to remove remote directory with the same
420 418 name as basename of the local repository.
421 419 .PP
422 420 For the nested directory case it is necessary to specify the full target:
423 421 .IP
424 422 .nf
425 423 \f(CW$ webrev -D -t \\
426 424 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
427 425 .fi
428 426 .PP
429 427 This will remove just the \fIbugfix.onnv\fR directory.
430 428
431 429 .SH SEE ALSO
432 430 .BR git "(1),"
433 431 .BR ssh_config "(4),"
434 432 .BR svn "(1),"
435 433 .BR which_scm "(1ONBLD)"
436 434
437 435 .SH ACKNOWLEDGEMENTS
438 436 Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling,
439 437 Rod Evans, Mike Kupfer, Greg Onufer, Glenn Skinner,
440 438 Oleg Larin, David Robinson, Matthew Cross, David L. Paktor,
441 439 Neal Gafter, John Beck, Darren Moffat, Norm Shulman, Bill Watson,
442 440 Pedro Rubio and Bill Shannon for valuable feedback and insight in
443 441 building webrev.
444 442
445 443 Have fun!
446 444 .br
447 445 .nf
448 446 Brent Callaghan 11/28/96
449 447 .fi
450 448
|
↓ open down ↓ |
193 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX