home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Programming / vbcc_MorphOS / machines / amiga / doc / fd2lib.doc next >
Text File  |  2000-08-20  |  6KB  |  159 lines
  1. fd2lib by Volker Barthelmann / Johnny Tevessen
  2.  
  3.  
  4. INTRODUCTION
  5.  
  6.     fd2lib takes .fd-files as input and generates assembler source to
  7.     create a library with stubs to call the functions (including stubs
  8.     for varargs functions).
  9.  
  10.     It will create stubs suitable for vbcc, i.e. restore all necessary
  11.     registers (including a6) etc.
  12.  
  13.  
  14. LEGAL
  15.  
  16.     fd2lib is public domain.
  17.  
  18.  
  19. USAGE
  20.  
  21.     Usage : fd2lib [-sc] [-sd] [-40] [-on] [-nv] [-o <dir>] [-of <format>]
  22.                    [-d] [-?|--help] [files/pattern]
  23.  
  24.       -sc : Use small code model (else large code model)
  25.       -sd : Use small data model (else large data model)
  26.       -40 : Use fast call model for 68040's (no `movem's)
  27.       -on : Use old motorola assembler notation
  28.       -nv : No varargs logic - ...A and ...TagList will not be detected
  29.       -o  : Specify directory to store source files in
  30.       -of : C printf style output format to generate compiling
  31.             script. Three `%s' are replaced with output file name
  32.       -d  : Turn on debugging/verbose mode
  33.       -?  : Show help/version and quit
  34.     files : FD files to convert, defaults to stdin
  35.  
  36.     Commandline is parsed left-to-right. So specifying
  37.  
  38.     > fd2lib alib_lib.fd -sd blib_lib.fd
  39.  
  40.     will result in alib created using large data model.
  41.  
  42.     There will also be a -prof option in future, but it's not yet
  43.     implemented.
  44.  
  45.     fd2lib will process all the .fd-files specified at the command line
  46.     (not specifying any filename results in fd2lib using stdin (console)
  47.     as input) and will generate an assembler source for each library
  48.     function as functionname.s and a file containing all the library
  49.     vector offsets as libname_lvo.s.
  50.  
  51.     Files are placed in the current directory. Specify an alternative
  52.     destination using the `-o <dir>' option.
  53.  
  54.  
  55. GENERATED CODE
  56.  
  57.     In default mode fd2lib will output Opcodes in so-called "new Motorola"
  58.     style. This means `(_libBase,A4)' rather than `_libBase(A4)'. So don't
  59.     get confused when you examine fd2lib's output. 8-)
  60.  
  61.     Switch to old-style output with the `-on' switch.
  62.  
  63.     fd2lib versions newer than 1.0 no longer trash the baserel pointer
  64.     in small data mode if some function uses A4. Anyway, now it's safe to
  65.     use all registers - excluding A6 of course.
  66.  
  67.     movem's: fd2lib uses `move.l's if only less than three registers have
  68.     to be saved. If you are a lucky owner of an 68040 processor, you should
  69.     use the `-40' switch. It will make fd2lib output `move.l's for any
  70.     number of registers pushed and popped and is faster on the 68040.
  71.  
  72.  
  73. VARARGS
  74.  
  75.     Some functions take a pointer to a list of arguments as the last
  76.     argument. fd2lib has a hardcoded list of such function and creates
  77.     additional stubs that can be called with a variable number of arguments
  78.     from C (e.g. OpenWindowTagList and OpenWindowTags).
  79.  
  80.     If you want to extend this list, you have to add the name of the
  81.     function and the name of the varargs function to the file vargs.h
  82.     and recompile fd2lib.
  83.  
  84.     Since version 1.2 fd2lib also tries to recognize functions that might
  85.     have varargs automatically. It scans for `TagList' and `A' postfixes
  86.     and substitutes them with `Tags' or `'. `A's are only suggested to be
  87.     varargs if the letter right before is lowercase.
  88.  
  89.     You may turn off automatic recognition by specifying `-nv'.
  90.  
  91.  
  92. GOODIES
  93.  
  94.     `-of <string>' allows you to get runtime output. You may use this
  95.     feature to show fd2lib's progress or to create batch files for post-
  96.     processing fd2lib's output. `%s' is substituted by the output asm file
  97.     just processed. E.g.:
  98.  
  99.     > fd2lib -of "phxass %s opt ! noexe" fd:dos_lib.fd >batchfile
  100.     > execute batchfile
  101.  
  102.     will process dos' functions and then compile them straight-forward.
  103.  
  104.     You may use `%s' upto three times in the format string. C like jokes
  105.     like `%30s' to show the file's name right-aligned are also allowed.
  106.  
  107.  
  108. CREATING LIBRARIES
  109.  
  110.     If you want to create a library from some .fd-files proceed like this:
  111.  
  112.     > delete T:#?.(s|o) quiet
  113.     > fd2lib -o T: <all the .fd-files you want>
  114.  
  115.     (copying PhxAss to ram: now may speed up the process)
  116.  
  117.     > vc -c T:#?.s
  118.     > join T:#?.o as <name of resulting lib>
  119.     > delete T:#?.(s|o)
  120.  
  121.  
  122. MakeALIB.script
  123.  
  124.     This is a small but smart script which will create an amiga.lib or
  125.     amigas.lib in T:. It will delete files from T: before and assumes
  126.     nothing is written to T: while it is running.
  127.  
  128.     You have to assign FD: to a directory that contains the .fd-files for
  129.     the Amiga shared libraries and cd into the libsrc/AmigaLib directory
  130.     and start it from there. Otherwise you will get an error.
  131.  
  132.     Without further parameters you will get a large data model amiga.lib.
  133.     To create small data model amigas.lib start the script with option
  134.     "-sd".
  135.  
  136.     It will then create all library stubs and LVOs with fd2lib (this will
  137.     result in many many small files in T: which will be assembled by
  138.     PhxAss - so having PhxAss in RAM: will speed it up quite a lot).
  139.  
  140.     Then the support routines in libsrc/AmigaLib will be compiled/assembled
  141.     and the resulting object files will be put in T:, too. You must have
  142.     the C= includes.
  143.  
  144.     The support routines are taken from libnix and have been changed a bit
  145.     to work with vbcc. I have not tested them and several support routines
  146.     from the original amiga.lib are missing.
  147.  
  148.     The whole process may take quite some time and a few MB space in T:
  149.     The resulting amiga.lib should be free from any copyright and is a
  150.     rather good (but not complete) replacement for the original amiga.lib.
  151.  
  152.     If everything went right you will be asked whether you want to have the
  153.     library installed to vlib:. Type <y> or do so manually if you don't
  154.     trust my script. :-)
  155.  
  156.  
  157. Volker Barthelmann                                      volker@vb.franken.de
  158. Johnny Tevessen                                          j.tevessen@line.org
  159.