CBMCOMBINE(1)

NAME
cbmcombine - combines Commodore 8-bit executables

SYNOPSIS

cbmcombine [input-file[,load-address]] [[[input-file[,load-address]]] ...]

DESCRIPTION

cbmcombine combines several Commodore executables into one. All Commodore 8-bit machines (64, 128, VIC-20, Plus4, 16, PET, etc) are supported, since they all use the same executable file format.

Files are read in the order listed on the command line. The combined executable is written to standard output. Each file's load address can be forced by adding a comma and the new address (in decimal, or in hex with 0x prefix), in which case the load address in the file will be read and ignored.

If any of the input files overlap the same area of memory, the overlap area will contain only data from the file(s) listed later in the command line. The output file's load address will be that of the input file with the lowest address, and it will extend to the highest address contained in any of the files. If there are gaps in the address space (areas where no file was loaded), the output will contain 0x00 bytes to fill the gap.

Load address overrides do NOT relocate code.

There are no switches (options) for cbmcombine.

EXAMPLES

The examples use 1024 byte input files, named after their load addresses in hex:

x1000.prg Load address $1000, last address $13FF

x1400.prg Load address $1400, last address $17FF

x1600.prg Load address $1600, last address $19FF

cmbcombine x1000.prg x1400.prg > new.prg new.prg will have a load address of 0x1000, and contain data from 0x1000 to 0x17ff. Since x1000.prg ends at address 0x13ff, there is no overlap. If the order of arguments were swapped, the result would be the same.

cmbcombine x1000.prg x1600.prg > new.prg new.prg's load address will be $1000, and its end address will be $19FF. From $1400 to $15FF, it will contain 512 bytes of zeroes, since none of the input files had any data at these addresses. If the order were swapped, the result would be the same.

cmbcombine x1400.prg x1600.prg > new.prg new.prg's load address will be $1400 and it will end at $19FF. The data from $1400 to $15FF comes from x1400.prg, and the rest from x1600.prg.

cmbcombine x1600.prg x1400.prg > new.prg As above, but data at $1400 to $15FF comes from x1400.prg.

cmbcombine x1400.prg x1600.prg,0x1800 > new.prg new.prg loads at $1400 and extends to $1BFF. Data at $1400 to $17FF comes from x1400.prg, data at $1800 to $1BFF comes from x1600.prg. If x1600.prg contains non-relocatable code org'ed at $1600, it will fail to run when loaded at $1800.

EXIT STATUS

0 for success, non-zero for failure. If any of the input files can't be read, the process exits with failure status, without writing anything to standard output.

BUGS

There is very little error-checking. It may be possible to crash cbmcombine by feeding it bogus input.

There's no way to give cbmcombine a filename containing a comma.

Not exactly bugs, per se, but missing features: The user should be notified if files overlap and/or there are gaps in the output.

There should be warnings if a file wraps around the top of the 64K address space, or loads into dangerous or invalid areas such as ROM or page zero. Odds are, the file isn't really a valid CBM executable.

There should be a cbmsplit utility that does the opposite of cbmcombine.

COPYRIGHT

As of 21.12.2005 Pucrunch is under GNU LGPL. See: http://creativecommons.org/licenses/LGPL/2.1/ http://www.gnu.org/copyleft/lesser.html

AUTHORS

cbmcombine was written by Pasi Ojala <a1bert@iki.fi>.

This man page written for the SlackBuilds.org project by B. Watson, and is licensed under the WTFPL.

SEE ALSO

pucrunch(1), exomizer(1), vice(1)

The pucrunch homepage: http://a1bert.kapsi.fi/Dev/pucrunch/

The full documentation and sample decompressor code: /usr/doc/pucrunch-20081122/