X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fcl65.sgml;h=0291f2eb31cc22ab423cab2b07459006f7868b09;hb=HEAD;hp=fd0feff5699c3b790d7394e32b113dab467df118;hpb=e1085adfc37d0ce564396e9e7b6754afc01ce542;p=cc65 diff --git a/doc/cl65.sgml b/doc/cl65.sgml index fd0feff56..0291f2eb3 100644 --- a/doc/cl65.sgml +++ b/doc/cl65.sgml @@ -2,8 +2,8 @@
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 @@ -34,152 +34,247 @@ and other things. --------------------------------------------------------------------------- Usage: cl65 [options] file [...] Short options: - -c Compile and assemble but don't link - -d Debug mode - -g Add debug info - -h Help (this text) - -l Create an assembler listing - -m name Create a map file - -o name Name the output file - -r Enable register variables - -t sys Set the target system - -v Verbose mode - -vm Verbose map file - -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 - -T Include source as comment - -V Print the version number - -W Suppress warnings + -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 + -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 more code + -Or Optimize code, honour the register keyword + -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 - --ansi Strict ANSI mode - --asm-include-dir dir Set an assembler include directory - --bss-label name Define and export a BSS segment label - --bss-name seg Set the name of the BSS segment - --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 - --cpu type Set cpu type - --create-dep Create a 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 - --help Help (this text) - --include-dir dir Set a compiler include directory path - --listing Create an assembler listing - --mapfile name Create a map file - --module Link as a module - --module-id id Specify a module id for the linker - --o65-model model Override the o65 model - --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 - --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 + --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 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 + --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 + --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> -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 choosen 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 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 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 +(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>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. +extensions. <sect>Examples<p> @@ -189,41 +284,33 @@ assembler file (irq.s) will need the following separate steps to compile into an executable named morse: <tscreen><verb> - 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 + 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-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: @@ -236,17 +323,16 @@ including commercial applications, and to alter it and redistribute it 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> -