.. RST source for blob2xex(1) man page. Convert with:
..   rst2man.py blob2xex.rst > blob2xex.1

========
blob2xex
========

--------------------------------------------------
Create Atari 8-bit executables from arbitrary data
--------------------------------------------------

.. include:: manhdr.rst

SYNOPSIS
========

blob2xex *outfile* [**-v**] [**-r** *runaddr*] [**-l** *loadaddr* [**-i** *initaddr*] [**-o** *offset*] [**-s** *size*] *infile*] ...

DESCRIPTION
===========

**blob2xex** creates an Atari 8-bit binary load (xex) file from one or
more files of arbitrary data. Each input file will become a separate
segment in the binary load file. A run address can be added with the
**-r** option.

Each input file *requires* a **-l** *loadaddr* option, to set the
load address. Optionally, init addresses can be included, per-segment
(**-i**). Also, using **-o** and **-s**, it's possible to include only
part of the input file. To read from standard input, use **-** for the
*infile*.

*outfile* must be given as the first argument. When multiple
input files are used, the resulting .xex file will have multiple
segments. If *outfile* already exists, it will be *overwritten*
(or *deleted*, in case of error). Use **-** to write to standard
output. **blob2xex** will not write output to a terminal; **-** must
be used with redirection or a pipe.

If *outfile* or any *infile* is a filename that begins with a **-**,
prefix it with "./", otherwise it'll be taken as an option. The GNU
style **--** (end of options) isn't implemented because it doesn't
make sense here. How often do you really use **-** at the start of a
filename, anyway?

Addresses, offsets, and sizes may be given in decimal or hex. Hex
addresses must be prefixed with either **$** or **0x**.

OPTIONS
=======

A space is required between an option and its argument; use e.g. **-l 0x2000**,
not **-l0x2000**.

-r *runaddr*
  Optional; set the run address. Default is no run address. Since a
  .xex file can only have one run address, there's no point in giving
  multiple **-r** options. If you do, the last one will be used. This
  option should be first on the command line (right after *outfile*),
  or at least must occur before any *infile*.

-l *loadaddr*
  Required; set the load address of the next *infile*. Each *infile*
  **must** be preceded by a **-l** option.

-i *initaddr*
  Optional; set an init address, to be executed after the next segment loads.
  Default is no init address.

-o *offset*
  Optional; skip this many bytes of the next input file. Default is **0**.
  See the **More Complex Example** below.

-s *size*
  Optional; read this many bytes of the next input file. Default is the entire file,
  or **0xffff** (**65535**) if the file is longer than 64KB. It's not an error
  for *size* to be larger than the file (reading will stop at EOF). Also, the
  file's data will be truncated at Atari address **$FFFF**, regardless of
  *size* or the size of the file.

-v
  Verbose output.

-h, --help
  Print usage message and exit.

-V, --version
  Print version number and exit.

DIAGNOSTICS
===========

Error messages and warnings are printed to standard error, and are
hopefully self-explanatory. Any message containing *fatal* causes
**blob2xex** to exit without creating the output file.

Messages containing *warning* are non-fatal, and the output file is
created. The only warning messages are there to let you know if your
.xex file's start/end addresses mean it would load into ROM (or, the
unmapped area at **$C000** on a 400/800). Normally this means the .xex
file won't load properly on the Atari, but feel free to ignore the
warnings if you know exactly what you're doing.

EXAMPLES
========

Simple Example
--------------

You've written an Atari 8-bit program that loads at **$2000**, which
is also the run address. The assembler you used doesn't create Atari
.xex files, so you've got a **program.bin** that's just raw object
code. To turn it into a runnable .xex file, use:

  blob2xex program.xex -l '$2000' -r '$2000' program.bin

Notice the use of quotes around the addresses? That's because the
$ character must be quoted, or the shell will try to interpret it
as a variable reference. You could also have typed **\$2000** or
**0x2000**. Or you could have used decimal (**4096**).

More Complex Example
--------------------

Suppose you want to write a program that can run on an Atari 800,
but you want to use the International Character Set font from the
XL/XE machines. Also suppose that you have the XL ROM image as
*atarixl.rom*.

The way to use the XL ICS font on the 800 is to load it somewhere
in memory, on a 1K boundary. Suppose you've decided to load it at
**$8000**.

Any good reference book or other documentation on the Atari XL/XE
computers will tell you the ICS font is located at **$CC00**. The ROM
image starts at **$C000** (the start of XL/XE ROM), so the font is
located at offset **$0C00** within the ROM image. As always for Atari
fonts, it's 1KB, or **$0400** bytes.

So you can create a .xex file of the ROM font with:

  blob2xex romfont.xex -l 0x8000 -o 0x0c00 -s 0x0400 atarixl.rom

Since fonts aren't executable programs, there are no run (**-r**) or
init (**-i**) address options.

The resulting *romfont.xex* can be combined with the rest of your
program with **xexcat**\(1).

.. include:: manftr.rst