Getting Started with C CC65

Beginner’s Guide to Getting Started with C CC65

Originally posted on January 29, 2024 @ 3:17 am

Greetings! We are pleased to present our introductory manual for learning about C CC65 programming. No matter your skill level, this thorough guide will aid you in beginning your exploration of C CC65 programming for 6502-based devices. Our tutorial includes detailed instructions, sample code, and valuable tips to make your learning process seamless and enjoyable.

Before we dive into the exciting world of C CC65 programming, it’s essential to have the necessary tools and environment set up. In the next section, we will guide you through the installation process of the cc65 compiler and target-specific files, along with instructions for setting up the required environment variables.

Key Takeaways:

  • Learn the fundamentals of C CC65 programming for 6502-based systems.
  • Follow step-by-step instructions and examples to build your skills.
  • Set up the cc65 compiler and environment for seamless development.
  • Understand the translation phases and target platforms for C CC65 programming.
  • Learn how to compile, link, and run your C CC65 programs.

Before You Start

In order to begin your C CC65 programming journey, it’s crucial to have the right tools and environment in place. This section will walk you through the process of installing the cc65 compiler and the necessary target-specific files. We will also provide step-by-step instructions for setting up the essential environment variables.

Getting your setup right from the start will ensure a smooth and efficient programming experience. So let’s dive in and get everything ready!

Installing the cc65 Compiler

The cc65 compiler is a powerful tool that allows you to write C code for 6502-based systems. Follow these steps to install it:

  1. Visit the cc65 website:
  2. Download the latest version of cc65 for your operating system (Windows, macOS, or Linux).
  3. Extract the downloaded archive to a location of your choice on your computer.
  4. Add the cc65 installation directory to your system’s PATH environment variable. This will allow you to run cc65 commands from any location in your command prompt or terminal.

Setting Up Target-Specific Files

In addition to the cc65 compiler, you need to have target-specific files for the systems you plan to develop for. These files include the system’s header files, libraries, and configuration files. Follow these steps to set them up:

  1. Identify the target platform(s) you want to develop for, such as Apple, Atari, Commodore, or Nintendo Entertainment System.
  2. For each target platform, download the corresponding target distribution files from the cc65 website.
  3. Extract the downloaded target distribution files to a separate directory.
  4. Configure your cc65 installation to include the target-specific files. This will enable the compiler to generate code specific to your target platform.

Setting Up Environment Variables

Environment variables play a crucial role in setting up your development environment. Follow these steps to configure the necessary variables:

  1. Identify the environment variables required for cc65, such as the path to the cc65 installation directory and the location of the target-specific files.
  2. Set the environment variables either globally on your system or within your preferred development environment or IDE.
  3. Verify that the environment variables are correctly set by opening a command prompt or terminal and running the necessary cc65 commands. You should see the expected output without any errors.

Once you have successfully installed and set up the cc65 compiler and the target-specific files, you are ready to embark on your C CC65 programming journey. In the next section, we will explore some sample modules to help you grasp the fundamental concepts of C CC65 programming.

c cc65 setup guide

Sample Modules

In our journey of understanding C CC65 programming, we will now introduce you to two sample modules: hello.c and text.s. These modules will serve as valuable examples throughout this guide, helping you grasp various concepts and techniques.

The hello.c module showcases the fundamental structure and syntax of a C CC65 program. It is a simple program that prints the classic “Hello, World!” message on the screen. This module will illustrate how to write basic code, use standard libraries, and compile and run your program.

The text.s module, on the other hand, delves into the assembly language aspect of C CC65 programming. It presents a small snippet of assembly code that demonstrates low-level operations such as memory manipulation and register usage. This module will help you understand the interaction between C and assembly code and how they work together to create more complex programs.

It’s worth noting that these modules serve as stepping stones for your learning journey. They set the foundation upon which you can build your understanding of C CC65 programming. By studying and experimenting with these examples, you will gain the necessary skills to tackle more advanced projects and explore the vast possibilities of C CC65.

Let’s take a closer look at the structure and functionality of these sample modules:

hello.c Module:

The hello.c module consists of a simple C program that prints the “Hello, World!” message. Here’s the code:

#include <stdio.h>

