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