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