Apple-2-Tools
/
atrcopy
mirror of https://github.com/robmcmullen/atrcopy.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated README

This commit is contained in:
Rob McMullen 2017-05-02 19:45:13 -07:00
parent ad1eca7b17
commit 95c0d081d1
1 changed files with 177 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

285
README.rst
View File

@ -1,46 +1,65 @@
atrcopy
=======
Utilities to list files on and extract files from Atari 8-bit emulator disk
images. Eventually, I hope to add support for these images to pyfilesystem.
Command line utility to manage file systems on Atari 8-bit and Apple ][ disk
images.
Prerequisites
-------------
Starting with atrcopy 2.0, numpy is required.
Starting with atrcopy 2.0, numpy is required. It will be automatically
installed when installing atrcopy with::
The standard python install tool, pip, does not seem to be able to handle the
automatic installation of numpy, so to install atrcopy, use::
pip install numpy
pip install atrcopy
References
==========
Features
========
* http://www.atariarchives.org/dere/chapt09.php
* http://atari.kensclassics.org/dos.htm
* http://www.crowcastle.net/preston/atari/
* http://www.atarimax.com/jindroush.atari.org/afmtatr.html
* list contents of disk images
* copy files to and from disk images
* delete files from disk images
* create new disk images
* compile assembly source into binary files if `pyatasm <https://pypi.python.org/pypi/pyatasm>`_ is installed
Supported Disk Image Formats
============================
Supported Formats
=================
Supported Disk Image Types
--------------------------
* ``XFD``: XFormer images, basically raw disk dumps
* ``ATR``: Nick Kennedy's disk image format; includes 16 byte header
* ``DSK``: Apple ][ DOS 3.3 disk image; raw sector dump
Supported Filesystem Formats
Supported File System Formats
----------------------------
* XEX format: Atari executable files
* Atari DOS in single, enhanced, and double density
* KBoot format: a single executable file packaged up into a bootable disk image
+--------------+-------------+---------+-------+-------------------+
| File System | Platform | Read | Write | Status |
+==============+=============+=========+=======+===================+
| DOS 2 (90K) | Atari 8-bit | Yes | Yes | Fully supported |
+--------------+-------------+---------+-------+-------------------+
| DOS 2 (180K) | Atari 8-bit | Yes | Yes | Fully supported |
+--------------+-------------+---------+-------+-------------------+
| DOS 3 (130K) | Atari 8-bit | Yes | Yes | Fully supported |
+--------------+-------------+---------+-------+-------------------+
| SpartaDOS | Atari 8-bit | No | No | Under development |
+--------------+-------------+---------+-------+-------------------+
| MyDOS | Atari 8-bit | Partial | No | Under development |
+--------------+-------------+---------+-------+-------------------+
| DOS 3.3 | Apple ][ | Yes | Yes | Fully supported |
+--------------+-------------+---------+-------+-------------------+
| ProDOS 8 | Apple ][ | No | No | Unimplemented |
+--------------+-------------+---------+-------+-------------------+
Other Supported Formats
-----------------------
* XEX format: Atari executable files
* KBoot format: a single executable file packaged up into a bootable disk image
* Atari ROM cartridges (both plain binary and Atari800 .CAR format)
* MAME ROM zipfiles
@ -48,20 +67,120 @@ Other Supported Formats
Example Usage
=============
To extract all non SYS files while converting to lower case, use::
Basic usage is::
$ python atrcopy.py /tmp/GAMES1.ATR -x -l -n
GAMES1.ATR
File #0 : *DOS SYS 039 : skipping system file dos.sys
File #1 : *MINER2 138 : copying to miner2
File #2 : *DEFENDER 132 : copying to defender
File #3 : *CENTIPEDE 045 : copying to centiped.e
File #4 : *GALAXIAN 066 : copying to galaxian
File #5 : *AUTORUN SYS 005 : skipping system file autorun.sys
File #6 : *DIGDUG 133 : copying to digdug
File #7 : *ANTEATER 066 : copying to anteater
File #8 : *ASTEROIDS 066 : copying to asteroid.s
atrcopy DISK_IMAGE <global options> COMMAND <command options>
where the available commands include:
* ``list``: list files on the disk image. This is the default if no command is specified
* ``create``: create a new disk image
* ``add``: add files to a disk image
* ``extract``: copy files from the disk image to the local file system
* ``assemble``: create a binary file from ATasm source, optionally including segments containing raw binary data
* ``delete``: delete files from the disk image
* ``vtoc``: show and manipulate the VTOC for images that support it
The ``DISK_IMAGE`` is always required which points to the path on your local
file system of the disk image. ``COMMAND`` is one of the commands listed
above, and the commands may be abbreviated as shown here::
$ atrcopy --help
usage: atrcopy DISK_IMAGE [-h] [-v] [--dry-run] COMMAND ...
Manipulate files on several types of 8-bit computer disk images. Type 'atrcopy
DISK_IMAGE COMMAND --help' for list of options available for each command.
positional arguments:
COMMAND
list (t,ls,dir,catalog)
List files on the disk image. This is the default if
no command is specified
extract (x) Copy files from the disk image to the local filesystem
add (a) Add files to the disk image
assemble (s,asm) Create a new binary file in the disk image
delete (rm,del) Delete files from the disk image
vtoc (v) Show a formatted display of sectors free in the disk
image
segments Show the list of parsed segments in the disk image
optional arguments:
-h, --help show this help message and exit
-v, --verbose
--dry-run don't perform operation, just show what would have
happened
Help for available options for each command is available using::
atrcopy COMMAND --help
so for example, the help for assembling a binary file is::
$ atrcopy asm --help
usage: atrcopy DISK_IMAGE assemble [-h] [-f] [-s [ASM [ASM ...]]]
[-d [DATA [DATA ...]]] [-r RUN_ADDR] -o
OUTPUT
optional arguments:
-h, --help show this help message and exit
-f, --force allow file overwrites in the disk image
-s [ASM [ASM ...]], --asm [ASM [ASM ...]]
source file(s) to assemble using pyatasm
-d [DATA [DATA ...]], -b [DATA [DATA ...]], --data [DATA [DATA ...]]
binary data file(s) to add to assembly, specify as
file@addr. Only a portion of the file may be included;
specify the subset using standard python slice
notation: file[subset]@addr
-r RUN_ADDR, --run-addr RUN_ADDR, --brun RUN_ADDR
run address of binary file if not the first byte of
the first segment
-o OUTPUT, --output OUTPUT
output file name in disk image
Examples
========
List all files on a disk image::
$ atrcopy DOS_25.ATR
DOS_25.ATR: ATR Disk Image (size=133120 (1040x128b), crc=0 flags=0 unused=0) Atari DOS Format: 1010 usable sectors (739 free), 6 files
File #0 (.2.u.*) 004 DOS SYS 037
File #1 (.2.u.*) 041 DUP SYS 042
File #2 (.2.u.*) 083 RAMDISK COM 009
File #3 (.2.u.*) 092 SETUP COM 070
File #4 (.2.u.*) 162 COPY32 COM 056
File #5 (.2.u.*) 218 DISKFIX COM 057
Extract a file::
$ atrcopy DOS_25.ATR extract SETUP.COM
DOS_25.ATR: ATR Disk Image (size=133120 (1040x128b), crc=0 flags=0 unused=0) Atari DOS Format: 1010 usable sectors (739 free), 6 files
extracting SETUP.COM -> SETUP.COM
Extract all files::
$ atrcopy DOS_25.ATR extract --all
DOS_25.ATR: ATR Disk Image (size=133120 (1040x128b), crc=0 flags=0 unused=0) Atari DOS Format: 1010 usable sectors (739 free), 6 files
extracting File #0 (.2.u.*) 004 DOS SYS 037 -> DOS.SYS
extracting File #1 (.2.u.*) 041 DUP SYS 042 -> DUP.SYS
extracting File #2 (.2.u.*) 083 RAMDISK COM 009 -> RAMDISK.COM
extracting File #3 (.2.u.*) 092 SETUP COM 070 -> SETUP.COM
extracting File #4 (.2.u.*) 162 COPY32 COM 056 -> COPY32.COM
extracting File #5 (.2.u.*) 218 DISKFIX COM 057 -> DISKFIX.COM
Extract all, renaming to lower case on the host file system::
$ atrcopy DOS_25.ATR extract --all -l
DOS_25.ATR: ATR Disk Image (size=133120 (1040x128b), crc=0 flags=0 unused=0) Atari DOS Format: 1010 usable sectors (739 free), 6 files
extracting File #0 (.2.u.*) 004 DOS SYS 037 -> dos.sys
extracting File #1 (.2.u.*) 041 DUP SYS 042 -> dup.sys
extracting File #2 (.2.u.*) 083 RAMDISK COM 009 -> ramdisk.com
extracting File #3 (.2.u.*) 092 SETUP COM 070 -> setup.com
extracting File #4 (.2.u.*) 162 COPY32 COM 056 -> copy32.com
extracting File #5 (.2.u.*) 218 DISKFIX COM 057 -> diskfix.com
Example on Mac OS X
-------------------
@ -74,18 +193,16 @@ folder: a new empty folder somewhere and do all your testing in that folder.
For this example, create a folder called ``atrtest`` in your ``Documents``
folder. Put a few disk images in this directory to use for testing.
Download or copy the file ``atrcopy.py`` and put it the ``Documents/atrtest``
folder.
Since this is a command line programe, you must start a Terminal by double
clicking on Terminal.app in the ``Applications/Utilities`` folder in
the Finder. When Terminal opens, it will put you in your home folder
automatically. Go to the ``atrtest`` folder by typing::
Since this is a command line program, you must get to a command line prompt.
Start a Terminal by double clicking on Terminal.app in the
``Applications/Utilities`` folder in the Finder. When Terminal opens, it will
put you in your home folder automatically. Go to the ``atrtest`` folder by
typing::
cd Documents/atrtest
You should see the file ``atrcopy.py`` as well as the other ATR images you
placed in this directory by using the command::
You can see the ATR images you placed in this directory by using the
command::
ls -l
@ -93,78 +210,30 @@ For example, you might see::
mac:~/Documents/atrtest $ ls -l
-rw-r--r-- 1 rob staff 92176 May 18 21:57 GAMES1.ATR
-rwxr-xr-x 1 rob staff 8154 May 18 22:36 atrcopy.py
Now, run the program by typing ``python atrcopy.py YOURFILE.ATR`` and you should
Now, run the program by typing ``atrcopy GAMES1.ATR`` and you should
see the contents of the ``ATR`` image in the familiar Atari DOS format::
mac:~/Documents/atrtest $ python atrcopy.py GAMES1.ATR
GAMES1.ATR
File #0 : *DOS SYS 039
File #1 : *MINER2 138
File #2 : *DEFENDER 132
File #3 : *CENTIPEDE 045
File #4 : *GALAXIAN 066
File #5 : *AUTORUN SYS 005
File #6 : *DIGDUG 133
File #7 : *ANTEATER 066
File #8 : *ASTEROIDS 066
mac:~/Documents/atrtest $ atrcopy GAMES1.ATR
GAMES1.ATR: ATR Disk Image (size=92160 (720x128b), crc=0 flags=0 unused=0) Atari DOS Format: 707 usable sectors (17 free), 9 files
File #0 (.2.u.*) 004 DOS SYS 039
File #1 (.2.u.*) 043 MINER2 138
File #2 (.2.u.*) 085 DEFENDER 132
File #3 (.2.u.*) 217 CENTIPEDE 045
File #4 (.2.u.*) 262 GALAXIAN 066
File #5 (.2.u.*) 328 AUTORUN SYS 005
File #6 (.2.u.*) 439 DIGDUG 133
File #7 (.2.u.*) 531 ANTEATER 066
File #8 (.2.u.*) 647 ASTEROIDS 066
Without any additional arguments, it will not extract files. To actually pull
the files out of the ``ATR`` image, you need to specify the ``-x`` command line
argument::
mac:~/Documents/atrtest $ python atrcopy.py -x GAMES1.ATR
GAMES1.ATR
File #0 : *DOS SYS 039 : copying to DOS.SYS
File #1 : *MINER2 138 : copying to MINER2
File #2 : *DEFENDER 132 : copying to DEFENDER
File #3 : *CENTIPEDE 045 : copying to CENTIPED.E
File #4 : *GALAXIAN 066 : copying to GALAXIAN
File #5 : *AUTORUN SYS 005 : copying to AUTORUN.SYS
File #6 : *DIGDUG 133 : copying to DIGDUG
File #7 : *ANTEATER 066 : copying to ANTEATER
File #8 : *ASTEROIDS 066 : copying to ASTEROID.S
There are other flags, like the ``-l`` flag to covert to lower case, and the
``--xex`` flag to add the `.XEX` extension to the filename, and ``-n`` to skip
DOS files. So a full example might be::
mac:~/Documents/atrtest $ python atrcopy.py -n -l -x --xex GAMES1.ATR
GAMES1.ATR
File #0 : *DOS SYS 039 : skipping system file dos.sys
File #1 : *MINER2 138 : copying to miner2.xex
File #2 : *DEFENDER 132 : copying to defender.xex
File #3 : *CENTIPEDE 045 : copying to centipede.xex
File #4 : *GALAXIAN 066 : copying to galaxian.xex
File #5 : *AUTORUN SYS 005 : skipping system file autorun.sys
File #6 : *DIGDUG 133 : copying to digdug.xex
File #7 : *ANTEATER 066 : copying to anteater.xex
File #8 : *ASTEROIDS 066 : copying to asteroids.xex
See other examples as above.
Command Line Arguments
----------------------
References
==========
The available command line arguments are summarized using the standard ``--
help`` argument::
$ python atrcopy.py --help
usage: atrcopy.py [-h] [-v] [-l] [--dry-run] [-n] [-x] [--xex] ATR [ATR ...]
Extract images off ATR or XFD format disks
positional arguments:
ATR a disk image file [or a list of them]
optional arguments:
-h, --help show this help message and exit
-v, --verbose
-l, --lower convert filenames to lower case
--dry-run don't extract, just show what would have been extracted
-n, --no-sys only extract things that look like games (no DOS or .SYS
files)
-x, --extract extract files
--xex add .xex extension
-f, --force force operation on disk images that have bad directory
entries or look like boot disks
* http://www.atariarchives.org/dere/chapt09.php
* http://atari.kensclassics.org/dos.htm
* http://www.crowcastle.net/preston/atari/
* http://www.atarimax.com/jindroush.atari.org/afmtatr.html
* https://archive.org/details/Beneath_Apple_DOS_OCR