Ophis/doc/preface.sgm
2012-06-12 23:13:55 -07:00

138 lines
6.5 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 the
Commodore 64.
</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 extremely difficult, and while Ophis has
been very successfully used to develop code for the Commodore
64, Nintendo Entertainment System, and Atari 2600, it has yet to
actually be 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>
This is an updated edition of <emphasis>Programming With
Ophis</emphasis>, including documentation for all new features
introduced and expanding the examples to include simple
demonstration programs for platforms besides the Commodore
64. It also includes updated versions of the <emphasis>To HLL
and Back</emphasis> essays I wrote using Ophis and Perl65 as
example languages.
</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>