Ws will configure your environment to build the SunOS source base from an avocet workspace. The ws script sets up the environment variables for a SunOS avocet workspace and spawns a shell for the environment that has been setup. In configuring the environment ws sets up the environment variables to define in which proto areas you will build against as well as the proto area the will be your install target.

The following Environment variables are set when you invoke this script:

CODEMGR_WS
SRC
ROOT
PARENT_ROOT
PATH
MAKEFLAGS
ENVCPPFLAGS{1-4}
ENVLDLIBS{1-3}

The MAKEFLAGS environment variable is set to force make to read default make variables from the environment.

The ENVCPPFLAGS{1-4} and the ENVLDLIBS{1-3} environment variables are used to configure a hierarchy of proto areas to be used when compiling and linking in the SunOS environment. The values for these environment variables will be set according to your values for PROTO1, PROTO2, and PROTO3 variables(discussed below).

Workspace names can be specified in two forms: pathname and hostname:pathname. If the hostname:pathname form is used the script will access the environment through the /net automounter maps. If <workspace> is is a relative pathname not found in the current directory, check for it in those directories listed in the CODEMGR_WSPATH variable (refer to the workspace(1) man page for more info on CODEMGR_WSPATH).

Note that if a workspace argument is not given ws will try to determine if the current directory is in a workspace and set the environment for that workspace.

ws will also check for the presense of the ONBLD construction set (/opt/onbld), if it is found it will prepend the ONBLD construction set directory to the front of your PATH. If you set your path in your shell start-up file (eg: .cshrc) then that will undo what what ws has done. If you do this in your shell start-up script, conditionally protect ws from your modification with something like this:

if ( ! $?ONBLD_DIR ) then
 set path=( ~/bin $path ) # or however you wish to modify path
endif

NOTE: this is a csh example, the code would vary with the shell type.

-e prevent ws from calling exit or exec, useful for setting environment in another Bourne (sh) compatible shell (hint: source ws -e)

At start-up time ws will determine the number of proto areas to be searched and in what order. This information is configured during the first invocation of ws for each workspace in the protodefs file. This file is located under the avocet directory in your workspace:

$CODEMGR_WS/avocet/sunos/protodefs

In this file you may configure from one to four proto variables (PROTO1, PROTO2, PROTO3, TERMPROTO). These variables define the order in which the proto areas will be searched, starting with the PROTO1 directory and ending in the PROTO3 directory.

When you define the PROTO hierarchy you are defining a list of proto directories in which to search for header files and libraries during a build. Refer to the Examples section below on how you might configure these PROTO definitions.

Also, your initial value for ROOT will be assigned to PROTO1. This means that if you do any install builds in the SunOS source tree; they will install in the proto area pointed to by PROTO1.

The format for the protodefs file is very simple, it follows the shell script formats for assigning variables. Here is an example of some definitions you might find in a protodefs file:

PROTO1=$CODEMGR_WS/proto
PROTO2=/parents_path/proto

The above example would specify that the current workspaces proto area is to be searched first, and then the parent workspace's proto area will be searched for included files and libraries. In that order.

The TERMPROTO variable is a special case from PROTO{1-3}, it is used to specify a terminating search path for your compiling and linking. If you specify a TERMPROTO directory then during your compile and link your search path for libraries and include files will terminate there. If you do not specify the TERMPROTO variable, then the terminating point for searches will be on the native machine. On a 5.x machine this will be /usr/include and /usr/lib.

The default values for PROTO1 and PROTO2 will be set by ws initially to point to your current workspaces proto area and the proto area of the workspace's parent, if the parent is an Avocet workspace.

The PROTO{1-3} variables will then be used to set your ROOT variable and to set the ENVCPPFLAGS{1-4} and the ENVDLLIBS{1-3} environment variables. These will be set to an architecture specific directory under each PROTO* directory. If, for example, PROTO1 had been set to PROTO1=/ws/train/proto then ROOT would be set to ROOT=/ws/train/proto/root_${MACH}. MACH would be equal to the architecture of the machine you are running on (ie: `uname -p`).

The exception to this is if there is already an existing non-architecture specific populated proto area under one of the PROTO{1-3} variables. If this is the case then the ROOT and other flags will be based on that instead of an architecture specific sub-directory.

The use of Constrained Files is very different between an NSE environment and an avocet workspace. Constrained files are files which are derived but files that you do not have source code for. For example in an NSE environment, a library would be a constrained file if you acquired a command that depended on that library but you did not acquire the library's sources. If a user is used to working in an NSE environment they should be aware of the differences.

In an NSE environment the user was isolated from updates to both constrained files and source files alike in the parent environment. You did not see updates to constrained files until you resynced a command or object which depended on the constrained file in question. This is no longer the case under Avocet.

If you are using ws to refer to a copy of such a library located in your parent workspace's proto area, you are no longer isolated as you were use the NSE. If your parent updates its copy of the constrained file(libc.so) in it's proto area and you are referencing the parents proto area via ws, then that update is immediately visible to you. The next time you build a new command in your avocet workspace you will be building against the new copy of the constrained file(libc.so) which you obtain from your parents proto area, you are no longer isolated from these updates as you were in the NSE.

