SYSDOC POPC                                       John Gibson June 1988
                                         extended by A.Sloman July 1988
                                                  Ian Rogers March 1990

This is a quick summary of the new compilation/linking setup, using
command files pgcomp, pglink, pglibr, and mksyscomp.

This extended description was produced by A.Sloman based on
~johng/newsys plus examination of the sh command scripts pgcomp, pglink
and pglibr I may have made errors. Proceed with caution, and examine the
scripts yourself if in doubt. I am least confident about the options for
pglibr.
    Aaron Fri Jul  8 17:27:28 BST 1988

A more up to date file can be found in REF POPC
    $usepop/pop/ref/popc
    http://www.cs.bham.ac.uk/research/projects/poplog/doc/popref/popc

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

 -- Terminology
 -- Three basic programs: popc, poplink, poplibr
 -- Rebuilding saved images: mksyscomp
 -- Other command files
 -- pgcomp: run popc on a .p or .s file
 -- Options for pgcomp: -imd <dir>, -pl, -ql
 -- pglink: run poplink to re-build newpop11
 -- Options for pglink: -imd <dir>, -srd <dir>, -q, etc..
 -- pglibr: run poplibr
 -- Possible arguments for pglibr
 -- mksyscomp: rebuild popc, poplink, or poplibr
 -- Options for the basic programs popc, poplink and poplibr

-- Terminology --------------------------------------------------------

Some of the flags to these programs, and scripts, indicate that there
will follow zero, one, or more pieces of data, eg -lf to poplink. These
data lists are represented below by <arg list>, and will take one of two
forms:

    1. If there is exactly one piece of data then it can simply follow
    the flag. eg.

        pglink -lo stuff.o

    2. If there is zero or more pieces of data then it is written, in
    sequence, between parentheses. eg.

        pglink -lf ( -Lmydir/lib -Lotherdir/lib )

    Note that this form can also be used for the case where there is
    exactly one piece of data.

-- Three basic programs: popc, poplink, poplibr -----------------------

popc:
    compiles .p and .s files, producing .w/.o files

poplink:
    links a POP-11 program from .w/.o files and libraries
    (Unless given the -q flag, it first creates poplink_?.o and
    poplink_cmnd files)

poplibr:
    maintains .w/.o libraries

NOTE:
The information below gives descriptions of the most commonly used
arguments and flags available for these commands. However, in some
cases additional flags are possible. For full details you will need
to look at the source files, e.g. syscomp/poplink_main.p for pglink.


-- Rebuilding saved images: mksyscomp ---------------------------------

For now, each of the programs has a saved image in the src directory,
based on safepop11.

The command file -mksyscomp- takes one or more of the arguments 'popc',
'poplink' and 'poplibr' and creates the corresponding saved images:

        popc.psv
        poplink.psv
        poplibr.psv


-- Other command files ------------------------------------------------

The above programs are general, and take a number of arguments
(documentation on that to follow). For the normal full POPLOG system,
there is a command file to run each program with appropriate arguments:


-- pgcomp: run popc on a .p or .s file --------------------------------

The most commonly used formats are

    pgcomp foo.p ...
    pgcomp foo.s ...

Other formats are explained below.

-pgcomp- is similar to the old -popas- command -- it runs -popc- on .p
and .s source files, and produces .o and .w files.

After using -pgcomp- successfully on a new file, you should edit the
file W_FILES to include the name of the .w file produced. This will be
used by the linker pglink and by pglibr as explained below. If there is
no corresponding entry in W_FILES, then the -pglink- command will use
the version of the program in the src.wlb and wrc.olb instead of the new
version.

[pgcomp should be changed to append to W_FILES if necessary - aaron]


-- Options for pgcomp: -imd <dir>, -pl, -ql ---------------------------

Full format:

    pgcomp [-imd <dir>] [-cs] [-pl | -ql] files ....

Options:

    -imd <dir>
        look in the named <dir> for the safepop11 and popc.psv
        files. Defaults to current directory.

    -cs
        Compile the result of `pglibr -lcs src.wlb`, i.e. any .s or .p
        source files that have changed since they were updated in
        src.wlb. Then does 'ls *.w > W_FILES' to create W_FILES.

    -pl
        Run pglink after compiling the files. This will do a full link.

    -ql
        Run pglink -q after compiling the files. This will do a quick
        link without re-building the poplink*.o files etc.


-- pglink: run poplink to re-build newpop11 ---------------------------

