diff options
Diffstat (limited to 'system/pucrunch/cbmcombine.rst')
| -rw-r--r-- | system/pucrunch/cbmcombine.rst | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/system/pucrunch/cbmcombine.rst b/system/pucrunch/cbmcombine.rst new file mode 100644 index 0000000000..5f9193e279 --- /dev/null +++ b/system/pucrunch/cbmcombine.rst @@ -0,0 +1,147 @@ +.. RST source for cbmcombine(1) man page. Convert with: +.. rst2man.py cbmcombine.rst > cbmcombine.1 +.. rst2man.py comes from the SBo development/docutils package. + +.. |version| replace:: 20081122 +.. |date| date:: + +.. converting from pod: +.. s/B<\([^>]*\)>/**\1**/g +.. s/I<\([^>]*\)>/*\1*/g + +========== +cbmcombine +========== + +------------------------------------ +combines Commodore 8-bit executables +------------------------------------ + +:Manual section: 1 +:Manual group: SlackBuilds.org +:Date: |date| +:Version: |version| + +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-|version|/ |