the symbol was referenced.
<item> Flexible output. The output of ld65 is highly configurable by a config
the symbol was referenced.
<item> Flexible output. The output of ld65 is highly configurable by a config
that may be activated by naming the target system. The output
generation was designed with different output formats in mind, so
adding other formats shouldn't be a great problem.
that may be activated by naming the target system. The output
generation was designed with different output formats in mind, so
adding other formats shouldn't be a great problem.
Start a library group. The libraries specified within a group are searched
multiple times to resolve crossreferences within the libraries. Normally,
Start a library group. The libraries specified within a group are searched
multiple times to resolve crossreferences within the libraries. Normally,
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
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
name for the output file. However, for the default configurations, this
name is used for the output file name.
name for the output file. However, for the default configurations, this
name is used for the output file name.
- <item>cbm510 (CBM-II series with 40 column video)
- <item>cbm610 (all CBM series-II computers with 80 column video)
+ <item>cbm510 (CBM-II series with 40-column video)
+ <item>cbm610 (all CBM series-II computers with 80-column video)
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.
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 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
+ 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,
for the target machine is used.
Please note that the symbol name needs to have the internal representation,
Must be used in conjunction with <tt><ref id="option-m" name="-m"></tt>
(generate map file). Normally the map file will not include empty segments
and sections, or unreferenced symbols. Using this option, you can force the
Must be used in conjunction with <tt><ref id="option-m" name="-m"></tt>
(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.
+ linker to include all that information into the map file. Also, it will
+ include a second <tt/Exports/ list. The first list is sorted by name;
+ the second one is sorted by value.
This option allows to define an external symbol on the command line. Value
may start with a '$' sign or with <tt/0x/ for hexadecimal values,
This option allows to define an external symbol on the command line. Value
may start with a '$' sign or with <tt/0x/ for hexadecimal values,
- otherwise a leading zero denotes octal values. See also the <ref
- id="SYMBOLS" name="SYMBOLS section"> in the configuration file.
+ otherwise a leading zero denotes octal values. See also <ref
+ id="SYMBOLS" name="the SYMBOLS section"> in the configuration file.
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
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/.
+ without a path are searched in the current directory, in the list of
+ directories specified using <tt/--lib-path/, in directories given by
+ environment variables, and in a built-in default directory.
- bugs in the label code. If you have problems, please get the latest VICE
- version.
+ bugs in the label code. If you have problems, please get the latest <url
+ url="http://vice-emu.sourceforge.net/" name="VICE"> version.
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
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/.
+ its name is searched in the current directory, in the list of directories
+ specified using <tt/--cfg-path/, in directories given by environment variables,
+ and in a built-in default directory.
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>
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>
of just naming the object file, if the linker is not able to determine the
file type because of an unusual extension.
of just naming the object file, if the linker is not able to determine the
file type because of an unusual extension.
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
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/.
+ passed to the linker that has no path in its name is searched in the current
+ directory, in the list of directories specified using <tt/--obj-path/, in
+ directories given by environment variables, and in a built-in default directory.
special naming conventions), all modules in the library are checked if an
export from this module would satisfy an import from other modules. All
modules where this is the case are marked. If duplicate identifiers are
special naming conventions), all modules in the library are checked if an
export from this module would satisfy an import from other modules. All
modules where this is the case are marked. If duplicate identifiers are
library may only satisfy references for object modules (given directly or from
a library) named <em/before/ that library. With the command line
<tscreen><verb>
library may only satisfy references for object modules (given directly or from
a library) named <em/before/ that library. With the command line
<tscreen><verb>
-the module test.o may not contain references to modules in the library
-clib.lib. If this is the case, you have to change the order of the modules
+the module <tt/test.o/ must not contain references to modules in the library
+<tt/clib.lib/. But, if it does, you have to change the order of the modules
After that, the linker is ready to produce an output file. Before doing that,
it checks its data for consistency. That is, it checks for unresolved
externals (if the output format is not relocatable) and for symbol type
After that, the linker is ready to produce an output file. Before doing that,
it checks its data for consistency. That is, it checks for unresolved
externals (if the output format is not relocatable) and for symbol type
And, last step, if you give the <tt><ref id="option-v" name="-v"></tt> switch
twice, you get a dump of the segment data. However, this may be quite
And, last step, if you give the <tt><ref id="option-v" name="-v"></tt> switch
twice, you get a dump of the segment data. However, this may be quite
- MEMORY {
- RAM1: start = $0800, size = $9800;
- ROM1: start = $A000, size = $2000;
- RAM2: start = $C000, size = $1000;
- ROM2: start = $E000, size = $2000;
- }
+ MEMORY {
+ RAM1: start = $0800, size = $9800;
+ ROM1: start = $A000, size = $2000;
+ RAM2: start = $C000, size = $1000;
+ ROM2: start = $E000, size = $2000;
+ }
(before the colon) are arbitrary names that must start with a letter, with
the remaining characters being letters or digits. The names of the memory
areas are used when assigning segments. As mentioned above, case is
(before the colon) are arbitrary names that must start with a letter, with
the remaining characters being letters or digits. The names of the memory
areas are used when assigning segments. As mentioned above, case is
The syntax above is used in all sections of the config file. The name
(<tt/ROM1/ etc.) is said to be an identifier, the remaining tokens up to the
The syntax above is used in all sections of the config file. The name
(<tt/ROM1/ etc.) is said to be an identifier, the remaining tokens up to the
- SEGMENTS {
- CODE: load = RAM1, type = ro;
- RODATA: load = RAM1, type = ro;
- DATA: load = RAM1, type = rw;
- BSS: load = RAM1, type = bss, define = yes;
- }
+ SEGMENTS {
+ CODE: load = RAM1, type = ro;
+ RODATA: load = RAM1, type = ro;
+ DATA: load = RAM1, type = rw;
+ BSS: load = RAM1, type = bss, define = yes;
+ }
</verb></tscreen>
What we are doing here is telling the linker, that all segments go into the
<tt/RAM1/ memory area in the order specified in the <tt/SEGMENTS/ section. So
the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/
segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/
</verb></tscreen>
What we are doing here is telling the linker, that all segments go into the
<tt/RAM1/ memory area in the order specified in the <tt/SEGMENTS/ section. So
the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/
segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/
For a <tt/bss/ type segment to be useful, it must be cleared somehow by your
program (this happens usually in the startup code - for example the startup
For a <tt/bss/ type segment to be useful, it must be cleared somehow by your
program (this happens usually in the startup code - for example the startup
code know, where the segment starts, and how big it is? The linker is able to
give that information, but you must request it. This is, what we're doing with
the "<tt/define = yes/" attribute in the <tt/BSS/ definitions. For each
segment, where this attribute is true, the linker will export three symbols.
<tscreen><verb>
code know, where the segment starts, and how big it is? The linker is able to
give that information, but you must request it. This is, what we're doing with
the "<tt/define = yes/" attribute in the <tt/BSS/ definitions. For each
segment, where this attribute is true, the linker will export three symbols.
<tscreen><verb>
- __NAME_LOAD__ This is set to the address where the
- segment is loaded.
- __NAME_RUN__ This is set to the run address of the
- segment. We will cover run addresses
- later.
- __NAME_SIZE__ This is set to the segment size.
+ __NAME_LOAD__ This is set to the address where the
+ segment is loaded.
+ __NAME_RUN__ This is set to the run address of the
+ segment. We will cover run addresses
+ later.
+ __NAME_SIZE__ This is set to the segment size.
write the area data into. If there is no file name given, the linker will
assign the default file name. This is "a.out" or the one given with the
<tt><ref id="option-o" name="-o"></tt> option on the command line. Since the
write the area data into. If there is no file name given, the linker will
assign the default file name. This is "a.out" or the one given with the
<tt><ref id="option-o" name="-o"></tt> option on the command line. Since the
example above. Let's have a look at it now.
The "file" attribute (the keyword may also be written as "FILE" if you like
example above. Let's have a look at it now.
The "file" attribute (the keyword may also be written as "FILE" if you like
file, where the data is written. You may specify the same file several times,
in that case the data for all memory areas having this file name is written
into this file, in the order of the memory areas defined in the <tt/MEMORY/
section. Let's specify some file names in the <tt/MEMORY/ section used above:
<tscreen><verb>
file, where the data is written. You may specify the same file several times,
in that case the data for all memory areas having this file name is written
into this file, in the order of the memory areas defined in the <tt/MEMORY/
section. Let's specify some file names in the <tt/MEMORY/ section used above:
<tscreen><verb>
- MEMORY {
- RAM1: start = $0800, size = $9800, file = %O;
- ROM1: start = $A000, size = $2000, file = "rom1.bin";
- RAM2: start = $C000, size = $1000, file = %O;
- ROM2: start = $E000, size = $2000, file = "rom2.bin";
- }
+ MEMORY {
+ RAM1: start = $0800, size = $9800, file = %O;
+ ROM1: start = $A000, size = $2000, file = "rom1.bin";
+ RAM2: start = $C000, size = $1000, file = %O;
+ ROM2: start = $E000, size = $2000, file = "rom2.bin";
+ }
- MEMORY {
- ROM1: start = $A000, size = $2000, file = "%O-1.bin";
- ROM2: start = $E000, size = $2000, file = "%O-2.bin";
- }
+ MEMORY {
+ ROM1: start = $A000, size = $2000, file = "%O-1.bin";
+ ROM2: start = $E000, size = $2000, file = "%O-2.bin";
+ }
</verb></tscreen>
Since <tt/BSS/ is not initialized, we must not care about it now, but what
about <tt/DATA/? <tt/DATA/ contains initialized data, that is, data that was
explicitly assigned a value. And your program will rely on these values on
</verb></tscreen>
Since <tt/BSS/ is not initialized, we must not care about it now, but what
about <tt/DATA/? <tt/DATA/ contains initialized data, that is, data that was
explicitly assigned a value. And your program will rely on these values on
-startup. Since there's no other way to remember the contents of the data
-segment, than storing it into one of the ROMs, we have to put it there. But
+startup. Since there's no way to remember the contents of the data segment,
+other than storing it into one of the ROMs, we have to put it there. But
- SEGMENTS {
- CODE: load = ROM1, type = ro;
- RODATA: load = ROM2, type = ro;
- DATA: load = ROM2, run = RAM2, type = rw, define = yes;
- BSS: load = RAM2, type = bss, define = yes;
- }
+ SEGMENTS {
+ CODE: load = ROM1, type = ro;
+ RODATA: load = ROM2, type = ro;
+ DATA: load = ROM2, run = RAM2, type = rw, define = yes;
+ BSS: load = RAM2, type = bss, define = yes;
+ }
- __DATA_LOAD__ This is set to the address where the segment
- 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.
- __DATA_SIZE__ This is set to the segment size.
+ __DATA_LOAD__ This is set to the address where the segment
+ 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.
+ __DATA_SIZE__ This is set to the segment size.
reference section, I will discuss the remaining things here.
You may request symbols definitions also for memory areas. This may be
reference section, I will discuss the remaining things here.
You may request symbols definitions also for memory areas. This may be
- __STACK_START__ This is set to the start of the memory
- area, $C000 in this example.
- __STACK_SIZE__ The size of the area, here $1000.
- __STACK_LAST__ This is NOT the same as START+SIZE.
- Instead, it it defined as the first
- address that is not used by data. If we
- don't define any segments for this area,
- the value will be the same as START.
+ __STACK_START__ This is set to the start of the memory
+ area, $C000 in this example.
+ __STACK_SIZE__ The size of the area, here $1000.
+ __STACK_LAST__ This is NOT the same as START+SIZE.
+ Instead, it is defined as the first
+ address that is not used by data. If we
+ don't define any segments for this area,
+ the value will be the same as START.
__STACK_FILEOFFS__ The binary offset in the output file. This
is not defined for relocatable output file
formats (o65).
__STACK_FILEOFFS__ The binary offset in the output file. This
is not defined for relocatable output file
formats (o65).
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
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
value given on the command line with the <tt><ref id="option-S" name="-S"></tt>
option).
To support systems with banked memory, a special attribute named <tt/bank/ is
value given on the command line with the <tt><ref id="option-S" name="-S"></tt>
option).
To support systems with banked memory, a special attribute named <tt/bank/ is
has a builtin function named <tt/.BANK/ which may be used with an argument
that has a segment reference (for example a symbol). The result of this
function is the value of the bank attribute for the run memory area of the
has a builtin function named <tt/.BANK/ which may be used with an argument
that has a segment reference (for example a symbol). The result of this
function is the value of the bank attribute for the run memory area of the
- SEGMENTS {
- CODE: load = ROM1, type = ro, align = $100;
- RODATA: load = ROM2, type = ro, align = $100;
- DATA: load = ROM2, run = RAM2, type = rw, define = yes,
- align = $100;
- BSS: load = RAM2, type = bss, define = yes, align = $100;
- }
+ SEGMENTS {
+ CODE: load = ROM1, type = ro, align = $100;
+ RODATA: load = ROM2, type = ro, align = $100;
+ DATA: load = ROM2, run = RAM2, type = rw, define = yes,
+ align = $100;
+ BSS: load = RAM2, type = bss, define = yes, align = $100;
+ }
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
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
+as the fill value for space reserved by the assembler's <tt/.ALIGN/ and <tt/.RES/
+commands. It is also used as the 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
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
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.
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.
The <tt/FORMAT/ section is used to describe file formats. The default (binary)
format has currently no attributes, so, while it may be listed in this
The <tt/FORMAT/ section is used to describe file formats. The default (binary)
format has currently no attributes, so, while it may be listed in this
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- }
+ FEATURES {
+ CONDES: segment = RODATA,
+ type = constructor,
+ label = __CONSTRUCTOR_TABLE__,
+ count = __CONSTRUCTOR_COUNT__;
+ }
<tag><tt>label</tt></tag>
This specifies the label to use for the table. The label points to the start
<tag><tt>label</tt></tag>
This specifies the label to use for the table. The label points to the start
<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
<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
<tag><tt>import</tt></tag>
This attribute defines a valid symbol name, that is added as an import
<tag><tt>import</tt></tag>
This attribute defines a valid symbol name, that is added as an import