path: root/blob2xex.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BLOB2XEX" 1 "2024-04-25" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
blob2xex \- Create Atari 8-bit executables from arbitrary data
.\" RST source for blob2xex(1) man page. Convert with:
.
.\" rst2man.py blob2xex.rst > blob2xex.1
.
.SH SYNOPSIS
.sp
blob2xex \fIoutfile\fP [\fB\-v\fP] [\fB\-r\fP \fIrunaddr\fP] [\fB\-l\fP \fIloadaddr\fP [\fB\-i\fP \fIinitaddr\fP] [\fB\-o\fP \fIoffset\fP] [\fB\-s\fP \fIsize\fP] \fIinfile\fP] ...
.SH DESCRIPTION
.sp
\fBblob2xex\fP 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
\fB\-r\fP option.
.sp
Each input file \fIrequires\fP a \fB\-l\fP \fIloadaddr\fP option, to set the
load address. Optionally, init addresses can be included, per\-segment
(\fB\-i\fP). Also, using \fB\-o\fP and \fB\-s\fP, it\(aqs possible to include only
part of the input file. To read from standard input, use \fB\-\fP for the
\fIinfile\fP\&.
.sp
\fIoutfile\fP must be given as the first argument. When multiple
input files are used, the resulting .xex file will have multiple
segments. If \fIoutfile\fP already exists, it will be overwritten.
If \fIoutfile\fP is a filename that begins with a \fB\-\fP, prefix it with
"./", otherwise it\(aqll be taken as an option.  Use \fB\-\fP to write to
standard output. \fBblob2xex\fP will not write output to a terminal;
\fB\-\fP must be used with redirection or a pipe.
.sp
Addresses, offsets, and sizes may be given in decimal or hex. Hex
addresses must be prefixed with either \fB$\fP or \fB0x\fP\&.
.SH OPTIONS
.sp
A space is required between an option and its argument; use e.g. \fB\-l 0x2000\fP,
not \fB\-l0x2000\fP\&.
.INDENT 0.0
.TP
.B \-l \fIloadaddr\fP
Set the load address of the next \fIinfile\fP\&. Each \fIinfile\fP must be preceded by
a \fB\-l\fP option.
.TP
.B \-r \fIrunaddr\fP
Optional; set the run address. Since a .xex file can only have one run address,
the last \fB\-r\fP option will be the one used.
.TP
.B \-i \fIinitaddr\fP
Optional; set an init address, to be executed after the next segment loads.
.TP
.B \-o \fIoffset\fP
Optional; skip this many bytes of the next input file. Default is \fB0\fP\&.
.TP
.B \-s \fIsize\fP
Optional; read this many bytes of the next input file. Default is the entire file,
or \fB0xffff\fP (\fB65535\fP) if the file is longer than 64KB.
.UNINDENT
.INDENT 0.0
.TP
.B  \-v
Verbose output.
.TP
.B  \-h\fP,\fB  \-\-help
Print usage message and exit.
.TP
.B  \-V\fP,\fB  \-\-version
Print version number and exit.
.UNINDENT
.SH EXAMPLES
.SS Simple Example
.sp
You\(aqve written an Atari 8\-bit program that loads at \fB$2000\fP, which
is also the run address. The assembler you used doesn\(aqt create Atari
\&.xex files, so you\(aqve got a \fBprogram.bin\fP that\(aqs just raw object
code. To turn it into a runnable .xex file, use:
.INDENT 0.0
.INDENT 3.5
blob2xex program.xex \-l \(aq$2000\(aq \-r \(aq$2000\(aq program.bin
.UNINDENT
.UNINDENT
.sp
Notice the use of quotes around the addresses? That\(aqs because the
$ character must be quoted, or the shell will try to interpret it
as a variable reference. You could also have typed \fB$2000\fP or
\fB0x2000\fP\&.
.SS More Complex Example
.sp
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
\fIatarixl.rom\fP\&.
.sp
The way to use the XL ICS font on the 800 is to load it somewhere
in memory, on a 1K boundary. Suppose you\(aqve decided to load it at
\fB$8000\fP\&.
.sp
Any good reference book or other documentation on the Atari XL/XE
computers will tell you the ICS font is located at \fB$CC00\fP\&. The ROM
image starts at \fB$C000\fP (the start of XL/XE ROM), so the font is
located at offset \fB$0C00\fP within the ROM image. As always for Atari
fonts, it\(aqs 1KB, or \fB$0400\fP bytes.
.sp
So you can create a .xex file of the ROM font with:
.INDENT 0.0
.INDENT 3.5
blob2xex romfont.xex \-l 0x8000 \-o 0x0c00 \-s 0x0400 atarixl.rom
.UNINDENT
.UNINDENT
.sp
Since fonts aren\(aqt executable programs, there are no run (\fB\-r\fP) or
init (\fB\-i\fP) address options.
.sp
The resulting \fIromfont.xex\fP can be combined with the rest of your
program with \fBxexcat\fP(1).
.SH COPYRIGHT
.sp
WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
.SH AUTHOR
.INDENT 0.0
.IP B. 3
Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fBa8eol\fP(1),
\fBa8utf8\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBblob2c\fP(1),
\fBcart2xex\fP(1),
\fBdasm2atasm\fP(1),
\fBfenders\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1).
.sp
Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
.\" Generated by docutils manpage writer.
.