home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / dirs / libtool_463.lzh / LibTool / LibTool.doc < prev    next >
Text File  |  1991-03-09  |  11KB  |  264 lines
  1. LibTool:
  2.  
  3.  This is a program which takes an fd file (the calling specifications for a
  4. shared library) and outputs PRAGMA statements for the Manx or Lattice C
  5. compilers, the C glue code (instead of PRAGMAS), BMAP files for Basic
  6. programs, an asm or C INCLUDE file, and an asm module which can turn any C or
  7. asm code into a shared library. It allows you to develop and test functions in
  8. a stand alone program, and then easily and quickly convert the functions into
  9. a shared library, plus make all support files for your library.
  10.  
  11.   It is written entirely in 68000 for speed and small size (about 9K). It's a
  12. necessary tool for anyone writing a shared library as it generates code
  13. necessary to make the library, as well as all support files needed by
  14. applications using the library.
  15.  
  16.  
  17. «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  18. 1) Usage:
  19.  
  20.  LibTool is meant to be used from the CLI. The args are as follows:
  21.  
  22. LibTool [-ibpschalm] [-e extension] [-o out] fdname1...
  23.  
  24.  -i = include ##private functions within the fd file
  25.  -b = generate a Basic BMAP file instead of Glue, PRAGMAS, or INCLUDE files
  26.  -p = generate PRAGMAS instead of the C glue modules or BMAP
  27.  -s = scratch reg a6 in the C glue code (default = SAVE reg a6)
  28.  -c = setup glue, PRAGMAS, and libstartup code for a lib made of C functions
  29.  -l = generate Lattice style pragmas (default = MANX Pragmas)
  30.  -o = PRAGMA, BMAP, or combined glue filename
  31.  -m = generate lib startup code (.src asm module)
  32.  -a = generate asm INCLUDE file instead of PRAGMAS, glue, or BMAP
  33.  -h = generate C INCLUDE file
  34.  -e = use an extension other than ".asm" for the C glue modules
  35.  
  36.  
  37. «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  38. 2). Glue Modules
  39.  
  40.   By default, LibTool generates the C glue modules with which a C application
  41. must be linked in order to access functions in a shared library. It generates
  42. a 68000 asm code file for each function in the library. These files should each
  43. be assembled (with your C compiler's assembler), and the resulting objects
  44. should be linked with your C application. You only need link with those files
  45. with the same name as functions that you intend to call within the library.
  46. For example, if you made the glue modules from an fd file for Exec, you would
  47. end up with several dozen 68000 asm files. Among them would be such files as
  48. AllocMem.asm, FreeMem.asm, WaitPort.asm, etc. You need assemble and link only
  49. those Exec functions which you call in your application. The -e option allows
  50. you to specify a different extension than ".asm". For example,
  51.  
  52. LibTool -e 68K exec_lib.fd
  53.  
  54. would take the fd file, exec_lib.fd, and create files with such names as
  55. AllocMem.68K, FreeMem.68K, etc.
  56.   By default, register a6 is saved upon entry to the glue code, and restored
  57. upon exit. If your compiler generates code where a6 is not considered scratch,
  58. you'll want this feature. The later versions of both Manx and Lattice treat
  59. a6 as scratch across calls, so you can make for more efficient and smaller C
  60. glue code by using the -s option. For example, the glue code for AllocMem.asm
  61. without the -s option is:
  62.  
  63. _AllocMem
  64.     move.l   a6,-(sp)
  65.     movea.l  _SysBase,a6
  66.     movem.l  4(sp),d0/d1
  67.     jsr      _LVOAllocMem(a6)
  68.     movea.l  (sp)+,a6
  69.     rts
  70.  
  71. With the -s option:
  72.  
  73. _AllocMem
  74.     movea.l  _SysBase,a6
  75.     movem.l  4(sp),d0/d1
  76.     jmp      _LVOAllocMem(a6)
  77.  
  78.  
  79.   Besides eliminating 3 of the 6 instructions, it eliminates 1 level of rts
  80. (which otherwise incurs some processor overhead). You should experiment to
  81. see if your compiler won't choke on glue code made with the -s option.
  82.   The -o option should be followed by a filename. If you supply this filename,
  83. then instead of making separate files for each function in the library, one
  84. complete file will be made. If you intend upon using all the functions in a
  85. library, then this option can save you from dealing with dozens of separate
  86. modules. The separate modules are always written to the current directory,
  87. whereas the -o option allows for choosing the directory to write the glue file.
  88.  
  89.  
  90. «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  91. 3). Pragmas
  92.  
  93.   LibTool will make PRAGMAS for Manx or Lattice compilers. Specifying the -p
  94. option causes the compiler to make one file with all the Pragma statements
  95. instead of any glue modules. The default style is for Manx PRAGMAS. Specifying
  96. the -l option causes Lattice style Pragmas to be output instead. This file
  97. should be INCLUDED in any C source that references functions in the library.
  98.   The -o option allows you to specify a filename for the Pragma file.
  99. Otherwise, a default filename is made from stripping the .fd extension from the
  100. source fd filename and appending ".pragma". For example,
  101.  
  102. LibTool -plo df0:MyPragmas exec_lib.fd
  103.  
  104. will make a Lattice Pragma file for the Exec library and place it on df0: as
  105. "MyPragmas".
  106.  
  107.  
  108. ««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  109. 4). ##private functions
  110.  
  111.   The -i option allows glue modules and PRAGMA statements for any library
  112. functions that are flagged as private in the fd file. Otherwise, private
  113. functions are ignored (as they should be).
  114.  
  115.  
  116. ««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  117. 5). Bmap files
  118.  
  119.   BMAP files allow basic programmers to use the library. Specifying the -b
  120. option causes LibTool to generate a BMAP file instead of PRAGMAS or glue
  121. modules. For example,
  122.  
  123. LibTool -b -o MyBmap exec_lib.fd
  124.  
  125. will generate a BMAP file of Exec called "MyBmap" in the current directory.
  126.   The program checks for the following known collisions between library names
  127. and AmigaBasic keywords:
  128.  
  129. abs, Close, Exit, Input, Open, Output, Read, tan, Translate, Wait, Write
  130.  
  131. If found, it prepends an x to the function name (i.e. "xRead" instead of
  132. "Read"), and posts a msg to the CLI.
  133.   Since AmigaBasic labels cannot have underscores, any underscores in a
  134. library function name are replaced by a period. An error msg will appear if
  135. this is the case, indicating the change.
  136.   Since AmigaBasic also cannot support a function which needs an argument
  137. passed in a5, an error msg will appear if this is the case. There is no way
  138. to call such a function from AmigaBasic.
  139.   The BMAP file always includes any ##private functions in the fd file.
  140.   The -o option allows the bmap file to be saved under any name. Otherwise,
  141. the .fd will be stripped from the source fd filename and ".bmap" appended.
  142.   Note that AmigaBasic requires the name of a BMAP file to be the name of the
  143. shared library minus its ".library" extension.
  144.   Also note that a library written in C (where args are expected on the stack)
  145. cannot be used by AmigaBasic.
  146.  
  147.  
  148. ««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  149. 6). Calling a C shared library
  150.  
  151.   If you are developing a library whose functions are written in C, then your
  152. functions normally expect arguments on the stack. You have 2 choices for
  153. interfacing between a C application and such a library.
  154.  
  155.  1). Make reverse glue functions inside of your library that push args back
  156.      onto the stack and call the "real" C functions.
  157.  
  158.  2). Make glue routines for your application which do not pull args off of
  159.      the stack. (i.e. args are left on the stack and the lib function is
  160.      called).
  161.  
  162.   By specifying the -c option, LibTool will make pragmas or glue modules
  163. which implement the second method. Therefore, you can develop libraries
  164. written in C and not have to worry about passing args in registers at all.
  165. Your fd file will simply contain the names of the functions as they appear
  166. in the lib's function table. For example, assume we made a C library called
  167. "mylib.library" which has 2 functions in its function table:
  168.  
  169. void Func1();
  170. BYTE Func2();
  171.  
  172. Func2() expects 2 args.
  173.  
  174. An excerpt of your my_lib.fd file looks like this:
  175.  
  176. ##base MyBase  * this is the name of our lib base returned by OpenLibrary()
  177. ##bias 30
  178. ##public
  179. ##ret void
  180. Func1()
  181. ##ret BYTE
  182. Func2()
  183.  
  184. These would be C functions in your library which expect their arguments as
  185. usual (on the stack). 
  186.  
  187. You would create your c glue module as so:
  188.  
  189. LibTool -c -o mylib.asm my_lib.fd
  190.  
  191. Assemble the resulting file, mylib.asm and link this with your C application.
  192. Your C application would open the lib as so:
  193.  
  194.  MyBase = OpenLibrary("mylib.library",0L);
  195.  
  196. And you might call Func2() as so:
  197.  
  198.   returnval = Func2( arg1, arg2 );
  199.  
  200. Please note that the glue routines treat a6 as a scratch register.
  201.  
  202. The -h option makes a C INCLUDE file for an application which simplifies
  203. opening and closing the library as well as declaring the returns of the lib
  204. functions. See the CSimple.DOC file for an explanation of how to make a C
  205. library and use these features. A default filename is made from stripping the
  206. .fd extension from the source fd filename and appending ".h".
  207.  
  208.  
  209. «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  210. 7). Generating a library startup
  211.  
  212.  The -m option will generate an assembly module which when assembled and linked
  213. with any C or asm routines, will turn those routines into a shared library.
  214. You need to make an fd file describing the functions which you wish to make
  215. callable by any application. See the example library and instructions.
  216.   A default filename is made from stripping the .fd extension from the
  217. source fd filename and appending ".src".
  218.  
  219.  
  220. «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  221. 8). Making an Asm INCLUDE file
  222.  
  223.  The -a option will make an INCLUDE file for asm language applications which
  224. wish to use the library. This file will contain _LVO labels for all of the
  225. callable functions in the library. Also, it will make an equate for the
  226. version number. The name of this symbol will be the library name (minus
  227. .library extention) plus the string VERSION. For example, if you had the
  228. following fd file, test.fd
  229.  
  230. ##name test.library
  231. ##bias 30
  232. ##vers 2
  233. Func1()
  234. ##end
  235.  
  236. and invoked LibTool as so
  237.  
  238. LibTool -a test.fd
  239.  
  240. then a file called "test.i" would be produced and it would contain
  241.  
  242. _LVOFunc1   equ -30
  243. testVERSION equ  2
  244.  
  245. A default filename is made from stripping the .fd extension from the
  246. source fd filename and appending ".i".
  247.  
  248.  
  249. «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««
  250. Final Notes
  251.  
  252.   You can do multiple fd conversions with LibTool at one invocation. Simply
  253. place the options before each filename. For example:
  254.  
  255. LibTool -po myPragma exec_lib.fd  -b dos_lib.fd  -a exec_lib.fd
  256.  
  257. will make a PRAGMA file from the Exec fd file called "MyPragma", then it will
  258. make a bmap file for the DOS fd file called "dos_lib.bmap", and finally make
  259. an asm INCLUDE file from the Exec fd file called "exec_lib.i"
  260.  
  261.   There has been a bug fix to this version. A previous version allowed the
  262. library to be opened if you installed an Init() function which returned
  263. FALSE (0).
  264.