http://www.cs.bham.ac.uk/research/poplog/sysdoc/rebuilding

REBUILDING A POPLOG SYSTEM

Some notes compiled by Aaron Sloman on the basis
of help and tips from Robert Duncan at Sussex University
and a bit of trial and error while trying to rebuild Poplog
V15.53 for the DEC Alpha with Digital unix and later Linux poplog
running on RedHat 6.1

None of this will work unless you have a Poplog system for the target
platform.

For some purposes you will need the system sources, i.e. the *.s. *.p
and *.ph files in these directories:

    $usepop/pop/src/
    $usepop/pop/ved/src/

The sources for linux poplog are included in the tar file used to
install poplog.

Additional sources (in gzipped tar files) are here, possibly out of date
in some respects, relative to the current linux sources.:

    http://www.cs.bham.ac.uk/research/poplog/new/

This is the master directory originally produced at Sussex university,
using *hard* links for files shared across systems:

    http://www.cs.bham.ac.uk/research/poplog/src/master

You must have at least one executable pop11 file that runs on the system
on which you are doing the work. If you have a fully functioning Poplog
system there should be no problem, though you may have to do some
relinking before you can use the system building facilities.

Instructions on relinking if the pglink or newpop commands do not work
are given below.

Cross-compiling from a working poplog system to another platform is a
(partly) different process.

CONTENTS

 -- Introduction
 -- Re-linking and re-configuring with newpop
 -- Warning: if you have local saved images in $poplocalbin
 -- Relinking if you have problems
 -- -- Relinking poplog using newpop (with or without motif)
 -- -- Creating "user" saved images, if needed
 -- -- Remember to rebuild local saved images also
 -- Rebuilding from sources
 -- -- The Pop-11 system dialect
 -- -- Stages in rebuilding Poplog
 -- -- More detailed documentation
 -- Where are the sources?
 -- -- $popsrc
 -- -- C files in $popexternlib
 -- -- The core VED source files in $usepop/pop/ved/src
 -- -- The core Pop-11 files invoking X window facilities
 -- -- The C files defining the Poplog Widget set
 -- Re-compiling and relinking poplog
 -- -- Prerequisites:
 -- -- How to recompile and relink from sources
 -- -- Building a reduced pop-11
 -- Porting Poplog to a new system

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

Please send me email if you find any mistakes. Address at end.

Please do not send me questions about this: I am less likely to be able
to answer than other experienced poplog builders. So please post your
questions to this newsgroup

    comp.lang.pop [DEFUNCT]

or to the email list pop-forum AT cs.bham.ac.uk

In that case you are likely to get help from some knowledgeable person.
Messages posted to me are likely to languish unanswered because I am too
busy and do not know the answer.

Thanks.


-- Re-linking and re-configuring with newpop --------------------------

If all you need to do is relink an existing poplog system, e.g. because
of a minor change in the operating system, the newpop command is well
described in HELP NEWPOP

The shell script which runs the command is
    $popsrc/newpop

It uses the saved image $popsys/newpop.psv, which is run on top of
the (usually old) $popsys/corepop

The pop-11 source code is in $usepop/pop/lib/lib/newpop.p

The saved image is rebuilt using
    $popsrc/mknewpop

    which uses $popsys/corepop11

Using two different files corepop and corepop11 is a relic of previous
times when Poplog was sold for money and the corepop file was of type
rsvpop11, for use only in running saved images. The file corepop11 is
now a symbolic link to corepop, kept in case needed.

Some of the options provided by newpop can be obtained directly without
re-linking, by running scripts in $popcom (= $usepop/pop/com/).

e.g.
    mkstartup
    mkclisp
    mkplog
    mkpml
    mkxved
    makeimages
    makeindexes

-- Warning: if you have local saved images in $poplocalbin

After re-linking poplog you will need to re-create any saved
images that you have in $poplocalbin.


-- Relinking if you have problems -------------------------------------

The contents of this section are relevant if you have Poplog V15.53
running on RedHat 6.1. It runs fine normally , but the attempt to relink
fails, as does attempting to use pgcomp, pglibr, pglink, described
below.

The following was posted to comp.lang.pop in response to a request for
help from Rod Chapman, who found that pglink would not work.

After some experimentation I found a way to relink poplog on Redhat 6.1
which should presumably work on other Unix systems. Relinking for VMS
will be slightly different and I don't know anything at all about
Windows or NT.

The main steps are described in the file

    http://www.cs.bham.ac.uk/research/poplog/sysdoc/rebuilding-corepop.txt

There is also a shell script which does what that file recommends. It is
accessible here:
    http://www.cs.bham.ac.uk/research/poplog/tools/relinking.linux.poplog

-- -- Relinking poplog using newpop (with or without motif)

