<article>
<title>cl65 Users Guide
-<author>Ullrich von Bassewitz, <tt/uz@musoftware.de/
-<date>01.08.2000
-<abstract>cl65 is the compile & link utility for cc65.
+<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
+<date>01.08.2000, 27.11.2000, 02.10.2001
+
+<abstract>
+cl65 is the compile & link utility for cc65, the 6502 C compiler. It was
+designed as a smart frontend for the C compiler (cc65), the assembler (ca65),
+the object file converter (co65), and the linker (ld65).
</abstract>
<!-- Table of contents -->
<sect>Overview<p>
-cl65 is a frontend for cc65, ca65 and ld65. While you may not use the full
-power of the tools when calling them through cl65, most features are
+cl65 is a frontend for cc65, ca65, co65 and ld65. While you may not use the
+full power of the tools when calling them through cl65, most features are
available, and the use of cl65 is much simpler.
<sect>Basic Usage<p>
-The cl65 compile and link utility may be used to compile, assemble and
-link files. While the separate tools do just one step, cl65 knows how to
-build object files from C files (by calling the compiler, then the
-assembler) and other things.
+The cl65 compile and link utility may be used to convert, compile, assemble
+and link files. While the separate tools do just one step, cl65 knows how to
+build object files from C files (by calling the compiler, then the assembler)
+and other things.
<tscreen><verb>
---------------------------------------------------------------------------
-Usage: cl65 [options] file
+Usage: cl65 [options] file [...]
Short options:
- -A Strict ANSI mode
- -C name Use linker config file
- -Cl Make local variables static
- -D sym[=defn] Define a preprocessor symbol
- -I dir Set a compiler include directory path
- -Ln name Create a VICE label file
- -O Optimize code
- -Oi Optimize code, inline functions
- -Or Optimize code, honour the register keyword
- -Os Optimize code, inline known C funtions
- -S Compile but don't assemble and link
- -V Print the version number
- -W Suppress warnings
- -c Compiler and assemble but don't link
- -d Debug mode
- -g Add debug info
- -h Help (this text)
- -m name Create a map file
- -o name Name the output file
- -t sys Set the target system
- -v Verbose mode
- -vm Verbose map file
+ -c Compile and assemble but don't link
+ -d Debug mode
+ -g Add debug info
+ -h Help (this text)
+ -l name Create an assembler listing file
+ -m name Create a map file
+ -mm model Set the memory model
+ -o name Name the output file
+ -r Enable register variables
+ -t sys Set the target system
+ -u sym Force an import of symbol `sym'
+ -v Verbose mode
+ -vm Verbose map file
+ -C name Use linker config file
+ -Cl Make local variables static
+ -D sym[=defn] Define a preprocessor symbol
+ -I dir Set a compiler include directory path
+ -L path Specify a library search path
+ -Ln name Create a VICE label file
+ -O Optimize code
+ -Oi Optimize code, inline functions
+ -Or Optimize code, honour the register keyword
+ -Os Optimize code, inline known C funtions
+ -S Compile but don't assemble and link
+ -T Include source as comment
+ -V Print the version number
+ -W name[,...] Supress compiler warnings
+ -Wa options Pass options to the assembler
+ -Wc options Pass options to the compiler
+ -Wl options Pass options to the linker
Long options:
- --ansi Strict ANSI mode
- --asm-include-dir dir Set an assembler include directory
- --debug Debug mode
- --debug-info Add debug info
- --help Help (this text)
- --include-dir dir Set a compiler include directory path
- --target sys Set the target system
- --version Print the version number
- --verbose Verbose mode
+ --add-source Include source as comment
+ --asm-args options Pass options to the assembler
+ --asm-define sym[=v] Define an assembler symbol
+ --asm-include-dir dir Set an assembler include directory
+ --bin-include-dir dir Set an assembler binary include directory
+ --bss-label name Define and export a BSS segment label
+ --bss-name seg Set the name of the BSS segment
+ --cc-args options Pass options to the compiler
+ --cfg-path path Specify a config file search path
+ --check-stack Generate stack overflow checks
+ --code-label name Define and export a CODE segment label
+ --code-name seg Set the name of the CODE segment
+ --codesize x Accept larger code by factor x
+ --config name Use linker config file
+ --cpu type Set cpu type
+ --create-dep name Create a make dependency file
+ --create-full-dep name Create a full make dependency file
+ --data-label name Define and export a DATA segment label
+ --data-name seg Set the name of the DATA segment
+ --debug Debug mode
+ --debug-info Add debug info
+ --feature name Set an emulation feature
+ --force-import sym Force an import of symbol `sym'
+ --help Help (this text)
+ --include-dir dir Set a compiler include directory path
+ --ld-args options Pass options to the linker
+ --lib file Link this library
+ --lib-path path Specify a library search path
+ --list-targets List all available targets
+ --listing name Create an assembler listing file
+ --list-bytes n Number of bytes per assembler listing line
+ --mapfile name Create a map file
+ --memory-model model Set the memory model
+ --module Link as a module
+ --module-id id Specify a module id for the linker
+ --o65-model model Override the o65 model
+ --obj file Link this object file
+ --obj-path path Specify an object file search path
+ --print-target-path Print the target file path
+ --register-space b Set space available for register variables
+ --register-vars Enable register variables
+ --rodata-name seg Set the name of the RODATA segment
+ --signed-chars Default characters are signed
+ --standard std Language standard (c89, c99, cc65)
+ --start-addr addr Set the default start address
+ --static-locals Make local variables static
+ --target sys Set the target system
+ --version Print the version number
+ --verbose Verbose mode
+ --zeropage-label name Define and export a ZEROPAGE segment label
+ --zeropage-name seg Set the name of the ZEROPAGE segment
---------------------------------------------------------------------------
</verb></tscreen>
shouldn't use -o when more than one output file is created.
+ <tag><tt>--print-target-path</tt></tag>
+
+ This option prints the absolute path of the target file directory and exits
+ then. It is supposed to be used with shell backquotes or the GNU make shell
+ function. This way you can write build scripts or Makefiles accessing target
+ files without any assumption about the cc65 installation path.
+
+
<tag><tt>-t sys, --target sys</tt></tag>
- The default for this option is different from the compiler and linker in
- the case that the option is missing: While the compiler and linker will
- use the "none" system settings by default, cl65 will use the C64 as a
- target system by default. This was choosen since most people seem to use
- cc65 to develop for the C64.
+ The default for this option is different from the compiler and linker in the
+ case that the option is missing: While the other tools (compiler, assembler
+ and linker) will use the "none" system settings by default, cl65 will use
+ the C64 as a target system by default. This was chosen since most people
+ seem to use cc65 to develop for the C64.
+
+
+ <tag><tt>-Wa options, --asm-args options</tt></tag>
+
+ Pass options directly to the assembler. This may be used to pass options
+ that aren't directly supported by cl65. Several options may be separated by
+ commas, the commas are replaced by spaces when passing them to the
+ assembler. Beware: Passing arguments directly to the assembler may interfere
+ with some of the defaults, because cl65 doesn't parse the options passed. So
+ if cl65 supports an option by itself, do not pass this option to the
+ assembler by means of the <tt/-Wa/ switch.
+
+
+ <tag><tt>-Wc options, --cc-args options</tt></tag>
+
+ Pass options directly to the compiler. This may be used to pass options
+ that aren't directly supported by cl65. Several options may be separated by
+ commas, the commas are replaced by spaces when passing them to the
+ compiler. Beware: Passing arguments directly to the compiler may interfere
+ with some of the defaults, because cl65 doesn't parse the options passed. So
+ if cl65 supports an option by itself, do not pass this option to the
+ compiler by means of the <tt/-Wc/ switch.
+
+
+ <tag><tt>-Wl options, --ld-args options</tt></tag>
+
+ Pass options directly to the linker. This may be used to pass options that
+ aren't directly supported by cl65. Several options may be separated by
+ commas, the commas are replaced by spaces when passing them to the linker.
+ Beware: Passing arguments directly to the linker may interfere with some of
+ the defaults, because cl65 doesn't parse the options passed. So if cl65
+ supports an option by itself, do not pass this option to the linker by means
+ of the <tt/-Wl/ switch.
</descrip>
cases, just give the name of your "main" file as first input file.
</itemize>
+The command line is parsed from left to right, and the actual processing tool
+(compiler, assembler, ...) is invoked whenever a file name is encountered.
+This means that only the options to the left of a file name are in effect when
+this file is processed. It does also mean that you're able to specify
+different options for different files on the command line. As an example.
+
+<tscreen><verb>
+ cl65 -Oirs main.c -O -g module.c
+</verb></tscreen>
+
+translates main.c with full optimization and module.c with less optimization
+and debug info enabled.
+
+The type of an input file is derived from its extension:
+
+<itemize>
+<item>C files: <tt/.c/
+<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/
+<item>Object files: <tt/.o/ <tt/.obj/
+<item>Libraries: <tt/.a/, <tt/.lib/
+<item>GEOS resource files: <tt/.grc/
+<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/
+</itemize>
+
+Please note that the program cannot handle input files with unknown file
+extensions.
+
<sect>Examples<p>
cc65 -g -Oi -t c64 morse.c
ca65 -g morse.s
ca65 -g irq.s
- ld65 -t c64 -o morse c64.o morse.o irq.o c64.lib
+ ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib
</verb></tscreen>
When using cl65, this is simplified to
-<sect>Bugs/Feedback<p>
-
-If you have problems using the utility, 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="uz@cc65.org" name="uz@cc65.org">).
-
-
-
<sect>Copyright<p>
-cl65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
+cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von
Bassewitz. For usage of the binaries and/or sources the following
conditions do apply:
</article>
-
projects / cc65 / blobdiff