home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 215.lha / GlueMaker_v1.0 / gluemaker.doc < prev    next >
Text File  |  1996-02-15  |  8KB  |  199 lines
  1. ***************************************************************************
  2. *                                                                         *
  3. *                              GlueMaker                                  *
  4. *                                                                         *
  5. *                               By Talin                                  *
  6. *                                                                         *
  7. *                              Version 1.0                                *
  8. *                (With some ideas/help from Joe Pearce)                   *
  9. *                                                                         *
  10. ***************************************************************************
  11.  
  12. GlueMaker is Copyright (c) 1989 by David Joiner, a.k.a. Talin.
  13.  
  14. GlueMaker is a utility that greatly simplifies the process of building
  15. shared libraries on the Amiga. It generates, automatically, a link library
  16. of all the 'glue routines' that are needed to access an exec library.
  17. It's input is a '.fd' file.
  18.  
  19. Distribution information:
  20.  
  21.     This is the latest in a series of "Talin's Tools", basically various
  22. utilities I've developed for my own personal use that I'm releasing for
  23. general distribution.
  24.     You can put this on any kind of disk or BBS that you want, as long as
  25. you give proper credit.
  26.     I'm trying to develop the concept of 'Trade-Ware', since I don't have
  27. the time or expertise to run a business. So don't send me money, send me
  28. fun software to play with. If you're a developer, send me something you're
  29. working on. If you are a collector, send me some nice PD thingies that
  30. you think are neat. (Whatever you do, be ethical and legal).
  31.     Of course, you don't have to send me anything at all if you don't want
  32. to. I get lots and lots of money from things like Faery Tale and such, so
  33. it's not like I need it. But it does make me feel good (One fellow sent me
  34. a copy of JET, still in the shrink wrapped box, because my Sectorama utility
  35. saved his hard disk...).
  36.  
  37.     My Address is:
  38.         David Joiner
  39.         17428 Chatsworth St.
  40.         Granada Hills, CA 91344
  41.  
  42.     Or, you can contact me through MicroIllusions at (818) 360-7124, or
  43.         1-800-522-2041.
  44.  
  45. GlueMaker instructions:
  46.  
  47.                                WARNING
  48.  
  49. Gluemaker produces a file called 'makefile' as one of it's output files.
  50. MAKE SURE YOU DON'T ACCIDENTALLY OVER-WRITE ONE OF YOUR VALUABLE MAKEFILES!!!
  51. I strongly sugggest putting all files related to a particular GlueMaker
  52. library in a directory by themselves. For example, my 'musicx.library'
  53. glue files are all in the file 'mx.glue'.
  54.  
  55. GlueMaker takes a '.fd' file, such as 'exec_lib.fd' and make all the
  56. requsite files for createing 'glue' subroutines. The files created will be:
  57.  
  58. 1. Assembly Files.
  59.     GlueMaker will create an assembly ('.asm') file for each entry point
  60.     in the library. The reason for a seperate file for each subroutine is so
  61.     that when the library is created, each object module will be independant.
  62.  
  63.     Currently, the conventions for register usage are as follows: (same as
  64.     Aztec C):
  65.         -- d0-d4 and a0-a1 are scratch - glue routines may modify them.
  66.         -- a6 is used as the library base pointer and is changed.
  67.         -- all other registers are preserved.
  68.         If the 'PROTECT' option is used in the input file, then d2 and d3 are
  69.             also preserved, thus following the ROM Kernal register conventions.
  70.  
  71.     Each file has a name of the form '<routine name>.asm'
  72.  
  73. 2. A Makefile.
  74.     Currently, the makefile created is in Aztec format, however it is
  75.     trivial to convert to other formats with a text editor.
  76.  
  77. 3. A Vector Offset file.
  78.     This is a file which defines the Library Vector Offsets (LVO's) for each
  79.     entry point in the library. It first defines a macro, LIBVEC, (which
  80.     is identical to the 'LIBDEF' macro in exec/libraries.h), and then
  81.     includes the Vector Header file, which has a bunch of LIBVECs. The
  82.     result, when 'make' is run, is an object module which has all the
  83.     Library Vector Offsets declared as external symbols.
  84.     The reason I didn't use the action LIBDEF macro (though I do use LIBINIT)
  85.     is that LIBVEC will be defined as a different macro when we actually
  86.     build the library.
  87.  
  88.     This file has a name of the form '<libname>_lvo.asm'.
  89.  
  90. 3. A Vector Header File.
  91.     This is a file of macros used in constructing the library. It consists
  92.     of one line of text for each library entry, of the form:
  93.  
  94.         LIBVEC    <functionname>
  95.  
  96.     I normally use this in two places:
  97.         First, I use it in generating the shared library to create the
  98.     vector table. I define the macro 'LIBVEC' as equivalent to 'dc.l',
  99.     which allows MakeLibrary to build a library from it.
  100.         Second, I use it when generating the link library, to create the
  101.     Library Vector Offsets (_LVO's). This is use in conjunction with the
  102.     Vector Offset File.
  103.  
  104.     This file has a name of the form '<libname>_lvo.i'.
  105.  
  106. To run GlueMaker, type:
  107.  
  108.     GlueMaker [input file]
  109.  
  110. where 'input file' is of the following format:
  111.  
  112.     FDFILE=<path name of fd file>
  113.     LIBFILE=<name of resulting link library file>
  114.     OUTDIR=<directory to write all output files to>
  115.     PROTECT
  116.  
  117.     FDFILE=
  118.         indicates the path name of the .fd file to read (not including
  119.         the '.fd'), such as "ram:exec_lib".
  120.  
  121.     OUTDIR=
  122.         indicates the output directory for all the files that will be produced.
  123.  
  124.     LIBFILE=
  125.         indicates the file name of the link library to be produced. Do not
  126.         include an extension.
  127.  
  128.     PROTECT
  129.         this is an option which causes GlueMaker to preserve registers d2/d3
  130.         in all the glue routines.
  131.  
  132.     for example:
  133.  
  134.     FDFILE=df1:fdfiles/exec_lib
  135.     OUTDIR=ram:
  136.     LIBFILE=exec
  137.  
  138.     See the example .fd file included in the arc file. Note that the
  139. 'exec_lib.fd' is not included, since it's copyrighted, but since it can
  140. be found on the Workbench 'Extras' disk, you can experiment with the
  141. examples.
  142.  
  143. In the above case, the follwing files will be produced:
  144.  
  145.     ram:exec_lvo.i
  146.     ram:exec_lvo.asm
  147.     ram:makefile
  148.  
  149.     plus a file for each routine, of the form 'ram:xxx.asm' where xxx is the
  150.     name of an exec entry point.
  151.  
  152. After GlueMaker has been run, then you need to run 'make'.
  153. This will assemble all of the file and create a linkable library of
  154. all the object files. In the above example, the files produced would be:
  155.  
  156.     ram:exec_lvo.o
  157.     ram:exec.lib
  158.  
  159.     plus a '.o' file for each '.asm' file.
  160.  
  161. Also, I've made some extensions to the .fd syntax, plus there are some
  162. planned extensions that I plan to do in the future, but haven't gotten around
  163. to yet. Most of them are pretty trivial.
  164.  
  165. Also note that currently, GlueMaker only supports 32-bit arguments on the
  166. stack - i.e. each argument is assumed to take a long word on the stack, just
  167. like the Amiga ROM Kernal routines.
  168.  
  169.     '&' before a register means use effective address rather than register
  170.         for use in things like RawDoFmt that need the address of the stack.
  171.  
  172.     ##jump        means instead of generating a return, generate a bra to
  173.                 the given label. Useful for routines that require a common
  174.                 cleanup routine, or for libs that pass resultsin registers
  175.                 other than d0.
  176.  
  177. Planned extensions to .fd format:
  178.  
  179.         .l, .w, or .b before a register means that size argument on stack.
  180.  
  181.         ##pre.insert
  182.                     insert this code before the jsr/jmp
  183.         ##post.insert
  184.                     insert this code after the jsr
  185.         ##*
  186.                     end of insertion
  187.         ##savealso
  188.                     save this reg in addition to the normal ones.
  189.  
  190. Planned enhancements to GlueMaker (not likely soon, though...!)
  191.  
  192.     1. Lattice C supports direct calling of shared libraries through
  193. #pragma directives, and I know that Jim Goodnow wants to add a similar
  194. capability to Aztec C. It would be nice to generate these files.
  195.     2. Specify Glue arguments directly on the command line.
  196.     3. Support for Lattice C and other compilers.
  197.     4. Support for other 'make' utilities.
  198.  
  199.