home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Programming / vbcc_MorphOS / doc / vlink.doc < prev    next >
Text File  |  2000-08-20  |  9KB  |  206 lines
  1. vlink V0.7        VBCC ANSI C Compiler Reference Manual           vlink V0.7
  2.  
  3. NAME
  4.      vlink - linker for multiple file formats
  5.  
  6. SYNOPSIS
  7.      vlink [-dhrstvwxMRSX] [-B linkmode] [-b targetname] [-baseoff offset]
  8.            [-F filename] [-L library-search-path] [-l library-specifier]
  9.            [-multibase] [-nostdlib] [-o filename] [-sc] [-sd] [-T script]
  10.            [-V version] [-y symbol] input-files...
  11.  
  12. DESCRIPTION
  13.      vlink combines the object and archive files given on the command line
  14.      into a new object file. The output object file is either an executable
  15.      program, a shared object suitable for loading at run-time, or an
  16.      object file that can once again be processed by vlink. Object files
  17.      and archives are processed in the order given on the command line.
  18.  
  19.      The file format of an input object file is determined automatically
  20.      by vlink. The default output file format is compiled in (see -v)
  21.      and may be changed by -b.
  22.  
  23.      Supported file formats:
  24.  
  25.      amigaos
  26.              The AmigaDos hunk format for M68k. Requires AmigaOS 2.04.
  27.              No shared objects. Small data offset: 0x7ffe. Linker
  28.              symbols: _DATA_BAS_, _DATA_LEN_, _BSS_LEN_ (PhxAss),
  29.              _LinkerDB, __BSSBAS, __BSSLEN (SASC/StormC), __DATA_BAS,
  30.              __DATA_LEN, __BSS_LEN, __RESIDENT (DICE-C). Automatic
  31.              constructor/destructor function tables: __ctors, __dtors.
  32.  
  33.      amigaehf
  34.              An extension of the AmigaDOS hunk format for the PowerPC,
  35.              32-bit, big endian, as introduced by Haage&Partner GmbH. No
  36.              executables (they are in amigaos format) or shared objects.
  37.              The same linker symbols, constructors/destructors as under
  38.              amigaos are supported. Additionally, "@_name" symbols will
  39.              be created on demand (when referenced).
  40.  
  41.      elf32ppcbe
  42.              ELF (executable linkable format) for PowerPC, 32-bit,
  43.              big endian. Small data offset: 0x7ff0. Linker symbols:
  44.              _SDA_BASE_ and _SDA2_BASE (EABI only). Automatic construc-
  45.              tor/destructor function tables will be placed into the
  46.              sections .ctors and .dtors.
  47.  
  48.      elf32powerup
  49.              ELF PowerPC 32-bit big endian for the PowerUp turbo boards
  50.              from Phase5. Main difference to elf32ppcbe is the format
  51.              of the executable (which is a relocatable object) and a new
  52.              linker symbol, _LinkerDB, for vbccppc-compatibility.
  53.  
  54.      rawbin1
  55.              Absolute raw binary file. The sections and base addresses
  56.              have to be specified by a linker script (option -T). Gaps
  57.              between sections are filled with 0-bytes. Without a linker
  58.              script, the raw binary will be relocated to base address 0.
  59.  
  60.      rawbin2
  61.              Like rawbin1. The only difference is, that a separate file
  62.              will be created for every section. The file name will get
  63.              the section's base address appended.
  64.  
  65.  
  66.      The options are as follows:
  67.  
  68.      -Bdynamic
  69.              Specifies that linking against dynamic libraries can take
  70.              place. If a library specifier of the form -lx appears on
  71.              the command line, ld searches for a library of the from
  72.              libx.so.n.m (see the -l option) according to the search
  73.              rules in effect. If such a file can not be found a tradi-
  74.              tional archive is looked for. This options can appear
  75.              anywhere on the command line and is complementary to -Bstatic.
  76.  
  77.      -Bstatic
  78.              The counterpart of -Bdynamic. This option turns off dynamic
  79.              linking for all library specifiers until a -Bdynamic is once
  80.              again given. Any explicitly mentioned shared object encoun-
  81.              tered on the command line while this option is in effect is
  82.              flagged as an error.
  83.  
  84.      -Bshareable
  85.              Instructs the linker to build a shared object from the object
  86.              files rather than a normal executable image.
  87.  
  88.      -Bsymbolic
  89.              This option causes all symbolic references in the output to be
  90.              resolved in this link-edit session. The only remaining run-
  91.              time relocation requirements are base-relative relocations,
  92.              ie. translation with respect to the load address. Failure to
  93.              resolve any symbolic reference causes an error to be reported.
  94.  
  95.      -Bforcearchive
  96.              Force all members of archives to be loaded, whether or not such
  97.              members contribute a definition to any plain object files.
  98.              Useful for making a shared library from an archive of PIC
  99.              objects without having to unpack the archive.
  100.  
  101.      -b targetname
  102.              Specifies target file format for the output file. See
  103.              also "Supported file formats".
  104.  
  105.      -baseoff offset
  106.              Defines section offset for base-relative relocations. The
  107.              default offset is target-dependant (e.g. 0x7ffe for amigaos
  108.              and 0x7ff0 for elf32ppcbe).
  109.  
  110.      -dc     Force allocation of commons even when producing relocatable
  111.              output.
  112.  
  113.      -dn     Same as: -Bstatic
  114.  
  115.      -dy     Same as: -Bdynamic
  116.  
  117.      -F filename
  118.              A list of object file names is read from the specified file.
  119.              Useful, if the number of objects exceeds the length of the
  120.              command line.
  121.  
  122.      -h      Prints a short help text.
  123.  
  124.      -L library-search-path
  125.              Add path to the list of directories to search for libraries
  126.              specified with the -l option. When a default search path
  127.              was compiled in (see -v), then it is searched last.
  128.  
  129.      -l library-specifier
  130.              This option specifies a library to be considered for inclusion
  131.              in the output. If the -Bdynamic option is in effect, a shared
  132.              library of the form lib<spec>.so.m.n (where m is the major,
  133.              and n is the minor version number, respectively) is searched
  134.              for first. The library with the highest version found in the
  135.              search path is selected. If no shared library is found or
  136.              the -Bstatic option is in effect, an archive of the form
  137.              lib<spec>.a is looked for in the library search path.
  138.              For amigaos/amigaehf file formats, the libraries are called
  139.  
  140.      -M      Produce output about the mapping of segments of the input
  141.              files and the values assigned to symbols in the output file.
  142.  
  143.      -multibase
  144.              The default behaviour of vlink is to merge all sections
  145.              which are accessed base-relative. This guarantees a single
  146.              small data section, which can be accessed through a base
  147.              register.
  148.              If this is not desired - maybe you have several base re-
  149.              gisters and small data sections - you can disable this
  150.              behavoiur by specifying -multibase. 
  151.  
  152.      -nostdlib
  153.              Ignore default library search path, if one was compiled in.
  154.  
  155.      -o filename
  156.              Specifies the name of the output file. Defaults to "a.out".
  157.  
  158.      -R      If the target file format supports it, use the short
  159.              format for relocations.
  160.  
  161.      -r      Produce relocatable object file, suitable for another
  162.              linker pass.
  163.  
  164.      -S      Strip all debugger symbols from the output.
  165.  
  166.      -s      Strip all symbols from the output.
  167.  
  168.      -sc     Merge all code sections to a single code section.
  169.  
  170.      -sd     Merge all data and bss sections to a single data-bss section.
  171.  
  172.      -T script
  173.              Specifies a linker script, which defines the absolute
  174.              locations for every section. The syntax is similar to
  175.              that used in GNU linker scripts, but still very limited.
  176.  
  177.      -t      Trace the linker's file accesses.
  178.  
  179.      -V version
  180.              Minimum major version of shared object to be linked.
  181.  
  182.      -v      Prints vlink version string, default library search path
  183.              and implemented target file formats.
  184.  
  185.      -w      Suppress all warning messages.
  186.  
  187.      -X      Discard local symbols in the input files that start with the
  188.              letter "L" or with a dot.
  189.  
  190.      -x      Discard all local symbols in the input files.
  191.  
  192.      -y symbol
  193.              Trace the manipulations inflicted on symbol.
  194.  
  195. BUGS
  196.      Target elf32ppcbe can't generate shared objects or executables.
  197.      Target elf32powerup can't generate shared objects.
  198.      The following options are not really supported: -B, -d, -S, -X.
  199.      Option -R for ELF is untested and should be avoided (works fine
  200.      for AmigaOS hunk format though).
  201.      Real debugger support (source level debugging, etc.) is still
  202.      missing for all target file formats.
  203.  
  204.  
  205. Frank Wille                  07-Mar-2000                frank@phoenix.owl.de
  206.