home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d3xx / d359 / dice.lha / DICE / DICE.lzh / doc / dlink.doc < prev    next >
Text File  |  1990-05-19  |  6KB  |  148 lines
  1.  
  2.                   DLINK.DOC
  3.  
  4.     DLINK <options> <files> <libraries>
  5.  
  6.     Options may occur anywhere on the command lines.  Any file ending in .o[bj]
  7.     is assumed to be an object file.  Any file ending in .l[ib] is assumed to
  8.     be a library.  Any file beginning with @ specifies a text file containing
  9.     a further list of files.
  10.  
  11.     File ordering is maintained.  Section ordering is maintained.  All
  12.     sections of the same name are coagulated together with ordering
  13.     maintained.  EXCEPTION: inter-section ordering is not maintained
  14.     within a library since library modules are random included.  However,
  15.     ordering is maintained *between* libraries.
  16.  
  17.     All object files specified are included in the final executable.  All
  18.     libraries specified are searched at the point they are specified (that is,
  19.     specifying an object file that references a symbol defined in a library
  20.     specified BEFORE the object file will cause an undefined symbol error).
  21.     Normally an object file is specified after a library to terminate an
  22.     autoinit or autoexit section.
  23.  
  24.     You do not have to order object files within a library, DLink will
  25.     automatically make as many passes as required to handle all internal
  26.     library references.  However, ordering object files will make DLink go
  27.     faster.
  28.  
  29.     Symbols defined in object files overide symbols defined in libraries.
  30.     Symbols defined in libraries specified before later libraries overide
  31.     symbols defined in later libraries.  Symbols defined in a library and
  32.     also defined in a later specified object module causes an error.
  33.  
  34.                 CREATING A LIBRARY
  35.  
  36.     DLink libraries are standard Amiga libraries... simply join one or more
  37.     object modules together and rename the result with a .lib extension.
  38.  
  39.              LINKER SYMBOLS AND A4 RELATIVE ADDRESSING
  40.  
  41.     __DATA_BAS        Base of data space
  42.     __DATA_LEN        Length of data space is LONGWORDS
  43.     __BSS_LEN        Length of bss space in LONGWORDS
  44.     __RESIDENT        Whether -r option was used or not
  45.  
  46.     If -r is not used then the BSS space occurs just after the DATA
  47.     space ends and must be manually cleared by the program startup
  48.     code.  __RESIDENT == 0
  49.  
  50.     If -r is used (__RESIDENT != 0) then NO bss space is allocated. !!!!!!
  51.     The startup code is expected to AllocMem((__DATA_LEN+__BSS_LEN)*4)
  52.     bytes, copy the static data __DATA_BAS to the newly allocated
  53.     memory, and zero the BSS portion.
  54.  
  55.     If A4 relative addressing is used the startup code is expected
  56.     to set A4 == BaseOfStaticData + 32766 (where BaseOfStaticData
  57.     is __DATA_BAS for non resident programs and the base of the
  58.     newly allocated memory for resident programs).
  59.  
  60.                     RESIDENT
  61.  
  62.     If the -r options is given then NO BSS SPACE is allocated after the
  63.     data space... the startup code MUST allocate a data+bss space as shown
  64.     above.  DLink will give error messages for any absolute data references
  65.     that occur (except the __DATA_BAS symbol which must be used to copy the
  66.     static data to the newly allocated data+bss memory on program startup).
  67.  
  68.     DLink will give an error message if any data-data reloco32s exist when
  69.     you specify the -r option as such relocations would be incorrect when
  70.     copied to the newly allocated data+bss space.  DC1 understands this and
  71.     will produce autoinit code to handle any such static data relocations
  72.     that occur in your C code when the -r option is given to compile a C
  73.     program.
  74.  
  75.                    PC-RELATIVE
  76.  
  77.     Because the linker will insert a jump table for PC-RELATIVE references
  78.     to different hunks (after coagulation) or where the range is larger
  79.     than +/-32K, data should not be placed into a code segment and be
  80.     referenced via an external label(pc) unless you are positive the
  81.     reference is within +/-32K.  This can only happen when referencing
  82.     between like-named code hunks.  NOTE that the jump table is tagged
  83.     onto the end of the section the jump(s) occur in and thus you do
  84.     not want to have any autoinit/autoexit code that might possibly
  85.     generate a jump table (since the whole idea with autoinit is that
  86.     the code falls through to other autoinit code until the terminating
  87.     section in x.o's RTS).
  88.  
  89.     Currently dlink cannot handle inter-module PC-RELATIVE references
  90.     beyond +/-32K (i.e. when one object file has more than 32K of code).
  91.     An error will occur.
  92.  
  93.     Note that if -frag is used you cannot make PC-RELATIVE calls
  94.     between sections of differing names ever, or make a program resident.
  95.     The -frag option is almost never used on untested.
  96.  
  97.                 OVERLAYS (NOT SUPPORTED)
  98.  
  99.     Overlays are not supported as yet.
  100.  
  101.                      OPTIONS
  102.  
  103.     Options:
  104.  
  105.     -o execname     name of executable
  106.  
  107.     -s            include symbolic information.  NOTE, if -r is used
  108.             symbolic info for the data sections will point to
  109.             the statically init'd stuff, NOT The actual data
  110.             space (in BSS) referenced by the code.  This is a bug.
  111.  
  112.     -f[rag]        Fragment output file (default is to coagulate all
  113.             hunks of the same type regardless of name).  If
  114.             frag is specified then only hunks of the same type
  115.             AND name are coagulated.
  116.  
  117.     -r[es]        Resident link.
  118.  
  119.     -d[#]        debug mode (spews lots of debugging junk out)
  120.  
  121.  
  122.                 EXAMPLE
  123.  
  124.     This is what DCC gives the linker to link the program 'foo.c' :
  125.  
  126. dlink dlib:c.o @tmp dlib:x.o -o ram:foo
  127.  
  128. --- tmp ---
  129. foo.o
  130. dlib:c.lib dlib:amiga.lib dlib:auto.lib
  131. -----------
  132.  
  133.     Basically it tells dlink to link the startup code, c.o, then the
  134.     program object module(s) (foo.o), then c.lib, amiga.lib, and auto.lib,
  135.     then finally x.o.
  136.  
  137.     DCC handles all this for you
  138.  
  139.     auto.lib contains autoinit code for certain selected libraries
  140.     including the dos.library.    Autoinit code is brought in whenever a
  141.     given library base symbol has been referenced BUT NOT DEFINED. auto.lib
  142.     defines the symbol and generates autoinit code to open the library and
  143.     autoexit code to close the library.
  144.  
  145.     x.o terminates the autoinit and autoexit sections with an RTS. The
  146.     autoinit and autoexit sections are called from the startup code c.o .
  147.  
  148.