int main() {
    printf("Hello, World!\n");
    return 0;

This program uses the standard input/output library (stdio.h) to access the printf() function, which is responsible for displaying the text on the screen. By compiling and running this module, you will be able to familiarize yourself with the basic structure and execution of a C CC65 program.

text.s Module:

The text.s module showcases a small portion of assembly code that can be integrated into your C CC65 program. Here’s the assembly code snippet:

  lda #$41
  sta $0400
  lda #$42
  sta $0401
  lda #$43
  sta $0402

This assembly code demonstrates the manipulation of memory by storing three ASCII characters (‘A’, ‘B’, ‘C’) at memory locations $0400, $0401, and $0402. By incorporating assembly code into your C programs, you can perform low-level operations and optimize certain functionality.

These sample modules form essential building blocks in your learning journey. Each module will be referenced, modified, and expanded upon throughout this guide to illustrate key concepts and techniques.

cc65 sample modules

Target Platforms

The cc65 compiler is versatile and supports a wide range of target platforms, making it a popular choice among developers. Whether you’re interested in programming for Apple, Atari, Commodore, or the Nintendo Entertainment System (NES), cc65 has got you covered.

Let’s take a closer look at each platform and its specific requirements for C CC65 programming:


The Apple II series of computers is known for its iconic design and user-friendly interface. With cc65, you can develop applications for Apple II systems, unleashing the full potential of this classic platform.


Atari computers, such as the Atari 8-bit series and the Atari 5200 console, have a dedicated fan base and a rich library of games. By using cc65, you can create engaging software and games for Atari systems, showcasing your creativity to the Atari community.


The Commodore 64 (C64) is one of the most popular home computers of all time. Its versatility and extensive software library make it a great platform for C CC65 programming. With cc65, you can develop C64 applications and games, exploring the capabilities of this beloved machine.

Nintendo Entertainment System (NES)

The NES revolutionized the gaming industry and laid the foundation for many iconic franchises. With cc65, you can harness the power of the NES and create your own games for this legendary console, immersing players in unforgettable gaming experiences.

Each platform has its own unique features and quirks, but cc65 provides a consistent development experience across all of them. By leveraging the power of cc65, you can unlock the potential of these platforms and bring your creative ideas to life.

Building Your Application

Now that you have successfully set up your environment and familiarized yourself with the translation process, it’s time to start building your C CC65 application. In this section, we will guide you through the essential steps of compiling and linking your source code using the powerful cc65 utilities.

  1. First, you need to ensure that your source code is error-free and properly organized. Take the time to review and debug your code before proceeding with the compilation process.
  2. Open your command line interface, navigate to the directory where your source code is located, and input the following command to compile your code:

cc65 your_source_code.c -o output_file.s

This command instructs the cc65 compiler to translate your C source code into assembly source code, which will be saved as output_file.s. Make sure to replace your_source_code.c with the actual name of your C file and output_file.s with your desired name for the assembly file.

Once the compilation process is complete, you can use the cl65 compile and link utility to link your assembly source code with any required system libraries and generate the final executable file. The cl65 utility streamlines the compilation and linking process by automating multiple steps into a single command.

cl65 -C target.cfg input_file.s -o program_name

Replace target.cfg with the appropriate target configuration file for your specific 6502-based system. Specify input_file.s as the assembly source code file you want to link, and choose a meaningful program_name for your executable file.

By using the cc65 utilities, you can efficiently compile and link your C CC65 application, ensuring optimal performance and compatibility with your target platform.


Let’s say you have a source code file named game.c and you want to compile it into assembly source code named game.s. After ensuring your code is error-free, you would run the following command in your command line interface:

cc65 game.c -o game.s

Once the compilation is successful, you can use the cl65 utility to link your assembly source code and generate the executable file named game.bin. Assuming you have a specific target configuration file named nes.cfg, you would execute the following command:

cl65 -C nes.cfg game.s -o game.bin

Following these steps will result in an executable file named game.bin, ready to be executed on your Nintendo Entertainment System.

Beyond the basics, you can explore additional functionalities and options provided by the cc65 compile and link utility to optimize and customize your C CC65 application. Experiment with different compiler flags, library inclusions, and linker options to enhance the performance and functionality of your program.

Now that you’ve learned how to build your application using the cc65 utilities, the next section will cover the process of running your C CC65 program on your target platform. Stay tuned!

Running Your Program

Once you’ve written your C CC65 program, it’s time to test and run it. To do this, you’ll need emulators specific to your target platform. Emulators allow you to simulate the behavior of different systems on your computer, enabling you to run and test your programs without the need for actual hardware.

There are several popular emulators available for different target platforms. Here are some recommendations:

AppleWin: If you’re targeting the Apple II platform, AppleWin is an excellent option. It accurately emulates the Apple IIe and supports various disk images and Apple II software.

You can download AppleWin from its official website:

Atari800Win PLus: For Atari 8-bit computers, Atari800Win PLus is a popular choice. It offers accurate emulation of Atari systems and provides extensive compatibility with Atari software and hardware.

You can download Atari800Win PLus from its official website:

Using these emulators, you can load your compiled program and run it to see how it performs. Emulators often provide additional tools and features that can help you debug and analyze your code, making the testing process more efficient.

  1. Download and install the emulator specific to your target platform.
  2. Open the emulator and locate the option to load or insert disk images.
  3. Select the compiled program file (e.g., a binary file with a .BIN extension) and load it into the emulator.
  4. Run the program through the emulator’s interface or by executing specific commands.
  5. Observe the output and behavior of your program, ensuring it functions as intended.

In addition to emulators, some developers prefer running their programs on real hardware for certain platforms. This allows for a more authentic experience and can uncover hardware-specific issues that may not be apparent in emulation. However, setting up and configuring real hardware for development purposes can be more challenging and may require additional resources.

When running your program, keep an eye out for any errors or unexpected behavior. This will help you identify and fix any issues in your code, ensuring that your program works correctly on the target platform.

Running Your Program Checklist

Here’s a quick checklist to follow when running your C CC65 program:

  1. Choose the emulator specific to your target platform.
  2. Download and install the emulator.
  3. Load or insert the compiled program file into the emulator.
  4. Run the program using the emulator’s interface or commands.
  5. Observe the output and behavior, ensuring the program functions as intended.
  6. Debug and fix any issues or unexpected behavior.

By following these steps, you’ll be able to test and run your C CC65 programs effectively using emulators or real hardware, depending on your preference and requirements.


Congratulations on completing our comprehensive beginner’s guide to getting started with C CC65! Throughout this tutorial, we have covered the basics of setting up your development environment, understanding the translation process, building your application, and running your program.

By learning C CC65, you have gained a solid foundation in programming for 6502-based systems. This versatile language allows you to create applications for a variety of target platforms, including Apple, Atari, Commodore, and Nintendo Entertainment System.

Now that you understand the fundamentals, you can continue your learning journey and explore the limitless possibilities of C CC65 programming. With your newly acquired knowledge, you can develop your own applications and contribute to the vibrant community of C CC65 developers.

Whether you are interested in game development, homebrew projects, or system programming, C CC65 offers endless opportunities for you to unleash your creativity and bring your ideas to life. Take advantage of the resources available online, such as tutorials, documentation, and forums, to further enhance your skills and deepen your understanding of this powerful programming language.


What is C CC65 programming?

C CC65 programming is a type of programming that involves coding in the C programming language for 6502-based systems. It allows developers to create software for platforms like Apple, Atari, Commodore, and Nintendo Entertainment System.

How do I set up my environment for C CC65 programming?

To set up your environment for C CC65 programming, you need to install the cc65 compiler and target-specific files. This guide provides step-by-step instructions for the installation process and setting up the required environment variables.

What are sample modules in C CC65 programming?

Sample modules are code examples used to demonstrate various concepts and techniques in C CC65 programming. In this guide, two sample modules, hello.c and text.s, are introduced and used throughout to help you understand the development flow.

What are the translation phases in C CC65 programming?

The translation process in C CC65 programming involves several phases. These include preprocessing, tokenizing, parsing, AST generation, type-checking, code generation, and optimization. Each phase plays a crucial role in converting C source code into assembly source code.

Which platforms does the cc65 compiler support?

The cc65 compiler supports a variety of target platforms, including Apple, Atari, Commodore, and Nintendo Entertainment System. Each platform has specific requirements and capabilities for C CC65 programming.

How do I build my application using cc65?

To build your C CC65 application, you need to compile and link your source code using the cc65 utilities. This guide provides step-by-step instructions and introduces the cl65 compile and link utility, which simplifies the building process.

How do I run my C CC65 program?

To test and run your C CC65 program, you will need to use emulators specific to your target platform. Popular emulators like AppleWin and Atari800Win PLus are recommended in this guide. Additionally, it briefly touches on running programs on real machines for certain platforms.

Source Links

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.