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