


WS(1)                     User Commands                     WS(1)



NAME
     ws - enable SunOS CodeManager workspaces

SYNOPSIS
     ws <workspace_name>

DESCRIPTION
     Ws will configure your environment to build the SunOS source
     base  from  an CodeManager workspace.  The ws script sets up
     the environment variables for a SunOS CodeManager  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
          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  environ-
     ment.   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).

     ws will also check for the presense of the  ONBLD  construc-
     tion  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:



SunOS 5.5         Last change: 10 January 1996                  1






WS(1)                     User Commands                     WS(1)



          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.

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

          $CODEMGR_WS/Codemgr_wsdata/sunos/protodefs

     In this file you may configure from one to four proto  vari-
     ables  (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 com-
     piling 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



SunOS 5.5         Last change: 10 January 1996                  2






WS(1)                     User Commands                     WS(1)



     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 CodeManager 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* direc-
     tory.   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 archi-
     tecture specific sub-directory.

ISSUES
     The use of Constrained Files is very  different  between  an
     NSE  environment  and an CodeManager 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  com-
     mand  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 CodeManager.

     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  CodeManager
     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.




SunOS 5.5         Last change: 10 January 1996                  3






WS(1)                     User Commands                     WS(1)



     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  responsi-
     blity to update your proto area as your work progressed.

EXAMPLES
     In   the   following   examples   you   will   modify    the
     ${CODEMGR_WS}/codemgr_wsdata/sunos/protodefs  file to define
     PROTO{1-3} to configure a proto hierarchy to  be  associated
     with  your  CodeManager workspace.  I have selected the four
     most common examples that  will  be  used  with  CodeManager
     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 CodeManager
     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.  Actu-
     ally,  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
     CodeManager 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



SunOS 5.5         Last change: 10 January 1996                  4






WS(1)                     User Commands                     WS(1)



     areas,   this   global   proto   area    is    located    at
     rainman:/space/I-team-protoarea.   Here  is what your proto-
     defs 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  configura-
     bility  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 pro-
     todefs 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   CodeManager    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 associ-
     ated with it that we can refer to.  Instead there is a  glo-
     bal  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



SunOS 5.5         Last change: 10 January 1996                  5






WS(1)                     User Commands                     WS(1)



     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.

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

     CODEMGR_WS
          Absolute pathname to the CodeManager  workspace.   This
          environment  variable  is referenced by the bringover ,
          putback , and workspace commands.
     SRC
          Root  of  SunOS  source  code,  referenced   by   SunOS
          Makefiles.
     ROOT
          Initial proto area for this workspace.  Again  this  is
          used  by  the SunOS Makefiles.  This value is set based
          on PROTO1 as defined in the protodefs  file.   ROOT  is
          also the destination of install operations.
     PATH
          If the construction set exists (/opt/onbld) it will  be
          prepended to the search path.
     MAKEFLAGS
          Default MAKEFLAGS used by make, set to 'e'  for  higher
          environment precedence.
     ENVCPPFLAGS{1-4}
          This set of environment variables is used  to  set  the
          CPPFLAGS.master  macro  within  the  SunOS source tree.
          These values usually point to a  hierarchy  of  Include
          directories for the build to search through.
     ENVLDLIBS{1-3}
          This set of environment variables is used  to  set  the
          LDLIBS.master  macro  within  the  SunOS  source  tree.
          These values usually point to  a  hierarchy  of  direc-
          tories to search for libraries.

FILES
     $CODEMGR_WS/Codemgr_wsdata/sunos/protodefs

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

BUGS
     TERMPROTO is broken.  On 5.x builds TERMPROTO is  incompati-
     ble  with  the  C++  driver.  The bug is that the C++ driver



SunOS 5.5         Last change: 10 January 1996                  6






WS(1)                     User Commands                     WS(1)



     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.














































SunOS 5.5         Last change: 10 January 1996                  7



