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.