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