home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsm / makealf / Doc / Text < prev   
Text File  |  1995-03-31  |  7KB  |  159 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.
  53.  
  54. If there are a lot of object files needing to be put into a library, you can
  55. instead put a list of their names into a file, and tell makeALF the name of that
  56. file.
  57.  
  58. To be a bit more precise: the syntax is
  59.   makeALF [-q] [-i inputfile] [object1 ...] [-o outputfile]
  60. and, as is usual with these things, you can put the bracketed elements in any
  61. order. The -q is used to suppress some friendly output from makeALF which you
  62. might not want cluttering up your screen.
  63.  
  64. You can also say just makeALF -v, which will tell you which version of makeALF
  65. you’re running. This version of the manual describes version 1.02.
  66.  
  67.  
  68. Input files
  69. -----------
  70.  
  71. If you give the -i inputfile option, the file should contain a list of object
  72. files, one per line. Actually you can have blank lines (meaning, lines
  73. containing only whitespace), which are ignored; and comment lines, meaning lines
  74. whose first non-whitespace character is a hash ‘#’. Also, if a line contains
  75. non-whitespace followed by whitespace, everything from that whitespace onwards
  76. is ignored; so you can have a comment on the same line as a filename. I advise
  77. you to begin such comments with a hash.
  78.  
  79. You can in fact give as many input files as you like; the effect is as if the
  80. filenames in each were spliced into the input line in place of the input file
  81. specification. (But you need a separate -i for each input file.)
  82.  
  83.  
  84. Other things
  85. ------------
  86.  
  87. Unless told not to with the -q option, makeALF will tell you what it’s doing as
  88. it goes along. The slowest part of the process is the first, namely finding the
  89. sizes and datestamps of the object files. You are told the name of each input
  90. file as makeALF begins to deal with it. The other two stages that take any time
  91. are the copying of the object files into the output file, and the building of
  92. the symbol table. For each of these, a dot is printed when each file has been
  93. completely dealt with.
  94.  
  95. There are a few arbitrary limitations. Lines in input files (that’s input files
  96. containing lists of object files, rather than the object files themselves) must
  97. be no more than 254 characters (I think it is) long. Since they can contain
  98. only one object filename per line, this isn’t likely to be a big problem. The
  99. total length of all names of input files must be at most 16384 bytes, including
  100. terminating nulls. If you’re building a really large library, this might be a
  101. problem, in which case you should change the definition of Object_name_size at
  102. the start of the program. And if the chunk file header of any of your object
  103. files is bigger than 4k (which will only happen if the file contains a really
  104. huge number of areas; I’d be willing to place a large bet on its never happening
  105. except through malice) you’ll need to change the function process_symbol_table.
  106.  
  107. If you don’t give an output file name, output is to a file named alf.
  108.  
  109.  
  110. A few other useful utilities
  111. ----------------------------
  112.  
  113. Along with makeALF I’m enclosing four other utilities that are likely to prove
  114. helpful in working with library files (and, indeed, with object files). I make
  115. no guarantees of their robustness.
  116.  
  117. Two of them are specifically for library files. ALFdir displays the contents of
  118. a library file’s directory; each line contains the chunk number of one of its
  119. component files, its filename, and its datestamp. (It’s possible that you may
  120. have an “old-style” library, as created by Acorn’s Fortran-77 compiler and just
  121. about nothing else; for these the datestamps will be garbage.) ALFsymt displays
  122. a library’s symbol table; each line contains a symbol name (second column) and
  123. the chunk number of the component file which defines that symbol (first column).
  124.  
  125. A library file is a special kind of chunk file. The other two little programs
  126. are for dealing with chunk files generally. ChunkList lists all the chunks in
  127. a chunk file, with their chunk identifiers, positions and sizes. (For a library
  128. file, most of the chunks will be called LIB_DATA.) More usefully, ChunkRead
  129. will extract a single chunk from a chunk file. This is useful if, for instance,
  130. you want to do something with a single object file from a library. It takes 3
  131. arguments: the name of the chunk file, the chunk number and the name of the
  132. file its output should go to.
  133.  
  134.  
  135. About me
  136. --------
  137.  
  138. You might want to get in touch with me, maybe to let me know of improvements
  139. you’ve made or to tell me what a pile of rubbish this software is. Or maybe to
  140. send me huge sums of money in gratitude for makeALF. Hmmm.
  141.  
  142. Anyway, here are an e-mail and a snail-mail address for me. Both are valid as of
  143. December 1994, and both are likely to remain valid for quite some time.
  144.  
  145. e-mail: gjm11@pmms.cam.ac.uk
  146.  
  147. snail-mail:    Gareth McCaughan
  148.         Trinity College
  149.         Cambridge CB2 1TQ
  150.         England
  151.  
  152.  
  153. Another program you might want
  154. ------------------------------
  155.  
  156. I have a slightly flaky program which reads object files and displays their
  157. contents, disassembling as it goes, dealing with relocations and so on. I find
  158. it invaluable. If you want a copy, let me know. (It’s free too.)
  159.