.. _supportedAssemblers:

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

If you use SkoolKit to generate an ASM version of your disassembly, and you
want to assemble it, 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 :ref:`skool2asm.py`:

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

.. _pasmo: http://pasmo.speccy.org/
.. _SjASMPlus: https://github.com/sjasmplus/sjasmplus
.. _z88dk: https://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 `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 must 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 a binary (raw memory) file or a tape file that can be used with an
emulator.

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

  $ skool2asm.py game.skool > game.asm

Then use `pasmo` to create a binary file named `game.bin` thus::

  $ pasmo game.asm game.bin

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

  $ skool2asm.py game.skool > game.asm

Then create a file named `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 named `game.bin` will be created.

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

  $ skool2asm.py game.skool > game.asm

Then use `z80asm` to create a binary file named `game.bin` thus::

  $ z80asm -rORG -b game.asm

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

Creating a TAP file
-------------------
Having created `game.bin` by using your chosen assembler, you can now create a
TAP file by using :ref:`bin2tap.py`::

  $ bin2tap.py game.bin

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

Creating a Z80 snapshot
-----------------------
Having created `game.bin` by using your chosen assembler, you can now create a
Z80 snapshot by using :ref:`bin2sna.py`::

  $ bin2sna.py game.bin

The resultant snapshot, `game.z80`, can then be loaded into an emulator.
