diff --git a/README.rst b/README.rst index 6313b89..572a308 100644 --- a/README.rst +++ b/README.rst @@ -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 `_ 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 COMMAND +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