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