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)