The C64 OS Programmer's Guide is being written
This guide is being written and released and few chapters at a time. If a chapter seems to be empty, or if you click a chapter in the table of contents but it loads up Chapter 1, that's mostly likely because the chapter you've clicked doesn't exist yet.
Discussion of development topics are on-going about what to put in this guide. The discusssions are happening in the C64 OS Community Support Discord server, available to licensed C64 OS users.
C64 OS PROGRAMMER'S GUIDE
Chapter 1: Introduction to C64 OS
C64 OS is an operating system add-on to the Commodore 64's built-in features and software. The C64's built-in software provides some low-level features and, in the form of BASIC v2, a high-level programming language akin to a scripting language. But, it provides very little of what a modern user expects from their computer. C64 OS does not erase the C64's low-level operating system; It augments it with the pieces that are missing.
In broad strokes, C64 OS is a single-tasking event-driven OS that adds a desperately needed suite of low-level technologies, and a framework for Applications, Utilities, drivers and libraries to work together to make building new, powerful, and sophisticated C64 software faster and easier. Upon this foundation, a few tentpole Applications have already been written, such as the App Launcher, File Manager, C64 Archiver, and Image Viewer, along with a number of useful Utilities, such as Calculator, Drives, TextView, Themes, Settings, Memory, Peek, Today, etc.
The true power of C64 OS is as a platform upon which to build new software for the Commodore 64. The future of what can be built upon C64 OS is a wide open canvas of possibilities and opportunities. But we need your creativity, your passion, and ideas to bring these possibilities to life. This guide is here to give you everything you need to get from opcodes to applications.
Developers, developers, developers, developers.
Developers, developers, developers, developers.
Developers, developers, developers, developers... The sweaty and inimitable Steve Balmer - Microsoft Pep-rally - The 90's
Here are some low-level technologies that C64 OS offers that make it easier to write more modern, more powerful software for the Commodore 64:
On these core technologies and more, C64 OS provides a framework to switch between Applications and to load any Utility concurrently with any Application. Apps and Utilities plug in to a common user interface that is controlled by mouse and by rich multi-modifier keyboard shortcuts.
By tapping into the object-oriented Toolkit, using its existing classes or building new ones, Applications and Utilities can have consistent, flexible, dynamic user interfaces with only a small amount of code. With a device-independent event model, the hard work of an Application is already done for you. To do the remaining work you can call on over a hundred new KERNAL routines or link to a growing collection of shared libraries. Libraries add new functionality to your Applications for free, and enable work done for one Application to benefit every other.
Small, Modular, Configurable, Expandable
Small, modular, configurable and expandable; These are the guiding design principles for an operating system that works in just 64 kilobytes of memory and runs on an 8-bit processor at 1 MHz.
C64 OS is designed to maximize the free exchange of components, classes, libraries, messages and data between Applications and Utilities so that everything you build isn't just an island to itself, but contributes to the environment and enhances the power and capabilities of the whole system.
Where to start
The first thing you need to start developing for C64 OS is a commercial copy of the operating system for use on your personal computers. If you haven't ordered a copy yet, you can do so here:
https://c64os.com/c64os/#order
Before you begin developing anything, you should familiarize yourself with how to use C64 OS. Learning how to use C64 OS will show you how Applications plug into the system, how Utilities are used in conjunction with Applications to provide them additional functionality, and give you a general idea of the naming conventions and standard behaviors of things like the menu bar, the status bar and its modes, the split-screen and fullscreen graphics modes, and more.
Developers should read the online User's Guide first, which can be found here:
https://c64os.com/c64os/usersguide
The C64 OS Programmer's Guide assumes that you are already capable of programming in 6502 Assembly Language. This Guide gives you everything else you need to know to write powerful Applications for the Commodore 64, by taking advantage of the technologies provided by C64 OS.
There is more to C64 OS development than just Applications. This Guide also teaches you how to write drivers, shared libraries, boot components, datatype loaders, Toolkit classes, and Utilities. It also discusses data files and formats such as App Launcher backdrops and aliases, the icon library, menu definitions files, MText, settings files, character sets, file jobs, message protocols and more.
There is a lot to learn and a lot to cover.
The Programmer's Guide by Section
Core Technologies: Chapters 2 to 6
The first several chapters cover core technologies. These are critical for understanding how C64 OS works from a broad perspective. It is important to have at least a passing familiarity with these Core Technologies, as they form the foundation upon which everything else is built. You should read through these chapters at least once, then you can return to them later for reference.
Story-Based Tutorials: Chapters 7 to 12
Once you have a familiarity with the Core Technologies, you can decided what kind of software you want to develop, then jump straight to the chapter that covers how to build it. A boot component is very simple, a driver or a library a bit more complex. A Toolkit class can vary widely in difficulty, and has particular requirements. A Utility pulls together many C64 OS technologies. An Application is the most complex; It can even embed libraries and Utilities, and makes use of an wider range of technologies.
Advanced Topics: Chapters 13 to 15
C64 OS has lots of technologies that can be used when creating a Utility or Application, but most of these are used in special circumstances. After you're able to put together an Application bundle that launches, provides a simple user interface with menus, and allows the user to safely return home, you'll want to flesh out the Application with all the custom features it needs. The chapters of this section provide tutorials and examples of how to use individual technologies from the KERNAL, the Toolkit, libraries, and more.
The appendices are where you will find lists and tables and summaries of memory locations. There is not a lot of descriptive prose in an appendix, it is used for pure reference.
How the Programmer's Guide is organized
Use the table of contents in the left sidebar to jump directly to any chapter or section of the Programmer's Guide.
Chapter 1: Introduction
You're reading it. This chapter introduces you to programming for C64 OS and to the Programmer's Guide. This chapter helps direct you to the information you need.
Core Technologies
Chapter 2: Architectural Overview
The architectural overview covers things such as the general flow of information through the layers of the system, this is known as command and control. It introduces you to the low-level event model, how events are generated and distributed. It covers the basics of memory management and how C64 OS 5 or 6 major regions. The low-level drawing system is explained. The role of the file system in C64 OS's functional organization and how and the omnipresent menu system works.
Chapter 3: Development Environment
This Guide assumes you can already program in 6502. However, a brief overview is provided for context. Registers, flags and symbols are explained, which covers how they are referred to throughout the documentation. A set of useful and common macros and constants are provided in the C64 OS headers and includes. These are explained, as sample code found throughout the Guide makes use of these macros and constants to make the code shorter and easier to read.
Chapter 4: Using the KERNAL
The C64 OS KERNAL is divided into 10 functional modules. In total 114 new KERNAL routines are added to the 39 provided by the KERNAL ROM. This chapter covers some of the most common ones. It shows how dynamically link to the KERNAL and describes the conventions used for making KERNAL calls.
Chapter 5: Using Libraries
The routines the KERNAL provides are ones that are so common they are used by almost everything, which is what warrants the memory they permenantly occupy. Many other useful routines, although they can make developing a new Application significantly easier, are not always needed. These routines are stored in libraries. This chapter explains how to load and link to a shared library, and the conventions used for making library calls.
Chapter 6: Using Toolkit
Toolkit, while technically optional, is a feature of C64 OS that allows you to build flexible and consistent user interfaces without much code. This chapter introduces the way Toolkit works and explains how to use some common classes that are permenantly memory resident. More detail on how to use all the classes, including those that can be loaded at runtime, is given in a later chapter.
Story-Based Tutorials
Chapter 7: Writing an Application
This chapter includes a complete tutorial for how to build an Application bundle, with an icon and about this app info file, a main binary, an initialization binary, and a menu definitions file. The core parts of an Application are explained with sample code; pushing a screen layer, processing events, drawing to a screen buffer, responding to menu actions and system messages.
Chapter 8: Writing a Utility
This chapter includes a complete tutorial for how to build a Utility. An explanation with sample code is provided for making use of the Utility framework, pushing a screen layer, responding to events and exchanging messages with the Application, saving and restoring state data, and how to make KERNAL calls from behind the KERNAL ROM.
Chapter 9: Writing a Driver
Drivers are much simpler to write than Applications or Utilities. This chapter gives a tutorial on how to write a relocatable driver. It provides the requirements for each driver type.
Chapter 10: Writing a Shared Library
Shared Libraries are more complex than drivers but less complex than an Application or a Utility. This chapter explains how to write a library with sample code. It covers various common situations, such as how to handle a library that needs to be initialized when it is first loaded, but not when a second process loads it resulting in it becoming shared. And how to handle unloading, so that library can free any additional resources it loaded or allocated.
Chapter 11: Writing a Toolkit Class
Toolkit classes can range from very simple to very complex. This chapter explains in detail with numerous source code examples how to create a new class, how to subclass an existing class and override its methods. How to handle events, how to perform drawing operations, and how to optimize drawing.
Chapter 12: Writing a Datatype Loader
Datatype loaders are relatively simple. This chapter explains how to create a datatype loader, which involves making use of the KERNAL to allocate memory and to operate on files and file references to load and validate data structures.
Advanced Topics
This section of the table of contents is under development.
Appendices
Appendices
The appendices contain summaries of useful information that can be easily referenced.
This section of the table of contents is under development.
Next Chapter: Architectural Overview
Table of Contents
This document is subject to revision updates.
Last modified: Apr 20, 2023