HOW TO INSTALL SOFTWARE IN /r/share1


    To install packages into /r/share1 you need to be a member of the 
"share" group. To become a member of this group, send mail to share@cs
including information on what you plan to install.
    Being member of the share group gives you rights and responsabilities.
/r/share1 must be understood as a service offered to all users.

DIRECTIONS - (for foreign language software, look further)

1) Build the software in its own hierarchy under /r/share1/src. Some software
   needs 2 hierarchies, one for the construction and one for the "installation"
   ("make" and "make install"). In this case, create both hierarchies under
   /r/share1/src, eg src/emacs-19.29 (to build), src/emacs (to "install"),
   and remove the building hierarchy at the end. Do NOT run "make install"
   to install outside /r/share1/src.
2) Make symbolic links from /r/share1/man/man?/, /r/share1/include,
   /r/share1/lib as needed. Create sub-hierarchies in /r/share/lib to
   gather the related symbolic links and to distinguish architecture specific
   files.
3) Under /r/share1/bin:
   - make symbolic links to architecture-independent executable files,
   - write shell scripts that launch the executable files on supported 
     architectures and output an error message on unsupported architectures
     (see /r/share1/bin/hotjava for an example).
4) Write a UCLA-README with as little information as is needed to use the
   program (especially the installation-specific information). 
   You may also (this is optional) write a UCLA-INSTALL intended to future
   maintainers.
   Examples are /r/share1/src/hotjava/UCLA-README, src/mindy/UCLA-README, 
   and src/mindy/UCLA-INSTALL.
5) Add 2 lines describing what you installed in the "content" section in
   /r/share1/README. This part will be regularly posted on "grads".
6) Post an announce for your software on "grads". The UCLA-README is fine for
   that.

*Please, do all steps or none*

Update the windex database:

If you added man pages in /r/share1/man, update the windex database
(so that man -k <keyword> will work). To update (actually, rebuild) the 
database, do:
	catman -M /r/share1/man

FILE ORGANIZATION

/r/share1/
     |- src/<package>
     |- bin/<scripts-or-symb-links-to-package-commands>
     |- man/
     |   |-  man?/<symb-links-to-package-man-pages>
     |   |-  cat?/<formated-man-pages-built-by-catman>
     |   +-  windex (index built by catman for use with "man -k") 
     |- lib/
     |   |-  <package-name>/<symb-links-to-package-libs> 
     |   |       ( <package-name> is optional, the organization 
     |   |        of lib/<package-name> package dependent, may contain
     |   |        "sunos" and "solaris" sub-directories... )
     |   +-  X11/app-defaults/<symb-links-to-package-X-res-files>
     |- include
     |   |-   <package-name>/<symb-links-to-package-incs> (as for lib above)
     |   +-   X11/pixmaps/<symb-links-to-package-xpm-files>
     |
     |- foreign/ (/r/share1 area dedicated to sw for foreign countries,
     |            see below for a proposed hierarchy)
     |- news/ (CSD news archives and web pages)
     |- www/ (web pages for /r/share1)
     |- setup/ (sample .cshrc, .xinitrc, etc)
     |- faq/
     |   |-  faq.html  (last version of the User-Run FAQ for the WS room)
     |   +-  faq.txt 
     |- README  
     +- HOW-TO-INSTALL

PROPOSED FILE ORGANIZATION FOR FOREIGN SOFTWARE

* /r/share1/src,bin.lib,include,man : 
  This directories should not contain any foreign language  package

* /r/share1/
      |- src 
      |- ...
      |- foreign - sw supporting foreign languages
           |- src :     source and installation of sw 
           |            supporting several foreign languages
           |- bin      \ 
           |- lib      |  links and scripts pointing to
           |- include  |  packages in foreign/src
           |- man      / 
           |- chinese
           |    |- src :  sw supporting only chinese
           |    |- bin      \ 
           |    |- lib      |  links and scripts pointing to
           |    |- include  |  packages in foreign/chinese/src
           |    +- man      / 
           |- japanese
           |    |- src : sw supporting only japanese
          ...     ...    

IDEAS BEHIND THE FILE ORGANIZATION

* Separation between package mass and interface:

Packages reside in /r/share1/src/<package>. Their interfaces are in
/r/share1/[bin|lib|include|man] and exclusively consist of symbolic links
(or tiny shell scripts for bin, see below). Users only "see" the interface,
while, by contrast, /r/share1/src/<package> is the main installer/maintainer's
workplace.
This scheme makes it easier to 
     1) know how much memory each package uses,
     2) relate files in bin|include|lib|man to their packages, 
     3) accomodate multi-platform support of software transparently 
        for the user (see below).

A little bit more work for the installer may save a lot of time to the users:

- Documentation: man pages installed, UCLA-READMEs for local info, roadmaps,
  "quick try" directions.

- Writing some shell code provides transparent multi-platform support. 
  As a user, suppose you are on maui and do "man javac": you'll get the info.
  Then do "javac": you'll get the message
  "Sorry: javac runs only on Solaris 2.3 and above (SunOS 5.3)".
  Isn't that neat? especially considering we are using unix ;-)
  (The example assumes you correctly set you (man)paths.)

- Minimal environment variables setting to use the /r/share1 resources.
  Not much work on the installer side, but worth mentioned.

* Separation of foreign language software from "English" versions

 These software should not be mixed. The sub-hierachy of foreign/
 is built around the same concepts than the one of /r/share1.
 The additional separation of languages allows a better control and
 understanding of what is available for each language. 

EXAMPLE OF INSTALLATION

Assuming the shell is csh:

chiton% umask 022
chiton% cd /r/share1/bin
chiton% foreach a (`ls ../src/xv-3.10a/bin`)
? echo '#\!/usr/bin/csh' > $a
? echo 'switch (`/usr/bin/uname -r`)' >> $a
? echo 'case 5.*:' >>$a
? echo '        exec /r/share1/src/xv-3.10a/bin/'$a' $*' >>$a
? echo '        breaksw' >>$a
? echo '        ;;' >>$a
? echo 'default:' >>$a
? echo '        echo "Sorry: `basename $0` runs only on Solaris."' >>$a
? echo '        breaksw' >>$a
? echo '        ;;' >>$a
? echo 'endsw' >>$a
? chmod 755 $a
? end
chiton% cd ../man
chiton% ln -s /r/share1/src/xv-3.10a/man/man1/* man1
chiton% catman -M /r/share1/man
chiton% umask <what-you-like>

-The "share" people.