rdoff/README

   1 *******
   2 This file is getting obsolete. RDOFF documentation is written in Texinfo now.
   3 Directory doc/ contains Texinfo source (rdoff.texi) and makefile for creating
   4 different output formats (info, HTML, PostScript and PDF).
   5 *******
   6
   7 RDOFF Utilities, version 0.3.2
   8 ==============================
   9
  10 The files contained in this directory are the C source code of a set
  11 of tools (and general purpose library files) for the manipulation of
  12 RDOFF version 2 object files. Note that these programs (with the
  13 exception of 'rdfdump') will NOT work with version 1 object files.
  14 Version 1 of RDOFF is no longer supported.
  15
  16 There is also a 'doc' directory with 'v1-v2' file, which documents the
  17 differences between RDOFF 1 and 2, and an 'rdoff2.texi' (texinfo source),
  18 with complete documentation for the new format.
  19
  20 Here is a brief summary of the programs' usage:
  21
  22
  23 rdfdump
  24 =======
  25
  26 This tool prints a list of the header records in an RDOFF object in
  27 human-readable form, and optionally prints a hex dump of the contents
  28 of the segments.
  29
  30 Usage:
  31         rdfdump [-v] filename
  32
  33 The -v flag specifies that the hex dump (see above) should be printed.
  34
  35 Changes from previous versions:
  36
  37 * rdfdump supports both version 1 and 2 of RDOFF.
  38 * rdfdump now gives warnings if the RDOFF2 format is violated (it
  39   looks for incorrect lengths for header records, and checks the
  40   overall length count at the start of the file)
  41
  42
  43 ldrdf
  44 =====
  45
  46 This tool is a version of unix 'ld' (or DOS 'link') for use with RDOFF
  47 files. It is capable of linking RDOFF objects, and libraries produced
  48 with the 'rdlib' utility discussed below.
  49
  50 In normal usage, its command line takes the form:
  51
  52         ldrdf [-o output-file] object files [-llibrary ...]
  53
  54 Modules in libraries are not linked to the program unless they are
  55 referred to.
  56
  57 Most of its options are not implemented, but those that are are listed here:
  58
  59   -2    redirect all output from stderr to stdout. It is useful for some
  60         systems which don't have such a redirection in shell (e.g. DOS).
  61
  62   -v    increase verbosity level. Currently 4 verbosity levels are
  63         available: default (which only prints error information), normal
  64         (which prints information about the produced object, -v), medium
  65         (which prints information about what the program is doing, -v -v)
  66         and high (which prints all available information, -v -v -v).
  67
  68   -a    change alignment value to which multiple segments combigned into
  69         a single segment should be aligned (must be either 1, 2, 4, 8,
  70         16, 32 or 256. Default is 16).
  71
  72   -s    strip exported symbols from output file. Symbols marked as
  73         SYM_GLOBAL are never stripped.
  74
  75   -x    warn about unresolved symbols.
  76
  77   -xe   issue an error when at least one symbol is unresolved.
  78
  79   -o name       write output to file <name>. The default output filename
  80                 is 'aout.rdx'.
  81
  82   -j path       specify search path for object files. Default path is a
  83                 current directory.
  84
  85   -L path       specify search path for libraries. Default path is a
  86                 current directory.
  87
  88   -g file       embed 'file' as a first header record with type 'generic'.
  89
  90
  91 rdx
  92 ===
  93
  94 This program simply loads and executes an RDOFF object, by calling
  95 '_main', which it expects to be a C-style function, which will accept
  96 two parameters, argc and argv in normal C style.
  97
  98
  99 rdflib
 100 ======
 101
 102 This program creates a library file for use with ldrdf.
 103
 104 It is supplied with a shell script 'makelib' which should probably be used
 105 to create libraries.
 106
 107 Usage:
 108         rdflib command library [optional arguments]
 109
 110 Valid commands are:
 111
 112         c       Create (or truncate) the library
 113         a       Add a module (requires a filename and a name to give the
 114                 module, ie 'rdflib a libc.rdl strcpy.rdf strcpy' puts the
 115                 file 'strcpy.rdf' into 'libc.rdl', and calls it 'strcpy'.
 116         x       Extract (arguments are the opposite to the 'a' command,
 117                 ie you'd do 'rdflib x libc.rdl strcpy strcpy.rdf to get
 118                 a copy of strcpy.rdf back out again...)
 119         t       List modules in the library
 120         d       Delete modules from library
 121         r       Replace a module in library with a new file
 122
 123
 124 Library functions
 125 =================
 126
 127 The files 'rdoff.c', 'rdoff.h', 'rdfload.c' and 'rdfload.h' contain
 128 code which you may find useful. They retain the same interface as
 129 the previous version, so any code that used them previously should
 130 still work OK (maybe). 'rdoff.c' contains at the top a line:
 131
 132 #define STRICT_ERRORS
 133
 134 Comment this line out if you wish to use record types other than the
 135 7 predefined types; it will then not report such records as an error,
 136 but accept them gracefully, and read them byte for byte into
 137 a 'generic record' (see the definition of GenericRec in 'rdoff.h').
 138
 139 If you are using these functions to write RDF modules (rather than
 140 just reading them), then please note the existance of a new function
 141 'rdfaddsegment(rdf_headerbuf,long)'. This must be called once for
 142 each segment in your object, to tell the header writing functions
 143 how long the segment is.
 144
 145
 146 BUGS
 147 ====
 148
 149 This product has recently undergone a major revision, and as such there
 150 are probably several bugs left over from the testing phase (although the
 151 previous version had quite a few that have now been fixed!). Could you
 152 please report any bugs to maintainers at the addresses below, including the
 153 following information:
 154
 155   - A description of the bug
 156   - What you think the program should be doing
 157   - Which programs you are using
 158   - Which operating system you are using, and which C compiler was used to
 159     compile the programs (or state that the pre-compiled versions were used).
 160   - If appropriate, any of the following:
 161     * source code (preferably cut down to a minimum that will still assemble
 162       and show the bug)
 163     * the output of rdfdump on produced modules (or send the module if the
 164       problem is in code generated)
 165     * exact descriptions of error messages/symptoms/etc
 166
 167
 168 TODO
 169 ====
 170
 171 There are still various things unimplemented that we would like to add.
 172 If you want to find out what these are, search near the top of each *.c
 173 file for a comment containing the word 'TODO'. A brief list is given here:
 174
 175 - Improve the performace of ldrdf (there are several enhancements I can think
 176   of that wouldn't be too hard to add)
 177 - Stop assuming that we're on a little endian machine
 178 - Check for more bugs
 179
 180
 181 MAINTAINERS
 182 ===========
 183
 184 Yuri Zaporozhets <r_tty@yahoo.co.uk> - primary maintainer
 185 Julian Hall <jules@dsf.org.uk> - original designer and author