SYSDOC HERE                                 R.Evans March 1989

'here' directories are working directories for Poplog system
development. This file describes the structure of here directories in
the master system.

         CONTENTS - (Use <ENTER> g to access required sections)

 -- Introduction
 -- Here directories' structure
 -- Sun3 here directory
 -- Sun4 here directory
 -- Hpbob here directory

-- Introduction -------------------------------------------------------

'here' directories are working directories for Poplog system
development. They typically contain a contain everything needed to build
and test a Poplog system. They are used (a) for testing actual changes
to the system masters and (b) as the PM_REMOTE directory for 'popmake'
systems (see SYSDOC *POPMAKE).

Because most development is carried out on a sun3 (and because the
masters are kept on a sun3), the primary here directory is for a sun3
system. This is generally kept fully up to date (ie consistent with the
masters) at all times. However for some purposes here directories for
other systems are also useful (eg bobcat systems), so that developments
can be tested on the current masters for these systems.

This file describes the organisation of here directories and recommended
methods of use. The current set-up includes here directories for sun3,
sun4 and hpbob systems, but because of various access limitations it is
not as elegant as we would like.


-- Here directories' structure ----------------------------------------

There are currently three 'master' here (mhere) directories, for sun3,
sun4 and hpbob systems. The directories are:

    /pop/csuna/mhere.sun3
    /pop/csuna/mhere.sun4
    /pop/csuna/mhere.hpbob

These directories contain hard links to the source files the master
tree, so changes to the masters are reflected instantly.

The following symbolic links provide an alternative form of access:

    /pop/csuna/here -> /pop/csuna/mhere.sun3
    /pop/csunb/here -> /pop/csuna/mhere.sun4
    /pop/tbobf/here -> /pop/csuna/mhere.hpbob

Thus on each fileserver machine you can find its particular here
directory by looking in /pop/`hostname`/here.

In an ideal world, we could use all the mhere directories for
development and testing. However this is not possible for two reasons:
a) there's not enough space in /pop/csuna and b) /pop/csuna isn't
accessible from everywhere, in particular, from tbobf.

To overcome these problems a third set of directories exist:

    /pop/csunb/here.sun4
    /pop/tbobf/here.hpbob

These provide space for non-master bits of the mhere directories (ie
stuff which doesn't have to be hard linked to the masters) in a
different file system accessible from the machine on which the system
will run. Symbolic links are used for individual files from
the appropiate mhere directory into these directories (eg safepop11,
newpop11, *.psv *.?lb etc.).

NB: here.sun3 doesn't exist simply because it would add complication
    without benefit, since mhere.sun3 is in the same filesystem anyway.

NB2:/pop/tbobf has very little space in it, so in fact
    /pop/tbobf/here.hpbob is a symbolic link onto tsuna!:

    /pop/tbobf/here.hpbob -> /pop/tsuna/here/hpbob


-- Sun3 here directory ------------------------------------------------

We treat this just as before - compiling, linking etc. in
/pop/csuna/here (or mhere.sun3). And as now, if you update the masters,
remember to test and rebuild the archive.


-- Sun4 here directory ------------------------------------------------

Most of the non-master files in mhere.sun4 are symbolic links into
here.sun4 (on csunb). These include safepop11, newpop11, saved images
and the .olb and .wlb files. Generally however, you can ignore this
fact, and build everything (on csunb) in the mhere directory, since
Poplog copes correctly with the symbolic links. The only thing to watch
is doing things like 'mv newpop11 safepop11', which clobbers the link
and creates safepop11 under /pop/csuna. To achieve the right effect,
do such a mv in /pop/csunb/here.sun4.

Regarding maintenance, it is not expected that non-sun3 systems be kept
up to date during normal system development. So if you use the sun4
system, check first that it is up to date (do ls -lrt and look for files
listed after newpop11 to see what needs rebuilding). Slightly harder to
check is for brand new files in the masters which have not been linked
into the mhere.sun4 directory. Because of this, it would be nice if
people clould take the trouble to link new files into ALL the MHERE
directories, not just the sun3 on as they do now.


-- Hpbob here directory -----------------------------------------------

This is slightly messy. mhere.hpbob contains the master sources and the
other nonmaster files are linked to /pop/tbobf/here.hpbob (this
directory is actually a link to /pop/tsuna/here.hpbob, because tbobf
hasn't enough space!). So mhere.hpbob looks like a here directory from
CRN machines. The catch is that you cannot access it from Bobcats - you
can only get at the here.hpbob directory. Since this contains safepop11,
newpop11, the .psv, .olb and .wlb files it is fine for some purposes (eg
as a remote directory for POPMAKE). But it does not contain the system
source files and so changes cannot be incorporated into newpop11
directly. Two solutions:

    1)  temporarily mount /pop/csuna on tbobf to do updates
    2)  copy the source files (and relevant .ph files) into
        /pop/tbobf/here.hpbob and build them there, then delete them.

(1) is clearly best - once mounted, you can treat /pop/tbobf/here as a
here directory just like any other. But you should check with systems
staff before mounting (and remember to unmount afterwards).

For maintenance, the same comments as for the sun4 system apply.
