Next Previous Contents

2. Usage

2.1 Command line option overview

The linker is called as follows:

---------------------------------------------------------------------------
Usage: ld65 [options] module ...
Short options:
  -(                    Start a library group
  -)                    End a library group
  -C name               Use linker config file
  -D sym=val            Define a symbol
  -L path               Specify a library search path
  -Ln name              Create a VICE label file
  -S addr               Set the default start address
  -V                    Print the linker version
  -h                    Help (this text)
  -m name               Create a map file
  -o name               Name the default output file
  -t sys                Set the target system
  -u sym                Force an import of symbol `sym'
  -v                    Verbose mode
  -vm                   Verbose map file

Long options:
  --cfg-path path       Specify a config file search path
  --config name         Use linker config file
  --dbgfile name        Generate debug information
  --define sym=val      Define a symbol
  --dump-config name    Dump a builtin configuration
  --end-group           End a library group
  --force-import sym    Force an import of symbol `sym'
  --help                Help (this text)
  --lib file            Link this library
  --lib-path path       Specify a library search path
  --mapfile name        Create a map file
  --module-id id        Specify a module id
  --obj file            Link this object file
  --obj-path path       Specify an object file search path
  --start-addr addr     Set the default start address
  --start-group         Start a library group
  --target sys          Set the target system
  --version             Print the linker version
---------------------------------------------------------------------------

2.2 Command line options in detail

Here is a description of all the command line options:

-(, --start-group

Start a library group. The libraries specified within a group are searched multiple times to resolve crossreferences within the libraries. Normally, crossreferences are only resolved within a library, that is the library is searched multiple times. Libraries specified later on the command line cannot reference otherwise unreferenced symbols in libraries specified earlier, because the linker has already handled them. Library groups are a solution for this problem, because the linker will search repeatedly through all libraries specified in the group, until all possible open symbol references have been satisfied.

-), --end-group

End a library group. See the explanation of the --start-group option.

-h, --help

Print the short option summary shown above.

-m name, --mapfile name

This option (which needs an argument that will used as a filename for the generated map file) will cause the linker to generate a map file. The map file does contain a detailed overview over the modules used, the sizes for the different segments, and a table containing exported symbols.

-o name

The -o switch is used to give the name of the default output file. Depending on your output configuration, this name may NOT be used as name for the output file. However, for the builtin configurations, this name is used for the output file name.

-t sys, --target sys

The argument for the -t switch is the name of the target system. Since this switch will activate a builtin configuration, it may not be used together with the -C option. The following target systems are currently supported:

There are a few more targets defined but neither of them is actually supported.

-u sym[:addrsize], --force-import sym[:addrsize]

Force an import of a symbol. While object files are always linked to the output file, regardless if there are any references, object modules from libraries get only linked in if an import can be satisfied by this module. The --fore-import option may be used to add a reference to a symbol and as a result force linkage of the module that exports the identifier.

The name of the symbol may optionally be followed by a colon and an address size specifier. If no address size is specified, the default address size for the target machine is used.

Please note that the symbol name needs to have the internal representation, meaning you have to prepend an underline for C identifiers.

-v, --verbose

Using the -v option, you may enable more output that may help you to locate problems. If an undefined symbol is encountered, -v causes the linker to print a detailed list of the references (that is, source file and line) for this symbol.

-vm

Must be used in conjunction with -m (generate map file). Normally the map file will not include empty segments and sections, or unreferenced symbols. Using this option, you can force the linker to include all this information into the map file.

-C

This gives the name of an output config file to use. See section 4 for more information about config files. -C may not be used together with -t.

-D sym=value, --define sym=value

This option allows to define an external symbol on the command line. Value may start with a '$' sign or with 0x for hexadecimal values, otherwise a leading zero denotes octal values. See also the SYMBOLS section in the configuration file.

-L path, --lib-path path

Specify a library search path. This option may be used more than once. It adds a directory to the search path for library files. Libraries specified without a path are searched in current directory, in the directory given in the LD65_LIB environment variable, and in the list of directories specified using --lib-path.

-Ln

This option allows you to create a file that contains all global labels and may be loaded into VICE emulator using the ll (load label) command. You may use this to debug your code with VICE. Note: Older versions had some bugs in the label code. If you have problems, please get the latest VICE version.

-S addr, --start-addr addr

Using -S you may define the default starting address. If and how this address is used depends on the config file in use. For the builtin configurations, only the "none", "apple2" and "apple2enh" systems honor an explicit start address, all other builtin config provide their own.

-V, --version

This option print the version number of the linker. If you send any suggestions or bugfixes, please include this number.

--cfg-path path

Specify a config file search path. This option may be used more than once. It adds a directory to the search path for config files. A config file given with the -C option that has no path in its name is searched in the current directory, in the directory given in the LD65_CFG environment variable, and in the list of directories specified using --cfg-path.

--dbgfile name

Specify an output file for debug information. Available information will be written to this file. Using the -g option for the compiler and assembler will increase the amount of information available. Please note that debug information generation is currently being developed, so the format of the file and its contents are subject to change without further notice.

--lib file

Links a library to the output. Use this command line option instead of just naming the library file, if the linker is not able to determine the file type because of an unusual extension.

--obj file

Links an object file to the output. Use this command line option instead of just naming the object file, if the linker is not able to determine the file type because of an unusual extension.

--obj-path path

Specify an object file search path. This option may be used more than once. It adds a directory to the search path for object files. An object file passed to the linker that has no path in its name is searched in current directory, in the directory given in the LD65_OBJ environment variable, and in the list of directories specified using --obj-path.

Next Previous Contents