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

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