home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 274.lha / Bind_v1.1 / bind.doc < prev    next >
Encoding:
Text File  |  1989-07-26  |  9.5 KB  |  291 lines
  1. Bind - Binding (glue) library builder
  2.  
  3. Version 1.1 - 9-Jul-89
  4.  
  5.  
  6. Overview
  7. --------
  8.  
  9. This program takes a standard .fd (function definition) file and
  10. generates a binding library for the functions defined in the .fd file.
  11. The bindings are generated based on a set of rules for a target compiler
  12. defined in a file called "bindfile".  These rules specifiy which
  13. registers need to be preserved, how the arguments are passed on the
  14. stack, and the syntax to call an assembler and a librarian.
  15.  
  16. Unlike similar programs, Bind actually generates a linkable library instead
  17. of just a bunch of assembly files and a makefile.  It does this by running
  18. an assembler and librarian specified for a given set of rules in the
  19. bindfile.
  20.  
  21.  
  22. Requirements
  23. ------------
  24.  
  25. Bind requires arp.library v39+ (release 3) to function.
  26.  
  27.  
  28. New stuff
  29. ---------
  30.  
  31. Version 1.1 - 9-Jul-89
  32.  
  33.     This version of Bind was more or less made necessary because v1.0
  34.     choked on the iffparse_lib.fd function arguments.  Bind now correctly
  35.     deals with register argument lists and is much more bullet-proof than
  36.     it previously was.
  37.  
  38.     The zlib program has been removed for this version since the ARP Join
  39.     command can be used instead.  Since Bind requires ARP, you should have
  40.     already have the ARP Join command.
  41.  
  42.  
  43. Arc File Contents
  44. -----------------
  45.  
  46.     Bind    -- The Bind program
  47.  
  48.     Bind.doc    -- This file
  49.  
  50.     bindfile    -- A sample bindfile containing rules for Aztec C (small
  51.            code/data and large code/data version) and Lattice C.
  52.            The Lattice C rules should work for any language that
  53.            uses the amiga.lib supplied by C=.
  54.  
  55.     misc_res.fd -- An .FD file for the Amiga's misc.resource.  According
  56.            to the the RKM manuals, this resource is supposed to be
  57.            called only from assembly.  I can see no good reason for
  58.            this other than that no one ever made any glue routines
  59.            for it.  Now you can make your own using Bind.
  60.  
  61.  
  62. Usage
  63. -----
  64.  
  65. The syntax for Bind is:
  66.  
  67.     Bind [opts] <.fd file>
  68.  
  69.     <.fd file> - name of the function definition file to use as a
  70.          source.  The ".fd" portion may be left off of the name.
  71.          The output library name is derived from the portion of
  72.          the .fd file to the left of the period (e.g.
  73.          midi_lib.fd will generate midi_lib.lib)
  74.  
  75.     opts:
  76.     -a    generate assembly only
  77.     -c    generate object modules only
  78.     -f<s>    specify alternate bindfile
  79.     -o<s>    specify output library name
  80.     -r<s>    specify rule name
  81.     -w<s>    specify work directory (default=CCTEMP env. variable)
  82.  
  83.  
  84.  
  85. A library is built by first generating an object module for each binding
  86. routine and an LVO definition module.  Each module is created by writing
  87. an assembly file to the work directory and then assembling it.    Once all
  88. the object modules are generated they are collected into a library.
  89. Temporary files (assembly and object) are deleted from the work
  90. directory as soon as they are no longer needed.  The actual invocations
  91. for the assembler and librarian depend on the selected set of rules.
  92.  
  93. Binding rules are defined in a "bindfile".  By default this file is
  94. called bindfile and resides in the current directory or the s:
  95. directory.  An alternate bindfile may be specified with the -f switch.
  96. A bindfile contains entries for target compilers.  Each entry contains
  97. rule definitions that specify how to build a binding routine for the
  98. target compiler.  The syntax is as follows:
  99.  
  100. <target>:
  101.     <rule key> = <value>
  102.     .
  103.     .
  104.     .
  105.     <rule key> = <value>
  106.  
  107. <target>:
  108.     <rule key> = <value>
  109.     .
  110.     .
  111.     .
  112.     <rule key> = <value>
  113.  
  114.     .
  115.     .
  116.     .
  117.  
  118.  
  119. The target name can contain any name but must not contain embedded
  120. spaces.  It should begin in the first column and be terminated with a
  121. colon.    Target name matching is case insensitive.
  122.  
  123. Rule keys must be preceded with white space and spelled exactly as
  124. follows (case is not significant).  They may be placed in any order
  125. within a rule set.
  126.  
  127.     Comment = <comment>
  128.  
  129.     An optional comment string to be placed in assembly files (only
  130.     visible if the -a switch is used) and the file comment for the
  131.     output library (visible with the List command).  The default is the
  132.     rule name.
  133.  
  134.  
  135.     StackOffset = <offset>
  136.  
  137.     Specifies how many bytes preceded arguments in the stack frame when
  138.     the routine first becomes active.  If nothing is pushed on the
  139.     stack between the arguments and the return location (pushed by jsr)
  140.     then <offset> would be 4.  This depends very heavily on how the
  141.     target compiler calls routines.  The default value is 4.
  142.  
  143.  
  144.     SaveRegs = <register set>
  145.  
  146.     This specifies the registers that the compiler expects to have
  147.     preserved.  Use a standard 68000 MOVEM register set here (e.g.
  148.     d2-d7/a2-a5).  The default is to preserve d2-d7/a2-a6.    Currently
  149.     you are not allowed to preserve D0 or A7 this way.  D0 is where
  150.     return values from placed by standard Kernal routines.    A7 is the
  151.     stack pointer and is automatically preserved.
  152.  
  153.  
  154.     Assembler = <asm syntax>
  155.  
  156.     Specifies the name of the assembler to use and its syntax.  Two
  157.     string substitutions are performed here.
  158.  
  159.         $A - gets replaced by the name of the assembly file
  160.          generated by Bind.
  161.  
  162.         $O - gets replaced by the name of the object module that
  163.          should be produced by the assembler.
  164.  
  165.     (e.g. as $A -o $O)  Bind generates assembly files suffixed with
  166.     .asm and expects object files to suffixed by .o.  These suffixes
  167.     are supplied with the $a and $o string substitutions.
  168.  
  169.     The assembler used should be capable of generating a
  170.     non-zero return code on failure in order to shut down Bind.
  171.     Both Aztec's as and MCC's assem behave well.
  172.  
  173.     The assembler is loaded using the ARP SyncRun() function so that
  174.     the current path will be searched in order to find the assembler.
  175.  
  176.     The default is no assembler.  This will not permit you to make
  177.     anything other than assembly files.
  178.  
  179.  
  180.     Librarian = <lb syntax>
  181.  
  182.     Specifies the name of the librarian to use and its syntax.  Two
  183.     string substitutions are performed here.
  184.  
  185.         $L - is replaced by the selected name of the output library.
  186.  
  187.         $O - is replaced by the entire list of object modules to
  188.          place in the library.
  189.  
  190.     (e.g. lb $L $O)  By default Bind will generate a library name based
  191.     on the .fd file name (e.g. midi_lib.fd becomes midi_lib.lib).  You
  192.     can select another output library name using the -o option.
  193.  
  194.     As with the assembler, the librarian should be capable of
  195.     generating a non-zero return code on failure in order.    Aztec's lb
  196.     utility, and the ARP Join command all behave this way.
  197.  
  198.     To generate an Amiga object module library (ALink/BLink
  199.     compatible), use the ARP Join command as the Librarian:
  200.  
  201.         Librarian = join $O as $L
  202.  
  203.     Amiga object module libraries appear to be simply a concatenation
  204.     of the constituent object modules so Join can be used to make one
  205.     out of object files.  NOTE: The AmigaDOS Join command can't be used
  206.     for this since it is limited to joining no more than 15 files.
  207.  
  208.     The default is no librarian.  This will prevent you from
  209.     going beyond the object module stage.
  210.  
  211.  
  212. Comments may be placed in the bindfile if they are preceeded with a
  213. pound sign (#) in the first column (like makefile comments).  Also,
  214. blank lines are considered comments.
  215.  
  216. There is a sample bindfile contained in the .arc file containing rules for
  217. Aztec C and Lattice C.    The Lattice C rules may be applicable to other
  218. languages as well since they conform to the Amiga register preservation
  219. rules.
  220.  
  221.  
  222. Work files
  223. ----------
  224.  
  225. Work files are placed in the "work directory".  The work directory is
  226. determined in one of two ways.    If none is specified, the directory
  227. associated with the environment variable CCTEMP is used (this is set by
  228. either the Manx or ARP Set command or the C= or ARP SetEnv command).  You
  229. may override this by using the -w switch to specify any directory.  The
  230. default is the current directory.
  231.  
  232. Work files are automatically deleted when they are no longer needed or
  233. when the program fails or is aborted using Control-C.
  234.  
  235.  
  236. The options
  237. -----------
  238.  
  239. -a  Causes Bind to stop after generating the assembly code for the
  240.     bindings.  They appear in the work directory.
  241.  
  242. -c  Causes Bind to assemble the modules that it generates but leave just
  243.     the object modules without making a library.
  244.  
  245. -f  Allows you to specify some other file to use as a bindfile.  The
  246.     default bindfile may exist in the current directory or in the s:
  247.     directory.
  248.  
  249. -o  Allows you to specify another name for the output library.    The default
  250.     is made by replacing .fd in the source file name with .lib.  The
  251.     library name you specify here will be suffixed with .lib unless you
  252.     specify some other suffix.
  253.  
  254.     A file comment is set for the output library indicating which rules
  255.     were used to create it.  The Comment bindfile rule is used for the file
  256.     comment if present, otherwise the rule name is used.
  257.  
  258. -r  Specifies a rule name.  The default is to use the first rule in the
  259.     bindfile.
  260.  
  261. -w  Specifies an alternate work directory.  The default is the value of the
  262.     CCTEMP environment variable (set by Set or SetEnv).
  263.  
  264.  
  265. Tech info
  266. ---------
  267.  
  268. The program was compiled using Aztec C3.6a.  Everything described works. At
  269. the very least this can be used to generate bindings for Aztec C (any
  270. model) and Lattice C.
  271.  
  272. Compilers that don't use A7 for a stack, don't return values in D0, pack
  273. the arguments in reverse order, or require that the bindings pop arguments
  274. off the stack are not currently supported by Bind.  This may change if
  275. there is demand for this and the appropriate technical data is available.
  276.  
  277. .fd files are not described in this document.
  278.  
  279.  
  280. Last words
  281. ----------
  282.  
  283. Bind is copyright (c) 1987-89 by Pregnant Badger Software, but feel free to
  284. distribute it for non-profit.
  285.  
  286.     Bill Barton
  287.  
  288.     Bix: peabody
  289.     plink: peabody
  290.  
  291.