From 5d34df27c25c18731dde9e309ba9ede08b076d36 Mon Sep 17 00:00:00 2001 From: cuz Date: Sun, 3 Dec 2000 18:34:50 +0000 Subject: [PATCH] More SGML conversions git-svn-id: svn://svn.cc65.org/cc65/trunk@531 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/Makefile | 1 + doc/index.sgml | 2 +- doc/intro.sgml | 222 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/intro.txt | 210 ---------------------------------------------- 4 files changed, 224 insertions(+), 211 deletions(-) create mode 100644 doc/intro.sgml delete mode 100644 doc/intro.txt diff --git a/doc/Makefile b/doc/Makefile index d5201f1c5..074901ec9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -13,6 +13,7 @@ SGML = ar65.sgml \ dio.sgml \ geos.sgml \ index.sgml \ + intro.sgml \ ld65.sgml \ library.sgml diff --git a/doc/index.sgml b/doc/index.sgml index f0003991f..1e4c44fee 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -55,7 +55,7 @@ Main documentation page, contains links to other available stuff. internal.doc - A somewhat older text describing several cc65 internals. - + Describes the use of the tools by a short "hello world" example. diff --git a/doc/intro.sgml b/doc/intro.sgml new file mode 100644 index 000000000..14ec3ab46 --- /dev/null +++ b/doc/intro.sgml @@ -0,0 +1,222 @@ + + +
+ +cc65 compiler intro +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>19.07.2000 + +<abstract> +How to use the cc65 C compiler - an introduction. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This is a short intro, how to use the compiler and the binutils. It contains a +step-by-step example, how to build a complete application from one C and one +assembler module. This file does <em/not/ contain a complete reference for the +tools used in the process. There are separate files describing these tools in +detail. + +<bf>Note</bf>: There is a much simpler way to compile this example using the +cl65 compiler and link utility. However, it makes sense to understand how the +separate steps work. How to do the example with the cl65 utility is described +<ref id="using-cl65" name="below">. + + +<sect1>The sample modules<p> + +To explain the development flow, I will use the following example modules: + +hello.c: + +<tscreen><code> + #include <stdio.h> + #include <stdlib.h> + + extern const char text[]; /* In text.s */ + + int main (void) + { + printf ("%s\n", text); + return EXIT_SUCCESS; + } +</code></tscreen> + +text.s: +<tscreen><code> + .export _text + _text: .asciiz "Hello world!" +</code></tscreen> + + +<sect1>Translation phases<p> + +We assume that the target file should be named "hello", and the target system +is the C64. + +<tscreen><verb> + +---------+ + | hello.c | + +---------+ + | + cc65 + \/ + +---------+ +---------+ + | hello.s | | text.s | + +---------+ +---------+ + | | + ca65 ca65 + \/ \/ + +---------+ +---------+ +----------+ +---------+ + | hello.o | | text.o | | c64.o | | c64.lib | + +---------+ +---------+ +----------+ +---------+ + | \ / | + | \ / | + | \ / | + +----------------------->ld65<-------------------------+ + \/ + hello +</verb></tscreen> + +<tt/c64.o/ (the startup code) and <tt/c64.lib/ (the c64 version of the runtime +and C library) are provided in binary form in the cc65 package. + + + +<sect>The compiler<p> + +The compiler translates one C source into one assembler source for each +invocation. It does <em/not/ create object files directly, and it is <em/not/ +able to translate more than one file per run. + +In the example above, we would use the following command line, to translate +<tt/hello.c/ into <tt/hello.s/: + +<tscreen><verb> + cc65 -O -I ../include -t c64 hello.c +</verb></tscreen> + +The <tt/-O/ switch tells the compiler to do an additional optimizer run, which +is usually a good idea, since it makes the code smaller. If you don't care +about the size, but want to have slightly faster code, use <tt/-Oi/ to inline +some runtime functions. + +The <tt/-I/ switch gives a search path for the include files. You may also set +the environment variable CC65_INC to the search path. + +The <tt/-t/ switch is followed by the target system. + +If the compiler does not complain about errors in our hello world, we will +have a file named "<tt/hello.s/" in our directory that contains the assembler +source for the hello module. + +For more information about the compiler see <htmlurl url="cc65.html" +name="cc65.html">. + + + +<sect>The assembler<p> + +The assembler translates one assembler source into an object file for each +invocation. The assembler is <tt/not/ able to translate more than one source +file per run. + +Let's translate the hello.s and text.s files from our example: + +<tscreen><verb> + ca65 hello.s + ca65 -t c64 text.s +</verb></tscreen> + +The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the +text is converted from the input character set (usually ISO-8859-1) into the +target character set (PETSCII) by the assembler. The compiler generated file +<tt/hello.s/ does not contain any character constants, so specification of a +target is not necessary (it wouldn't do any harm, however). + +If the assembler does not complain, we should now have two object files (named +<tt/hello.o/ and <tt/text.o/) in the current directory. + +For more information about the assembler see <htmlurl url="ca65.html" +name="ca65.html">. + + + +<sect>The linker<p> + +The linker combines several object and library file into one output file. ld65 +is very configurable, but fortunately has a builtin configuration for the C64, +so we don't need to mess with configuration files here. + +The compiler uses small functions to do things that cannot be done inline +without big impact on code size. These runtime functions, together with the C +library are in an object file archive named after the system, in this case +"<tt/c64.lib/". We have to specify this file on the command line so that the +linker can resolve these functions. + +A second file (this time an object file) needed, is the startup code that +prepares the grounds for the C program to run. The startup file must be +executed first, so it must be the first file on the linker command line. + +Let's link our files to get the final executable: + +<tscreen><verb> + ld65 -t c64 -o hello c64.o hello.o text.o c64.lib +</verb></tscreen> + +The argument after <tt/-o/ specifies the name of the output file, the argument +after <tt/-t/ gives the target system. As discussed, the startup file must be +the first file on the command line (you may have to add a path here, if +<tt/c64.o/ is not in your current directory). Since the library resolves +imports in <tt/hello.o/ and <tt/text.o/, it must be specified <em/after/ these +files. + +After a successful linker run, we have a file named "<tt/hello/", ready for +our C64! + +For more information about the linker see <htmlurl url="ld65.html" +name="ld65.html">. + + + +<sect>The easy way (using the cl65 utility)<label id="using-cl65"><p> + +The cl65 utility is able to do all of the steps described above in just one +call, and it has defaults for some options that are very well suited for our +example. + +To compile both files into one executable enter + +<tscreen><verb> + cl65 -O -I ../include hello.c test.s +</verb></tscreen> + +(The <tt/-I/ switch is not needed if you are working under Linux with the +include files in the default path, or the <tt/CC65_INC/ environment variable +is set correctly). + +The cl65 utility knows, how to translate C files into object files (it will +call the compiler and then the assembler). It does also know how to create +object files from assembler files (it will call the assember for that). It +knows how to build an executable (it will pass all object files to the +linker). And, finally, it has the C64 as a default target and will supply the +correct startup file and runtime library names to the linker, so you don't +have to care about that. + +The one-liner above should give you a C64 executable named "<tt/hello/" in the +current directory. + +For more information about the compile & link utility see <htmlurl +url="cl65.html" name="cl65.html">. + + +</article> + + + diff --git a/doc/intro.txt b/doc/intro.txt deleted file mode 100644 index 2c4c79055..000000000 --- a/doc/intro.txt +++ /dev/null @@ -1,210 +0,0 @@ - - - How to use the cc65 C compiler - - Ullrich von Bassewitz, 1998/1999 - - - -Contents --------- - - 1. Overview - - 2. The compiler - - 3. The assembler - - 4. The linker - - 5. The easy way (using the cl65 utility) - - - -1. Overview ------------ - -This is a short intro, how to use the compiler and the binutils. It -contains a step-by-step example, how to build a complete application from -one C and one assembler module. This file does *NOT* contain a complete -reference for the tools used in the process. There are separate files -describing these tools in detail. - -Note: There is a much simpler way to compile this example using the cl65 -compiler and link utility. However, it makes sense to understand how the -separate steps work. How to do the example with the cl65 utility is -described in section 5. - -To explain the development flow, I will use the following example modules: - - -hello.c: - - #include <stdio.h> - #include <stdlib.h> - - extern const char text[]; /* In text.s */ - - int main (void) - { - printf ("%s\n", text); - return EXIT_SUCCESS; - } - - -text.s: - - .export _text - _text: .asciiz "Hello world!" - - -(The example is rather stupid, since the text in text.s does not use the -correct character set for the target machine - conversion is usually done -by the compiler. However, we will ignore that here.) - -We assume that the target file should be named "hello", and the target -system is the C64. - - - +---------+ - | hello.c | - +---------+ - | - cc65 - \/ - +---------+ +---------+ - | hello.s | | text.s | - +---------+ +---------+ - | | - ca65 ca65 - \/ \/ - +---------+ +---------+ +----------+ +---------+ - | hello.o | | text.o | | c64.o | | c64.lib | - +---------+ +---------+ +----------+ +---------+ - | \ / | - | \ / | - | \ / | - +----------------------->ld65<-------------------------+ - \/ - hello - - -c64.o (the startup code) and c64.lib (the c64 version of the runtime and C -library) are provided in binary form in the cc65 package. - - - -2. The compiler ---------------- - -The compiler translates one C source into one assembler source for each -invocation. It does *NOT* create object files directly, and it is *NOT* -able to translate more than one file per run. - -In the example above, we would use the following command line, to -translate hello.c into hello.s: - - cc65 -O -I ../include -t c64 hello.c - -The -O switch tells the compiler to do an additional optimizer run, which -is usually a good idea, since it makes the code smaller. If you don't care -about the size, but want to have slightly faster code, use -Oi to inline -some runtime functions. - -The -I switch gives a search path for the include files. You may also set -the environment variable CC65_INC to the search path. - -The -t switch is followed by the target system. - -If the compiler does not complain about errors in our hello world, we will -have a file named "hello.s" in our directory that contains the assembler -source for the hello module. - -For more information about the compiler see cc65.txt. - - - -3. The assembler ----------------- - -The assembler translates one assembler source into an object file for each -invocation. The assembler is *NOT* able to translate more than one source -file per run. - -Let's translate the hello.s and text.s files from our example: - - ca65 hello.s - ca65 text.s - -If the assembler does not complain, we should now have two object files -(named hello.o and text.o) in the current directory. - -For more information about the assembler see ca65.txt. - - - -4. The linker -------------- - -The linker combines several object and library file into one output file. -ld65 is very configurable, but fortunately has a builtin configuration for -the C64, so we don't need to mess with configuration files here. - -The compiler uses small functions to do things that cannot be done inline -without big impact on code size. These runtime functions, together with -the C library are in an object file archive named after the system, in -this case "c64.lib". We have to specify this file on the command line so -that the linker can resolve these functions. - -A second file (this time an object file) needed, is the startup code that -prepares the grounds for the C program to run. The startup file must be -executed first, so it must be the first file on the linker command line. - -Let's link our files to get the final executable: - - ld65 -t c64 -o hello c64.o hello.o text.o c64.lib - -The argument after -o specifies the name of the output file, the argument -after -t gives the target system. As discussed, the startup file must be the -first file on the command line (you may have to add a path here, if c64.o is -not in your current directory). Since the library resolves imports in hello.o -and text.o, it must be specified *after* these files. - -After a successful linker run, we have a file named "hello", ready for our -C64! - -For more information about the linker see ld65.txt. - - - -5. The easy way (using the cl65 utility) ----------------------------------------- - -The cl65 utility is able to do all of the steps described above in just -one call, and it has defaults for some options that are very well suited -for our example. - -To compile both files into one executable enter - - cl65 -O -I ../include hello.c test.s - -(The -I switch is not needed if you are working under Linux with the -include files in the default path, or the CC65_INC environment variable is -set correctly). - -The cl65 utility knows, how to translate C files into object files (it -will call the compiler and then the assembler). It does also know how to -create object files from assembler files (it will call the assember for -that). It knows how to build an executable (it will pass all object files -to the linker). And, finally, it has the C64 as a default target and will -supply the correct startup file and runtime library names to the linker, -so you don't have to care about that. - -The one-liner above should give you a C64 executable named "hello" in the -current directory. - -For more information about the compile & link utility see cl65.txt. - - - - -- 2.39.5