.. _supportedAssemblers:

Supported assemblers
====================

If you want to use SkoolKit to generate an ASM version of your disassembly, you
will need to use a supported assembler. At the time of writing, the assemblers
listed below are known to work with the ASM format generated by `skool2asm.py`:

* pasmo_ (v0.5.3)
* SjASMPlus_ (v1.07-rc7)
* z80asm, the assembler distributed with z88dk_ (v1.8)

.. _pasmo: http://pasmo.speccy.org/
.. _SjASMPlus: http://sjasmplus.sourceforge.net/
.. _z88dk: http://www.z88dk.org/

.. note::

   SjASMPlus does not recognise instructions that operate on the high or low
   half of the IX and IY registers in the default form used by SkoolKit (e.g.
   ``LD A,IXl``). A workaround is to write the ASM file in lower case using the
   ``--lower`` option of :ref:`skool2asm.py`.

.. note::

   z80asm does not recognise binary constants in the form supported by SkoolKit
   (e.g. ``%10101010``). If your `skool` file contains any such constants, the
   ``%`` characters will have to be replaced by ``@`` (e.g. ``@10101010``)
   after conversion to ASM format.

The following sections give examples of how to use each of these assemblers to
create binary (raw memory) files or tape files that can be used with an
emulator.

pasmo
-----
First, create an ASM version of the disassembly::

  $ skool2asm.py game.skool > game.asm

Then use `pasmo` to create a binary file thus::

  $ pasmo game.asm game.bin

To create a TAP file from `game.bin`, use the :ref:`bin2tap.py` utility,
included with SkoolKit::

  $ bin2tap.py game.bin

The resultant TAP file, `game.tap`, can then be loaded into an emulator.

SjASMPlus
---------
First, create an ASM version of the disassembly::

  $ skool2asm.py game.skool > game.asm

Then create a file called `game.sjasm` with the following contents::

  ; SjASMPlus source file for game.asm
    device zxspectrum48
    include game.asm
    savebin "game.bin",ORG,LENGTH

replacing ``ORG`` and ``LENGTH`` with the origin address and the length of the
assembled program. Now run `sjasmplus` on this source file::

  $ sjasmplus game.sjasm

and a binary file called `game.bin` will be created.

To create a TAP file from `game.bin`, use the :ref:`bin2tap.py` utility,
included with SkoolKit::

  $ bin2tap.py game.bin

The resultant TAP file, `game.tap`, can then be loaded into an emulator.

z80asm (z88dk)
--------------
First, create an ASM version of the disassembly::

  $ skool2asm.py game.skool > game.asm

Then use `z80asm` to create a binary file thus::

  $ z80asm -rORG -b game.asm

replacing ``ORG`` with the origin address (in hexadecimal notation) of the
program.

To create a TAP file from `game.bin`, use the :ref:`bin2tap.py` utility,
included with SkoolKit::

  $ bin2tap.py game.bin

The resultant TAP file, `game.tap`, can then be loaded into an emulator.