home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / basic / blib / Docs / Guide next >
Encoding:
Text File  |  1993-03-02  |  9.3 KB  |  253 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. Removing libraries
  53. ------------------
  54.  
  55. Once you have installed a library BlibII remembers the contents of that
  56. library until you install it again, where it removes all it knows about that
  57. library then installs it again. But what if you want to remove a library
  58. for good?
  59.  
  60. The answer is to place BlibII into 'Install' mode and then bring up the main
  61. menu, and locate the library you wish to remove on the 'Help' submenu. Then
  62. select that menu option whilst holding down 'Ctrl'. BlibII will then remove
  63. that library from it's lists.
  64.  
  65. Note: To avoid accidental removal, this can only be performed while in
  66. 'Install' mode.
  67.  
  68.  
  69. Viewing 'Help' entries
  70. ----------------------
  71.  
  72. Blib libraries contain a facility for allowing descriptions of the
  73. procedures and functions to be read quickly, and easily. The 'Help' entry in
  74. the main menu leads to a list of all known libraries (listed in alphabetical
  75. order), each entry leading to a further submenu which contains a list of all
  76. the library entries known to Blib.
  77.  
  78. Selecting any library entry will bring up a window which contains the
  79. description of that library entry (usually a procedure or function).
  80.  
  81. BlibII also supports the StrongEdII help mechanism (at least at version 1.20
  82. of StrongEdII). Thus pressing F1 inside StrongEdII when the cursor is over
  83. a procedure or function known by BlibII, it will bring up a help window for
  84. that function.
  85.  
  86.  
  87. Performing Linking
  88. ------------------
  89.  
  90. Before linking can take place, you need to check that all the required
  91. libraries are installed, and are located in directories pointed to be the
  92. BlibII$Path variable.
  93.  
  94. Then to link a Basic program, first checking the 'Install' option of the
  95. main menu is NOT selected, simply drag the file to Blib II's iconbar icon. A
  96. standard 'Save' window will then appear and you should then drag the save
  97. icon to where you wish to store the linked program. Note if you try to make
  98. the destination file the same as the source file, BlibII will first rename
  99. the source file 'BlibImage' (overwriting any file with this name).
  100.  
  101. Once you have dragged the save icon (or typed in the save path) linking will
  102. take place. Once linking is complete a window will appear giving details of
  103. the linking that was just taken place.
  104.  
  105. This window contains a list of all procedures and functions in the linked
  106. program, split into three areas :
  107.  
  108. 1) Called & Defined routines
  109.  
  110.    This section contains a list of all routines (procedures and functions)
  111.    which are both called and defined in the linked program. Those in red
  112.    are the ones which were extracted from libraries during the linking
  113.    process.
  114.  
  115. 2) Defined routines which are not called
  116.  
  117.    This section lists routines which are defined, but not called. In a
  118.    finished program there should be no entries in this section, as anything
  119.    listed here is redundant code.
  120.  
  121. 3) Routines which are still undefined
  122.  
  123.    This section lists all routines which are called but not defined. As with
  124.    the above section a finished program should contain no entries in this
  125.    section.
  126.  
  127.  
  128. Blib libraries
  129. --------------
  130.  
  131. Blib libraries are basically Basic libraries with extra bits. These extra
  132. bits will not interfere with the libraries functionality, and Blib libraries
  133. can also be used as normal Basic libraries.
  134.  
  135. All extra Blib 'commands' are placed on lines of their own, and start with
  136. the two characters '*|'. This sequence was chosen as it will not interfere
  137. with the Basic library, and it also is independent of Basic's own REMark
  138. system.
  139.  
  140. Blib II commands are :
  141.  
  142.   *|start <Routine>
  143.   *|stop <Routine>
  144.   *|extract <Routine>
  145.   *|! <string>
  146.   *|define <Blib-variable>
  147.   *|undefine <Blib-variable>
  148.   *|ifdef <Blib-variable>
  149.   *|ifndef <Blib-variable>
  150.   *|else
  151.   *|endif
  152.   *|update
  153.   *|downdate
  154.   *|copy
  155.  
  156. These commands are also valid inside the program which is being linked,
  157. although in some cases the effect is slightly different.
  158.  
  159.  
  160. Routines :
  161.  
  162. Every routine (procedure or function) in a library which is to be considered
  163. as an exportable routine (ie. called from outside the library) must be
  164. contained between a '*|start' and '*|stop' combination.
  165.  
  166. You can fake a call to a routine by using the '*|extract' command. This will
  167. ensure that a routine is linked, even if there are no actual calls to it.
  168.  
  169. Descriptions of routines should be placed on lines starting with the '*|!'
  170. command, and must be between the '*|start' and '*|stop' for that routine.
  171.  
  172.  
  173. Blib-variables :
  174.  
  175. Blib-variables are available to give more power to Blib linking. When ever a
  176. routine is encountered by Blib (either a call to it, or the definiton of it)
  177. a Blib-variable is defined with it's name (including the PROC of FN part).
  178.  
  179. The user can define further variables at will using the '*|define' command,
  180. and also undefine variables with the '*|undefine' command.
  181.  
  182. These variables can then be used with the '*|ifdef' and '*|ifndef' commands
  183. to perform 'conditional linking'. These commands (used with '*|else' and
  184. '*|endif') form Blib 'conditional' blocks of Basic. A '*|ifdef' block is
  185. TRUE if the variable placed after the command is defined, and the '*|ifndef'
  186. is TRUE if the variable is not defined. These conditional blocks are handled
  187. as follows :
  188.  
  189. 1) In the Basic program being linked, the whole input program is copied to
  190. the output file regardless of '*|ifdef' and '*|ifndef' commands. However
  191. lines are only 'scanned' if within a TRUE block.
  192.  
  193. 2) In a Blib library only the parts of a routine within a TRUE block are
  194. copied to the output file.
  195.  
  196. This means that you could write very complex routines where only relevant
  197. parts are linked. An example of this is used in the WIMP library in
  198. PROCwimp_poll. This procedure has the ability to call specific event
  199. procedures upon most standard poll reasons (eg. idle, redraw, message,
  200. etc.). However not all programs need to respond to all poll reasons, and
  201. thus only the parts needed by your program are linked in by Blib
  202. automatically. 
  203.  
  204. As an example here is a portion of the main CASE statement in PROCwimp_poll
  205. which shows conditional linking :
  206.  
  207. *|ifdef PROCevent_idle
  208.   WHEN 0 : PROCevent_idle(I%)
  209. *|endif
  210.  
  211. This means that if you have defined a procedure for handling idle polling
  212. events (as PROCevent_idle) then that line will be linked, otherwise that
  213. line will not be linked into your program.
  214.  
  215. Now imagine your program development follows a path similar to :
  216.  
  217.   1) You start your program which has a call to PROCwimp_poll, but there
  218.      is no PROCevent_idle defined.
  219.  
  220.   2) You link your program using Blib - thus PROCwimp_poll is linked in
  221.      without any reference to PROCevent_idle.
  222.  
  223.   3) You now create a definition for PROCevent_idle in your program...
  224.  
  225. This will cause a problem as PROCwimp_poll will not be able to call your
  226. PROCevent_idle. To get around this there is a special set of commands that
  227. can define an 'update' block. An update block is a block of code in a main
  228. program (the unlinked program) which is NOT copied to the destination program
  229. (the linked program). This is done by including the block between two lines :
  230.  
  231. *|update
  232. *|downdate
  233.  
  234. As this block will not be copied, it will be relinked during the linking
  235. process. Now the only problem is getting the *|update and *|downdate commands
  236. into your program, as commands are not normally copied from library to linked
  237. program. To get around this there is a special command called '*|copy' which
  238. makes the linker copy the next line to the linked program no matter what that
  239. line is, eg.
  240.  
  241. *|copy
  242. *|update
  243.  
  244. will copy the '*|update' line to the output program.
  245.  
  246. Some care needs to be taken when using update blocks. An update block should be 
  247. defined over a complete body of a BlibII routine, ie. an update block should
  248. be placed directly after a '*|start' (excepting the description part can be
  249. before the update) and the corresponding 'downdate' should be directly before
  250. the corresponding '*|stop'.
  251.  
  252.  
  253.