?he 'LIBLIST''Page %'
?fo 'Steven Hardy'- % -'22nd February, 1977'
.ce 2
A description of POP11 libraries.
=================================
.pg
This handout explains the POP11 libraries, what they are, how they
are made and how to use them.
I will tackle the last point first.
.sp
How to use libraries
.br
--------------------
.pg
As the POP11 system is compiling programs (whether from the
teletype or a disc file) it will occasionally come across words
it doesn't recognize.
The response of most POP systems to this problem is to assume the
words are ordinary variables, declare them as such, print a warning
message and then continue compiling.
This mechanism can be shown by the following:
 	% pop11
 	...
 	: function silly(x);
 	:	x + 1 -> y;
 	{vars y}
 	: end;
.br
In this example the POP11 system has assumed the word "y" denotes
an ordinary variable.
.pg
I had long felt the lack of a 'proper' library facility for POP
programmers where library routines would be loaded automatically.
I have answered this need by making the POP11 system search
a list of 'library files' for the definition of unknown words -
only if a word is not defined in a library is it
.ul
assumed
to be an ordinary variable (as in the case above).
If, however, a library contains a module of the same name as the new
word that module is compiled. The module should declare the unknown
word in some way. (Perhaps as a MACRO or whatever).
Try the following:
 	: function silly(num);
 	:	sqrt(num) + sqrt(num)
 	: end;
.br
In the POP11 system the function
SQRT
is defined, in POP11, in a module in the system library.
You will notice a slight pause whilst the relevant library module
is compiled.
.pg
The system library is in the file /lib/pop.l - when POP11 is loaded
its library search list contains only this file.
.pg
Of course, the POP11 sytem must know of a library file's existence
before it will be searched for unknown words.
Deep in the system there is a variable accessable with:
 	: popmess(Liblist)
.br
This variable holds a list of 'device records' representing
library files to be searched by the system.
If you had a library file called 'mylib.l' you could add it to the search list
by executing:
 	: popmess([%Open,'mylib.l',0%]) :: popmess(Liblist)
 	:	-> popmess(Liblist);
.br
.tp 6
This is a bit messy, so there is a function - Library - provided:
 	: function Library(name);
 	:	if isword(name) then name >< '.l' -> name close;
 	:	popmess([%Open, name, 0%]) :: popmess(Liblist)
 	:		-> popmess(Liblist);
 	: end;
.br
For example:
 	: Library("mylib");
.br
or	: Library('mylib.l');
.br
will both add your file to the search list.
.sp2
What are libraries?
.br
-------------------
.pg
A POP11 library is a collection of POP11 source code files
concatenated into one big file and preceded by an index for fast
access by the POP11 system.
All comments, redundant spaces and tabs etc are stripped from
library files for faster compilation.
.pg
Notice that POP11 libraries are in source code form - there is no
equivalent to 'object code' for POP11.
.sp2
How do I make a library?
.br
------------------------
.pg
There is a system program called 'par' (for Pop11 ARchiver) which
constructs POP11 libraries.
This program takes as argument a number of filenames, each of which
will form one module of the library.
For example, if the file 'sum.p' contained a definition
of a function called "sum" and the file 'addup.p' contained a definition
of function "addup" we could execute:
 	% par sum.p addup.p >mylib.l
.br
Notice that the normal extension for a library file is '.l' as against
'.p' for a source code file.
.pg
There is a stupid restriction in
UNIX
such that there is a limit on the number of arguments
a program can receive. For this reason the following does not always
work:
 	% par *.p >mylib.l
.br
The error message will be
 	arg list too long
.br
To overcome this problem 'par' will read file names from its
standard input if given no arguments, for example:
 	% par <specfile >libfile
.br
.tp 10
.sp
Warning
.br
-------
.pg
The POP11 system reacts VERY badly to errors in library files or to
errors in modules in library files.
Debug functions BEFORE putting them into a library.
If you want to crash the POP11 system put something silly on Liblist
(like a non-library file or, even better, a non-file).
.pg
Library files created by 'par' cannot be edited.
If you create a library file you MUST keep the original
source code files if they are ever to be changed.
Once a source code file has been altered you must re-create the library
file with 'par'.
