Cc65

Overview
--------

cc65 is a complete cross development package for 65(C)02 systems, including a
powerful macro assembler, a C compiler, linker, librarian and several other
tools. It is based on a C compiler that was originally adapted for the Atari
8bit computers by John R. Dunning. The original C compiler is a Small C
descendant but has several extensions, and some of the limits of the original
Small C compiler are gone. The original copyright allows free redistribution
including sources, even if it would not qualify as Open Source Software
according to the Open Source Definition.
The original Atari compiler is available from
http://www.umich.edu/~archive/atari/8bit/Languages/Cc65/. The complete
package consists of the compiler, an assembler, a librarian, a linker, and a
C library for the Atari. There are some packages on the net that claim to be
adapted as a crosscompiler for DOS or Unix, but was not able to get them
working correctly.

Because I wanted a C compiler for my CBM machines, I took the Atari compiler
and started a rewrite. Until today, I have rewritten large parts of the
compiler, all of the library, completely replaced the assembler, the linker
and the librarian, and added a frontend to simplify use. All changes have
been done with portability in mind, so porting to new 6502 architectures
should be quite easy.


Compiler Features
-----------------
The compiler is almost ISO C compatible, so you should be able to translate
many sources from other systems. Here is a list of the differences:


* The compiler allows single line comments that start with //. This feature
  is disabled in strict ANSI mode.


* The compiler allows unnamed parameters in parameter lists. The compiler
  will not issue warnings about unused parameters that don't have a name.
  This feature is disabled in strict ANSI mode.


* The compiler has some additional keywords that are needed for special
  features. In strict ANSI mode, the additional keywords start with two
  underscores.


* The volatile modifier has no effect.


* The datatypes float and double are not available. 


* The compiler does not support bit fields.


* C functions may not return structs and structs may not be passed as
  parameters by value. Struct assignment is possible.


* There are some limitation on the size of local variables. Not all
  operations are available if the size of local variables exceeds 256 bytes.


* Part of the C library is available only with fastcall calling conventions
  (see below). This means, that you may not mix pointers to those functions
  with pointers to user written functions.


* There may be other target system dependent limitations. One example is
  file I/O, which is not implemented on all platforms. This is no technical
  limitation (as with the stuff mentioned above) but does just mean that no
  one cared enough to write the actual code.


Other Tools
-----------
The compiler is only one of the tools available in this package. The
assembler suite (assembler, linker, archiver) is a complete development
environment for itself, that may be used to write programs for any 6502
machine. C code and assembler code may be used together and may call each
other.

The assembler is a one pass macroassembler and is able to output code for
the 6502, the 65SC02 and 65SC816. It has a lot of nifty features like
include files, conditional assembly, macros, nested lexical levels (that
is, local symbols), and more. The assembler creates object files
containing relocatable code. These files must be run through a linker to
create the final program.

The linker has a flexible output format and is able to support ROMable
code (different load and run addresses for data), banked systems (segments
may share the same run address), systems with multiple ROMs, unlimited
segments, more than one BSS segment and lots of other things.

The archiver is used to create libraries containing objects files. This
simplifies code management. The linker will extract only those modules from
a library that are actually needed.

To simplifiy use, there is also a frontend to the tools contained in the
cc65 package. The frontend is named cl65. It knows how to build binaries
from a list of C files, assembler files, object files and libraries. For
smaller projects, just one invocation of the cl65 utility is needed to
build a binary from several source files and libraries.


Supported Targets
-----------------
The runtime library and the standard C library have been designed with
portability in mind. Changes for any 6502 system shouldn't be necessary.
If you have a system not listed below, all you need is a new startup code.

Direct library support (that is, startup/initialization code) and support
libraries for other features are available for:


...the Commodore C64



...the GEOS operating system for the Commodore C64



...the Commodore C128



...the Commodore C16, C116 and Plus/4



...the Commodore P500



...the Commodore 600/700 family of computers



