Print this page
6282 ONBLD man pages not pbchk clean
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Reviewed by: Josef Sipek <jeffpc@josefsipek.net>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/ws.1onbld
+++ new/usr/src/tools/scripts/ws.1onbld
1 1 .\" " CDDL HEADER START
2 2 .\" "
3 3 .\" " The contents of this file are subject to the terms of the
4 4 .\" " Common Development and Distribution License, Version 1.0 only
5 5 .\" " (the "License"). You may not use this file except in compliance
6 6 .\" " 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 2004 Sun Microsystems, Inc."
22 22 .\" "All rights reserved"
23 23 .\" "Use is subject to license terms."
24 -.TH WS 1ONBLD "28 January 1992"
24 +.TH WS 1ONBLD "Jan 28, 1992"
25 25 .SH NAME
26 -.I ws
26 +.I ws
27 27 \- enable SunOS avocet environments
28 28 .SH SYNOPSIS
29 29 .B ws
30 30 [-e] [workspace_name]
31 -.LP
32 31 .SH DESCRIPTION
33 -.IX "Avocet" "ws" "" "\fBws\fP"
34 32 .LP
35 -.I Ws
33 +.I Ws
36 34 will configure your environment to build the SunOS
37 35 source base from an
38 36 .I avocet
39 37 workspace. The
40 38 .I ws
41 39 script sets up the environment variables for a SunOS avocet
42 -workspace and spawns a shell for the environment
40 +workspace and spawns a shell for the environment
43 41 that has been setup. In configuring the environment
44 42 .I ws
45 43 sets up the environment variables to define in which proto areas
46 44 you will build against as well as the proto area the will be your
47 45 install target.
48 46 .LP
49 47 The following Environment variables are set when you invoke this script:
50 48 .LP
51 49 .RS 5
52 50 .nf
53 51 CODEMGR_WS
54 52 SRC
55 53 ROOT
56 54 PARENT_ROOT
57 55 PATH
58 56 MAKEFLAGS
59 57 ENVCPPFLAGS{1-4}
60 58 ENVLDLIBS{1-3}
61 59 .fi
62 60 .RE
63 61 .LP
64 62 The MAKEFLAGS environment variable is set to force make to
65 63 read default make variables from the environment.
66 64 .LP
67 65 The ENVCPPFLAGS{1-4} and the ENVLDLIBS{1-3} environment variables
68 66 are used to configure a hierarchy of proto areas to be used
|
↓ open down ↓ |
16 lines elided |
↑ open up ↑ |
69 67 when compiling and linking in the SunOS environment.
70 68 The values for these environment variables will be set according to
71 69 your values for PROTO1, PROTO2, and PROTO3 variables(discussed below).
72 70 .LP
73 71 Workspace names can be specified in two forms: pathname and
74 72 hostname:pathname. If the hostname:pathname form is used
75 73 the script will access the environment through the /net automounter
76 74 maps. If <workspace> is is a relative pathname not found
77 75 in the current directory, check for it in those
78 76 directories listed in the CODEMGR_WSPATH variable (refer to the
79 -workspace(1) man page for more info on CODEMGR_WSPATH).
77 +workspace(1) man page for more info on CODEMGR_WSPATH).
80 78 .LP
81 79 Note that if a workspace argument is not given ws will try to determine
82 80 if the current directory is in a workspace and set the environment for
83 81 that workspace.
84 82 .LP
85 83 .I ws
86 -will also check for the presense of the ONBLD construction set
87 -(/opt/onbld), if it is found it will prepend the
84 +will also check for the presense of the ONBLD construction set
85 +(/opt/onbld), if it is found it will prepend the
88 86 ONBLD construction set directory to the front of your PATH.
89 87 If you set your path in your shell
90 88 start-up file (eg: .cshrc) then that will undo what what
91 89 .I ws
92 90 has done. If you do this in your shell start-up script,
93 91 conditionally protect
94 -.I ws
92 +.I ws
95 93 from your modification with something like this:
96 94 .LP
97 95 .RS 5
98 96 .nf
99 97 if ( ! $?ONBLD_DIR ) then
100 98 set path=( ~/bin $path ) # or however you wish to modify path
101 99 endif
102 100 .fi
103 101 .RE
104 102 .LP
105 103 NOTE: this is a csh example, the code would vary with the shell type.
106 -.LP
107 104 .SH OPTIONS
108 -.LP
109 105 .TP
110 106 .B \-e
111 107 prevent ws from calling exit or exec, useful for setting environment in
112 108 another Bourne (sh) compatible shell (hint: source ws -e)
113 -.LP
114 109 .SH USAGE
115 110 .LP
116 -At start-up time
117 -.I ws
111 +At start-up time
112 +.I ws
118 113 will determine the number of proto areas to
119 114 be searched and in what order. This information is configured
120 -during the first invocation of
115 +during the first invocation of
121 116 .I ws
122 117 for each workspace in the protodefs
123 118 file. This file is located under the avocet directory
124 119 in your workspace:
125 120 .LP
126 121 .RS 5
127 122 .nf
128 123 $CODEMGR_WS/avocet/sunos/protodefs
129 124 .fi
130 125 .RE
131 126 .LP
132 -In this file you may configure from one to four proto
133 -variables (PROTO1, PROTO2, PROTO3, TERMPROTO).
127 +In this file you may configure from one to four proto
128 +variables (PROTO1, PROTO2, PROTO3, TERMPROTO).
134 129 These variables define the order in
135 130 which the proto areas will be searched, starting with the PROTO1
136 -directory and ending in the PROTO3 directory.
131 +directory and ending in the PROTO3 directory.
137 132 .LP
138 133 When you define the PROTO hierarchy you are defining a list of proto
139 134 directories in which to search for header files and libraries during
140 135 a build. Refer to the
141 136 Examples section below on how you might configure these PROTO
142 137 definitions.
143 138 .LP
144 139 Also, your initial value for ROOT will be assigned to PROTO1. This
145 140 means that if you do any install builds in the SunOS source tree;
146 -they will install in the proto area pointed to by PROTO1.
141 +they will install in the proto area pointed to by PROTO1.
147 142 .LP
148 143 The format for the protodefs file is very simple, it follows the
149 -shell script formats for assigning variables. Here is an
144 +shell script formats for assigning variables. Here is an
150 145 example of some definitions
151 146 you might find in a protodefs file:
152 147 .LP
153 148 .RS 5
154 149 .nf
155 150 PROTO1=$CODEMGR_WS/proto
156 151 PROTO2=/parents_path/proto
157 152 .fi
158 153 .RE
159 154 .LP
160 -The above example would specify
155 +The above example would specify
161 156 that the current workspaces proto area is
162 157 to be searched first, and then the parent workspace's proto area will be
163 158 searched for included files and libraries. In that order.
164 159 .LP
165 160 The TERMPROTO variable is a special case from PROTO{1-3}, it is
166 161 used to specify a terminating search path for your compiling
167 -and linking. If you specify a TERMPROTO directory then during
162 +and linking. If you specify a TERMPROTO directory then during
168 163 your compile and link your search path for libraries and include
169 164 files will terminate there. If you do not specify the
170 165 TERMPROTO variable, then the terminating point for searches will
171 166 be on the native machine. On a 5.x machine this will be /usr/include
172 167 and /usr/lib.
173 168 .LP
174 169 The default values for PROTO1 and PROTO2 will be set by
175 170 .I ws
176 -initially to point to your current workspaces proto area and
171 +initially to point to your current workspaces proto area and
177 172 the proto area
178 173 of the workspace's parent, if the parent is an Avocet
179 -workspace.
174 +workspace.
180 175 .LP
181 176 The PROTO{1-3} variables will then be used to set your ROOT variable and
182 177 to set the ENVCPPFLAGS{1-4} and the ENVDLLIBS{1-3} environment variables.
183 178 These will be set to an architecture specific directory under
184 179 each PROTO* directory. If, for example, PROTO1 had been set
185 -to PROTO1=/ws/train/proto then ROOT would be set to
180 +to PROTO1=/ws/train/proto then ROOT would be set to
186 181 ROOT=/ws/train/proto/root_${MACH}. MACH would be equal to the
187 182 architecture of the machine you are running on (ie: `uname -p`).
188 183 .LP
189 184 The exception to this is if there is already an existing non-architecture
190 -specific populated proto area
185 +specific populated proto area
191 186 under one of the PROTO{1-3} variables. If this is the case then the
192 187 ROOT and other flags will be based on that instead of an architecture
193 188 specific sub-directory.
194 -.LP
195 189 .SH ISSUES
196 190 .LP
197 191 The use of Constrained Files is very different between an NSE
198 192 environment and an avocet workspace. Constrained files are files which
199 193 are derived but files that you do not have source code for. For
200 194 example in an NSE environment, a library would be a constrained file if
201 195 you acquired a command that depended on that library but you did not
202 196 acquire the library's sources. If a user is used to working in an NSE
203 197 environment they should be aware of the differences.
204 198 .LP
205 199 In an NSE environment the user was isolated from updates to both
206 200 constrained files and source files
207 201 alike in the parent environment. You did not see updates
208 -to constrained files until you
209 -.I resynced
202 +to constrained files until you
203 +.I resynced
210 204 a command or object which depended on the
211 -constrained file in question.
212 -This is no longer the case under Avocet.
205 +constrained file in question.
206 +This is no longer the case under Avocet.
213 207 .LP
214 208 If you are using
215 209 .I ws
216 210 to refer to a copy of such a library located in your parent
217 211 workspace's proto area, you are no longer isolated as you were use
218 212 the NSE.
219 213 If your parent updates its copy of the constrained file(libc.so)
220 214 in it's proto area and you are referencing the parents
221 215 proto area via ws, then
222 216 that update is immediately visible to you. The next time you
223 217 build a new command in your avocet workspace you will be building
224 218 against the new copy of the constrained file(libc.so) which you
225 219 obtain from your parents proto area, you are no longer isolated from
226 220 these updates as you were in the NSE.
227 221 .LP
228 222 If you would like to be isolated from updates in the
229 223 world around you there are a couple of approaches you can take. First,
230 224 if you bringover a full copy of the SunOS source base you could
231 -build your own PROTO area which you would link against.
225 +build your own PROTO area which you would link against.
232 226 Secondly, you could link against a private
233 227 PROTO area which is a stable snapshot of a global proto area.
234 228 This proto area could be a subset
235 229 of a full proto area and contain only those files which you are concerned
236 230 about. Both of these methods would protect you from updates to files
237 231 because you would be in full control of the proto areas you are linking
238 232 against. It would be your responsiblity to update your proto area
239 233 as your work progressed.
240 -.LP
241 234 .SH EXAMPLES
242 235 .LP
243 -In the following examples you will modify the
236 +In the following examples you will modify the
244 237 ${CODEMGR_WS}/avocet/sunos/protodefs file to define PROTO{1-3}
245 238 to configure a proto hierarchy to be associated with your
246 239 avocet workspace. I have selected the four
247 240 most common examples that will be used with avocet workspaces,
248 241 there can be many other combinations.
249 242 .LP
250 -In the first example we will
251 -configure a workspace named
243 +In the first example we will
244 +configure a workspace named
252 245 caltrans:/bld/child,
253 246 and it is a child of an avocet workspace named dunk:/build/parent. The
254 247 parent workspace (dunk:/build/parent)
255 248 is a complete copy of the usr/src source tree, while the
256 249 current workspace(caltrans:/bld/child) is a subset of the full
257 -source base. The current(child) workspace only contains the usr/src/cmd
250 +source base. The current(child) workspace only contains the usr/src/cmd
258 251 directories. The proto areas that
259 252 we want to search are the current workspaces proto area(/bld/child/proto)
260 253 and then the proto area of the parent(/net/dunk/build/parent/proto), in that
261 -order.
254 +order.
262 255 Actually, this example is the default behavior if the workspace
263 256 is not a child of an NSE parent. No modification would actually have
264 257 to have been done to the protodefs file.
265 258 Here is what the protodefs file would look like:
266 259 .LP
267 260 .RS 5
268 261 .nf
269 262 PROTO1=/bld/scrapbook/proto
270 263 PROTO2=/net/dunk/build/ws/proto
271 264 .fi
272 265 .RE
273 266 .LP
274 267 This example represents a model where the current workspaces needs
275 268 to reference a superset of its own proto area in order to build.
276 269 .LP
277 -Secondly, let us consider a workspace you have named
270 +Secondly, let us consider a workspace you have named
278 271 polyslo:/charlie/tuna. Your
279 272 workspace only contains the source code for the usr/src/cmd
280 -directories. Secondly, your avocet parent(dunk:/build/popeye) is not a
273 +directories. Secondly, your avocet parent(dunk:/build/popeye) is not a
281 274 full copy of
282 275 the source base, but it does have some files in the proto area which
283 276 you want to refer to. Lastly, you have a global proto area which you
284 277 will refer to if you have not found a header file or library in either
285 278 of the two previous proto areas, this global proto area is located
286 279 at rainman:/space/I-team-protoarea. Here is what your protodefs file
287 280 would look like:
288 281 .LP
289 282 .RS 5
290 283 .nf
291 284 PROTO1=/charlie/tuna/proto
292 285 PROTO2=/net/dunk/build/popeye/proto
293 286 PROTO3=/net/rainman/space/I-team-protoarea
294 -.fi
287 +.fi
295 288 .RE
296 289 .LP
297 290 The above model is meant to show you some of the configurability that can
298 291 be done
299 292 .I ws.
300 293 Here you have three proto areas that are searched one after the other. You
301 294 might configure an environment like this if needed to refer to some
302 -files that are in the PROTO2 area, but these files are not
295 +files that are in the PROTO2 area, but these files are not
303 296 easily placed into the 'global' I-Team proto area of PROTO3. It should
304 297 also be noted that there is a performance penalty for such a configuration.
305 298 During each compile the compiler is now potentially searching through
306 299 three directory structures to resolve the include files, this will slow
307 300 things down. If performance is critical you should also be aware
308 301 of which 'subnets' the PROTO areas are located on. The farther away
309 302 the PROTO area is from the 'subnet' you are building on the greater
310 303 the performance hit during compiles.
311 304 .LP
312 305 Next, here is a very simple example. We have a workspace which is a small
313 306 subset of the usr/src/cmd directory named(caltrans:/build/small_cmd) that
314 307 has no proto area associated with it. For our proto area we will refer
315 308 to a Global 'I-Team' proto area for all of our files. This area is
316 309 located at rainman:/space/global_proto_area. In the protodefs file
317 310 we will only need to define PROTO1 for this example:
318 311 .RS 5
319 -.nf
312 +.nf
320 313 PROTO1=/net/rainman/space/global_proto_area
321 314 .fi
322 315 .RE
323 316 .LP
324 317 This is the example you would follow for very small workspaces
325 318 with which you do not intend to modify and install any headers
326 319 or libraries. All of the
327 320 include files and libraries will be pulled from the I-TEAM proto area.
328 321 The advantage to this model is speed, there is only one area in which
329 322 the compiler is going to search for include files and libraries, this
330 -will help the compilers performance. Also, you should be aware that
323 +will help the compilers performance. Also, you should be aware that
331 324 ROOT is equal to PROTO1. If you attempt to do an install build it
332 325 will attempt to modify the I-Team proto area that you are pointing at!
333 326 .LP
334 -Lastly, we have an avocet workspace named
335 -caltrans:/bld/nse_child which is the child of an NSE environment.
327 +Lastly, we have an avocet workspace named
328 +caltrans:/bld/nse_child which is the child of an NSE environment.
336 329 Because the parent of the workspace is an NSE environment, that parent
337 -does not have a PROTO area associated with it that we can
330 +does not have a PROTO area associated with it that we can
338 331 refer to. Instead there is a global PROTO area that is maintained
339 332 by our 'I-Team' leader that we will refer to. That global area
340 333 is located at rainman:/space/I-team-protoarea. Here is what
341 334 the protodefs file would look like:
342 335 .LP
343 336 .RS 5
344 337 .nf
345 338 PROTO1=/bld/nse_child
346 339 PROTO2=/net/rainman/space/I-team-protoarea
347 340 .fi
348 341 .RE
349 342 .LP
350 343 This model differs from the one above in that we can not reference
351 -the parents proto area because the parent in an NSE environment.
344 +the parents proto area because the parent in an NSE environment.
352 345 Instead for our second proto area we point to a stable proto
353 346 area outside of the NSE.
354 -.LP
355 347 .SH ENVIRONMENT VARIABLES
356 348 .LP
357 -Here is a list of the environment variables that
349 +Here is a list of the environment variables that
358 350 .I ws
359 351 will set and how they are used:
360 352 .LP
361 -CODEMGR_WS
362 -.fi
353 +CODEMGR_WS
363 354 .RS 5
364 355 Absolute pathname to the Avocet workspace. This environment variable
365 356 is referenced by the
366 357 .I bringover
367 358 ,
368 359 .I putback
369 360 ,
370 361 and
371 362 .I workspace
372 363 commands.
373 364 .RE
374 365 SRC
375 366 .RS 5
376 367 Root of SunOS source code, referenced by SunOS Makefiles.
377 368 .RE
378 369 ROOT
379 370 .RS 5
380 -Initial proto area for this workspace. Again this is used by the
371 +Initial proto area for this workspace. Again this is used by the
381 372 SunOS Makefiles. This value is set based on PROTO1 as defined in
382 -the protodefs file. ROOT is also the destination of
383 -.I install
373 +the protodefs file. ROOT is also the destination of
374 +.I install
384 375 operations.
385 376 .RE
386 377 PARENT_ROOT
387 378 .RS 5
388 -Parent proto area for this workspace. This is used by the
379 +Parent proto area for this workspace. This is used by the
389 380 SunOS Makefiles. This value is set based on PROTO2 as defined in
390 -the protodefs file.
381 +the protodefs file.
391 382 .RE
392 383 PATH
393 384 .RS 5
394 -If the construction set exists (/opt/onbld) it will be prepended to
385 +If the construction set exists (/opt/onbld) it will be prepended to
395 386 the search path.
396 387 .RE
397 388 MAKEFLAGS
398 389 .RS 5
399 -Default MAKEFLAGS used by
390 +Default MAKEFLAGS used by
400 391 .I make,
401 392 set to 'e' for higher environment precedence.
402 393 .RE
403 394 ENVCPPFLAGS{1-4}
404 395 .RS 5
405 -This set of environment variables is used to set the
396 +This set of environment variables is used to set the
406 397 CPPFLAGS.master macro within the SunOS source tree. These values
407 398 usually point to a hierarchy of Include directories for the build
408 399 to search through.
409 400 .RE
410 401 ENVLDLIBS{1-3}
411 402 .RS 5
412 403 This set of environment variables is used to set the LDLIBS.master
413 404 macro within the SunOS source tree. These values usually point
414 405 to a hierarchy of directories to search for libraries.
415 406 .RE
416 -.LP
417 407 .SH FILES
418 408 .LP
419 409 .nf
420 410 $CODEMGR_WS/avocet/sunos/protodefs
421 411 .fi
422 -.LP
423 412 .SH "SEE ALSO"
424 413 .LP
425 414 .IR workspace (1),
426 415 .IR bringover (1ONBLD),
427 416 .IR putback (1),
428 417 .IR protodefs(5)
429 -.LP
430 418 .SH BUGS
431 419 .LP
432 420 TERMPROTO is broken.
433 421 On 5.x builds TERMPROTO is incompatible with the C++ driver. The bug
434 422 is that the C++ driver does not use the standard SVR4 notation
435 423 for the -Y I, option.
436 424 .LP
437 425 .I ws
438 426 can have problems with the automounter. If you refer to a workspace
439 -using a relative path, and that workspace is mounted via the automounter,
427 +using a relative path, and that workspace is mounted via the automounter,
440 428 then that workspace will be refered to via the /tmp_mnt/*
441 429 location. It's best to deal with automounted workspaces through
442 430 an absolute pathname when running
443 431 .I ws.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX