HELP POPC John Gibson Nov 1993
This file is a user-guide for the Pop-11 object-module compilation and
linking system. It describes how to run Popc, the object-module compiler
for Pop-11 programs, and the associated utilities Poplink and Poplibr.
See REF * POPC for a description of the concepts involved, and how to
make Pop-11 programs compile under Popc.
CONTENTS - (Use <ENTER> g to access required sections)
1 Overview
1.1 Program Options in General
1.2 Object & Library File Arguments
1.3 Standard Libraries in $popobjlib
2 Popc
2.1 popc.args
2.2 W-Libraries for Extracting Declarations
2.2 Options
3 Poplink
3.1 Use of W-Libraries
3.2 Additional Files Produced by Poplink
3.3 External Startup & Linking
3.4 Options
4 Poplibr
4.1 Options
-----------------------------------------------------------------------
1 Overview
-----------------------------------------------------------------------
The Pop-11 object-module compilation and linking system consists of
three programs: Popc, Poplink, and Poplibr.
Popc compiles Pop-11 program files to object modules. Each source file
name.p is compiled to an ordinary O/S object file name.o, plus an
associated file name.w (called a w-file). Together, these two files
comprise a composite 'Pop object file'.
Poplink links an executable image from Pop object files and library
modules. It may be run as a separate program, but (like cc running ld in
Unix), is normally run automatically by Popc.
Poplibr creates and maintains object libraries. A set of Pop object
files is combined into an ordinary O/S object library libname.olb, plus
an associated file libname.wlb (called a w-library). Together, these two
files comprise a composite 'Pop object library'.
1.1 Program Options in General
-------------------------------
Program options whose names end with the suffix -list may be either a
single argument, or a sequence of zero or more arguments enclosed in
parentheses (parentheses must be escaped with \ in Unix). For example,
the Popc option
-include file-list
will allow any of the following:
-include foo.ph
-include ( )
-include ( foo.ph )
-include ( foo.ph baz.ph )
Individual options may restrict this where necessary (e.g. insist that a
list be non-empty).
1.2 Object & Library File Arguments
------------------------------------
With all three programs, a Pop object file is always specified by its
w-file name, i.e. as name.w. Similarily, a Pop object library is always
specified by its w-library name, i.e. as libname.wlb. (The O/S object
and library files name.o and libname.olb are never referred to
explicitly.)
A w-library may also be given as a directory pathname dirpath, which is
interpreted as follows: if dirpath specifies a directory anywhere in the
tree
$usepop/pop/...
then the remainder of the path from $usepop/pop/ downwards is
automatically mapped to a filename in $popobjlib, e.g.
$usepop/pop/x/ved/src/ --> $popobjlib/xvedsrc.wlb
Otherwise, if dirpath is not a sub-directory of $usepop/pop/, it is
interpreted as the file
dirpath/src.wlb
Note that in either case, dirpath must be syntactically recognisable as
a directory pathname, that is end with `/` in Unix, or `:` or `]` in
VMS.
1.3 Standard Libraries in $popobjlib
-------------------------------------
In the normal Poplog distribution, $popobjlib contains only those
w-libraries needed to link $popsys/basepop11, i.e. corresponding to the
core source directories
src
ved/src
x/ved/src
Thus to use Popc, you may first need to run the command file
$popcom/buildobjlib (Unix)
popcom:buildobjlib.com (VMS)
This creates w-libraries in $popobjlib for other library directories:
currently, these are
lib/auto
lib/lib
lib/ved
lib/sun
lib/ved/term
x/pop/auto
x/pop/lib
x/pop/lib/Xpw
x/pop/lib/Xm
x/pop/lib/Xol
x/pop/lib/Xaw
x/ved/src
x/ved/lib
x/ved/auto
x/ui/lib
-----------------------------------------------------------------------
2 Popc
-----------------------------------------------------------------------
Popc compiles Pop-11 source files to object-module form, and then
(unless the -c option is present, or compilation errors have occurred)
runs Poplink to link the resulting files into an executable image.
The general format of a Popc command is
popc options files
where files may be any sequence of Pop-11 program files (extension .p),
or files to be input to Poplink (w-files and w-libraries). These may
occur in any order; each .p file is compiled to its corresponding .w/.o
pair, and then replaced by its w-file name in the list passed to
Poplink.
Note that if Poplink is to be run (i.e. -c absent), and only a single
source file is supplied, then the .w/.o files are created as temporaries
and deleted afterwards.
The allowable options are described below. options may also include any
valid options to Poplink, which are passed to that program along with
the file arguments.
2.1 popc.args
--------------
To enable a set of options to be specified automatically for all files
in a given directory, on startup Popc looks for a file called
popc.args
in the current directory. If this exists, arguments are read from it and
prepended to the normal argument list. Arguments in popc.args should be
whitespace-separated; end-of-line comments flagged by ;;; are
recognised.
2.2 W-Libraries for Extracting Declarations
--------------------------------------------
By default, Popc uses the w-libraries specified by the directories in
popsyslist for extracting permanent identifier declarations
(interpreting the directory names as described by Object & Library File
Arguments above). Changes to popsyslist caused by compiling libraries
which extend it (such as LIB * POPXLIB) are taken into account.
You can also specify other w-libraries for declaration-extraction with
the -wlb and -wlib options (which are searched before any popsyslist
ones). The -nosys option causes only -wlb and -wlib libraries to be
searched, i.e. disables the use of popsyslist.
2.2 Options
------------
-include file-list
Causes each file from file-list to be #_INCLUDEed at the
beginning of every source file compiled. (This option is
normally used to supply a .ph file containing permanent
identifier declarations which are required for Popc, but not
for ordinary interactive compilation.)
-a Produce assembler output (.a files) and w-files only. (If
Poplink is to be run, it is passed the -a option also.)
-c Compile source files only, don't run Poplink.
-createwlib w-library
If w-library does not already exist, compiles the given
source files and then runs
poplibr -c w-library w-files
to create it from the set of w-files produced by the
compilation and/or supplied explicitly, all of which are
deleted afterwards. (Poplink is not run.)
If w-library exists already, a warning message is printed
and Popc exits.
-g [ name ] source-file-list
This option enables the group of source files given by
source-file-list to be compiled to a single w/object file
called name.w/.o.
The name argument is optional, and because of this,
source-file-list MUST be a list (i.e. enclosed in
parentheses), since this is used to detect whether name is
present or not. If name is absent, the name of the first
source file is used instead.
-l Causes each filename to be listed as it is compiled. (This
happens anyway, except when compiling a single source file.)
-m idname=expr-list
Define Pop-11 macro(s). Each argument of the form
idname=expr is used to define a macro
constant macro idname = expr;
in the top-level section. (The definition is compiled in
non-Popc mode, see REF * POPC.)
-norec
Don't recompile any source file for which the corresponding
.w/.o files exist already.
-nosys
Stops popsyslist being included in the list of libraries to
be used for extracting permanent identifier declarations
(see W-Libraries for Extracting Declarations above).
-od directory
Produce output files in directory (can occur anywhere, and
affects all following source files).
-u arg-list
Use Pop-11 source libraries: for each arg in arg-list,
compiles
uses-now arg;
-wlb w-library-list
List of libraries to be used for extracting permanent
identifier declarations (see W-Libraries for Extracting
Declarations above). These will be used only for source
files preceding the option (i.e. not for any following it).
-wlib w-library-list
Same as -wlb, except that the specified libraries are put at
the end, i.e. after any other file arguments (and are
therefore used for all source files).
-----------------------------------------------------------------------
3 Poplink
-----------------------------------------------------------------------
Poplink links an executable image from a set of Pop object files and
libraries (i.e. w-files and w-libraries). It performs the global
structure linking necessary in a Pop program, and outputs the results as
additional object files. Poplink then passes these, together with all
O/S object files/libraries corresponding to the w-files/libraries used,
as input to the O/S linker. Poplink may also be supplied with other
object file or library arguments to be passed directly to the O/S
linker.
The format of a Poplink command is
poplink options-and-files
where the options (described below) generally appear before any files
arguments, although some (such as -in, -ex, -wlb, -wlbused, etc)
actually specify input files and should therefore occur at the
appropriate place within the file arguments.
Any argument not beginning with `-` is an input file, and must be either
a w-file or a w-library; these are processed and incorporated into the
link in the order given.
3.1 Use of W-Libraries
-----------------------
While an input w-file is included unconditionally in the linked program,
a w-library is used for conditional 'search extraction' of modules, that
is, only those library modules which provide initialisations for
uninitialised identifiers are extracted. The library is searched
repeatedly until no further identifiers can be extracted, after which
that library is skipped (i.e. Poplink does not go back to it at a later
point).
The -wlb option enables a group of libraries to be searched recursively
(effectively treating them as a single library). The files in the group
are cycled through, each being searched as above, until a complete pass
through all of them fails to extract any further identifiers.
If you wish to force library modules to be included in the link
unconditionally, use the -in or -ex option (see below).
HOWEVER, aside from special uses of -in or -ex, it should normally never
be necessary to specify any w-libraries, except via the -wlbused option.
The reason for this is that (as described in REF * POPC), every w-module
keeps a record of which w-libraries were used for extracting identifier
declarations when it was compiled. Thus each w-module knows which
w-libraries it needs.
As Poplink incorporates w-modules during linking, it accumulates a
running list of the w-libraries they referenced. The -wlbused option
then represents this list as a group for recursive search extract (i.e.
as if specified with -wlb). Moreover, as further modules are extracted
from libraries in the list, any new libraries that those modules in turn
reference are added to the end of the list, causing it to expand
dynamically.
In other words, linking a program should normally require no more than
specifying a set of w-files followed by -wlbused, i.e.
poplink foo.w baz.w ... -wlbused
which will cause all necessary libraries to be supplied automatically.
When Poplink is run from Popc, the -wlbused option is added by the
latter; thus the above is equivalent to
popc foo.w baz.w ...
or
popc foo.p baz.p ...
after source file compilation.
3.2 Additional Files Produced by Poplink
-----------------------------------------
The linked global data structures generated by Poplink are output as
additional object files. By default, these are created as temporaries
and deleted afterwards. However, specifying the -p option causes them to
be created as permanent files in the same directory as the image being
linked, where they can be used to perform a 'quick' relink with the -q
option. These files are
poplink_1.o
poplink_2.o
poplink_3.o
poplink_4.o
poplink_dat.o
poplink_cmnd
The file poplink_cmnd is a CShell/DCL command file containing the O/S
link command that was obeyed to link the executable image.
3.3 External Startup & Linking
-------------------------------
As described in REF * POPC, Embedding Pop in C, Popc-compiled code may
be linked into and called from a C program. There are two Poplink
options to enable this: -exmain and -exlink.
On the one hand, -exmain simply tells Poplink that the program will
start up in an external main function. Poplink does not then incorporate
Pop's own main in the linked code, and one of your C modules from a -lo
option must define it instead. Aside from this, Poplink behaves as
normal.
-exlink, on the other hand, tells Poplink that it is not responsible for
linking the final executable image at all. In this case, not only is
Pop's main function omitted, but poplink_cmnd will simply contain a list
of the object files and libraries needed by the Pop part of the program;
this can then be supplied to any required linking command.
For example, in Unix it could be incorporated into a cc command, as
follows:
% cc foo.o baz.o ... `cat poplink_cmnd`
In VMS, poplink_cmnd will be linker options file, which can be given
directly to the linker with a /options qualifier:
$ link foo.obj baz.obj ... poplink_cmnd./options
3.4 Options
------------
-a Produce the files poplink_*.a and poplink_cmnd only (implies
-p).
-e procedure-name
Name of the entry procedure to be called on startup --
defaults to $-Pop$-Main if not specified. The entry
procedure must be declared as 'constant procedure'. (Note
that this option is not valid in combination with -exmain or
-exlink.)
-emb External make base -- causes image-name.stb to be made. (For
system use.)
-exmain
-exlink
These options specify external startup, with -exlink also
specifying external linking. See External Startup & Linking
above; of necessity, the -exlink option also implies -ponly.
(Note that these options are not valid in combination with
-e.)
-date date
Date string to be given to image, and which will form the
last part of popversion in the linked image. Defaults to
sysdaytime().
-defc idname=expr-list
-defv idname=expr-list
-defcm idname=expr-list
-defvm idname=expr-list
Define (or declare) identifiers in the linked output (where
each idname may begin with a section pathname, with or
without the leading $-).
Constant/variable and identprops are specified by the
option: c = constant, v = variable, and m = macro
(identprops default to 0 without m).
=expr can be omitted to merely declare an identifier.
Otherwise, expr may be a Pop-11 expression consisting of any
combination of integers, booleans, strings, words, lists and
vectors. It should not reference any Pop identifiers except
true, false and []. (In particular, note that these options
do not declare identifiers in the Pop namespace, and so
cannot be referred to themselves.)
-ident integer
Image identification value. (System use only.)
-idexp letters
Identifier export: forces identifiers to appear in the
run-time dictionary/section tree. letters is a single
argument (possibly empty) consisting of any of the following
letters:
w Export all top-level identifiers whose name has been
used as a quoted word (this is the default).
s Export all syntax words.
m Export all macros.
-lf arg-list
O/S link command flags (these will be added to the link
command before any object file arguments specified with
-lo).
-lo arg-list
Other O/S object file and library arguments. These are
merged with any exload input files resulting from external
loads in program modules (see REF * EXTERNAL), and added to
the link command after the Pop object file arguments.
As with exload, an argument beginning with == is assumed to
specify an environment variable/logical name, and is
replaced by the list of strings (i.e. the exlibs result)
returned by * sys_translate_exlibs applied to it.
If in addition the translation of any == environment
variable specifies an X link type, then this determines the
X link type for the program -- see Poplog Image X Link
Specification in REF * X. If no such -lo argument is
present, and Poplog modules containing X code have been
incorporated into the program, the default will be
==POP_XLINK_EXLIBS. (It is an error if the resulting X link
type is incompatible with that required by any module
incorporated in the image.)
Note that the -x* options are shorthand for specifying
-lo ==POP_X*_EXLIBS
(-xlink thus corresponds to the default.)
-noshare
Link image without using shareable libraries.
-o image-name
Name of the executable image to link. Defaults to a.out in
the current directory.
-port (System use only.) For porting: implies -a, and stops the
addition of $popexternlib/libpop.olb to the link command.
-p Causes the files poplink_*.o and poplink_cmnd to be
generated in the current directory (as described above), for
use with a later 'quick' relink with -q.
-ponly Do Pop part of link only; similar to -p, but doesn't
actually obey poplink_cmnd to link the image.
-q Following a link with -p, do a 'quick' relink: instead of
redoing the Pop part of the link, do only the O/S
object-file link, using the existing poplink_?.o and
poplink_cmnd files (a new poplink_dat.o is generated
however, since this ensures that the image date will be
different).
Note that this option can be used ONLY when no changes have
been made to the declarations, initialisations, or locations
of any permanent identifiers. (Otherwise, the data contained
in the existing poplink_?.o files will be incorrect.)
(Note that you have to respecify the image name with this
option, otherwise it defaults as for an ordinary link.)
-s section-list
Names of sections to be set up at run-time. All identifiers
in each section are exported to the dictionary.
-tr Trace loading, i.e. list w-files and w-library modules used.
Where a w-library module is conditionally extracted (i.e. by
virtue of defining an undefined identifier), the name of the
identifier causing the extraction is given in brackets after
the module name.
-uses idname-list
Mark the specified identifers strongly used (forcing their
extraction from libraries, etc). For each idname, this is
equivalent to specifying the Pop-11 code
uses (idname);
somewhere in one or more program files.
-ubn idname-list
Uses by name -- as for uses, but also exports the
identifiers to the dictionary (like -idexp). For each
idname, this is equivalent to specifying the Pop-11 code
uses-by_name (idname);
somewhere in one or more program files.
-unum letters
Use number keys: letters is a single argument (possibly
empty) consisting of any of the following letters:
b biginteger_key
r ratio_key
f (d)decimal_key
c complex_key
Thus -unum br is equivalent to
-uses ( biginteger_key ratio_key )
etc. The default is brf (i.e. you have to ask for
complex_key explicitly).
-wlb w-library-list
Group of w-libraries for recursive search extract. See Use
of W-Libraries above.
-wlbused
Stands for the set of w-libraries used by all w-modules
incorporated so far, as a -wlb group. See Use of W-Libraries
above.
-x_complete
Special used by the system pglink command (only operative
for MIPS).
-x* Where * is a sequence of lowercase alphanumeric, specifies
the type of X link, and is the same as supplying the option
-lo ==POP_X*_EXLIBS
where X* is the same in uppercase. See -lo above.
w-library -in module-list
w-library -ex module-list
Following a w-library name, unconditionally incorporates
modules from that library in the link, where module-list is
a list of module names.
-in means include only the named modules in the link.
-ex means include all modules from w-library in the link,
excluding the named ones (thus an empty list ( ) for -ex
means include all modules).
-----------------------------------------------------------------------
4 Poplibr
-----------------------------------------------------------------------
Poplibr creates and maintains Pop object libraries, where each library
consists of two files, libname.wlb and libname.olb.
The format of a Poplibr command is
poplibr option w-library w-files
where option is one of the single options described below.
w-files is a sequence of w-file names. For each of these, the actual
file name part (i.e. the sys_fname_name part) is used as the module name
within the library; thus the whole argument is used by those options
requiring an actual file (-c, -r, -x), whereas any directory path on the
name is ignored by those options requiring only a module name (-d, -l,
etc).
4.1 Options
------------
-c Create w-library from w-files. w-library must not exist
already.
-d Delete the modules specified by w-files from w-library.
-l List the modules in w-library specified by w-files (or all
modules if none specified).
-lcs For each module in w-library specified by w-files (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 module date.
-ld As -l, but give module dates.
-r Replace (or add) the specified w-files in w-library.
-x Extract the modules specified by w-files from w-library (or
all modules if none specified; in this case the w-files are
created in the current directory).
--- C.all/help/popc
--- Copyright University of Sussex 1993. All rights reserved.