If you would like to be isolated from updates in the world around you there are a couple of approaches you can take. First, if you bringover a full copy of the SunOS source base you could build your own PROTO area which you would link against. Secondly, you could link against a private PROTO area which is a stable snapshot of a global proto area. This proto area could be a subset of a full proto area and contain only those files which you are concerned about. Both of these methods would protect you from updates to files because you would be in full control of the proto areas you are linking against. It would be your responsiblity to update your proto area as your work progressed.

In the following examples you will modify the ${CODEMGR_WS}/avocet/sunos/protodefs file to define PROTO{1-3} to configure a proto hierarchy to be associated with your avocet workspace. I have selected the four most common examples that will be used with avocet workspaces, there can be many other combinations.

In the first example we will configure a workspace named caltrans:/bld/child, and it is a child of an avocet workspace named dunk:/build/parent. The parent workspace (dunk:/build/parent) is a complete copy of the usr/src source tree, while the current workspace(caltrans:/bld/child) is a subset of the full source base. The current(child) workspace only contains the usr/src/cmd directories. The proto areas that we want to search are the current workspaces proto area(/bld/child/proto) and then the proto area of the parent(/net/dunk/build/parent/proto), in that order. Actually, this example is the default behavior if the workspace is not a child of an NSE parent. No modification would actually have to have been done to the protodefs file. Here is what the protodefs file would look like:

PROTO1=/bld/scrapbook/proto
PROTO2=/net/dunk/build/ws/proto

This example represents a model where the current workspaces needs to reference a superset of its own proto area in order to build.

Secondly, let us consider a workspace you have named polyslo:/charlie/tuna. Your workspace only contains the source code for the usr/src/cmd directories. Secondly, your avocet parent(dunk:/build/popeye) is not a full copy of the source base, but it does have some files in the proto area which you want to refer to. Lastly, you have a global proto area which you will refer to if you have not found a header file or library in either of the two previous proto areas, this global proto area is located at rainman:/space/I-team-protoarea. Here is what your protodefs file would look like:

PROTO1=/charlie/tuna/proto
PROTO2=/net/dunk/build/popeye/proto
PROTO3=/net/rainman/space/I-team-protoarea

The above model is meant to show you some of the configurability that can be done ws. Here you have three proto areas that are searched one after the other. You might configure an environment like this if needed to refer to some files that are in the PROTO2 area, but these files are not easily placed into the 'global' I-Team proto area of PROTO3. It should also be noted that there is a performance penalty for such a configuration. During each compile the compiler is now potentially searching through three directory structures to resolve the include files, this will slow things down. If performance is critical you should also be aware of which 'subnets' the PROTO areas are located on. The farther away the PROTO area is from the 'subnet' you are building on the greater the performance hit during compiles.

Next, here is a very simple example. We have a workspace which is a small subset of the usr/src/cmd directory named(caltrans:/build/small_cmd) that has no proto area associated with it. For our proto area we will refer to a Global 'I-Team' proto area for all of our files. This area is located at rainman:/space/global_proto_area. In the protodefs file we will only need to define PROTO1 for this example:

 
PROTO1=/net/rainman/space/global_proto_area

This is the example you would follow for very small workspaces with which you do not intend to modify and install any headers or libraries. All of the include files and libraries will be pulled from the I-TEAM proto area. The advantage to this model is speed, there is only one area in which the compiler is going to search for include files and libraries, this will help the compilers performance. Also, you should be aware that ROOT is equal to PROTO1. If you attempt to do an install build it will attempt to modify the I-Team proto area that you are pointing at!

Lastly, we have an avocet workspace named caltrans:/bld/nse_child which is the child of an NSE environment. Because the parent of the workspace is an NSE environment, that parent does not have a PROTO area associated with it that we can refer to. Instead there is a global PROTO area that is maintained by our 'I-Team' leader that we will refer to. That global area is located at rainman:/space/I-team-protoarea. Here is what the protodefs file would look like:

PROTO1=/bld/nse_child
PROTO2=/net/rainman/space/I-team-protoarea

This model differs from the one above in that we can not reference the parents proto area because the parent in an NSE environment. Instead for our second proto area we point to a stable proto area outside of the NSE.

Here is a list of the environment variables that ws will set and how they are used:

CODEMGR_WS

$CODEMGR_WS/avocet/sunos/protodefs

workspace (1), bringover (1), putback (1), protodefs(5)

TERMPROTO is broken. On 5.x builds TERMPROTO is incompatible with the C++ driver. The bug is that the C++ driver does not use the standard SVR4 notation for the -Y I, option.

ws can have problems with the automounter. If you refer to a workspace using a relative path, and that workspace is mounted via the automounter, then that workspace will be refered to via the /tmp_mnt/* location. It's best to deal with automounted workspaces through an absolute pathname when running ws.