<article>
<title>cl65 Users Guide
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>01.08.2000, 27.11.2000, 02.10.2001
+<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
<abstract>
cl65 is the compile & link utility for cc65, the 6502 C compiler. It was
-o name Name the output file
-r Enable register variables
-t sys Set the target system
- -u sym Force an import of symbol `sym'
+ -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
+ -E Stop after the preprocessing stage
-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
+ -Oi Optimize code, inline more code
-Or Optimize code, honour the register keyword
- -Os Optimize code, inline known C funtions
+ -Os Optimize code, inline standard 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:
--add-source Include source as comment
+ --all-cdecl Make functions default to __cdecl__
--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 assembker binary 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
--debug Debug mode
--debug-info Add debug info
--feature name Set an emulation feature
- --force-import sym Force an import of symbol `sym'
- --forget-inc-paths Forget include search paths (compiler)
+ --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
--memory-model model Set the memory model
--module Link as a module
--module-id id Specify a module id for the linker
+ --no-target-lib Don't link the target library
--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
---------------------------------------------------------------------------
</verb></tscreen>
-Most of the options have the same meaning than the corresponding compiler,
-assembler or linker option. See the documentation for these tools for an
+Most of the options have the same meanings as the corresponding compiler,
+assembler, and linker options. See the documentation for those tools for an
explanation. If an option is available for more than one of the tools, it
-is set for all tools, where it is available. One example for this is <tt/-v/:
-The compiler, the assembler and the linker are all called with the <tt/-v/
+is set for all tools where it is available. One example for that is <tt/-v/:
+The compiler, the assembler, and the linker are all called with the <tt/-v/
switch.
There are a few remaining options that control the behaviour of cl65:
<descrip>
+ <tag><tt>-E</tt></tag>
+
+ This option is passed to the cc65 compiler; and, it forces cl65 to stop
+ before the assembly step. That means that C-level preprocessor directives
+ are obeyed; and, macroes are expanded. But, the C source isn't compiled.
+ If the <tt/-o/ option isn't used, then the C code results are written into
+ files with a ".i" suffix on their base names. Assembler files, object
+ files, and libraries given on the command line are ignored.
+
+
<tag><tt>-S</tt></tag>
- This option forces cl65 to stop after the assembly step. This means that
- C files are translated into assembler files, but nothing more is done.
- Assembler files, object files and libraries given on the command line
+ This option forces cl65 to stop before the assembly step. That means that
+ C files are translated into assembler files; but, nothing more is done.
+ Assembler files, object files, and libraries given on the command line
are ignored.
<tag><tt>-c</tt></tag>
- This options forces cl65 to stop after the assembly step. This means
+ This option forces cl65 to stop after the assembly step. That means
that C and assembler files given on the command line are translated into
- object files, but there is no link step, and object files and libraries
+ object files; but, there is no link step. Object files and libraries
given on the command line are ignored.
<tag><tt>-o name</tt></tag>
- The -o option is used for the target name in the final step. This causes
- problems, if the linker will not be called, and there are several input
- files on the command line. In this case, the name given with -o will be
+ The -o option is used for the target name in the final step. That causes
+ problems if the linker will not be called, and there are several input
+ files on the command line. In that case, the name given with -o will be
used for all of them, which makes the option pretty useless. You
- shouldn't use -o when more than one output file is created.
+ shouldn't use <tt/-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. That 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 other tools (compiler, assembler
+ 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
+ "c64" as a target system by default. That was chosen because most people
seem to use cc65 to develop for the C64.
+
+ <tag><tt>--no-target-lib</tt></tag>
+
+ This option tells the cl65 to not include the target library into the list
+ of libraries.
+
+
+
<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
+ commas; the commas are replaced by spaces when passing them to the
+ assembler. Beware: Passing arguments directly to the assembler might 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 that 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 might 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 that 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
+ commas; the commas are replaced by spaces when passing them to the linker.
+ Beware: Passing arguments directly to the linker might 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 that option to the linker by means
of the <tt/-Wl/ switch.
</descrip>
<sect>More usage<p>
-Since cl65 was created to simplify the use of the cc65 development
+Because cl65 was created to simplify the use of the cc65 development
package, it tries to be smart about several things.
<itemize>
-<item> If you don't give a target system on the command line, cl65
- defaults to the C64.
+<item> If you don't give a target system on the command line, cl65
+ defaults to the C64.
-<item> When linking, cl65 will supply the names of the startup file and
- library for the target system to the linker, so you don't have to do
- that.
+<item> When linking, cl65 will supply the name of the library file for
+ the target system to the linker; so, you don't have to do that.
-<item> If the final step is the linker, and the name of the output file was
- not explicitly given, cl65 will use the name of the first input file
- without the extension, provided that the name of this file has an
- extension. So you don't need to name the executable name in most
- cases, just give the name of your "main" file as first input file.
+<item> If the final step is the linker, and the name of the output file was
+ not explicitly given, cl65 will use the name of the first input file
+ without the extension, provided that the name of that file has an
+ extension. So, you don't need to give the executable name in most
+ cases; just give the name of your "main" file as the first input file.
</itemize>
The command line is parsed from left to right, and the actual processing tool
<itemize>
<item>C files: <tt/.c/
<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/
-<item>Object files: <tt/.o/ <tt/.obj/
+<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/
into an executable named morse:
<tscreen><verb>
- cc65 -g -Oi -t c64 morse.c
- ca65 -g morse.s
- ca65 -g irq.s
- ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib
+ cc65 -g -Oi -t c64 morse.c
+ ca65 -g morse.s
+ ca65 -g irq.s
+ ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib
</verb></tscreen>
When using cl65, this is simplified to
<tscreen><verb>
- cl65 -g -Oi morse.c irq.s
+ cl65 -g -Oi morse.c irq.s
</verb></tscreen>
As a general rule, you may use cl65 instead of cc65 at most times,
especially in makefiles to build object files directly from C files. Use
<tscreen><verb>
- .c.o:
- cl65 -g -Oi $<
+ .c.o:
+ cl65 -g -Oi $<
</verb></tscreen>
to do this.
-<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="mailto:uz@cc65.org" name="uz@cc65.org">).
-
-
-
<sect>Copyright<p>
cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von
freely, subject to the following restrictions:
<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
+<item> The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+<item> Altered source versions must be plainly marked as such, and must not
+ be misrepresented as being the original software.
+<item> This notice may not be removed or altered from any source
+ distribution.
</enum>
</article>
-
projects / cc65 / blobdiff