
                   ------------------------------------
                                  LINKER

                         version 2.51 (01-Jul-05)

                            Andrew Ayre 1996-98
               Ray Favre, changes/additions from 1st May 1999
                  This version modified by Mike Sandells
                   ------------------------------------

INTRODUCTION

  Linker takes a BASIC 'Image' file (e.g. a !RunImage file or similar)
and a BASIC 'Library' file used by the Image (e.g. the DrWimp Library)
and creates a new Image file (referred to below as the Output file)
which is the old Image file plus just the parts of the Library file
that are required.

  This can be very useful if the Library is large, and a fair proportion of
it is not used.

  LINKER WILL NOT WORK IN A READ-ONLY FILING SYSTEM


USING

  Load in the usual way by double-clicking on the icon. Linker supports
interactive help applications such as Acorn's !Help.

  Click on the icon to open the main window, which consists of two large
drop boxes. One is for the Image to be dropped on and the other is for
the Library.

  Alternatively you can type the corresponding full pathnames into the
writeable icons below. 

  Clicking on Cancel will ignore any changes you have made and close the
window.

  Clicking on Link starts the action by bringing up a save box.

  Use the save box in the usual way to specify a place to which to
save the new Image (Output file) - by dragging and/or typing a full
path and/or leafname. (For your own protection, you are not allowed to
overwrite the original Image nor the Library.)

  If everything you have specified so far is valid, the linking will
then begin and a status window will open telling you what is going on
(although some phases are pretty short and may not give you time to
read them!). A progress bar will show how much has been completed of
each stage.

  The stages are (in order):

    - Reading Image function calls and definitions.
    
    - Reading Library function calls and definitions. ** see Note below
    
    - Compiling functions needed (will take several passes to complete).
    
    - Linking Image with Library and saving the new Output file.

  Note: If you are using exactly the same Library as used the last
time you used Linker (not neccessarily the same actual file, but a
file with exactly the same contents) then it will be recognised and
the second stage listed above will be very short indeed and may be too
quick to notice.

That's all there is to it - except for......

OPTIONS

  Once those parts of the Library that are needed have been added to
the Image, any Basic LIBRARY commands in the Image file are now
redundant, and need to be removed.

  Linker can strip out such LIBRARY calls automatically - and a few
options for this are controlled from the iconbar menu.

  Choosing 'Options...' from the iconbar menu will bring up the
Options window. There are three choices:

  'Strip none' - no LIBRARY calls will be removed.
  
  'Strip first' - only the first LIBRARY call in the Image will be removed
(this is the default option).

  'Strip all' - all LIBRARY calls in the Image will be removed.



NOTES

A) BlibII tags eg:

*|start <name>

are allowed but they must be on a line by themselves with no preceding
spaces.




B) From Version 2.31 onwards, it is unnecessary to separate DEF PROC/FNs
in Image or DrWimp library with an empty line with just a colon in it.
Whatever method used to separate them will (hopefully!) be faithfully
carried through to the linked output.




C) From Version 2.50 onwards, Linker's !Run file sets a System
Variable called:

Linker$MaxFuncs

and 'as supplied' it is set to 400.

This System Variable is interrogated by !Linker on start-up and is
used to dimension the several arrays involved in the linking process.
The value sets the maximum number of DEF PROC/FNs and different
PROC/FN calls that can be processed in the Image, Library or Output
files. (A value of 400 is pretty generous and is unlikely to be too
small.)

Theoretically, this limit can be transgressed in one of three sets of
ways:

i) too many DEFs in the original Image file, or
ii) too many (different) PROC/FN calls in the original Image file;

  A 'Subscript too large...' error will occur during reading of Image
file

iii) too many DEFs in the Library file, or
iv) too many (different) PROC/FN calls in the Library file;

  A 'Subscript too large...' error will occur during reading of Library
file

   v) too many DEFs in the intended Output file, or
   vi) too many (different) PROC/FN calls in the intended Output file;

   A 'Subscript too large...' error will occur during the compiling of
the needed functions.

If any of these errors occur - and the third type is more likely than
the first two types - then the first remedy to try is to increase the
value of 'Linker$MaxFuncs' in the !Run file - but do not be too
extravagant or you may also need to increase the WimpSlot value - also
in the !Run file.

 
CONTACTS

Web-site:   http://www.rayfavre.me.uk

Email:      drwimp@rayfavre.me.uk

  
    CONDITIONS OF DISTRIBUTION...

  Linker may be distributed freely as long as all of the files are
included and unaltered and no profit is made.

  If you got your copy with the DrWimp programming system then it may
be distributed seperately, but I remind you that the DrWimp system
must not be distributed without Linker.

EOF251
