From ca1b9deb592e25889f75cc0a9f32b198e8de011c Mon Sep 17 00:00:00 2001 From: Greg King Date: Wed, 24 May 2017 16:47:12 -0400 Subject: [PATCH] Added a description of the "-E" command-line option to cl65's document. Improved other descriptions, to make them more consistent and accurate. --- doc/cl65.sgml | 91 +++++++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 40 deletions(-) diff --git a/doc/cl65.sgml b/doc/cl65.sgml index ffeba2321..8b3c02cbb 100644 --- a/doc/cl65.sgml +++ b/doc/cl65.sgml @@ -2,8 +2,9 @@
cl65 Users Guide -<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz"> -<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"> +<date>2017-05-24 <abstract> cl65 is the compile & link utility for cc65, the 6502 C compiler. It was @@ -50,6 +51,7 @@ Short options: -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 @@ -120,56 +122,66 @@ Long options: --------------------------------------------------------------------------- </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 + 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 + 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. @@ -177,10 +189,10 @@ There are a few remaining options that control the behaviour of cl65: 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. @@ -188,10 +200,10 @@ There are a few remaining options that control the behaviour of cl65: 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 + 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. @@ -199,10 +211,10 @@ There are a few remaining options that control the behaviour of cl65: 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> @@ -211,7 +223,7 @@ There are a few remaining options that control the behaviour of cl65: <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> @@ -219,15 +231,14 @@ package, it tries to be smart about several things. <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. + 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 @@ -248,7 +259,7 @@ 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/