...the Apple ][



...the Atari 8bit machines



...the Oric Atmos



...the Nintendo Entertainment System (NES)



...the Supervision Game Console



...the Atari Lynx Console


Especially the CBM 600/700 are very nice targets, since the programs
created by cc65 run in a separate memory bank and have almost FULL 64K of
memory available!

The apple2 port was done by by Kevin Ruland, <kevin at rodin. wustl. edu>.

Support for GEOS was added by Maciej Witkowiak, <ytm at friko. onet. pl>.

The port back to the Atari machines was contributed by

Christian Groessler, <cpg at aladdin. de>
Mark Keates, <mark. keates at dendrite. com>
Freddy Offenga, <taf_offenga at yahoo. com>
David Lloyd, <dmlloyd at atari-central. com>


The NES port was done by groepaz, <groepaz at gmx. net>.

The Supervision startup files and linker config were supplied by Peter
Trauner, <peter. trauner at utanet. at>.

The Lynx port was done by Karri Kaksonen, <karri at sipo. fi>based on the
original Lynx compiler by Bastian Schick. Bastians code was used with
permission - thanks!

The assembler sources from the runtime and C library, and the C64 specific
files are available online, converted to HTML and crosslinked by ca65html
for more viewing pleasure.


Host Systems
------------
With one exception in the compiler (access()) the code is plain ISO C, so
it should compile on most systems. Memory usage may be a problem, however.

Amiga: This readme is from the AmigaOS 4 port. 

Linux: This is the primary development platform, so the sources should
compile out of the box under Linux. Binary and source RPMs for RedHat
Linux are available. 

DOS: The binaries are compiled with the Watcom compiler and use the
DOS4G/W extender. 

OS/2: There are very few downloads for this version, so while it is still
available, it may get removed soon. 

Windows NT and 95/98: Watcom compiled binaries.

Apart from that, I have reports that the sources compile on the following
platforms without, or with only minor changes:

FreeBSD (report from Tim Vanderhoek <hoek at FreeBSD. org>).

DOS using DJGPP (report from Keith W. Gerdes, <kwg at netzero. net>, see
compile.txt for some notes).

Windows NT using VC++ (report from
Bill Craig <craigw at gusun. georgetown. edu>).

Windows 9x/NT/2000/XP using cygwin (report from
groepaz <groepaz at gmx. net>).

BeOS using gcc as C compiler (report from
Arvid Norberg <c99ang at cs. umu. se>).

Irix 6.5 using gcc (tested that myself, compiles out of the box).

Solaris 2.6 using gcc 2.95.3, no changes needed
according to B. Watson, <atari at hardcoders. org>.

MiNT on the Atari 68K, compiles without changes (report
from Daniel Pralle <daniel. pralle at stud. uni-hannover. de>).

Amiga OS using either StormC v4.0 or SAS/C 6.58. No changes to the
source code are needed, however SAS/C outputs a few warnings that can be
ignored (report from Leslie Ayling <layling at intercoast. com. au>).

QNX (report from Greg King <gngking at erols. com>. No changes needed.

Mac OS X 10.2 using the gcc version that comes with the system (report
from Eric Shepherd <sheppy at syndicomm. com>). No changes needed.

SuSE Linux 7.1 for PowerPC (report from
Stefan Andree <sandree at physik. tu-berlin. de>). No changes needed. 

MorphOS using spawn-amiga (report
from Stefan Haubenthal <polluks at web. de>).

Docs and Samples
----------------
About 600K of documentation in HTML and ASCII format is available,
describing the compiler and the other tools.

Please note, that there is nothing in the documentation that will
teach you C! If you have never programmed in C before, your first
action should be to get a good book covering C. The documentation
files cover invocation of the programs, special features and
differences to the standard, some internal workings and a
step-by-step intro.

The docs are included in the distribution packages and are also
available online.

The distribution packages do contain some sample programs that may
be used as a first starting point:
 

hello.c

is a simple hello world style program using the conio library.


sieve.c

is an implementation of a popular benchmarking program.

 
nachtm.c

runs on machines with a SID only. It plays
"Eine kleine Nachtmusik" by W. A. Mozart.


mousedemo.c 

shows how to use the mouse routines on systems that support it.


plasma.c

is a graphics demo written by groepaz/hitmem.
It will run on the C64, C128 and P500.


fire.c

is another graphics demo written by groepaz/hitmem.
It does currently run on the C64, but should be portable to all
machines with a VIC (C128 and P500).


gunzip65.c

is a demo of the zlib code that comes with cc65. It was written
by Piotr Fusik.


diodemo.c

shows the use of the direct disc i/o API. It was contributed by
Oliver Schmidt <ol. sc at web. de>.  


Code from the sample programs may be freely used in your own programs.


User Contributions
------------------
In addition to the sample programs, there are also some user
contributed programs. If you're searching for examples of working
code, you may want to give them a try.


Copyright
---------
This is the original cc65 compiler copyright:



  -*- Mode: Text -*-

     This is the copyright notice for RA65, LINK65, LIBR65, and other
  Atari 8-bit programs.  Said programs are Copyright 1989, by John R.
  Dunning.  All rights reserved, with the following exceptions:

      Anyone may copy or redistribute these programs, provided that:

  1:  You don't charge anything for the copy.  It is permissable to
      charge a nominal fee for media, etc.

  2:  All source code and documentation for the programs is made
      available as part of the distribution.

  3:  This copyright notice is preserved verbatim, and included in
      the distribution.

      You are allowed to modify these programs, and redistribute the
  modified versions, provided that the modifications are clearly noted.

      There is NO WARRANTY with this software, it comes as is, and is
  distributed in the hope that it may be useful.

      This copyright notice applies to any program which contains
  this text, or the refers to this file.

      This copyright notice is based on the one published by the Free
  Software Foundation, sometimes known as the GNU project.  The idea
  is the same as theirs, ie the software is free, and is intended to
  stay that way.  Everybody has the right to copy, modify, and re-
  distribute this software.  Nobody has the right to prevent anyone
  else from copying, modifying or redistributing it.



 In acknowledgment of this copyright, I will place my own changes to
 the compiler under the same copyright.

 The library and the binary utils are a complete rewrite done by me
 and covered by the following license:


 This software is provided 'as-is', without any express or implied
 warranty. In no event will the authors be held liable for any damages
 arising from the use of this software.

 Permission is granted to anyone to use this software for any purpose,
 including commercial applications, and to alter it and redistribute
 it freely, subject to the following restrictions:

The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software in
a product, an acknowledgment in the product documentation would be
appreciated but is not required.
Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
This notice may not be removed or altered from any source distribution.