mirror of
https://github.com/cc65/cc65.git
synced 2024-08-19 17:29:37 +00:00
223 lines
6.9 KiB
Plaintext
223 lines
6.9 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
|
|
<title>cc65 compiler intro
|
|
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
|
<date>03.12.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>
|
|
|
|
|
|
|