From: cuz Date: Tue, 1 Aug 2000 19:57:01 +0000 (+0000) Subject: Replaced the cl65 docs by an sgml version X-Git-Tag: V2.12.0~3262 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=ac8e1702153a92de37fd8625c748971c5c5f430a;p=cc65 Replaced the cl65 docs by an sgml version git-svn-id: svn://svn.cc65.org/cc65/trunk@256 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- diff --git a/doc/cl65.sgml b/doc/cl65.sgml new file mode 100644 index 000000000..76a51993f --- /dev/null +++ b/doc/cl65.sgml @@ -0,0 +1,206 @@ + + +
+cl65 Users Guide +<author>Ullrich von Bassewitz, <tt/uz@musoftware.de/ +<date>01.08.2000 +<abstract>cl65 is the compile & link utility for cc65. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<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 +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. + +<tscreen><verb> +--------------------------------------------------------------------------- +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 + +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 +--------------------------------------------------------------------------- +</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 +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/ +switch. + +There are a few remaining options that control the behaviour of cl65: + +<descrip> + + <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 + are ignored. + + + <tag><tt>-c</tt></tag> + + This options forces cl65 to stop after the assembly step. This 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 + 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 + used for all of them, which makes the option pretty useless. You + shouldn't use -o when more than one output file is created. + + + <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. + +</descrip> + + + +<sect>More usage<p> + +Since 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> 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> 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. +</itemize> + + +<sect>Examples<p> + +The morse trainer software, which consists of one C file (morse.c) and one +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 +</verb></tscreen> + +When using cl65, this is simplified to + +<tscreen><verb> + 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 $< +</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="uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +cl65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +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. +</enum> + + + +</article> + diff --git a/doc/cl65.txt b/doc/cl65.txt deleted file mode 100644 index 88c9cd60c..000000000 --- a/doc/cl65.txt +++ /dev/null @@ -1,210 +0,0 @@ - - - cl65 - - Compile and link utility for cc65 - - (C) Copyright 1998-2000 Ullrich von Bassewitz - (uz@musoftware.de) - - - -Contents --------- - - 1. Overview - - 2. Basic Usage - - 3. More usage - - 4. Examples - - 5. Bugs/Feedback - - 6. Copyright - - - -1. Overview ------------ - -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 -available, and the use of cl65 is much simpler. - - - -2. Basic Usage --------------- - -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. - ---------------------------------------------------------------------------- -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 - -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 ---------------------------------------------------------------------------- - -Most of the options have the same meaning than the corresponding compiler, -assembler or linker option. See the documentation for these 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 -v: -The compiler, the assembler and the linker are all called with the -v -switch. - -There are a few remaining options that control the behaviour of cl65: - - -S - - 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 - are ignored. - - - -c - - This options forces cl65 to stop after the assembly step. This 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 - given on the command line are ignored. - - - -o name - - 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 - used for all of them, which makes the option pretty useless. You - shouldn't use -o when more than one output file is created. - - - -t sys - --target sys - - 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. - - - -3. More usage -------------- - -Since cl65 was created to simplify the use of the cc65 development -package, it tries to be smart about several things. - - - If you don't give a target system on the command line, cl65 - defaults to the C64. - - - 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. - - - 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. - - - -4. Examples ------------ - -The morse trainer software, which consists of one C file (morse.c) and one -assembler file (irq.s) will need the following separate steps to compile -into an executable named morse: - - 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 - -When using cl65, this is simplified to - - cl65 -g -Oi morse.c irq.s - - -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 - - .c.o: - cl65 -g -Oi $< - -to do this. - - - -5. Bugs/Feedback ----------------- - -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 (uz@musoftware.de). - - - -6. Copyright ------------- - -cl65 is (C) Copyright 1998-2000 Ullrich von Bassewitz. For usage of the -binaries and/or sources the following conditions do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -1. 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. -2. Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -3. This notice may not be removed or altered from any source - distribution. - - -