To:       MAB Distribution

From:     Paul W. Benjamin

Date:     04/26/83

Subject:  The Experimental Library


To  define  policy  and   procedure  governing  the  experimental
library.   This document  supercedes and  replaces MAB-032, which
was written in 1976 by Steve  Webber.  Much of the information in
that  document  is  outdated  and  the  information  that  is not
outdated has become suspect by  association.  As of this writing,
the  only rule  governing EXL is  that there are  no rules.  This
document is being written in hopes of correcting that situation.


The purpose of the library is twofold.  It is for the exposure of
new versions of existing software,  changes that are destined for
installation  in  standard libraries  and  are made  available in
hopes of finding  errors prior to such installation.   It is also
for experimental software, i.e.  new  products or new features in
existing  products that  are being  "tried out"  in some fashion.
Such  software  is  often  subject  to  drastic  change  and even
deletion.  There has  been discussion on the need  for 2 separate
libraries, >experimental and >exposure,  the rationale being that
users  could  include  >exposure  in their  search  rules, taking
advantage of bugfixes, while  avoiding the more volatile software
in  >exl.    The  main  problem   with  that  proposal   is  that
experimental enhancements and bugfixes  often coexist in the same
body of software, perhaps the same bound segment or even the same
module  therein.  Trying  to maintain two  distinct versions, one
for  bugfixes  and  one   for  experimentation  would  present  a
nightmare  in  configuration management.   Further, there  is not
always a clear distinction between "new feature" and "bugfix".  A
modest enhancement  in response to  a TR System  suggestion would
fall somewhere in the middle.


With the dual nature of the library in mind, it is useful to call
upon  a  portion  of  Mr.   Webber's  description,  altered where
appropriate, of the attributes of software in the library:

1.   The programs  will not be  needed in any way  to generate or
     run the standard system.

2.   The  programs will  be documented  by online  info segs and,
     where available and appropriate, online MPM documentation.

3.   The programs will not be formally supported.  However, users
     will  be  encouraged  to  use  those  that  are  preliminary
     versions  of  software to  be formally  released at  a later
     date.   The TR  System may  be used  to report  bugs or make

4.   The programs  might exist only  in the transient  state from
     one Multics release to another.  They are not distributed to
     customer sites except by  special agreement (e.g., Beta Test
     Site or RPQ agreements).


The library  exists as a  directory off the  root, >experimental,
with added  names EXL, experimental_library, exl  and x.  The EXL
library will be maintained on  both System-M and the MIT-Multics.
Those  sites  shall grant  appropriate access  to members  of the
Multics  project  to maintain  the libraries.   These individuals
will, in  turn, grant sma  access for the  sub-hierarchies to the
appropriate  developers.   Each item  in  the EXL  library  has a
primary  site (the  site at  which it  is first  installed) and a
secondary site.

In describing a standardization of  the structure of the library,
it should  be understood that there  are existing sub-hierarchies
within the library  that do not conform.  It  is recommended that
existing  libraries  be  altered   to  conform  to  the  standard
structure, but  this is not  a requirement.  It  is required that
any new directories conform to the standard.  Under the directory
>exl, there are 3 standard directories:


and multiple software-specific directories.  Note that this is an
alteration of  the structure as  of this writing.   There is much
confusion  vis-a-vis  directories  named  object,  executable and
bound_components.  The intent here is to conform to the directory
structure used in >ldd>hard.  The names object, O and o are added
to executable for compatibility with the existing structure.  The
3 standard directories should contain  nothing but links into the
appropriate location  in the software-specific  directories.  The
software-specific directories  should have a primary  name of the
form  product_dir,  (examples:   forum_dir,  probe_dir, ted_dir).
Added names are at the discretion of the responsible developer (3
character  names terminating  with the letter  d such  as pld for
pl1_dir  or  emd  for  emacs_dir  are  quite  common).   The only
restriction  is  that  the  name  must  not  be  the  name  of an
executable entry,  i.e.  fdoc would  not be an  appropriate added
name for >exl>fdoc_dir.

These sub-hierarchies should have the following directories:

     >exl>product_dir>source (s, S)
     >exl>product_dir>execution (e, executable, x, ex)
     >exl>product_dir>object (o, O)
     >exl>product_dir>include (incl, i)

