Ophis/doc/preface.sgm
2024-07-24 23:17:42 -07:00

167 lines
8.0 KiB
Plaintext

<preface>
<title>Preface</title>
<para>
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.
</para>
<para>
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&mdash;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.
</para>
<para>
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&mdash;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.
</para>
<section>
<title>History of the project</title>
<para>
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.
</para>
<para>
The Perl one&mdash;uncreatively dubbed
<quote>Perl65</quote>&mdash;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. <quote>Ophis</quote> is
Greek for <quote>snake</quote>, and a number of traditions also
use it as the actual <emphasis>name</emphasis> of the serpent in
the Garden of Eden. So, Pythons, snakes, and stories involving
really old Apples all combined to name the
assembler.<footnote><para>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.</para></footnote>
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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&mdash;Python 2 was still installed on non-Windows
machines by default, and the Windows distribution was as a
bundled .EXE file&mdash;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
<emphasis>that</emphasis>, enough bug reports and bug fixes had
trickled in to justify a fresh release, and 2.2 was published in
2024&mdash;a lightly polished update that now fit more neatly
into the Python toolchains of the 2020s.
</para>
<para>
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
<emphasis>To HLL and Back</emphasis> 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 <emphasis>wrong</emphasis> with them
either so I'm happy to leave them as a testament to my younger,
brasher self.
</para>
</section>
<section>
<title>Getting a copy of Ophis</title>
<para>
As of this writing, the Ophis assembler is hosted at Github. The
latest downloads and documentation will be available
at <ulink url="http://github.com/michaelcmartin/Ophis"></ulink>. If
this is out-of-date, a Web search on <quote>Ophis 6502
assembler</quote> (without the quotation marks) should yield its
page.
</para>
<para>
Ophis is written entirely in Python and packaged using the
distutils. The default installation script on Unix and Mac OS X
systems should put the files where they need to go. If you are
running it locally, you will need to install
the <literal>Ophis</literal> package somewhere in your Python
package path, and then put the <command>ophis</command> script
somewhere in your path.
</para>
<para>
For Windows users, a prepackaged system made
with <command>py2exe</command> is also available. The default
Windows installer will use this. In this case, all you need to
do is have <command>ophis.exe</command> in your path.
</para>
<para>
If you are working on a system with Python installed but to
which you do not wish to install software, there is also a
standalone pure-Python edition with an ophis.py script. This may
be placed anywhere and running ophis.py will temporarily set the
library path to point to your directory.
</para>
</section>
<section>
<title>About the examples</title>
<para>
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.
</para>
<para>
The code in this book is available in
the <literal>examples/</literal> subdirectory, while extra
examples will be in subdirectories of their own with brief
descriptions. They are largely all simple <quote>Hello
world</quote> 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.
</para>
<para>
Most examples will require use of <emphasis>platform
headers</emphasis>&mdash;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 <literal>platform/</literal> subdirectory.
</para>
</section>
</preface>