home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / m / makealf / Doc / text < prev   
Encoding:
Text File  |  1997-06-03  |  7.6 KB  |  174 lines
  1. [[ Note: This text-only version of the manual was produced by hand from
  2.    the Impression version. It is therefore likely that there are lots of
  3.    infelicities in the formatting; in particular, font changes have been
  4.    lost. If a sentence doesn’t seem to make any sense, see whether it’s
  5.    any better if you pretend some of the words in it are in italics. :-) ]]
  6.  
  7. User manual for makeALF
  8. =======================
  9.  
  10.  
  11. This is the user manual for makeALF, a program which creates a library file
  12. from a number of object files. It’s very short.
  13.  
  14.  
  15. Legal rubbish
  16. -------------
  17.  
  18. These programs (makeALF and the smaller utilities included with it) are not
  19. public domain; they are mine. The same applies to this documentation. You
  20. don’t have to pay for it, and you may distribute it freely. You may not, however,
  21. (1) distribute modified copies, or (2) make money from it in any way.
  22. You may, of course, modify your own copy. If you think your modifications are
  23. improvements, get in touch with me and tell me more...
  24.  
  25. About library files
  26. -------------------
  27.  
  28. A library file is a file containing several object files, together with
  29. information about what symbols are defined in what files (so that your linker
  30. can read the right bits of the file). The Shared C Library is not in this sense
  31. a library file, by the way. There is a special format for library files, called
  32. ALF for “Acorn Library Format”.
  33.  
  34. Why use library files? Because it saves effort when linking programs (or, if you
  35. use makefiles, when writing makefiles). Instead of linking with 500 different
  36. object files, you just use the name of your library and let the linker work out
  37. which bits it needs. This doesn’t result in the entire contents of the library
  38. being duplicated in your program; the effect is just as if you had linked with
  39. each of the individual object files needed.
  40.  
  41. If you want more information about library files (for instance, about the exact
  42. file format used), look in the PRMs. Or mail me.
  43.  
  44.  
  45. About makeALF
  46. -------------
  47.  
  48. This is a simple program which produces library files. You just give it a list
  49. of filenames, which should be names of object files (I am not answerable for
  50. the consequences if they are names of non-object files, but there’s no problem
  51. if one of the files doesn’t exist at all), and the name of the file it should
  52. create, and it does its nefarious work. The object filenames can be wildcarded,
  53. but if a filename begins with a hash then it will be ignored, for resaons that
  54. will be obvious when you've read the next section.
  55.  
  56. If there are a lot of object files needing to be put into a library, you can
  57. instead put a list of their names into a file, and tell makeALF the name of that
  58. file.
  59.  
  60. To be a bit more precise: the syntax is
  61.   makeALF [-q] [-s] [-m maxfiles] [-i inputfile] [object1 ...] [-o outputfile]
  62. and, as is usual with these things, you can put the bracketed elements in any
  63. order. The -q is used to suppress some friendly output from makeALF which you
  64. might not want cluttering up your screen, and the -s to warn makeALF that you
  65. might be using foo.o instead of o.foo .
  66.  
  67. You can also say just makeALF -v, which will tell you which version of makeALF
  68. you’re running. This version of the manual describes version 1.05.
  69.  
  70.  
  71. Input files
  72. -----------
  73.  
  74. If you give the -i inputfile option, the file should contain a list of object
  75. files, one per line. Actually you can have blank lines (meaning, lines
  76. containing only whitespace), which are ignored; and comment lines, meaning lines
  77. whose first non-whitespace character is a hash ‘#’. Also, if a line contains
  78. non-whitespace followed by whitespace, everything from that whitespace onwards
  79. is ignored; so you can have a comment on the same line as a filename. I advise
  80. you to begin such comments with a hash.
  81.  
  82. You can in fact give as many input files as you like; the effect is as if the
  83. filenames in each were spliced into the input line in place of the input file
  84. specification. (But you need a separate -i for each input file.)
  85.  
  86.  
  87. Other things
  88. ------------
  89.  
  90. Unless told not to with the -q option, makeALF will tell you what it’s doing
  91. as it goes along. Its operation is divided into three phases: first it reads
  92. some information about each input file, then it copies the actual data from
  93. the input files to the output file, and finally it builds the symbol table of
  94. the output file.
  95.  
  96. If you give the -s option, makeALF will transform any filename you give it
  97. ending in .o into one with o. just before the leafname; this can be useful
  98. if you’re porting programs from other systems.
  99.  
  100. There are a few arbitrary limitations.
  101.  
  102.   - Lines in input files (that’s input files containing lists of object
  103.     files, rather than the object files themselves) must be no more than
  104.     254 characters (I think it is) long. Since they can contain only one
  105.     object filename per line, this isn’t likely to be a big problem.
  106.   - And if the chunk file header of any of your object files is bigger than
  107.     4k (which will only happen if the file contains a really huge number of
  108.     areas; I’d be willing to place a large bet on its never happening
  109.     except through malice) you’ll need to change the function
  110.     process_symbol_table.
  111.  
  112. If you don’t give an output file name, output is to a file named alf.
  113.  
  114.  
  115. A few other useful utilities
  116. ----------------------------
  117.  
  118. Along with makeALF I’m enclosing four other utilities that are likely to prove
  119. helpful in working with library files (and, indeed, with object files). I make
  120. no guarantees of their robustness.
  121.  
  122. Two of them are specifically for library files. ALFdir displays the contents of
  123. a library file’s directory; each line contains the chunk number of one of its
  124. component files, its filename, and its datestamp. (It’s possible that you may
  125. have an “old-style” library, as created by Acorn’s Fortran-77 compiler and just
  126. about nothing else; for these the datestamps will be garbage.) ALFsymt displays
  127. a library’s symbol table; each line contains a symbol name (second column) and
  128. the chunk number of the component file which defines that symbol (first column).
  129.  
  130. A library file is a special kind of chunk file. The other two little programs
  131. are for dealing with chunk files generally. ChunkList lists all the chunks in
  132. a chunk file, with their chunk identifiers, positions and sizes. (For a library
  133. file, most of the chunks will be called LIB_DATA.) More usefully, ChunkRead
  134. will extract a single chunk from a chunk file. This is useful if, for instance,
  135. you want to do something with a single object file from a library. It takes 3
  136. arguments: the name of the chunk file, the chunk number and the name of the
  137. file its output should go to.
  138.  
  139.  
  140. About me
  141. --------
  142.  
  143. You might want to get in touch with me, maybe to let me know of improvements
  144. you’ve made or to tell me what a pile of rubbish this software is. Or maybe to
  145. send me huge sums of money in gratitude for makeALF. Hmmm.
  146.  
  147. Anyway, here are an e-mail and a snail-mail address for me. Both are valid as of
  148. December 1996, and both are likely to remain valid for quite some time.
  149.  
  150. e-mail: gjm11@dpmms.cam.ac.uk
  151.  
  152. snail-mail:    Gareth McCaughan
  153.         Peterhouse
  154.         Cambridge CB2 1RD
  155.         England
  156.  
  157.  
  158. Another program you might want
  159. ------------------------------
  160.  
  161. I have a slightly flaky program which reads object files and displays their
  162. contents, disassembling as it goes, dealing with relocations and so on. I find
  163. it invaluable. If you want a copy, let me know. (It’s free too.)
  164.  
  165.  
  166. Acknowledgements
  167. ----------------
  168.  
  169. The change from version 1.02 to version 1.03 (which introduced wildcards and
  170. made the program somewhat faster) was provoked by Nick Burrett, who sent me
  171. some suggested changes. I haven’t actually used any of his code (not because
  172. there’s anything wrong with it, but because I have a neurotic preference for
  173. writing my own!) but the ideas are his. Any bugs are, of course, mine.
  174.