After running the script mentioned in the previous paragraph,
you should now be able to run pgcomp, pglibr, popc and newpop,
if needed.

E.g. to relink an entirely new poplog including motif (if you have motif
or lesstif libraries installed in the usual motif location) do the
following, as described in HELP NEWPOP

    $popsrc/newpop -link -x=-xm -norsv

(The rsvpop11 file is no longer needed for "delivering" applications.)

You can see all the actions newpop will take by default by looking in
the file    $popsrc/newpop_options

You may wish to remove or modify some of them.

It may or may not be necessary to run $popcom/mkXpw to rebuild the
poplog widget set libraries. If you have problems running X facilities
in poplog try that command.

If you wish simply to create an executable and test it out do this:

    $popsrc/newpop -link -x=-xm -norsv -noinstall

That will create the files newpop11 newpop11.stb newpop11.map

Later you can copy them (using "cp" not "mv" to preserve links) to the
basepop11 versions and then delete the newpop11*

If you don't have motif or lesstif, and want the basic X facilities
replace "-xm" with "-xt".


-- -- Creating "user" saved images, if needed

Having got a basepop11 that you are sure works as required, you can
either start again and let newpop do everything, or run various
command files separately, e.g.

    $popcom/mkstartup
        creates the file startup.psv run by the pop11 command

    $popcom/mkxved
        allows you to go directly into xved

    $popcom/makeimages
        creates additional language images: prolog, lisp, ML

    $popcom/mkind
        To create indexes for "ENTER sourcefile"

    $popcom/makeindexes
        To create an index in each help, doc, ref, teach. lib directory,
        etc. WARNING if you have symbolic links that are circular this
        script will follow them all.

It is also desirable to change the scripts in
    $popsrc/mksyscomp
    $popsrc/mknewpop

so that they use corepop instead of corepop11. That will remove some of
the steps in the process described above.


-- -- Remember to rebuild local saved images also