-pglink- replaces both the old -poplink- and -link- commands. It uses
the .w files listed in the file $popsrc/W_FILES together with the
remaining files in the $popsrc/src.wlb and $popsrc/../x/src/src.wlb
libraries to create files called poplink_?.o for building the dictionary
and other structures required at run time, and also creates the file
poplink_cmnd which is used to run the linker and build newpop11.

The most common forms of invocation of -pglink- are

    pglink
        produce poplink_?.o and poplink_cmnd, then link newpop11
    pglink -q
        use existing poplink_?.o and poplink_cmnd, link newpop11

Additional options are explained below.

-pglink- assumes that the files $popsrc/src.wlb and $popsrc/src.olb
represent the Poplog library (plus $popsrc/../x/src/src.[ow]lb) if
linking with X).

It also takes the file W_FILES, if it exists, to be a list of .w names
for modules that have been recompiled to .w/.o form since the library
was last updated (using -pglibr-). -pglink- therefore takes these as
separate, and excludes any modules in the src.olb/src.wlb library with
the same names. Using the list of .w files in W_FILES it lists the
corresponding .o files explicitly in poplink_cmnd.


-- Options for pglink: -imd <dir>, -srd <dir>, -q, etc.. --------------

Full format:

    pglink [-imd <dir>] [-srd <dir>] [-xsrd <dir>] [-q]
           [-nox] [-noved] [-noshare] [-safe] [-a]
           [-map] [-rsv] [-port] [-sunfp <option>]
           [-lf <arg list>] [-lo <arg list>] [-L<dir> | -L <dir>]
           [-x*] [*.wlb [-in | -ex ( <files> )]]

Options:

    -imd <dir>
        Use <dir> to look for safepop11 and poplink.psv. Defaults to
        current directory.

    -srd <dir>
        Use <dir> for the directory containing the file src.wlb.
        Defaults to current directory.

    -xsrd <dir>
        Use <dir> for the directory containing the file src.wlb for The
        Poplog X sources. Defaults to ../x/src (relative to the source
        directory).

    -q
        Simply run poplink to re-build newpop11. If -q is absent, pgcomp
        first uses src.wlb to (re-)create the files

            poplink_1.o
            poplink_2.o
            poplink_3.o
            poplink_cmnd

        which are used by pglink -q .

    -noved
        Tells pglink not to link in the Poplog VED sources.

    -nox
        Tells pglink not to link in the Poplog X sources or X libraries.

    -a
        Produce poplink_*.a and poplink_cmnd only.

    -map
        If present pglink runs

            nm -n newpop11 > newpop11.map

        The default is not to do this.

    -rsv
        If this is present pglink builds rsvpop11 at the same time.

    -port
        Produce poplink_?.a and poplink_cmnd for porting, using *.w and
        omitting $popexternlib/libpop.olb from the link command.

    -lf <arg list>
        O/S link command flags (added to the link command before
        any object file arguments)

    -lo <arg list>
        O/S link command object file args (added to the link command at
        the end of pop object file arguments)

    -L<dir> | -L <dir>
        Tells O/S link command to add <dir> to its list of directories
        in which to search for libraries. The optional space between the
        -L and the directory is significant: this option is passed on
        literally to the UNIX link editor ld(1), which generally does
        not allow a space, except on HP-UX, which requires one.

    -sunfp <option>
        (Sun-3 only) Where option is one of

                switch  68881  fpa  sky  soft

        links in the appropriate C library startup file /lib/Xcrt1.o
        and adds -L/lib/f<option> to UNIX ld(1) command.

    -noshare
        (Currently, ignored except in VMS) Link image without shareable
        libraries.

    -safe
        Equivalent to -noved -nox -noshare (i.e. link a safepop11).

    -x*
        Passed as the X link type to poplink.

    *.wlb
        Aribitrary "wlb" files can be added to the argument list of
        pglink. Each may be followed, optionally, by one of the flags
        -in or -ex, which have the same function as in poplink.

    -defc    <pathname=expr list>
    -defv    <pathname=expr list>
    -defcm   <pathname=expr list>
    -defvm   <pathname=expr list>
        Define (or declare) identifiers in the linked output.
            Constant/variable and identprops are specified by the
        option: `c` = constant, `v` = variable, and `m` = macro
        (identprops default to 0 without `m`). '=expr' may be omitted
        to just declare an identifier. The leading $- on a pathname may
        be omitted.
            <expr> may consist of any combination of integers, booleans,
        strings, words, lists and vectors. It should not reference any
        pop identifiers except -true-, -false- and -nil-. (In
        particular, note that these options DON'T declare identifiers
        in the pop namespace, and so cannot be referred to themselves.)

