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
Select headings to return to index
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.
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.
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
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:
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]
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- 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.
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.
-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.
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').
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).
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 <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 <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 <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. ----------