3 How to use the cc65 C compiler
5 Ullrich von Bassewitz, 1998/1999
20 5. The easy way (using the cl65 utility)
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.
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.
38 To explain the development flow, I will use the following example modules:
46 extern const char text[]; /* In text.s */
50 printf ("%s\n", text);
58 _text: .asciiz "Hello world!"
61 We assume that the target file should be named "hello", and the target
71 +---------+ +---------+
72 | hello.s | | text.s |
73 +---------+ +---------+
77 +---------+ +---------+ +----------+ +---------+
78 | hello.o | | text.o | | c64.o | | c64.lib |
79 +---------+ +---------+ +----------+ +---------+
83 +----------------------->ld65<-------------------------+
88 c64.o (the startup code) and c64.lib (the c64 version of the runtime and C
89 library) are provided in binary form in the cc65 package.
96 The compiler translates one C source into one assembler source for each
97 invocation. It does *NOT* create object files directly, and it is *NOT*
98 able to translate more than one file per run.
100 In the example above, we would use the following command line, to
101 translate hello.c into hello.s:
103 cc65 -O -I ../include -t c64 hello.c
105 The -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 -Oi to inline
108 some runtime functions.
110 The -I switch gives a search path for the include files. You may also set
111 the environment variable CC65_INC to the search path.
113 The -t switch is followed by the target system.
115 If the compiler does not complain about errors in our hello world, we will
116 have a file named "hello.s" in our directory that contains the assembler
117 source for the hello module.
119 For more information about the compiler see cc65.txt.
126 The assembler translates one assembler source into an object file for each
127 invocation. The assembler is *NOT* able to translate more than one source
130 Let's translate the hello.s and text.s files from our example:
135 If the assembler does not complain, we should now have two object files
136 (named hello.o and text.o) in the current directory.
138 For more information about the assembler see ca65.txt.
145 The linker combines several object and library file into one output file.
146 ld65 is very configurable, but fortunately has a builtin configuration for
147 the C64, so we don't need to mess with configuration files here.
149 The compiler uses small functions to do things that cannot be done inline
150 without big impact on code size. These runtime functions, together with
151 the C library are in an object file archive named after the system, in
152 this case "c64.lib". We have to specify this file on the command line so
153 that the linker can resolve these functions.
155 A second file (this time an object file) needed, is the startup code that
156 prepares the grounds for the C program to run. The startup file must be
157 executed first, so it must be the first file on the linker command line.
159 Let's link our files to get the final executable:
161 ld65 -t c64 -o hello c64.o hello.o text.o c64.lib
163 The argument after -o specifies the name of the output file, the argument
164 after -t gives the target system. As discussed, the startup file must be the
165 first file on the command line (you may have to add a path here, if c64.o is
166 not in your current directory). Since the library resolves imports in hello.o
167 and text.o, it must be specified *after* these files.
169 After a successful linker run, we have a file named "hello", ready for our
172 For more information about the linker see ld65.txt.
176 5. The easy way (using the cl65 utility)
177 ----------------------------------------
179 The cl65 utility is able to do all of the steps described above in just
180 one call, and it has defaults for some options that are very well suited
183 To compile both files into one executable enter
185 cl65 -O -I ../include hello.c test.s
187 (The -I switch is not needed if you are working under Linux with the
188 include files in the default path, or the CC65_INC environment variable is
191 The cl65 utility knows, how to translate C files into object files (it
192 will call the compiler and then the assembler). It does also know how to
193 create object files from assembler files (it will call the assember for
194 that). It knows how to build an executable (it will pass all object files
195 to the linker). And, finally, it has the C64 as a default target and will
196 supply the correct startup file and runtime library names to the linker,
197 so you don't have to care about that.
199 The one-liner above should give you a C64 executable named "hello" in the
202 For more information about the compile & link utility see cl65.txt.