# Preface

Ophis is an assembler for the 6502 microprocessor - the famous chip used in the vast majority of the classic 8-bit computers and consoles. Its primary design goals are code readability and output flexibility - Ophis has successfully been used to create programs for the Nintendo Entertainment System, the Atari 2600, and various 8-bit Commodore and Apple machines.

Ophis's syntax is noticably different from the formats traditionally used for these chips; it draws its syntactic inspiration primarily from the assemblers for more modern chips, where the role of tokens is determined more by what they're made of and their grammatical location on a line rather than their absolute position on a line. It also borrows the sophisticated methods of tracking the location of labels when writing relinkable code—Ophis expects that the final output it produces will have only a vague resemblance to the memory image when loaded. Most of the alternatives when Ophis was first designed would place instructions and data into a memory map and then dump that map.

That said, there remain many actively used 6502 assemblers out there. If you're already a seasoned 6502 assembly programmer, or want to get your old sources built again, Ophis is likely not for you—however, if you are writing new code, or are new to the chip while still having other experience, then Ophis is a tool built with you in mind.

## History of the project

The Ophis project started on a lark back in 2001. My graduate studies required me to learn Perl and Python, and I'd been playing around with Commodore 64 emulators in my spare time, so I decided to learn both languages by writing a simple cross-assembler for the 6502 chip the C64 used in both.

The Perl one—uncreatively dubbed Perl65—was quickly abandoned, but the Python one saw more work. When it came time to name it, one of the things I had been hoping to do with the assembler was to produce working Apple II programs. Ophis is Greek for snake, and a number of traditions also use it as the actual name of the serpent in the Garden of Eden. So, Pythons, snakes, and stories involving really old Apples all combined to name the assembler.

Ironically, cross-platform development for the Apple II is much less straightforward than for the Commodore 8-bits or ROM-based consoles, and it took many years after its release before it was actually used to write code deployed on any of the Apples which inspired its name.

Ophis slowly grew in scope and power over the years, and by 2005 was a very powerful, flexible macro assembler that saw more use than I'd expect. In 2007 Ophis 1.0 was formally released. However, Ophis was written for Python 2.1 and this became more and more untenable as time has gone by. As I started receiving patches for parts of Ophis, and as I used it for some projects of my own, it became clear that Ophis needed to be modernized and to become better able to interoperate with other toolchains. It was this process that led to Ophis 2.

After its release Ophis 2 was picked up by a number of developers working with actual hardware from the period, including prototype machines that never saw production. Some of their contributions have refined the code generators for version 2.1.

At that point, the program was basically done, and very little changes for about five years. The world, however, moved on, and Python 2, my implementation language, was deprecated and rendered obsolete. That didn't change much about the 2.1 release—Python 2 was still installed on non-Windows machines by default, and the Windows distribution was as a bundled .EXE file—but it threatened the viability of the program overall. In 2019, then, I converted the source base to the backwards-incompatible Python 3, in the hopes of future-proofing the system. Five years after that, enough bug reports and bug fixes had trickled in to justify a fresh release, and 2.2 was published in 2024—a lightly polished update that now fit more neatly into the Python toolchains of the 2020s.

In the twenty years since I first started this project, I've gained quite a bit more experience with programming the computer systems of the 1970s and 1980s. I have left this manual largely as it was in its 2014 edition, including its versions of the To HLL and Back essays I wrote using Ophis and Perl65 as example languages. I don't think I stand behind my design decisions back then as firmly as I did when I wrote those essays, but there's noting wrong with them either so I'm happy to leave them as a testament to my younger, brasher self.

## Getting a copy of Ophis

As of version 2.2, the Python Package Index offers Ophis at . This version may be installed on any system where `pip` or `pipx` works.

Development is hosted at Github. The latest downloads and documentation will be available at . If this is out-of-date, a Web search on Ophis 6502 assembler (without the quotation marks) should yield its page.

For Windows users, a prepackaged system made with `py2exe` is also available. The default Windows installer will use this. In this case, all you need to do is have `ophis.exe` in your path.

## About the examples

Versions of the examples in this book are available from the Ophis site. Windows users will find them packaged with the distribution; all other users can get them as a separate download or pull them directly from github.

The code in this book is available in the `examples/` subdirectory, while extra examples will be in subdirectories of their own with brief descriptions. They are largely all simple Hello world applications, designed mainly to demonstrate how to package assembled binaries into forms that emulators or ROM loaders can use. They are not primarily intended as tutorials for writing for the platforms themselves.

Most examples will require use of platform headers—standardized header files that set useful constants for the target system and, if needed, contain small programs to allow the program to be loaded and run. These are stored in the `platform/` subdirectory.