-<!doctype linuxdoc system>
+<!doctype linuxdoc system> <!-- -*- text-mode -*- -->
<article>
<title>ld65 Users Guide
--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)
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 for the output file. However, for the default configurations, this
name is used for the output file name.
<tag><tt>-t sys, --target sys</tt></tag>
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
+ switch will activate a default configuration, it may not be used together
with the <tt><ref id="option-C" name="-C"></tt> option. The following target
systems are currently supported:
<item>apple2
<item>apple2enh
<item>atari
+ <item>atarixl
<item>atmos
<item>c16 (works also for the c116 with memory up to 32K)
<item>c64
<item>nes
<item>pet (all CBM PET systems except the 2001)
<item>plus4
+ <item>sim6502
+ <item>sim65c02
<item>supervision
<item>vic20
</itemize>
<tag><tt>-S addr, --start-addr addr</tt></tag>
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
+ address is used depends on the config file in use. For the default
configurations, only the "none", "apple2" and "apple2enh" systems honor an
- explicit start address, all other builtin config provide their own.
+ explicit start address, all other default configs provide their own.
<tag><tt>-V, --version</tt></tag>
<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
+Starting with version 2.10, there are now several search-path lists 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:
+The library search-path list 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>Any directory added with the <tt><ref id="option--lib-path"
+ name="--lib-path"></tt> option on the command line.
<item>The value of the environment variable <tt/LD65_LIB/ if it is defined.
<item>A subdirectory named <tt/lib/ of the directory defined in the environment
variable <tt/CC65_HOME/, if it is defined.
-<item>Any directory added with the <tt><ref id="option--lib-path"
- name="--lib-path"></tt> option on the command line.
+<item>An optionally compiled-in library path.
</enum>
<sect1>Object file search path<p>
-The object file search path contains in this order:
+The object file search-path list contains in this order:
<enum>
<item>The current directory.
-<item>A compiled in directory which is often <tt>/usr/lib/cc65/obj</tt> on
- Linux systems.
+<item>Any directory added with the <tt><ref id="option--obj-path"
+ name="--obj-path"></tt> option on the command line.
<item>The value of the environment variable <tt/LD65_OBJ/ if it is defined.
<item>A subdirectory named <tt/obj/ of the directory defined in the environment
variable <tt/CC65_HOME/, if it is defined.
-<item>Any directory added with the <tt><ref id="option--obj-path"
- name="--obj-path"></tt> option on the command line.
+<item>An optionally compiled-in directory.
</enum>
<sect1>Config file search path<p>
-The config file search path contains in this order:
+The config file search-path list contains in this order:
<enum>
<item>The current directory.
-<item>A compiled in directory which is often <tt>/usr/lib/cc65/cfg</tt> on
- Linux systems.
+<item>Any directory added with the <tt><ref id="option--cfg-path"
+ name="--cfg-path"></tt> option on the command line.
<item>The value of the environment variable <tt/LD65_CFG/ if it is defined.
<item>A subdirectory named <tt/cfg/ of the directory defined in the environment
variable <tt/CC65_HOME/, 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.
+<item>An optionally compiled-in directory.
</enum>
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. This is useful, if the a memory area has segments assigned that are
-empty (for example because they are of type bss). In that case, the linker
-will create an empty output file. This may be suppressed by assigning an empty
-file name to that memory area.
+to it. This is useful, if the memory area has segments assigned that are empty
+(for example because they are of type bss). In that case, the linker will
+create an empty output file. This may be suppressed by assigning an empty file
+name to that memory area.
The <tt/%O/ sequence is also allowed inside a string. So using
unfortunately, ROM is not writable, so we have to copy it into RAM before
running the actual code.
-The linker cannot help you copying the data from ROM into RAM (this must be
-done by the startup code of your program), but it has some features that will
-help you in this process.
+The linker won't copy the data from ROM into RAM for you (this must be done by
+the startup code of your program), but it has some features that will help you
+in this process.
First, you may not only specify a "<tt/load/" attribute for a segment, but
also a "<tt/run/" attribute. The "<tt/load/" attribute is mandatory, and, if
All references to labels in the <tt/DATA/ segment are relocated to <tt/RAM2/
by the linker, so things will work properly.
+There's a library subroutine called <tt/copydata/ (in a module named
+<tt/copydata.s/) that might be used to do actual copying. Be sure to have a
+look at it's inner workings before using it!
+
<sect1>Other MEMORY area attributes<p>
Unused memory in a memory area may be filled. Use the "<tt/fill = yes/"
attribute to request this. The default value to fill unused space is zero. If
you don't like this, you may specify a byte value that is used to fill these
-areas with the "<tt/fillval/" attribute. This value is also used to fill unfilled
-areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/ directives.
+areas with the "<tt/fillval/" attribute. If there is no "<tt/fillval/"
+attribute for the segment, the "<tt/fillval/" attribute of the memory area (or
+its default) is used instead. This means that the value may also be used to
+fill unfilled areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/
+directives.
The symbol <tt/%S/ may be used to access the default start address (that is,
the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the
been specified. There are no special attributes to set start or offset for
just the load memory area.
+A "<tt/fillval/" attribute may not only be specified for a memory area, but
+also for a segment. The value must be an integer between 0 and 255. It is used
+as fill value for space reserved by the assemblers <tt/.ALIGN/ and <tt/.RES/
+commands. It is also used as fill value for space between sections (part of a
+segment that comes from one object file) caused by alignment, but not for
+space that preceeds the first section.
+
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
Please note that the order of entries with equal priority is undefined.
+ <tag><tt>import</tt></tag>
+
+ This attribute defines a valid symbol name, that is added as an import
+ to the modules defining a constructor/desctructor of the given type.
+ This can be used to force linkage of a module if this module exports the
+ requested symbol.
+
</descrip>
Without specifying the <tt/CONDES/ feature, the linker will not create any
-<sect1>Builtin configurations<p>
-
-The builtin configurations are part of the linker source. They can be retrieved
-with <tt/--dump-config/ 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/. Then go on and modify the config file to suit your needs.
-
-
-
-<sect1>Secondary configurations<p>
-
-Several machine specific binary packages are distributed together with secondary
-configurations (in the cfg directory). These configurations can be used with
-<tt/-C configfile/ too.
-
-
-
<sect>Special segments<p>
The builtin config files do contain segments that have a special meaning for
-<sect>Bugs/Feedback<p>
-
-If you have problems using the linker, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
<sect>Copyright<p>
ld65 (and all cc65 binutils) are (C) Copyright 1998-2005 Ullrich von
projects / cc65 / blobdiff