Building a new Poplog system.
Select headings to return to index
The command script NEWPOP located in the Poplog source directory ($popsrc) is used to build a new Poplog system.
The command synopsis is:
For the Unix C shell:
For the Unix Bourne shell:
For VMS:
The command installs a new Poplog system in the directory denoted by the path <poplog-root-directory>.
If you have deleted the source directory to save space, you must recover it from your distribution tape before trying to run NEWPOP.
NEWPOP installs a completely new Poplog system in the directory identified by the environment variable (or logical name) "usepop". If you have an existing Poplog system at that location, it will be overwritten. You must ensure that "usepop" has been set to the correct directory name before you run NEWPOP.
In order to avoid tedious repetition of examples using different syntaxes and notations, the following conventions are adopted throughout the remainder of this file.
1) Environment variables (logical names) are written in the Unix
style, prefixed with a '$' sign, e.g.
$popsys (for the Poplog executable directory) $popsrc (for the Poplog source directory)
VMS users should simply ignore the leading '$'.
2) Filenames are written in the Unix style, e.g.
$poplocal/local/com/ (for the local command directory)
which corresponds to the VMS pathname
poplocal:[local.com]
The procedure * sysfileok on VMS systems will perform this conversion automatically, e.g. try
sysfileok('$poplocal/local/com/')=>
3) Examples of operating system commands are written to assume the
Unix shell. The arguments to commands are the same for all
systems, only the syntax for denoting the command script varies.
Thus the example:
$popsrc/newpop -link
corresponds to the VMS DCL command:
@popsrc:newpop -link
4) The word NEWPOP is used in the text to stand for the command:
$popsrc/newpop
NEWPOP runs in an environment initialised by reading the standard Poplog login script
$popcom/poplog
(see HELP * INITIAL). This depends on an initial setting of the environment variable $usepop; other environment variables are then defined relative to that. The principal environment variables used by NEWPOP are
$popsrc (the Poplog source directory) $popsys (the Poplog executable directory) $popsavelib (the Poplog saved image directory) $popcom (the Poplog command directory) $poplocal (the Poplog local directory)
If you are unfamiliar with the Poplog environment, you should read DOC * SYSSPEC.
NEWPOP performs the following functions:
Any of these functions can be omitted or controlled by means of appropriate options.
The behaviour of NEWPOP is completely option-driven: only those actions explicitly selected by options are performed. The available options are summarised in Table 1; their meanings are discussed in more detail in the sections which follow.
--------------------------------------------------------------------
Table 1 lists only the "enabling" options: specifying any of these implies the inclusion of some particular step in the NEWPOP process. For each one there is a corresponding "disabling" option which suppresses that same feature, obtained by prefixing the option name with no: e.g. nolink, noprolog etc.
Also, certain options (described below) allow for an extra "qualifier" argument separated from the option name by an "=" sign:
option = qualifier
option and qualifier together make up a single item.
The case of options is not significant, as all options are converted internally to lower case.
NEWPOP obtains its options from two sources:
The configuration file provides the primary control; command-line options are used to refine its behaviour. The default configuration file is
$popsrc/newpop_options
This contains all the options necessary to build a standard configuration Poplog system (with slight variations between Unix and VMS). So running the NEWPOP command with no options will regenerate this standard configuration. You can provide an alternative configuration file as the last argument to the NEWPOP command, e.g:
$popsrc/newpop $poplocal/local/newpop_options
In this case, the default file is not consulted at all: only the options specified in your own file will be acted upon. If you want to write your own configuration file, a good idea is to copy the default version and delete or modify lines as appropriate. Within a configuration file, each option (together with any associated qualifier) must appear on a line by itself. End-of-line comments can be indicated with the usual Poplog ';;;' convention, and blank lines are ignored.
Regardless of which configuration file is to be used, you can also specify options on the command line to override those in the file. Command-line options are the same as those from Table 1 above, but prefixed with a '-' sign, e.g.
$popsrc/newpop -link
Disabling options are particularly useful on the command-line, where they can be used to suppress features requested in the configuration file, e.g. the command:
$popsrc/newpop -nolink -nolocal
runs the default NEWPOP, but omitting the link and local steps.
If you add a qualifier to a command-line option, remember that the two must be passed as a single item, so will probably need quoting. Any special characters in the qualifier will need quoting too. This is not a problem with options in a file.
If the number or complexity of command-line options becomes too unwieldy (particularly on VMS systems, where a limit is imposed on the number of arguments) you can place the options into a file and use the options flag to get that file consulted, e.g:
$popsrc/newpop -options tempfile
This file is read in addition to the configuration file.
Finally, if you want to ignore configuration files altogether and supply all the options on the command line, you can use the special word only in place of the configuration file name; e.g. the command:
$popsrc/newpop -link only
will perform only the link step.
Step 1 of the NEWPOP process is to link a new version of the Poplog executable -- newpop11 -- in $popsrc. This step is enabled with the link option.
Within the link step, there are two further parameters of variation: whether to include X support within Poplog and whether to build an RSV image for delivery systems.
X support is included by default. In order to make use of it, your system must have an implementation of the X Toolkit and Xlib libraries (X11 Release 4 or later) available to the system linker. NEWPOP will look for these in standard places -- exactly where depends on your system. If this fails to work, or if you want to do something different, then read the next section.
If your system doesn't have X, or if you're sure you're not going to use it and want to reduce the size of the Poplog images, then you can exclude it from Poplog by specifying the option nox.
RSV support is not included by default: it must be enabled with the rsv option. This causes a special copy of the newpop11 image to be made as $popsrc/rsvpop11. This image is required for delivery systems.
Linking newpop11 requires the Poplog "external" library
$popexternlib/libpop.olb
If this does not exist, NEWPOP will rebuild it.
As well as the executable image itself, NEWPOP may also create in $popsrc a symbol table file for external loads ($popsrc/newpop11.stb) and a map file for debugging ($popsrc/newpop11.map).
The newpop11 image created by the NEWPOP link step will include support for X unless you override it with the nox option.
As described in the section Poplog Image X Link Specification in REF * X, X linking is controlled by the values of Unix environment variables/VMS logical names, whose names have the form
POP_XPREFIX_EXLIBS
where XPREFIX is a short prefix corresponding to the X link type. The format of the NEWPOP x option is thus
x = -xprefix
where (lowercase) xprefix selects the corresponding (uppercase) variable name. Standard values for -xprefix include
-xm (selects POP_XM_EXLIBS, for Motif) -xol ( " POP_XOL_EXLIBS, " OpenLook) -xt ( " POP_XT_EXLIBS, " MIT)
If the '= -xprefix' qualifier is omitted, it default to -xlink, which selects POP_XLINK_EXLIBS. This variable is set to give the appropriate host-specific default.
For example, to link a system with MIT only, use
$popsrc/newpop -link -x=-xt
See REF * X for further details.
Step 2 of the NEWPOP process is the installation of the newpop11 image as the base Poplog executable:
$popsys/basepop11
This step is enabled with the install option.
The first stage of the installation is to clear out any existing executables and saved images from the $popsys and $popsavelib directories: it's primarily for this reason that you must be sure that you have set $usepop correctly before you run NEWPOP, to avoid your existing Poplog system from being deleted in this way. However, if there is an existing basepop11 executable in $popsys, it is renamed as "oldpop11" rather than being deleted, so you can recover it if something goes wrong.
The newpop11 executable, symbol table and map files are then moved from $popsrc to $popsys and renamed as basepop11. There must be a newpop11 executable in the $popsrc directory. In the normal progress of events, it will have been created by a preceding link step. If you have chosen to omit this step, you should ensure that the newpop11 executable has been created by some other means: either by manual linking, or by copying an existing executable from $popsys.
NEWPOP also creates a new "popenv" file in $popsys for definitions of command symbols for Poplog shell/DCL commands such as "pop11", "ved", "prolog", etc. This file is consulted by the standard Poplog login script, $popcom/poplog. It wil always contain at least the definition of the command "pop11".
Step 3 of the NEWPOP process involves building executables and libraries needed for Poplog run-time support. Currently there is just one such object: the archive library for the Poplog Widget Set (Xpw).
The Poplog Widget Set is enabled with the xpw option. This causes NEWPOP to run the command $popcom/mkXpw which will rebuild and install the Poplog Widget Set archive library in $popexternlib. This option is ignored if you have selected nox.
Step 4 of the NEWPOP process is to build the standard saved images in $popsavelib. The full set of standard images consists of:
startup.psv # Default start-up code prolog.psv # Prolog language subsystem clisp.psv # Common Lisp language subsystem pml.psv # Standard ML language subsystem xved.psv # XVed (X based version of Ved) eliza.psv # Eliza demo (not built by default) logic.psv # Logic demo (uses Prolog; not built by default)
For each image there is a corresponding option -- startup, prolog, clisp, etc. -- such that selecting the option causes NEWPOP to build the image. The default configuration file includes options for all the images except eliza and logic; if you want these two built as well, use the command:
$popsrc/newpop -eliza -logic
The status of the startup image is special in that (if it exists) it is loaded by default with all Poplog commands. In particular, all subsequent saved images are layered on top of the startup image. The image contains code which is viewed as part of the base Poplog system, but which is not part of the Poplog executable itself. It may well be customised on a per-site basis, depending on how Poplog is used at each site.
Other dependencies exist between images: you can't build the logic image without prolog, and you can't have xved without x. Also, none of the images (except startup) will be built if you specify noimages.
Images are normally built using command scripts from $popcom. You can specify your own commands instead, by qualifying the image-name argument with the command to use: the qualifier is simply executed as a Shell or DCL command without interpretation. For example, the option
prolog = $poplocal/local/com/mkprolog # Unix
prolog = @poplocal:[local.com]mkprolog # VMS
would use a local version of the "mkprolog" command in place of the system-supplied one. If such an option is to be given on the command line, make sure that you add the required amount of quoting to allow the option to be read as a single item, e.g:
$popsrc/newpop -"prolog = $poplocal/local/com/mkprolog"
Step 5 of the NEWPOP process consists of writing to the $popsys/popenv file definitions of any additional Poplog shell/DCL commands which are to be made available to users on login. This step is associated with the commands option and is always performed unless you disable it by specifying nocommands.
If this step is enabled, NEWPOP will create command definitions for any of the following standard saved images you have chosen to build:
prolog # Run Prolog clisp # Run Common Lisp pml # Run Standard ML xved # Run XVed
Beyond that, there are several other commands which you can request to have defined:
ved help ref teach doc vt100
which provide various entry points to the Ved editor. Note that on VMS systems, the commands ved and help are normally replaced with the commands
ve*d hlp
The first allows for command abbreviation; the second is to avoid conflict with the DCL help command.
Having each command specified individually allows you to avoid any which conflict with existing command names. For example, some Unix sites may also prefer not to have the help command enabled, so the command-line option:
$popsrc/newpop -nohelp
would suppress that.
Step 6 of the NEWPOP process is making the documentation indexes. This means creating an index file in each HELP, TEACH and REF directory, and also creating the DOC_INDEX database for the <ENTER> ?? command. This step is enabled with the indexes option.
The standard Poplog system is distributed with indexes already built, so if you are rebuilding a system, using the same documentation directories as before, it is unlikely that you will need to rebuild the index files. The command-line option
$popsrc/newpop -noindexes
will suppress the index-building stage and save a little time.
Indexes are built with the command $popcom/makeindexes.
An additional function performed by $popcom/makeindexes is to strip all documentation files of Ved special character encodings.
Files written by Ved use extra control characters to represent attributes like bold and italic, as well as a special graphics character set. Since they are not recognised by editors other than Ved, the extra control characters will show up explicitly when a file is viewed with another editor.
One way round this problem is to use the command 'pop11 stripvedfile' to filter individual files (see LIB * STRIPVEDFILE). This removes Ved encodings from a file and writes the result either to standard output or to another file, from whence another editor can access it.
On the other hand, if you will mainly be using other editors to examine Poplog documentation, you have the option of employing
$popsrc/newpop -stripdoc
to (permanently) remove special encodings from all documentation files (this implies the indexes option).
NOTE
Even if you prefer not to use Ved for your normal editing, in an
X environment you always have the option of using XVed to view
Poplog documentation. This will in no way interfere with the
operation of another editor.
The final stage in the NEWPOP process is to run the local NEWPOP command script:
$poplocal/local/com/newpop
This step is enabled with the local option.
This file need not exist; if it does, it may contain any commands for tailoring the newly-installed Poplog system, e.g. adding local command definitions, building local saved images in $poplocalbin etc.
--- C.all/help/newpop --- Copyright University of Sussex 1997. All rights reserved.