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