HELP MKIMAGE Robert Duncan, June 1991
A library to simplify the making of saved images.
CONTENTS - (Use <ENTER> g to access required sections)
1 Introduction
2 Loading Libraries
3 Mixed Language Images
4 Startup Actions
5 Optional Flags
-----------------------------------------------------------------------
1 Introduction
-----------------------------------------------------------------------
LIB * MKIMAGE helps to simplify the process of making saved images. It
provides a standard method for making saved images built from a list of
files. It is not a library which should be loaded interactively in the
usual way, but a "command" library designed for use as part of a Shell
or DCL command.
The synopsis of a MKIMAGE command is:
pop11 %nort mkimage [flags...] image [files...] [: startup...]
The flags, files and startup components are all optional, so the
simplest example of this would be:
pop11 %nort mkimage example
which makes a saved image called 'example.psv' in the current (default)
directory. The image can be run with the command
pop11 +example
This particular image won't do very much: its behaviour will typically
be indistinguishable from that of the base 'pop11' command.
You should always pass the %nort argument to Poplog commands which make
saved images: if you want to know why, read Runtime Actions in
REF * SYSTEM.
-----------------------------------------------------------------------
2 Loading Libraries
-----------------------------------------------------------------------
To make a more interesting image, you can include library names as part
of the command line, as in:
pop11 %nort mkimage example flavours
This too creates an 'example.psv' saved image, but this version will
include the * FLAVOURS package. You can specify as many libraries as you
like, to be loaded in order:
pop11 %nort mkimage example flavours browseself_message
You can also give the pathnames of files to compile if you want to
include some of your own code in an image:
pop11 %nort mkimage myapp myapp/build.p ;;; Unix
pop11 %nort mkimage myapp [myapp]build.p ;;; VMS
A name on its own like 'flavours' is taken as the name of a library
file; a name with a directory component like 'myapp/build.p' is taken as
the name of a file to compile.
-----------------------------------------------------------------------
3 Mixed Language Images
-----------------------------------------------------------------------
LIB * MKIMAGE supports mixed language images. To get a particular
language in your image, just include the corresponding library.
For example, the command
pop11 %nort mkimage example prolog
will create an image which behaves just like the standard Prolog saved
image (since LIB * PROLOG loads the Prolog subsystem).
Once the language itself has been loaded, you can then add libraries
from that subsystem. The command
pop11 %nort mkimage example prolog edinsynt
first loads Prolog and then the Prolog Edinburgh syntax library, just as
if you had typed
library(edinsynt).
to the Prolog prompt.
Multiple languages can be mixed in one image: to build an image
containing both Prolog and Common Lisp, do
pop11 %nort mkimage example prolog clisp
By default, when a mixed-language image is restored, it will start up
using the top-level of the first language subsystem which was loaded. So
the previous command would make an image which would start up in Prolog,
whereas the command
pop11 %nort mkimage example clisp prolog
makes an image which will start up in Lisp. If you don't like the
default behaviour, you can explicitly nominate a start-up subsystem with
the -subsystem option described below.
There is another difference between these two Prolog/Lisp images. When
making mixed language images, libraries are always sought first relative
to the most recently loaded language subsystem. So the command
pop11 %nort mkimage example clisp prolog
first loads the 'clisp' library from pop11, but then loads the 'prolog'
library from Lisp, as if you had typed
(require 'prolog)
to the Lisp prompt. This library contains more than just the base Prolog
subsystem, because it also defines constructs for running Prolog goals
from Lisp. With the libraries given in the original order:
pop11 %nort mkimage example prolog clisp
because there is no Prolog 'clisp' library, both libraries are loaded
from pop11 and hence the extra Prolog/Lisp mixed-language features
aren't included.
Searching for libraries relative to the most recently loaded subsystem
usually gives the best behaviour. If there's an undesirable name clash,
and you can't change the order of loading, you can add a file extension
to the library name to disambiguate. The command
pop11 %nort mkimage example clisp prolog.p
will force the pop11 'prolog.p' library to be loaded in preference to
the Lisp version ('prolog.lsp').
All the standard language saved images (prolog, clisp and pml) will
accept 'mkimage' as a first argument and load this library accordingly.
Thus the Prolog/Lisp saved image could be better built with the command:
clisp %nort mkimage example prolog
The resulting image will be smaller, because it shares the Common Lisp
code with the existing 'clisp' image, but of course it must be restored
using 'clisp' as the base command:
clisp +example
This property is inherited by all images made with the MKIMAGE command.
To build another layer on top of the last example, do
clisp +example %nort mkimage example2 .....
The resulting image 'example2.psv' would be restored with the command:
clisp +example +example2
-----------------------------------------------------------------------
4 Startup Actions
-----------------------------------------------------------------------
As already described, the normal start-up behaviour of an image made with
MKIMAGE is to run the top-level of the primary subsystem. The idea is to
make images which behave just like the standard language images but with
frequently-used libraries already built in.
An alternative use of saved images is to make specialised applications,
and you can do this by adding a <startup> option to the MKIMAGE command.
This relies on the fact that all subsystem images, when restored, will
interpret an argument beginning ':' as an expression to evaluate. For
example:
pop11 ":3=>"
** 3
prolog ":write('** 3\n')."
** 3
yes
etc. If you add such an argument to the end of the MKIMAGE command, then
that argument is automatically prefixed to the argument list every time
the image is restored.
Example:
pop11 %nort mkimage example ":3=>"
pop11 +example
** 3
So if you have an application myapp which is built from a file
"myapp/build.p", you can turn this into an application image with the
command:
pop11 %nort mkimage myapp myapp/build.p ":myapp();"
Certain libraries you might want to initialise before the image is made:
you can do this with the -init option described below.
-----------------------------------------------------------------------
5 Optional Flags
-----------------------------------------------------------------------
There are several optional flags which can be added to the MKIMAGE
command to tailor its behaviour. All flags are prefixed with '-' and
should precede the image name.
-ved
Changes the default start-up behaviour to Ved mode: when the image is
restored, any command-line argument is interpreted as the name of a
file to be edited.
Example: the command
pop11 %nort mkimage -ved vt220 vedvt220
builds an image 'vt220.psv' which includes the code to customise Ved
for a VT220 terminal. The subsequent command
pop11 +vt220 foo.p
will restore the image and invoke Ved on the file 'foo.p'.
-subsystem subsystem
Selects the named subsystem as the primary subsystem to be run when
the image is restored. The nominated subsystem must be included in
the image.
Example: the command
pop11 %nort mkimage -subsystem pop11 prolog clisp
builds an image which contains both Prolog and Lisp subsystems, but
which will start up in the standard Pop-11 top-level.
-init subsystem code
Adds initialisation code for the named subsystem, to be run
immediately before the image is made. You can specify this option
many times, and the fragments of code will be evaluated in order.
Example:
pop11 %nort mkimage -init pop11 "myapp_init();" myapp \
myapp/build.p ":myapp();"
-share
-noshare
Determine whether the image is to be shareable or not. Images are
always made using * sys_lock_system, so the non-writeable part of
the image can be made shareable. The default behaviour is to share
images which are installed in the Poplog system image directories
"popsavelib" and "poplocalbin" and not to share others.
-nonwriteable
If supplied, calls * sys_lock_system with a flag saying that the
default placement for all structures not individually or
class-marked as writeable/nonwriteable, and for all closures, should
be non-writeable. If not supplied, these items are marked as
writeable. (The effect of this that things like lists and vectors
which aren't marked as writeable with the writeable operator will go
into non-writeable memory in the image.)
Note that MKIMAGE always sets the variable pop_record_writeable true
anyway, regardless of whether -nonwriteable is supplied or not.
-install
On Unix systems, this is the same as -share. On VMS systems, this
implies -share, but also enables the use of * sys_install_image to
make the image shareable by all users.
-entrymain
-entry procedure-name
As an alternative to supplying an argument beginning with ':' (as
described above), the -entry option requests that control be passed
directly to the procedure given by procedure-name when the image is
restored (note that procedure-name may contain a Pop-11 section
pathname component.) The -entrymain option specifies the default
name $-Pop$-Main as the entry procedure.
With either of these options, control is passed directly to the
procedure, WITHOUT calling syssetup. Thus none of the standard
language subsystem interpretation of arguments in poparglist
occurs.
-debug
-nodebug
Causes true (-debug) or false (-nodebug) to be assigned to
pop_debugging while files are being compiled (the default setting is
"undef"). (Has no affect on the value of pop_debugging when the
saved image is restored.)
-flags key flags
LIB * MKIMAGE defines a property named mkimage_flags_table. This
option adds to the table a mapping from the word key to a list of
flags, where flags may be a single string or a sequence of strings
written between '(' ')' (these typically need quoting to get past
the Shell). The property can be interrogated by the libraries being
loaded.
For example, a library may contain code of the form:
global vars debugging = false;
#_IF DEF mkimage_flags_table
mkimage_flags_table("debugging") -> debugging;
#_ENDIF
To load this library in debugging mode, you could do
pop11 %nort mkimage -flags debugging "" example ....
--- C.all/help/mkimage
--- Copyright University of Sussex 1993. All rights reserved.