<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 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 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>
      After its release Ophis 2 was picked up by a number of
      developers work 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>
      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>
