home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / drlink / Drlink_doc < prev    next >
Text File  |  1996-10-12  |  51KB  |  1,137 lines
  1.                      The 'Drlink' AOF Linker
  2.                      ~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. Disclaimer
  5. ~~~~~~~~~~
  6. The 'Drlink' linker is provided 'as is' and people using it do so
  7. entirely at their own risk. No liability whatsoever will be
  8. accepted for any loss or damage arising from the use of this
  9. software.
  10.  
  11.  
  12. Introduction
  13. ~~~~~~~~~~~~
  14. Drlink is a linker that is intended to be a partial substitute for
  15. the Acorn linker, 'link'. It is aimed at people with compilers
  16. that generate object files in Acorn's AOF format but who do not
  17. have a copy of 'link', for example, people who want to use the DDE
  18. Pascal compiler or TLA or perhaps their own homebrew compilers.
  19. Drlink accepts object files in Acorn's AOF format and libraries in
  20. Acorn's ALF format and links them to produce an executable image
  21. in either Acorn's AIF format or a plain binary image. It can also
  22. be used to link relocatable modules or to create partially-linked
  23. AOF files. Drlink is modelled very closely on the version of
  24. 'link' that comes with release 3 of Acorn's C compiler but it is
  25. not really a complete replacement for it as it does not have the
  26. same range of facilities. What is there, it is hoped, should be
  27. adequate in most cases. Drlink is designed to link 'ordinary'
  28. programs and cannot do some of the fancy things link can, such as
  29. create image files that use overlays. Of course, some of these
  30. features could be added at a later date but the current version of
  31. Drlink, 0.30, does not support them. On the other hand, it does
  32. contain some features found on later releases of 'link' such as
  33. the ability to increase the size of the wimpslot if necessary when
  34. running in a task window and support for extended command lines.
  35. Other features include the ability to scan libraries more than
  36. once when resolving symbols and, assuming the right compiler
  37. options have been used when compiling programs, being able to
  38. leave out unused functions from executable images. Hopefully
  39. features like these will make the linker attractive to people who
  40. use link as well.
  41.  
  42.  
  43. Thanks...
  44. ~~~~~~~~~
  45. I would like to thank the many people on Arcade who have tested
  46. Drlink for me over the months and who made many helpful and useful
  47. suggestions. Drlink would never have reached the state it has
  48. today without their generous assistance.
  49.  
  50.  
  51. Using Drlink
  52. ~~~~~~~~~~~~
  53. Drlink is a command line-based program and has the same command
  54. syntax as 'link'. It can be used in the same environments as
  55. 'link', for example, with amu. If it is renamed as 'link', then
  56. it can be dynamically invoked from either the Acorn C or DDE
  57. Pascal compilers as well. It accepts the same options as 'link',
  58. although a number of them are unsupported and will be flagged as
  59. errors. Drlink also supports extended command lines. (Further
  60. information on this can be found in the section 'Extended Command
  61. Line Support' below.)
  62.  
  63. The command syntax is:
  64.  
  65.     drlink <list of files> <options>
  66.  
  67. where:
  68.  
  69. <list of files> is the list of object files and libraries to be
  70.                 included in the linked program.
  71.  
  72. <options>       is the options to be used when linking the
  73.                 program.
  74.  
  75. Options and object file names can be freely intermixed. The linker
  76. processes all the options before moving on to the link itself.
  77.  
  78. Filenames
  79. Each filename in the list of object files should be fully
  80. qualified, that is, Drlink makes no assumptions as to where the
  81. object files are to be found. Wildcards are permitted, in which
  82. case Drlink loads all the files that match the wildcard. If the
  83. directory containing the object files is called 'o', then Drlink
  84. will also accept 'back-to-front' filenames, for example, 'sieve.o'
  85. instead of 'o.sieve'. If a path is used as part of a filename, for
  86. example, 'C:', the way Drlink treats the filename depends on
  87. whether it contains wildcards or not. If it does not, then every
  88. directory on the path will be searched to find the file until
  89. either the file is found or the end of the list is reached. On the
  90. other hand, if the filename contains wildcards, only the first
  91. directory listed on the path will be checked. (This is how link
  92. behaves.) Examples:
  93.  
  94.     o.sieve
  95.     o.dhry1 o.dhry2 c:o.stubs
  96.     o.dhry* c:o.ansilib
  97.     dhry*.o c:ansilib.o
  98.     o.* c:o.*
  99.     O.world scsi::Arc.$.programs.!Pascal.O.Plib C:O.stubs
  100.  
  101. Drlink ignores the case of object file and library names.
  102.  
  103. Options
  104. As noted above, Drlink recognises the same options as 'link',
  105. even if it does flag a number as unsupported, plus has a number of
  106. its own. Options take the form of a '-' followed by the option
  107. name. Some options are followed by an argument. One or more blanks
  108. should be left between the option name and the argument. The case
  109. of the option and any argument is ignored. Options that are
  110. supported are:
  111.  
  112.     -aif       Create an AIF image file.
  113.  
  114.                This is the standard format for programs running
  115.                under RISCOS where a small header is attached to
  116.                the start of the program containing various bits
  117.                and pieces of information. It is the default option
  118.                used for the image type when no type is explicitly
  119.                given unless the '-base' option is used when '-bin'
  120.                is the default value.
  121.  
  122.     -aof       Create a partially-linked AOF file.
  123.  
  124.                The image file created takes the form of an AOF
  125.                file where as many references as possible between
  126.                the object files included in the link are resolved
  127.                and then the object files are merged together to
  128.                form another object file in AOF format that can be
  129.                used in a future link.
  130.  
  131.                There are a couple of points to watch out for here:
  132.                a) To include debug information in the AOF file,
  133.                   either '-debug' or '-keepdebug' must be used.
  134.                b) All local symbol names are lost, so they will
  135.                   not appear in the low-level debug tables if
  136.                   these are generated in the final image.
  137.  
  138.     -base <address>
  139.                This option allows the initial load address of the
  140.                read-only part of the image file to be specified.
  141.                The read-only part normally contains code.
  142.                <address> is taken to be decimal by default but if
  143.                prefixed by '&' or '0x' it will be treated as a
  144.                hexadecimal value. It can be postfixed by 'k' or
  145.                'm' to indicate the address is in kilobytes or
  146.                megabytes. The case of the 'k', 'm', 'x' or any of
  147.                the hex digits 'a' to 'f' is ignored. The value of
  148.                <address> is rounded up to the next word boundary
  149.                if it is not already so aligned.
  150.                
  151.                The initial load address can only be specified for
  152.                a binary image file.
  153.                
  154.                Image files created when this option is used do not
  155.                have a filetype but have 'load' and 'excute'
  156.                addresses instead. The load address is set to
  157.                whatever was specified on '-base' and the 'execute'
  158.                address to the program's entry point address. The
  159.                files themselves contain plain binary images as
  160.                created by the option '-bin'. This behaviour is
  161.                different to that of 'link'. 
  162.                
  163.     -bin       Create a plain binary image file.
  164.  
  165.                A binary image file does not have the header that
  166.                AIF files have on them and consist of nothing but
  167.                the linked program. This has two consequences.
  168.                Firstly, and most importantly, zero-initialised
  169.                data areas will not be cleared to zeros when the
  170.                program starts running as the routine to do this is
  171.                part of the AIF header. Secondly, if debugging
  172.                tables are included in the executable image, there
  173.                is nothing to indicate where they are.
  174.  
  175.                Note that when the option '-base' is used and the
  176.                image file type is not given, '-bin' is assumed to
  177.                be the image type.
  178.  
  179.     -case      Ignore the case of symbols when tryin