Environment Variables:

    PGLINK_OPTIONS
        List of default options prefixed to the command line arguments.


-- pglibr: run poplibr ------------------------------------------------

-poplink- (and so -pglink-) make use of two archive files, src.wlb
derived from .w files, and src.olb derived from .o files. These are
created by poplibr, using the -pglibr- command. It makes use of the file
W_FILES, to determine which .w and .o files should be archived.

In what follows <src file> is normally src.wlb and the <files> are .w
files. The appropriate action is then automatically taken for src.olb
and the corresponding .o files.

Format:
    pglibr [-imd <dir>] [-r|l|ld|x|c|d <src file> [<files>]]

Options:

    Without any arguments, -pglibr- updates src.wlb and src.olb
    from the modules specified by W_FILES, deletes the .w/.o files,
    and then deletes W_FILES itself.

    Thus the general idea is to add the .w names of recompiled
    files to W_FILES, and then occasionally update the library with
    -pglibr-.

After running -pglibr- the file

            poplink_cmnd

could be out of date, if it refers to .o files which have been removed
by -pglibr-. This would screw up any subsequent attempts to run
"pglink -q". So -pglibr- deletes poplink_cmnd.


-- Possible arguments for pglibr --------------------------------------

Note that in all the following <src file> is normally src.wlb or a
similar file.

    -imd <dir>

        Use <dir> to look for safepop11 and poplibr.psv. Defaults to
        current directory.

    -r <src file> file1.w file2.w ....

        Replace the files in the src.wlb and src.olb files. However, no
        files are automatically deleted, and the file W_FILES is
        ignored.

    -l <src file> file1.w file2.w ....

        Lists the whole contents of <src file> if no module names are
        given, or just the ones given.

    -lcs <src file> file1.w file2.w ....

        For each .w module specified in <src file> (or all if no names
        given), list the names of the corresponding .p or .s source
        files whose last changed date is later than the date of the w
        module.

    -ld <src file> file1.w file2.w ....

        Same as -l, but gives the date of each module listed (i.e. the
        creation date of the file the module was copied from when it was
        added to the library).

    -x src.wlib file1.w file2.w ...

        Extracts the named files from src.wlb and src.olb

    -c <src file> files

        Create the archive file

    -d <src file> files

        Delete the files from the archive

