home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Fred Fish Collection 1.5
/
ffcollection-1-5-1992-11.iso
/
ff_disks
/
200-299
/
ff227.lzh
/
MidiLib
/
docs
/
bind.doc
< prev
next >
Wrap
Text File
|
1989-06-25
|
8KB
|
258 lines
Bind - Binding routine builder
Overview
--------
This program takes a standard .fd (function definition) file and
generates a binding library for the functions defined in the .fd file.
The bindings are generated based on a set of rules for a target compiler
defined in a file called "bindfile". These rules specifiy which
registers need to be preserved, how the arguments are passed on the
stack, and the syntax to call an assembler and a librarian.
Arc File Contents
-----------------
Bind -- the AutoDoc program
bind.doc -- this file
bindfile -- a sample bindfile containing rules for Aztec (small
code/data and large code/data version) and Lattice.
midi_lib.fd -- the .FD file for the MIDI Library. It's included here
as a sample non-Rom-Kernal library that use to try
bind on.
zlib -- simple Amiga object module librarian
zlib.c -- source code to zlib
Usage
-----
The syntax for Bind is:
Bind [opts] <.fd file>
<.fd file> - name of the function definition file to use as a
source. The ".fd" portion may be left off of the name.
The output library name is derived from the portion of
the .fd file to the left of the period (e.g.
midi_lib.fd will generate midi_lib.lib)
opts:
-a generate assembly only
-c generate object modules only
-f<s> specify alternate bindfile
-o<s> specify output library name
-r<s> specify rule name
-w<s> specify work directory
A library is built by first generating an object module for each binding
routine and an LVO definition module. Each module is created by writing
an assembly file to the work directory and then assembling it. Once all
the object modules are generated they are collected into a library.
Temporary files (assembly and object) are deleted from the work
directory as soon as they are no longer needed. The actual invocations
for the assembler and librarian depend on the selected set of rules.
Binding rules are defined in a "bindfile". By default this file is
called bindfile and resides in the current directory or the s:
directory. An alternate bindfile may be specified with the -f switch.
A bindfile contains entries for target compilers. Each entry contains
rule definitions that specify how to build a binding routine for the
target compiler. The syntax is as follows:
<target>:
<rule key> = <value>
.
.
.
<rule key> = <value>
<target>:
<rule key> = <value>
.
.
.
<rule key> = <value>
.
.
.
The target name can contain any name but must not contain embedded
spaces. It should begin in the first column and be terminated with a
colon. Target name matching is case insensitive.
Rule keys must be preceded with white space and spelled exactly as
follows (case is not significant). They may be placed in any order
within a rule set.
StackOffset = <offset>
Specifies how many bytes preceded arguments in the stack frame
when the routine first becomes active. If nothing is pushed on
the stack between the arguments and the return location (pushed
by jsr) then <offset> would be 4. This depends very heavily on
how the target compiler calls routines. The default value is 0.
SaveRegs = <register set>
This specifies the registers that the compiler expects to have
preserved. Use a standard 68000 MOVEM register set here (e.g.
d2-d7/a2-a5). The default is to preserve no registers.
Currently you are not allowed to preserve D0 or A7 this way. D0
is where return values from placed by standard Kernal routines.
A7 is the stack and is automatically preserved.
Assembler = <asm syntax>
Specifies the name of the assembler to use and its syntax. Two
string substitutions are performed here.
$a - gets replaced by the name of the assembly file
generated by bind.
$o - gets replaced by the name of the object module that
should be produced by the assembler.
(e.g. as $a -o $o) Bind generates assembly files suffixed with
.asm and expects object files to suffixed by .o. These suffixes
are supplied with the $a and $o string substitutions.
The assembler used should be capable of generating a
non-zero return code on failure in order to shut down bind.
Both Aztec's as and MCC's assem behave well.
The assembler is loaded using fexecl() so that the current path
will be searched in order to find the assembler.
The default is no assembler. This will not permit you to make
anything other than assembly files.
Librarian = <lb syntax>
Specifies the name of the librarian to use and its syntax. Two
string substitutions are performed here.
$l - is replaced by the selected name of the output library.
$o - is replaced by the entire list of object modules to
place in the library.
(e.g. lb $l $o) By default bind will generate a library name
based on the .fd file name (e.g. midi_lib.fd becomes
midi_lib.lib). You can select another output library name using
the -o option. .lib is not automatically attached to the name;
you need to specify it.
As with the assembler, the librarian should be capable of
generating a non-zero return code on failure in order. Aztec's
lb utility and zlib both work this way.
The default is no librarian. This will prevent you from
going beyond the object module stage.
Comments may be placed in the bindfile if they are preceeded with a
pound sign (#) in the first column (like makefile comments). Also,
blank lines are considered comments.
There is a sample bindfile contained in the .arc file.
Work files
----------
Work files are placed in the "work directory". The work directory is
determined in one of two ways. If none is specified, the directory
associated with the environment variable CCTEMP is used (this is set by
either the Aztec or the ARP set command). You may override this by
using the -w switch to specify any directory. The default is the
current directory.
Work files are automatically deleted when they are no longer needed or
when the program fails or is aborted using Control-C.
The options
-----------
-a causes bind to stop after generating the assembly code for the
bindings. They appear in the work directory.
-c causes bind to assemble the modules that it generates but leave just
the object modules without making a library.
-f allows you to specify some other file to use as a bindfile. The
default bindfile may exist in the current directory or in the s:
directory.
-o allows you to specify another name for the output library. The
default is made by replacing .fd in the source file name with .lib. A
file comment is set for the output library indicating which rules were
used to create it.
-r specifies a rule name. The default is to use the first rule in the
bind file.
-w specifies an alternate work directory.
Tech info
---------
The program was compiled using Aztec C3.4B. Everything described works.
At the very least this can be used to generate bindings for Aztec (any
model) and Lattice.
Compilers that don't use A7 for a stack, don't return values in D0, pack
the arguments in reverse order, or require that the bindings pop
arguments off the stack are not currently supported by Bind. This may
change if there is demand for this and the appropriate technical data is
available.
.fd files are not described in this document.
zlib
----
This is a quick and dirty means of generating a Lattice (Amiga) object
module library. These appear to be little more than a concatenation of
the constituent object modules. So this program simply joins all of the
files specified into one file. Its syntax is:
zlib <out> <source>...
The source code is included.
(btw AmigaDOS (or ARP) join command doesn't work since it is limited to
only 10 (I think) files)
Last words
----------
There were several inspirations for this program. I was requested to
make an .fd file for the MIDI Library and also someone told me that the
Aztec bindings for the MIDI Library failed with Lattice (mainly because
Lattice expects A6 to be preserved and Aztec doesn't). Also, I got
tired of waiting for C bindings for C. Heath's ARP library and hopefully
this will speed things along.
Bind is copyright 1987 by Pregnant Badger Software, but feel free to
distribute it without profit.
Bill Barton
Bix: peabody
delphi: bbarton
plink: peabody