The  source  directory  should   contain  source  archives.   The
execution directory should contain executable code.  There should
be links in  >exl>e (with appropriate added names)  that point to
this  code.   A  developer   requiring  such  links  should  make
arrangement  with  one  of  the  site-specified  individuals with
access  to  do so.   The object  directory should  contain object
archives   (the   archives  themselves   containing   object  and
bindfiles).  The info and include directories should contain info
segs and  include files, respectively, with  appropriate links in
>exl>info  and  >exl>include.   This   is  not  to  preclude  the
existence of other directories  in sub-hierarchies, but it should
be noted that space is limited in  >exl and it should not be used
a repository for whatever the developer happens to need stored.

The  directories  should be  structured so  that users  can alter
their  search  rules  or  search   paths  to  use  them.   Object
directories, for example, should contain only executable code and
exec_coms.   Include files  should not  be archived,  in order to
allow  the  user to  include the  directory in  translator search


The installation of new versions  of software that already exists
in the EXL  library is the responsibility of  the developer.  The
only guideline  is that some method  (update_seg, for example) be

used  to  avoid  problems  with   users  that  already  have  the
about-to-be-replaced  version initiated.   In general, executable
code  should have  an ACLE  of re  * and  source archives, object
archives, include files and info segs  should all have ACLEs of r
*.  All such segments should  have ring brackets of 4,5,5, again,
unless there is specific reason not to do so.

To add a new directory to the library, the procedure differs with
the  nature  of what  is being  installed.  If  a version  of the
software  in  question  exists  in a  standard  library,  then no
special procedures are required.  One  need only ask someone with
the correct access to create a directory for them and then follow
the rules of this MAB in  setting up the directory.  If, however,
the software is new and does  not exist in a productized form, it
shall  require  an  approved MCR  prior  to the  creation  of the
directory.  The subject of the MCR could either be to install the
product  in  a  system  library  or  simply  to  create  the  EXL
directory.  To paraphrase, it would  not require an MCR to create
an alm_dir, but it would require an MCR to create a qbe_dir.

In addition, a  forum meeting (>udd>m>meetings>EXL_Library (exl))
shall  be established.   Developers will  be encouraged  to enter
information  relevant to  new directories  and new  or changed or
deleted software in this meeting.


All  software   in  the  EXL  library   should  have  appropriate
copyrights.   It is  the responsibility  of the  developer to see
that this  is done.  The  add_pnotice command is  the appropriate
means of copyrighting software.  The developer should be familiar
with  the content  of MAB-052, Standards  for Software Protection
and Software Technical Identifiers.


The following information has been contributed by Charles Hornig:

It is possible to have  EXL software transferred to the secondary
site automatically.  To have this done, you should send a list of
the directories you wish carried to the current EXL Carrymeister.
The  EXL  Carrymeister is  the  CISL developer  who  is currently
responsible for  the Carry procedures.   As of this  writing that
individual  is  Charles  Hornig,  but  the  resonsibility changes
periodically.   The list  of directories  should be  divided into
those  which  can  be carried  in  place (like  include  and info
directories)  and   those  which  must   be  installed  specially
(executable).  You should also indicate  which of System-M or MIT
is the  primary site for  the software.  The  directories will be
added to the list of those carried.

The carries themselves are done  on Sunday morning.  Any segments
in  the directories  listed which  has had  its contents modified
since the  last carry will  be transferred to  the secondary site
via IMFT.  Those which  need special installation are transferred
to a  holding directory and  installed in their  proper places on
Monday morning.

Segments with  an exclamation point  ("!") in any  of their names
will not be  carried.  This can be used  to protect site-specific
segments, as well as old versions made by update_seg.  Please use
this convention to cut down on congestion on the IMFT link.

The  following are  suggestions on  how to  keep the Carrymeister
happy.  Don't ask for all your  directores to be carried.  If you
don't  need  source and  object archives  at the  secondary site,
don't have them carried.  IMFT is pretty slow sometimes.

Don't  move  names  from  one  bound  segment  to  another.   The
update_seg is used to install  the special segments, and this can
make it unhappy.  This means that  the EXL Carrymeister has to go
in and fix it up by hand.

Keep  your directories  clean.  Don't  make the  EXL Carrymeister
spend  a  lot of  time carrying  .list segments  you left  in the
source directory.