NOTE
No options of pglibr (or the other commands) allow for object-module
names to be specified; they all work via w-module names. So
'pglibr -l src.wlb' (= 'poplibr -l src.wlb') lists the contents of
src.wlb and assumes that src.olb is the same (if you wanted to look
directly at src.olb you'd have to use 'ar t src.olb').


-- mksyscomp: rebuild popc, poplink, or poplibr -----------------------

Usage is:

    mksyscomp [-d] [image ...]

where 'image' is one of 'popc', 'poplink' or 'poplibr'.

The '-d' option assigns <true> to -pop_debugging- while building the
image(s).


-- Options for the basic programs popc, poplink and poplibr ----------

In all cases, a <list> is either a single <arg> or 0 or more enclosed in
parentheses, i.e. ( <arg> ... <arg> )

With all three programs, a w-library can be given as a directory path <dir>
meaning 'src.wlb' in that directory. (Unix: the path must be recognisable as
a directory by ending with / .)

popc
----
    popc <options> <program/w-file/w-library filenames>

    -a
        produce .a/.w files only (for porting)

    -c
        compile files only, don't run poplink

    -createwlib <w-library>
        If <w-library> doesn't already exist, compile given source
        files and then run

            poplibr -c <w-library> <w-files>

        If <w-library> exists already, prints a warning message and
        exits.

    -g <name> <program file list>
        group of files to be compiled to a single w/object file called
        <name> (uses name of first program file if <name> not specified).

    -l
        list each filename compiled

    -m <name=expr list>
        define macro(s)

    -norec
        Don't recompile any source file for which .w/.o files exist
        already.

    -nosys
        Don't add system libraries $popsrc ^^popuseslist at end

    -od <dir>
        produce output files in <dir> (can occur anywhere, and affects
        all following files)

    -u <arg list>
        For each <arg> in <arg list>, compiles 'uses-now ' <> <arg>

    -wlb <w-library list>
        Group of libraries for recursive search extract. In this,
        ^^popuseslist means all the directories in popuseslist.

    -wlib <w-library list>
        Same as -wlb, except that the specified libraries are put at the
        end (ie after any other file arguments).


poplink
-------
    poplink <options> <w-file/w-library names>

    -a
        produce poplink_*.a and poplink_cmnd only

    -e <procedure name>
        name of entry procedure to be called on startup (for full
        Poplog this is $-Sys$-Poplog_Main). Defaults to $-Pop$-Main if
        not specified.

    -emb
        External Make Base -- make <image name>.stb

    -date <date>
        date to be given to image (i.e. date in -popversion-)

    -defc    <id_pathname=expr list>
    -defv    <id_pathname=expr list>
    -defcm   <id_pathname=expr list>
    -defvm   <id_pathname=expr list>
        Define (or declare) identifiers in the linked output.
            Constant/variable and identprops are specified by the
        option: `c` = constant, `v` = variable, and `m` = macro
        (identprops default to 0 without `m`). '=expr' may be omitted
        to just declare an identifier. The leading $- on a pathname may
        be omitted.
            <expr> may consist of any combination of integers, booleans,
        strings, words, lists and vectors. It should not reference any
        pop identifiers except -true-, -false- and -nil-. (In
        particular, note that these options DON'T declare identifiers
        in the pop namespace, and so cannot be referred to themselves.)

    -ident <integer>
        image identification value

    -idexp <letters>
        IDentifier EXPort: forces identifiers to appear in the
        dictionary/section tree. <letters> is a single arg consisting of
        any of the following letters:

            w   Export all top-level identifiers for which a quoted
                word has been used (default)

            s   Export all syntax words

            m   Export all macros

        <letters> may also be empty ("") to specify none.

    -lf <arg list>
        O/S link command flags (added to the link command before
        any object file arguments)

    -lo <arg list>
        O/S link command object file args (added to the link command at
        the end of pop object file arguments)

    -noshare
        Link image without shareable libraries.

    -o  <image name>
        name of image to link

    -port
        for porting: implies -a, and stops addition of
        $popexternlib/libpop.olb to link command.

    -p
        do complete link, but leave poplink_*.o and poplink_cmnd intact

    -q
        do object link only, using existing poplink_?.o and poplink_cmnd,
        but generating new poplink_dat.o

    -s <section list>
        Names of sections to be set up at run-time. All identifiers in
        each section are exported.

    -sunfp <option>
        (Sun-3 only) Where option is one of

                switch  68881  fpa  sky  soft

        links in the appropriate C library startup file /lib/Xcrt1.o
        and adds -L/lib/f<option> to "ld" command.

    -tr
        trace loading, i.e. list object files/library modules used

    -uses <id_pathname list>
        Mark the specified identifers strongly used (forcing their
        extraction from libraries, etc).

    -ubn <id_pathname list>
        'uses-by_name' -- as for 'uses', but also exports the
        identifiers.

    -unum <letters>
        Use NUMber keys: <letters> is a single arg consisting of
        any of the following letters:

            b   biginteger_key
            r   ratio_key
            f   (d)decimal_key
            c   complex_key

        Thus '-unum br' is the same as
        '-uses \( biginteger_key ratio_key \) etc. Default is
        'brf', i.e. you have to ask for complex_key explicitly.

    -wlb <w-library list>
        Group of libraries for recursive search extract.

    -x_complete
        Special used by pglink (only operative for MIPS)

    -x*
        Same as '-lo ==POP_X*_EXLIBS' (X* in uppercase).

    <library> -ex <module list>
    <library> -in <module list>
        Following a w-library name, exclude/include modules in <library>.
        (An empty list ( ) for -ex means include all modules)


poplibr
-------
    poplibr <option> <lib> <module names>

    -c
        Create <lib> from <modules> (mustn't exist already)

    -d
        Delete <modules> from <lib>

    -l
        List <modules> in <lib> (or all modules if none specified)

    -lcs
        For each <module> in <lib> (or all modules if none specified),
        list the names of the corresponding (.p or .s) source files
        whose last changed date is later than the date of the module.

    -ld
        As -l, but give module dates

    -r
        Replace <modules> in <lib>

    -x
        Extract <modules> from <lib> (or all modules if none specified)




--- sysdoc/popc
--- Copyright University of Sussex 1992. All rights reserved. ----------