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