home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / languages / panebasic / lib / blib2 / !BlibII / Docs / Guide next >
Encoding:
Text File  |  1993-01-25  |  8.4 KB  |  231 lines
  1.  
  2.  
  3.             Blib II  User Guide                      © Ian Palmer, 1992
  4.             -------------------
  5.  
  6.  
  7. Introduction
  8. ------------
  9.  
  10. The Blib application is an application designed to allow simple management
  11. of Basic libraries, allowing the user all the advantages of the Basic
  12. Library system, but with fewer of the disadvantages.
  13.  
  14. Blib also comes with a set of libraries which are described in detail in
  15. other files within the 'Docs' directory.
  16.  
  17. What Blib offers the user is a sort of Basic linker, which takes a Basic
  18. program and a set of libraries, and produces a single Basic program which
  19. contains the initial program plus all the library routines needed by that
  20. program (but not any library routines not required).
  21.  
  22.  
  23. Starting up
  24. -----------
  25.  
  26. When you run Blib II it will install itself on the iconbar. There may be a
  27. slight pause before it appears on the iconbar, this is quite normal and is
  28. just Blib II initialising itself, and setting up all it's data structures.
  29.  
  30.  
  31. The main menu
  32. -------------
  33.  
  34. The main menu contains four entries, the usual 'Info' and 'Quit' options, as
  35. well as an 'Install' entry and a 'Help' submenu. These two entries are
  36. explained in detail later on.
  37.  
  38.  
  39. Installing Libraries
  40. --------------------
  41.  
  42. So that the Blib linker can locate procedures and functions you need to
  43. install all the libraries. Before a library can be installed it needs to be
  44. formatted as described later on.
  45.  
  46. Once a library is correctly formatted, you first need to check that the
  47. install option on the main menu is selected (ticked), and then you need to
  48. simply drag the library to Blib II's icon. The library file will then be
  49. scanned, and the library will be installed.
  50.  
  51.  
  52. Viewing 'Help' entries
  53. ----------------------
  54.  
  55. Blib libraries contain a facility for allowing descriptions of the
  56. procedures and functions to be read quickly, and easily. The 'Help' entry in
  57. the main menu leads to a list of all known libraries (listed in alphabetical
  58. order), each entry leading to a further submenu which contains a list of all
  59. the library entries known to Blib.
  60.  
  61. Selecting any library entry will bring up a window which contains the
  62. decription of that library entry (usually a procedure or function).
  63.  
  64. BlibII also supports the StrongEdII help machanism (at least at version 1.20
  65. of StrongEdII). Thus pressing F1 inside StrongEdII when the cursor is over
  66. a procedure or function known by BlibII, it will bring up a help window for
  67. that function.
  68.  
  69.  
  70. Performing Linking
  71. ------------------
  72.  
  73. Before linking can take place, you need to check that all the required
  74. libraries are installed, and are located in directories pointed to be the
  75. BlibII$Path variable.
  76.  
  77. Then to link a Basic program, first checking the 'Install' option of the
  78. main menu is NOT selected, simply drag the file to Blib II's iconbar icon. A
  79. standard 'Save' window will then appear and you should then drag the save
  80. icon to where you wish to store the linked program. Note if you try to make
  81. the destination file the same as the source file, BlibII will first rename
  82. the source file 'BlibImage' (overwriting any file with this name).
  83.  
  84. Once you have dragged the save icon (or typed in the save path) linking will
  85. take place. Once linking is complete a window will appear giving details of
  86. the linking that was just taken place.
  87.  
  88. This window contains a list of all procedures and functions in the linked
  89. program, split into three areas :
  90.  
  91. 1) Called & Defined routines
  92.  
  93.    This section contains a list of all routines (procedures and functions)
  94.    which are both called and defined in the linked program. Those in red
  95.    are the ones which were extracted from libraries during the linking
  96.    process.
  97.  
  98. 2) Defined routines which are not called
  99.  
  100.    This section lists routines which are defined, but not called. In a
  101.    finished program there should be no entries in this section, as anything
  102.    listed here is redundent code.
  103.  
  104. 3) Routines which are still undefined
  105.  
  106.    This section lists all routines which are called but not defined. As with
  107.    the above section a finished program should contain no entries in this
  108.    section.
  109.  
  110.  
  111. Blib libraries
  112. --------------
  113.  
  114. Blib libraries are basically Basic libraries with extra bits. These extra
  115. bits will not interfere with the libraries functionality, and Blib libraries
  116. can also be used as normal Basic libraries.
  117.  
  118. All extra Blib 'commands' are placed on lines of their own, and start with
  119. the two characters '*|'. This sequence was chosen as it will not interfere
  120. with the Basic library, and it also is independent of Basic's own REMark
  121. system.
  122.  
  123. Blib II commands are :
  124.  
  125.   *|start <Routine>
  126.   *|stop <Routine>
  127.   *|extract <Routine>
  128.   *|! <string>
  129.   *|define <Blib-variable>
  130.   *|undefine <Blib-variable>
  131.   *|ifdef <Blib-variable>
  132.   *|ifndef <Blib-variable>
  133.   *|else
  134.   *|endif
  135.   *|update
  136.   *|downdate
  137.   *|copy
  138.  
  139. These commands are also valid inside the program which is being linked,
  140. although in some cases the effect is slightly different.
  141.  
  142.  
  143. Routines :
  144.  
  145. Every routine (procedure or function) in a library which is to be considered
  146. as an exportable routine (ie. called from outside the library) must be
  147. contained between a '*|start' and '*|stop' combination.
  148.  
  149. You can fake a call to a routine by using the '*|extract' command. This will
  150. ensure that a routine is linked, even if there are no actual calls to it.
  151.  
  152. Descriptions of routines should be placed on lines starting with the '*|!'
  153. command, and must be between the '*|start' and '*|stop' for that routine.
  154.  
  155.  
  156. Blib-variables :
  157.  
  158. Blib-variables are available to give more power to Blib linking. When ever a
  159. routine is encountered by Blib (either a call to it, or the definiton of it)
  160. a Blib-variable is defined with it's name (including the PROC of FN part).
  161.  
  162. The user can define further variables at will using the '*|define' command,
  163. and also undefine variables with the '*|undefine' command.
  164.  
  165. These variables can then be used with the '*|ifdef' and '*|ifndef' commands
  166. to perform 'conditional linking'. These commands (used with '*|else' and
  167. '*|endif') form Blib 'conditional' blocks of Basic. A '*|ifdef' block is
  168. TRUE if the variable placed after the command is defined, and the '*|ifndef'
  169. is TRUE if the variable is not defined. These conditional blocks are handled
  170. as follows :
  171.  
  172. 1) In the Basic program being linked, the whole input program is copied to
  173. the output file reguardless of '*|ifdef' and '*|ifndef' commands. However
  174. lines are only 'scanned' if within a TRUE block.
  175.  
  176. 2) In a Blib library only the parts of a routine within a TRUE block are
  177. copied to the output file.
  178.  
  179. This means that you could write very complex routines where only relevant
  180. parts are linked. An example of this is used in the WIMP library in
  181. PROCwimp_poll. This procedure has the ablility to call specific event
  182. procedures upon most standard poll reasons (eg. idle, redraw, message,
  183. etc.). However not all programs need to respond to all poll reasons, and
  184. thus only the parts needed by your program are linked in by Blib
  185. automatically. 
  186.  
  187. As an example here is a portion of the main CASE statemwnt in PROCwimp_poll
  188. which shows conditional linking :
  189.  
  190. *|ifdef PROCevent_idle
  191.   WHEN 0 : PROCevent_idle(I%)
  192. *|endif
  193.  
  194. This means that if you have defined a procedure for handling idle polling
  195. events (as PROCevent_idle) then that line will be linked, otherwise that
  196. line will not be linked into your program.
  197.  
  198. Now imagine your program developement follows a path similar to :
  199.  
  200.   1) You start your program which has a call to PROCwimp_poll, but there
  201.      is no PROCevent_idle defined.
  202.  
  203.   2) You link your program using Blib - thus PROCwimp_poll is linked in
  204.      without any reference to PROCevent_idle.
  205.  
  206.   3) You now create a definition for PROCevent_idle in your program...
  207.  
  208. This will cause a problem as PROCwimp_poll will not be able to call your
  209. PROCevent_idle. To get around this there is a special set of commands that
  210. can define an 'update' block. An update block is a block of code in a main
  211. program (the unlinked program) which is NOT copied to the destination program
  212. (the linked program). This is done by including the block between two lines :
  213.  
  214. *|update
  215. *|downdate
  216.  
  217. As this block will not be copied, it will be relinked during the linking
  218. process. Now the only problem is getting the *|update and *|downdate commands
  219. into your program, as commands are not nomally copied from library to linked
  220. program. To gat around this there is a special command called '*|copy' which
  221. makes the linker copy the next line to the linked program no matter what that
  222. line is, eg.
  223.  
  224. *|copy
  225. *|update
  226.  
  227. will copy the '*|update' line to the output program.
  228.  
  229.  
  230.  
  231.