---------------------------------------------------------------------------
Usage: ld65 [options] module ...
Short options:
- -C name Use linker config file
- -Ln name Create a VICE label file
- -Lp Mark write protected segments as such (VICE)
- -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
- -v Verbose mode
- -vm Verbose map file
+ -C name Use linker config file
+ -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
+ -v Verbose mode
+ -vm Verbose map file
Long options:
- --config name Use linker config file
- --help Help (this text)
- --mapfile name Create a map file
+ --cfg-path path Specify a config file search path
+ --config name Use linker config file
+ --dbgfile name Generate debug information
+ --dump-config name Dump a builtin configuration
+ --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
- --target sys Set the target system
- --version Print the linker version
+ --target sys Set the target system
+ --version Print the linker version
---------------------------------------------------------------------------
</verb></tscreen>
<itemize>
<item>none
+ <item>apple2
<item>atari
+ <item>atmos
+ <item>c16 (works also for the c116 with memory up to 32K)
<item>c64
<item>c128
<item>plus4
<item>cbm510 (CBM-II series with 40 column video)
<item>cbm610 (all CBM series-II computers with 80 column video)
<item>pet (all CBM PET systems except the 2001)
- <item>apple2
<item>geos
+ <item>lunix
+ <item>atmos
+ <item>nes
</itemize>
There are a few more targets defined but neither of them is actually
- supported. See <ref id="builtin-configs" name="builtin configurations"> for
- more information.
+ supported.
<label id="option-v">
id="option-t" name="-t"></tt>.
+ <label id="option--lib-path">
+ <tag><tt>-L path, --lib-path path</tt></tag>
+
+ 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 <tt/LD65_LIB/ environment variable, and in the list of directories
+ specified using <tt/--lib-path/.
+
+
<tag><tt>-Ln</tt></tag>
This option allows you to create a file that contains all global labels and
version.
- <tag><tt>-Lp</tt></tag>
-
- Deprecated option.
-
-
<label id="option-S">
<tag><tt>-S addr, --start-addr addr</tt></tag>
This option print the version number of the linker. If you send any
suggestions or bugfixes, please include this number.
+
+ <label id="option--cfg-path">
+ <tag><tt>--cfg-path path</tt></tag>
+
+ 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 <tt><ref id="option-C" name="-C"></tt> option that has no path in
+ its name is searched in the current directory, in the directory given in the
+ <tt/LD65_CFG/ environment variable, and in the list of directories specified
+ using <tt/--cfg-path/.
+
+
+ <label id="option--dbgfile">
+ <tag><tt>--dbgfile name</tt></tag>
+
+ Specify an output file for debug information. Available information will be
+ written to this file. Using the <tt/-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 it's contents are subject to change without further notice.
+
+
+ <tag><tt>--lib file</tt></tag>
+
+ 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.
+
+
+ <tag><tt>--obj file</tt></tag>
+
+ 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.
+
+
+ <label id="option--obj-path">
+ <tag><tt>--obj-path path</tt></tag>
+
+ 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 <tt/LD65_OBJ/ environment variable,
+ and in the list of directories specified using <tt/--obj-path/.
+
</descrip>
-If one of the modules is not found in the current directory, and the module
-name does not have a path component, the value of the environment variable
-<tt/CC65_LIB/ is prepended to the name, and the linker tries to open the
-module with this new name.
+
+
+<sect>Search paths<p>
+
+Starting with version 2.10 there are now several search paths for files needed
+by the linker: One for libraries, one for object files and one for config
+files.
+
+
+<sect1>Library search path<p>
+
+The library search path contains in this order:
+
+<enum>
+<item>The current directory.
+<item>A compiled in library path which is often <tt>/usr/lib/cc65/lib</tt> on
+ Linux systems.
+<item>The value of the environment variable <tt/LD65_LIB/ if it is defined.
+<item>The value of the environment variable <tt/CC65_LIB/ if it is defined.
+ Please note that use of this environment variable is obsolete and may
+ get removed in future versions.
+<item>Any directory added with the <tt><ref id="option--lib-path"
+ name="--lib-path"></tt> option on the command line.
+</enum>
+
+
+<sect1>Object file search path<p>
+
+The object file search path contains in this order:
+
+<enum>
+<item>The current directory.
+<item>A compiled in directory which is often <tt>/usr/lib/cc65/lib</tt> on
+ Linux systems.
+<item>The value of the environment variable <tt/LD65_OBJ/ if it is defined.
+<item>The value of the environment variable <tt/CC65_LIB/ if it is defined.
+ Please note that use of this environment variable is obsolete and may
+ get removed in future versions.
+<item>Any directory added with the <tt><ref id="option--obj-path"
+ name="--obj-path"></tt> option on the command line.
+</enum>
+
+
+<sect1>Config file search path<p>
+
+The config file search path contains in this order:
+
+<enum>
+<item>The current directory.
+<item>A compiled in directory which is often <tt>/usr/lib/cc65/lib</tt> on
+ Linux systems.
+<item>The value of the environment variable <tt/LD65_CFG/ if it is defined.
+<item>Any directory added with the <tt><ref id="option--cfg-path"
+ name="--cfg-path"></tt> option on the command line.
+</enum>
the VICE label file if -Lp is given
rw means read/write
bss means that this is an uninitialized segment
- empty will not go in any output file
zp a zeropage segment
</verb></tscreen>
<tscreen><verb>
__NAME_LOAD__ This is set to the address where the
- segment is loaded.
+ segment is loaded.
__NAME_RUN__ This is set to the run address of the
- segment. We will cover run addresses
- later.
+ segment. We will cover run addresses
+ later.
__NAME_SIZE__ This is set to the segment size.
</verb></tscreen>
"rom1.bin", and segments that go into <tt/ROM2/ will be written to a file
named "rom2.bin". The name given on the command line is ignored in both cases.
+Assigning an empty file name for a memory area will discard the data written
+to it.
<sect1>LOAD and RUN addresses (ROMable code)<p>
<tscreen><verb>
__DATA_LOAD__ This is set to the address where the segment
- is loaded, in this case, it is an address in
- ROM2.
+ is loaded, in this case, it is an address in
+ ROM2.
__DATA_RUN__ This is set to the run address of the segment,
- in this case, it is an address in RAM2.
+ in this case, it is an address in RAM2.
__DATA_SIZE__ This is set to the segment size.
</verb></tscreen>
}
</verb></tscreen>
+To suppress the warning, the linker issues if it encounters a segment that is
+not found in any of the input files, use "<tt/optional=yes/" as additional
+segment attribute. Be careful when using this attribute, because a missing
+segment may be a sign of a problem, and if you're suppressing the warning,
+there is no one left to tell you about it.
+
File names may be empty, data from segments assigned to a memory area with
an empty file name is discarded. This is useful, if the a memory area has
segments assigned that are empty (for example because they are of type
<tt/decreasing/ as an argument. Specifies the sorting order of the entries
within the table. The default is <tt/increasing/, which means that the
entries are sorted with increasing priority (the first entry has the lowest
- priority). You may change this behaviour by specifying <tt/decreasing/ as
- the argument, the order of entries is reversed in this case.
+ priority). "Priority" is the priority specified when declaring a symbol as
+ <tt/.CONDES/ with the assembler, higher values mean higher priority. You may
+ change this behaviour by specifying <tt/decreasing/ as the argument, the
+ order of entries is reversed in this case.
Please note that the order of entries with equal priority is undefined.
-<sect1>Builtin configurations<label id="builtin-configs"><p>
-
-Here is a list of the builin configurations for the different target
-types:
-
-<descrip>
-<tag><tt>none</tt></tag>
-<tscreen><verb>
- MEMORY {
- RAM: start = %S, size = $10000, file = %O;
- }
- SEGMENTS {
- CODE: load = RAM, type = rw;
- RODATA: load = RAM, type = rw;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-<tag><tt>atari</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $82, size = $7E, type = rw;
- HEADER: start = $0000, size = $6, file = %O;
- RAM: start = $1F00, size = $9D1F, file = %O; # $9D1F: matches upper bound $BC1F
- }
- SEGMENTS {
- EXEHDR: load = HEADER, type = wprot;
- CODE: load = RAM, type = wprot, define = yes;
- RODATA: load = RAM, type = wprot;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- AUTOSTRT: load = RAM, type = wprot;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-<tag><tt>c64</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $02, size = $1A, type = rw;
- RAM: start = $7FF, size = $c801, define = yes, file = %O;
- }
- SEGMENTS {
- CODE: load = RAM, type = wprot;
- RODATA: load = RAM, type = wprot;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-<tag><tt>c128</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $02, size = $1A, type = rw;
- RAM: start = $1bff, size = $a401, define = yes, file = %O;
- }
- SEGMENTS {
- CODE: load = RAM, type = wprot;
- RODATA: load = RAM, type = wprot;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = 2,
- label = __IRQFUNC_TABLE__,
- count = __IRQFUNC_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-<tag><tt>plus4</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $02, size = $1A, type = rw;
- RAM: start = $0fff, size = $7001, file = %O;
- }
- SEGMENTS {
- CODE: load = RAM, type = wprot;
- RODATA: load = RAM, type = wprot;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-<tag><tt>cbm510</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $02, size = $1A, type = rw;
- RAM: start = $0001, size = $F3FF, file = %O;
- VIDRAM: start = $F400, size = $0400, define = yes, file = "";
- }
- SEGMENTS {
- CODE: load = RAM, type = wprot;
- RODATA: load = RAM, type = wprot;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = 2,
- label = __IRQFUNC_TABLE__,
- count = __IRQFUNC_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $781; # ~2K stack
- }
-</verb></tscreen>
-
-<tag><tt>cbm610</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $02, size = $1A, type = rw;
- RAM: start = $0001, size = $FFF0, file = %O;
- }
- SEGMENTS {
- CODE: load = RAM, type = wprot;
- RODATA: load = RAM, type = wprot;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-<tag><tt>pet</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $02, size = $1A, type = rw;
- RAM: start = $03FF, size = $7BFF, file = %O;
- }
- SEGMENTS {
- CODE: load = RAM, type = wprot;
- RODATA: load = RAM, type = wprot;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-<tag><tt>apple2</tt></tag>
-<tscreen><verb>
- MEMORY {
- ZP: start = $00, size = $1A, type = rw;
- RAM: start = $800, size = $8E00, file = %O;
- }
- SEGMENTS {
- CODE: load = RAM, type = ro;
- RODATA: load = RAM, type = ro;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- ZEROPAGE: load = ZP, type = zp;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
+<sect1>Builtin configurations<p>
-<tag><tt>geos</tt></tag>
-<tscreen><verb>
- MEMORY {
- HEADER: start = $204, size = 508, file = %O;
- RAM: start = $400, size = $5C00, file = %O;
- }
- SEGMENTS {
- HEADER: load = HEADER, type = ro;
- CODE: load = RAM, type = ro;
- RODATA: load = RAM, type = ro;
- DATA: load = RAM, type = rw;
- BSS: load = RAM, type = bss, define = yes;
- }
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
- }
- SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- }
-</verb></tscreen>
-
-</descrip>
-
-The "<tt/start/" attribute for the <tt/RAM/ memory area of the CBM systems is
-two less than the actual start of the basic RAM to account for the two bytes
-load address that is needed on disk and supplied by the startup code.
+The builtin configurations are part of the linker source. They are also
+distributed together with the machine specific binary packages (usually in the
+doc directory) and don't have a special format. So if you need a special
+configuration, it's a good idea to start with the builtin configuration for
+your system. In a first step, just replace <tt/-t target/ by <tt/-C
+configfile/. The go on and modify the config file to suit your needs.
</article>
-
projects / cc65 / blobdiff