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