git.sur5r.net Git - cc65/blob - doc/intro.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <title>cc65 compiler intro
   6 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
   7 <date>03.12.2000
   8
   9 <abstract>
  10 How to use the cc65 C compiler - an introduction.
  11 </abstract>
  12
  13 <!-- Table of contents -->
  14 <toc>
  15
  16 <!-- Begin the document -->
  17
  18 <sect>Overview<p>
  19
  20 This is a short intro, how to use the compiler and the binutils. It contains a
  21 step-by-step example, how to build a complete application from one C and one
  22 assembler module. This file does <em/not/ contain a complete reference for the
  23 tools used in the process. There are separate files describing these tools in
  24 detail.
  25
  26 <bf>Note</bf>: There is a much simpler way to compile this example using the
  27 cl65 compiler and link utility. However, it makes sense to understand how the
  28 separate steps work. How to do the example with the cl65 utility is described
  29 <ref id="using-cl65" name="below">.
  30
  31
  32 <sect1>The sample modules<p>
  33
  34 To explain the development flow, I will use the following example modules:
  35
  36 hello.c:
  37
  38 <tscreen><code>
  39         #include <stdio.h>
  40         #include <stdlib.h>
  41
  42         extern const char text[];       /* In text.s */
  43
  44         int main (void)
  45         {
  46             printf ("%s\n", text);
  47             return EXIT_SUCCESS;
  48         }
  49 </code></tscreen>
  50
  51 text.s:
  52 <tscreen><code>
  53         .export _text
  54         _text:  .asciiz "Hello world!"
  55 </code></tscreen>
  56
  57
  58 <sect1>Translation phases<p>
  59
  60 We assume that the target file should be named "hello", and the target system
  61 is the C64.
  62
  63 <tscreen><verb>
  64     +---------+
  65     | hello.c |
  66     +---------+
  67          |
  68         cc65
  69          \/
  70     +---------+       +---------+
  71     | hello.s |       | text.s  |
  72     +---------+       +---------+
  73          |                 |
  74         ca65              ca65
  75          \/                \/
  76     +---------+       +---------+       +----------+       +---------+
  77     | hello.o |       | text.o  |       |  c64.o   |       | c64.lib |
  78     +---------+       +---------+       +----------+       +---------+
  79          |                     \         /                      |
  80          |                      \       /                       |
  81          |                       \     /                        |
  82          +----------------------->ld65<-------------------------+
  83                                    \/
  84                                   hello
  85 </verb></tscreen>
  86
  87 <tt/c64.o/ (the startup code) and <tt/c64.lib/ (the c64 version of the runtime
  88 and C library) are provided in binary form in the cc65 package.
  89
  90
  91
  92 <sect>The compiler<p>
  93
  94 The compiler translates one C source into one assembler source for each
  95 invocation. It does <em/not/ create object files directly, and it is <em/not/
  96 able to translate more than one file per run.
  97
  98 In the example above, we would use the following command line, to translate
  99 <tt/hello.c/ into <tt/hello.s/:
 100
 101 <tscreen><verb>
 102         cc65 -O -I ../include -t c64 hello.c
 103 </verb></tscreen>
 104
 105 The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
 106 is usually a good idea, since it makes the code smaller. If you don't care
 107 about the size, but want to have slightly faster code, use <tt/-Oi/ to inline
 108 some runtime functions.
 109
 110 The <tt/-I/ switch gives a search path for the include files. You may also set
 111 the environment variable CC65_INC to the search path.
 112
 113 The <tt/-t/ switch is followed by the target system.
 114
 115 If the compiler does not complain about errors in our hello world, we will
 116 have a file named "<tt/hello.s/" in our directory that contains the assembler
 117 source for the hello module.
 118
 119 For more information about the compiler see <htmlurl url="cc65.html"
 120 name="cc65.html">.
 121
 122
 123
 124 <sect>The assembler<p>
 125
 126 The assembler translates one assembler source into an object file for each
 127 invocation. The assembler is <tt/not/ able to translate more than one source
 128 file per run.
 129
 130 Let's translate the hello.s and text.s files from our example:
 131
 132 <tscreen><verb>
 133         ca65 hello.s
 134         ca65 -t c64 text.s
 135 </verb></tscreen>
 136
 137 The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the
 138 text is converted from the input character set (usually ISO-8859-1) into the
 139 target character set (PETSCII) by the assembler. The compiler generated file
 140 <tt/hello.s/ does not contain any character constants, so specification of a
 141 target is not necessary (it wouldn't do any harm, however).
 142
 143 If the assembler does not complain, we should now have two object files (named
 144 <tt/hello.o/ and <tt/text.o/) in the current directory.
 145
 146 For more information about the assembler see <htmlurl url="ca65.html"
 147 name="ca65.html">.
 148
 149
 150
 151 <sect>The linker<p>
 152
 153 The linker combines several object and library file into one output file. ld65
 154 is very configurable, but fortunately has a builtin configuration for the C64,
 155 so we don't need to mess with configuration files here.
 156
 157 The compiler uses small functions to do things that cannot be done inline
 158 without big impact on code size. These runtime functions, together with the C
 159 library are in an object file archive named after the system, in this case
 160 "<tt/c64.lib/". We have to specify this file on the command line so that the
 161 linker can resolve these functions.
 162
 163 A second file (this time an object file) needed, is the startup code that
 164 prepares the grounds for the C program to run. The startup file must be
 165 executed first, so it must be the first file on the linker command line.
 166
 167 Let's link our files to get the final executable:
 168
 169 <tscreen><verb>
 170         ld65 -t c64 -o hello c64.o hello.o text.o c64.lib
 171 </verb></tscreen>
 172
 173 The argument after <tt/-o/ specifies the name of the output file, the argument
 174 after <tt/-t/ gives the target system. As discussed, the startup file must be
 175 the first file on the command line (you may have to add a path here, if
 176 <tt/c64.o/ is not in your current directory). Since the library resolves
 177 imports in <tt/hello.o/ and <tt/text.o/, it must be specified <em/after/ these
 178 files.
 179
 180 After a successful linker run, we have a file named "<tt/hello/", ready for
 181 our C64!
 182
 183 For more information about the linker see <htmlurl url="ld65.html"
 184 name="ld65.html">.
 185
 186
 187
 188 <sect>The easy way (using the cl65 utility)<label id="using-cl65"><p>
 189
 190 The cl65 utility is able to do all of the steps described above in just one
 191 call, and it has defaults for some options that are very well suited for our
 192 example.
 193
 194 To compile both files into one executable enter
 195
 196 <tscreen><verb>
 197         cl65 -O -I ../include hello.c test.s
 198 </verb></tscreen>
 199
 200 (The <tt/-I/ switch is not needed if you are working under Linux with the
 201 include files in the default path, or the <tt/CC65_INC/ environment variable
 202 is set correctly).
 203
 204 The cl65 utility knows, how to translate C files into object files (it will
 205 call the compiler and then the assembler). It does also know how to create
 206 object files from assembler files (it will call the assember for that). It
 207 knows how to build an executable (it will pass all object files to the
 208 linker). And, finally, it has the C64 as a default target and will supply the
 209 correct startup file and runtime library names to the linker, so you don't
 210 have to care about that.
 211
 212 The one-liner above should give you a C64 executable named "<tt/hello/" in the
 213 current directory.
 214
 215 For more information about the compile &amp; link utility see <htmlurl
 216 url="cl65.html" name="cl65.html">.
 217
 218
 219 </article>
 220
 221
 222