From 5afb710f9801ff697969e9e07a469e72356100f7 Mon Sep 17 00:00:00 2001
From: cuz <cuz@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Thu, 29 May 2003 10:15:29 +0000
Subject: [PATCH] Added docs for search paths. Removed builtin configs - It's
 too difficult to keep them up-to-date.

git-svn-id: svn://svn.cc65.org/cc65/trunk@2179 b7a2c559-68d2-44c3-8de9-860c34a00d81
---
 doc/ld65.sgml | 432 +++++++-------------------------------------------
 1 file changed, 58 insertions(+), 374 deletions(-)

diff --git a/doc/ld65.sgml b/doc/ld65.sgml
index c8e001158..49ba18758 100644
--- a/doc/ld65.sgml
+++ b/doc/ld65.sgml
@@ -55,25 +55,31 @@ The linker is called as follows:
 ---------------------------------------------------------------------------
 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
+  -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
 
 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
+  --dump-config name    Dump a builtin configuration
+  --help                Help (this text)
+  --lib-path path       Specify a library search path
+  --mapfile name        Create a map file
+  --module-id id        Specify a module id
+  --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>
 
@@ -129,11 +135,13 @@ Here is a description of all the command line options:
   <item>cbm610 (all CBM series-II computers with 80 column video)
   <item>pet (all CBM PET systems except the 2001)
   <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">
@@ -161,6 +169,14 @@ Here is a description of all the command line options:
   id="option-t" name="-t"></tt>.
 
 
+  <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 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
@@ -189,6 +205,23 @@ Here is a description of all the command line options:
   This option print the version number of the linker. If you send any
   suggestions or bugfixes, please include this number.
 
+
+  <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 and in the list of directories
+  specified using <tt/--cfg-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 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
@@ -730,363 +763,14 @@ url="ca65.html" name="ca65 manual">.
 
 
 
-<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>atmos</tt></tag>
-<tscreen><verb>
-        MEMORY {
-            ZP: start = $02, size = $1A, type = rw, define = yes;
-            RAM: start = $0600, size = $9200, 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>c16</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>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>
-
-<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>
+<sect1>Builtin configurations<p>
 
-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.
 
 
 
-- 
2.39.5