The system saved images are in
    $usepop/pop/pop/*.psv
        These are used for system developers
        popc.psv poplink.psv poplibr.psv newpop.psv

    $usepop/pop/lib/psv/*.psv
        These are needed for pop11, prolog, lisp, pml, xved, etc.

It is possible that you have created some saved images in the
$poplocalbin library. In that case you will need to re-run whatever
scripts were used to create those images.

You may have acquired such scripts separately from the main poplog
system, in which case you will probably have them in
    $poplocal/local/com

For more information see the file
    http://www.cs.bham.ac.uk/research/poplog/sysdoc/rebuilding-corepop


-- Rebuilding from sources --------------------------------------------

There are several different kinds of sources in Poplog, and they do not
all have to be built into the system. E.g. you can build a poplog system
without Ved, without the X window system, and possibly without other
facilities.

The sources are of three main kinds: a small number of assembler files,
a small number of C files, and a very large number of Pop-11 files.

-- -- The Pop-11 system dialect

The Pop-11 files are in an extended dialect of Pop-11 sometimes referred
to as Syspop, or Syspop11, and partly described in in the probably
partly out of date file

    http://www.cs.bham.ac.uk/research/poplog/sysdoc/syspop11
or
    ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/sysdoc/syspop11


-- -- Stages in rebuilding Poplog

Re-building a poplog system requires
    1.  Recompiling the assembler files, using a poplog tool, pgcomp,
        which invokes the relevant assembler to do part of the task.
        pgcomp produces a collection of .o and .w files. The latter
        are used to build the poplog run-time dictionary, when poplog
        is linked.

    2.  Recompiling the syspop11 files using the same tool pgcomp.
        Again it produces .o and .w files.

    3.  Use a tool called pglibr to store the .o and .w files in
        libraries in the directory $usepop/pop/obj, also known as
        $popobjlib
            $usepop/pop/obj/src.olb
            $usepop/pop/obj/src.wlb
            $usepop/pop/obj/vedsrc.olb
            $usepop/pop/obj/vedsrc.wlb
            $usepop/pop/obj/xsrc.olb
            $usepop/pop/obj/xsrc.wlb

        where the. olb files contain object file libraries and the wlb
        files contain the word information used to create the dictionary.

    4.  Recompiling the C files using shell scripts which invoke a
        C compiler, either a default one for the system or the one
        held in the variable $POP__cc which you may have to set.
        This produces .o files which are stored in C libraries, e.g.
            $usepop/pop/extern/lib/libpop.a
            $usepop/pop/extern/lib/libXpw.so
            $usepop/pop/extern/lib/libXpm.so

    5.  Using the tool pglink to link an executable system, usually
        named newpop11 at first, and then copied (not renamed) to
        basepop11 as part of the installation procedure.

        Depending on the arguments with which it is run (e.g.
        -nox to exclude the X facilities, -noved to exclude VED, etc)
        the pglink command produces various files in the directory in
        which it is invoked, starting with 'poplink_' e.g.
            $popsys/poplink_*

        One of these is an executable shell script, poplink_cmnd, which
        when run invokes the system linker to create an executable which
        by default is called newpop11.

        When poplog is supplied it contains the poplink_cmnd last used
        to relink the system. In some cases if the corepop command does
        not work, the poplink_cmnd script can be run to relink the
        system. However, you may have to edit it to ensure paths are
        correct on your system.

The remainder of this file explains where the different kinds of
source files are and ends with a set of commands for recompiling and
relinking, e.g. after some or all of the system sources have changed.

-- -- More detailed documentation

More information about the poplog compilation tools and how to
use them can be found in

    http://www.cs.bham.ac.uk/research/poplog/sysdoc/popc.txt
        (A more detailed guide to compiling and linking)

Also see these files in the standard Poplog distribution
    HELP POPC and REF POPC

and other files in the directory

    http://www.cs.bham.ac.uk/research/poplog/sysdoc/

(We should add SYSDOC to the standard distribution, along with
VED tools for accessing the files.)

-- Where are the sources? ---------------------------------------------

-- -- $popsrc

The main source directory for Poplog is $popsrc. This contains

1. A subdirectory syscomp/ which has tools for compiling and rebuilding
   poplog. It is important that the sysdefs.p file is linked to the
   appropriate file among these
        $popsrc/syscomp/sysdefs*.p
   if there is more than one, e.g. in the alpha unix (osf/linux) source
   directory.

    (I presume the appropriate sysdefs.p file must be available if you
    are cross-compiling poplog.)

2. Various header files used when poplog is rebuilt
        $popsrc/*.ph

3. A small collection of assembler files for core operations in the run
   time system,
        $popsrc/*.s

4. A large collection of source files in the Syspop dialect of Pop-11,
        $popsrc/*.p

-- -- C files in $popexternlib

5. A small collection of C files and C header files in
        $usepop/pop/extern/lib/*.h
        $usepop/pop/extern/lib/*.c

    This directory is also known as $popexternlib. It contains a file
    for recompiling the C files
        $popexternlib/mklibpop

-- -- The core VED source files in $usepop/pop/ved/src

6. A lot of Pop-11 and Pop-11 header files can be found defining
    the core functionality of the editor Ved, in
        $usepop/pop/ved/src/*.ph
        $usepop/pop/ved/src/*.p

These include some files concerned with windows, but they are not X
specific. There are many more files for Ved and XVed in various
libraries, but they do not need to be compiled into the system. Instead
they are either built into the startup.psv saved image, or compiled as
needed. Some are available only if motif libraries are available.

-- -- The core Pop-11 files invoking X window facilities

7. A collection of pop-11 header and source files used when Poplog is
linked with the X window system. These are in

        $usepop/pop/x/src/*.ph
        $usepop/pop/x/src/*.p

-- -- The C files defining the Poplog Widget set

8. The C and C header files defining the X Poplog Widget set (Xpw) and
the Xpm (X pixmap?) libraries in

        $usepop/pop/x/Xpw/*.h
        $usepop/pop/x/Xpw/*.c

and
        $usepop/pop/x/Xpm/*.h
        $usepop/pop/x/Xpm/*.c

    The Xpw files are recompiled by the shell script
        $usepop/pop/com/mkXpw

    The Xpm files are recompiled by
        $usepop/pop/com/mkXpm

    The Poplog widget set is accessed via a large collection of Pop-11
    facilities which use those C mechanisms to invoke the X window
    system libraries. Xpw is described in a collection of files in:

        $usepop/pop/x/pop/teach
        $usepop/pop/x/pop/help
        $usepop/pop/x/pop/ref

    especially TEACH Xpw, HELP Xpw, REF Xpw and files referenced
    therein, e.g.
        REF *XpwCore
        REF *XpwPixmap
        REF *XpwGraphic
        REF *XpwScrollText
        REF *XpwComposite
        REF *XpwTransparent

        REF *XpwMethods
        REF *XpwResources
        REF *XpwCallMethod

    NOTE:
    Most of the Pop-11 X procedures are in defined in subdirectories of
    these files:
        $usepop/pop/x/pop/
        $usepop/pop/x/ved/
        $usepop/pop/x/ui/

    However these are not linked into the core executable images.

    Instead they are typically compiled into saved images, e.g. in the
    startup.psv file created by

        $usepop/pop/com/mkstartup

    which looks in here:

        $usepop/pop/lib/lib/startup.p

-- Re-compiling and relinking poplog ----------------------------------

-- -- Prerequisites:

It is possible to rebuild a poplog system completely from all the
above sources, assuming that these work:

    $popsys/corepop

and the saved images which use it:
    $popsys/popc.psv
        invoked by pgcomp
    $popsys/poplibr.psv
        invoked by pglibr
    $popsys/poplink.psv
        invoked by pglink

If those three saved images do not exist, but the corepop file exists
then the saved images can be rebuilt using this script
    $popsrc/mksyscomp
with appropriate arguments, e.g. one or more of
        popc poplibr poplink
for which it compiles sources in
    $popsrc/syscomp/make_*.p

If those saved images exist, then the following commands should work,
possibly after setting the environment variable $POP__cc to name the
available C compiler, e.g. gcc.

-- -- How to recompile and relink from sources

If the prerequisites are satisfied, Robert Duncan provided me with the
following set of commands for rebuilding poplog:

    # Compile the main Poplog C files
    cd $popexternlib
    ./mklibpop

    # Delete old poplog libraries in $usepop/pop/obj
    rm $popobjlib/*.[ow]lb

    # Compile the assembler and Pop-11 sources using pgcomp and
    # archive them using pglibr

    cd $usepop/pop
    for dir in src, ved/src and x/src:
        cd $dir
        pgcomp *.[ps]
        pglibr -c ./ *.w
        rm *.[ow]

    # link a complete system into a newpop11 image, using pglink
    cd $popsys
    pglink

To link a reduced version of pop11 you can give pglink some arguments,
e.g. either or both of "-nox" and "-noved".

If all that works, you can copy newpop11 by hand to basepop11 after
saving basepop11 in basepop11.old perhaps. (don't use "mv" or you will
destroy links). It is then possible to go through various steps
reconfiguring the system. However it may be simpler to do

    $popsrc/newpop

and wait a minute or two, while it links again, and then does everything
else including rebuilding saved images for pop-11, common lisp, prolog,
and standard ML, as described in HELP NEWPOP. Sometimes that won't work
because it uses a saved image $popsys/newpop.psv If that will not run,
rebuild it on top of corepop11 with the command
    $popsrc/mknewpop

If corepop11 does not run and you have just created an executable
newpop11 you can do

    cd $popsys
    cp newpop11 corepop11
    $popsrc/mknewpop

After which
    $popsrc/newpop

should work. If not, post a description of the problems to
    pop-forum@cs.bham.ac.uk

-- -- Building a reduced pop-11

The above steps can also be used to produce a reduced version of pop11.
Simply run pgcomp on a subset of the system source files, to include
just what you need and no more. E.g. for some applications you may not
need the garbage collector, or the bigintegers, or complex arithmetic,
or access to external procedures.

In that case you can replace this part

    cd $usepop/pop
    for dir in src, ved/src and x/src:
        cd $dir
        pgcomp *.[ps]
        pglibr -c ./ *.w
        rm *.[ow]

with the following:

Select the files in $popsrc which you wish to include in your reduced
Pop-11 system, which I expect will have to include all the assembler
files.

Then

    # Delete the core object libraries (or move them somewhere)
    rm $popobjlib/src.[ow]lb

    cd $popsrc
    # compile the assembler files
    pgcomp *.s

    # compile the desired syspop files
    pgcomp file1.p file2.p file3.p ..... filen.p

    # create new libraries with the compiled files
    # this uses the .w and .o files
    pglibr -c ./ *.w

    # delete the newly created .o and .w files
    rm *.[ow]

    # link a complete system into a newpop11 image, using pglink
    cd $popsys
    pglink -nox -noved

A better alternative would be to create a copy of the $popsrc directory
e.g. $usepop/mini/src in the poplog tree, containing only the source
files you need (which might be linked to those in $popsrc). Then the
above pglibr command would create libraries called
    $usepop/pop/obj/minisrc.olb
    $usepop/pop/obj/minisrc.wlb

You can then link from those libraries using pglink, e.g. if you
temporarily name them as src.olb and src.wlb (having saved the
originals). Alternatively, build your own $usepop tree with
    $usepop/pop/pop
    $usepop/pop/obj
    $usepop/pop/extern
    $usepop/pop/pop
    $usepop/pop/src

containing files linked to the original usepop, then simply delete from
your src directory the files you don't want. In that case you can use
the standard method to compile and link.

If you have tried to exclude too much you'll discover when you try to
link and find something undefined. Using grep on the sources you can
then work out what you need.

-- Porting Poplog to a new system -------------------------------------

The process of porting poplog is somewhat different. Lots of assembler
files have to be created and compiled and linked on the new system.
For details see the (partly out of date) porting guide:

    http://www.cs.bham.ac.uk/research/poplog/sysdoc/ppg.txt

Other files in the same directory are probably essential reading, and
also HELP POPC, REF POPC.


Good luck to all system builders.

Aaron Sloman
Last modified 20 Aug 2002; 8 Jun 2012
Email: A.Sloman AT cs.bham.ac.uk