Package: atrcopy
atrcopyPython command line utility to manage file systems on Atari 8-bit and Apple ][
disk images.ContentsatrcopyPrerequisitesPythonDependenciesInstallationFeaturesSupported FormatsSupported Disk Image TypesSupported File System FormatsOther Supported FormatsSupported Compression/Container FormatsUsageExamplesCreating Disk ImagesCreating a Custom Boot DiskCreating Programs on the Disk ImageCreating Atari 8-bit ExecutablesCreating DOS 3.3 BinariesExample on macOSReferencesRelated Atari ProjectsRelated Apple ProjectsPrerequisitesPythonStarting withatrcopy7.0, Python 3.6 isrequired. Python 2 support has
been dropped. Python 3.7 and beyond will be supported when they are released,
but 3.6 will probably remain the minimum version. From what I know now of
future Python versions, I don’t plan on requiring any language features beyond
3.6.Supported Python versions:Python 3.6 (and later)If you need Python 2 support,atrcopy6.5 and earlier supports Python 2.7,
which you can install withpip install "atrcopy<7.0"DependenciesnumpyIt will be automatically installed when installingatrcopywithpipas
described below.For development, pytest is used to run the test suite, but this is not required
for normal installation ofatrcopy.Installationatrcopyis available in thePyPIand installable usingpip:pip install atrcopyLinux and macOS note: if numpy needs to be installed on your system, it may be
compiled from source which can take several minutes.Featureslist contents of disk imagescopy files to and from disk imagesdelete files from disk imagescreate new disk imagesconcatenate binary data together into a file on the disk imagecompile assembly source into binary files ifpyatasmis installedNote:The command line argument structure was changed starting withatrcopy4.0 – it is now based on subcommands, much likegitusesgit pull,git clone,git branch, etc. Upgrading from a version prior to
4.0 will require modification of scripts that useatrcopy3.x-style command
line arguments.Supported FormatsSupported Disk Image TypesXFD: XFormer images, basically raw disk dumpsATR: Nick Kennedy’s disk image format; includes 16 byte headerDSK: Apple ][ DOS 3.3 disk image; raw sector dumpSupported File System FormatsFile SystemPlatformReadWriteStatusDOS 2 (90K)Atari 8-bitYesYesFully supportedDOS 2 (180K)Atari 8-bitYesYesFully supportedDOS 2.5 (130K)Atari 8-bitYesYesFully supportedDOS 3 (130K)Atari 8-bitNoNoUnimplementedSpartaDOSAtari 8-bitNoNoUnder developmentMyDOSAtari 8-bitPartialNoUnder developmentDOS 3.3Apple ][YesYesFully supportedProDOS 8Apple ][NoNoUnimplementedOther Supported FormatsFormatPlatform/descriptionReadWriteStatus.xexAtari 8-bit executable filesYesYesFully supportedKBootAtari 8-bitxexin boot diskYesYesFully supported.carAtari 8-bit cartridge imagesYesNoRead onlyBSAVEApple ][BSAVEdataYesYesFully supported.zipMAME ROM zipfilesPartialNoExperimentalNote:Atari ROM cartridges are supported in both both plain binary and
atari800.carformatSupported Compression/Container FormatsStarting withatrcopy8.0, compressed disk images are supported
transparently, so any type of disk image compressed with one of the supported
container formats can be used directly, without first decompressing it before
runningatrcopy.ContainerFile ExtReadWriteStatusgzip.gzYesNoRead onlybzip2.bz2YesNoRead onlylzma.xzYesNoRead onlyDisk Communicator.dcmNoNoRecognized but unimplementedUsageatrcopy 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 specifiedcreate: create a new disk imageadd: add files to a disk imageextract: copy files from the disk image to the local file systemassemble: create a binary file from ATasm source, optionally including segments containing raw binary databoot: create a boot disk using various binary data as inputdelete: delete files from the disk imagevtoc: show and manipulate the VTOC for images that support itExcept when using the--helpoption, theDISK_IMAGEis always required
which points to the path on your local file system of the disk image.COMMANDis 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
    crc                 List files on the disk image and the CRC32 value in
                        format suitable for parsing
    extract (x)         Copy files from the disk image to the local filesystem
    add (a)             Add files to the disk image
    create (c)          Create a new disk image
    assemble (s,asm)    Create a new binary file in the disk image
    boot (b)            Create a bootable 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
                        happenedHelp for available options for each command is available without specifying a
disk image, using a command line like:atrcopy COMMAND --helpso 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 imageExamplesList 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  057Extract 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.COMExtract 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.COMExtract all, using the abbreviated command and converting to lower case on the
host file system:$ atrcopy DOS_25.ATR x --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.comCreating Disk ImagesSeveral template disk images are included in the distribution, and these can be
used to create blank disk images that subsequent uses ofatrcopycan
reference.The available disk images can be viewed usingatrcopy create--help:$ atrcopy create --help
usage: atrcopy DISK_IMAGE create [-h] [-f] TEMPLATE

positional arguments:
  TEMPLATE     template to use to create new disk image; see below for list of
               available built-in templates

optional arguments:
  -h, --help   show this help message and exit
  -f, --force  replace disk image file if it exists

available templates:
  dos2dd          Atari 8-bit DOS 2 double density (180K), empty VTOC
  dos2ed          Atari 8-bit DOS 2 enhanced density (130K), empty VTOC
  dos2ed+2.5      Atari 8-bit DOS 2 enhanced density (130K) DOS 2.5 system disk
  dos2sd          Atari 8-bit DOS 2 single density (90K), empty VTOC
  dos2sd+2.0s     Atari 8-bit DOS 2 single density (90K) DOS 2.0S system disk
  dos33           Apple ][ DOS 3.3 (140K) standard RWTS, empty VTOC
  dos33autobrun   Apple ][ DOS 3.3 (140K) disk image for binary program
                  development: HELLO sets fullscreen HGR and calls BRUN on
                  user-supplied AUTOBRUN binary fileTo create a new image, use:$ atrcopy game.dsk create dos33autobrunwhich will create a new file calledgame.dskbased on thedos33autobrunimage.dos33autobrunis a special image that can be used to create autoloading
binary programs. It contains an Applesoft Basic file calledHELLOwhich
will autoload on boot. It sets the graphics mode to fullscreen hi-res graphics
(the first screen at $2000) and executes aBRUNcommand to start a binary
file namedAUTOBRUN.AUTOBRUNdoesn’t exist in the image, it’s for you
to supply.Creating a Custom Boot DiskBlocks of binary data can be combined into a boot disk in either ATR format for
Atari or DSK format for Apple:$ atrcopy boot --help
usage: atrcopy DISK_IMAGE boot [-h] [-f] [-s [ASM [ASM ...]]]
                               [-d [DATA [DATA ...]]] [-b [OBJ [OBJ ...]]]
                               [-r RUN_ADDR]

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 ...]], --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
  -b [OBJ [OBJ ...]], --obj [OBJ [OBJ ...]], --bload [OBJ [OBJ ...]]
                        binary file(s) to add to assembly, either executables
                        or labeled memory dumps (e.g. BSAVE on Apple ][),
                        parsing each file's binary segments to add to the
                        resulting disk image at the load address for each
                        segment
  -r RUN_ADDR, --run-addr RUN_ADDR, --brun RUN_ADDR
                        run address of binary file if not the first byte of
                        the first segmentOne of-s,-d, or-bmust be speficied to provide the source for
the boot disk. The-bargument can take an Atari binary in XEX format, and
will properly handle multiple segments within that file. If no starting address
is supplied (or, if using an XEX, to override the start address normally
contained within the XEX), use the-roption. Otherwise, the run address
will point to the first byte of the first binary segment.Creating Programs on the Disk ImageThe simple assembler included inatrcopycan create binary programs by
connecting binary data together in a single file and specifying a start address
so it can be executed by the system’s binary run command.It is also possible to assemble text files that use the MAC/65 syntax, because
support forpyatasmis built-in (but
optional). MAC/65 is a macro assembler originally designed for the Atari 8-bit
machines but since it produces 6502 code it can be used to compile for any
machine that uses the 6502: Apple, Commodore, etc.Creating Atari 8-bit ExecutablesAtari 8-bit object files include a small header and an arbitrary number of
segments. Each segment defines a contiguous block of data with a start and end
address. If the file has multiple segments, they will be processed in the order
they appear in the file, not by segment start address.This example creates a newxexon a disk that combines the segments of an
already existing executable with some new assembly code.After creating the test image with:$ atrcopy test.atr create dos2sd
using dos2sd template:
  Atari 8-bit DOS 2 single density (90K), empty VTOC
created test.atr: ATR Disk Image (size=92160 (720x128B), crc=0 flags=0 unused=0) Atari DOS Format: 707 usable sectors (707 free), 0 filesthis command compiles the filetest_header.sand prefixes it to the
existing executable:$ atrcopy test.atr asm -s test_header.s -b air_defense_v18.xex -o test.xex -f
test.atr: ATR Disk Image (size=92160 (720x128B), crc=0 flags=0 unused=0) Atari DOS Format: 707 usable sectors (707 free), 0 files
fname: test_header.s
Pass 1: Success. (0 warnings)
Pass 2:
adding 0600 - 0653, size=0053 ($53 bytes @ 0600) from test_header.s assembly
adding 02e2 - 02e4, size=0002 ($2 bytes @ 02e2) from test_header.s assembly
adding  $02e0-$02e2 ($0002 @ $0006) from air_defense_v18.xex
adding  $6000-$6bd4 ($0bd4 @ $000c) from air_defense_v18.xex
total file size: $c3d (3133) bytes
copying test.xex to test.atrCreating DOS 3.3 BinariesFor this example, the goal is to produce a single binary file that combines a
hi-res imagetitle.binloaded at 2000 hex (the first hi-res screen) and
code at 6000 hex from the binary filegame, with a start address of 6000
hex.The binary filegamewas assembled using the assembler from thecc65project, using the command:cl65 -t apple2 --cpu 6502 --start-addr 0x6000 -o game game.sBecause the Apple ][ binary format is limited to a single contiguous block of
data with a start address of the first byte of data loaded,atrcopywill
fill the gaps between any segments that aren’t contiguous with zeros. If the
start address is not the first byte of the first specified segment, a small
segment will be included at the beginning that jumps to the specifiedbrunaddress (shown here as the segment from 1ffd - 2000). Note the gap between 4000
and 6000 hex will be filled with zeros:$ atrcopy game.dsk create dos33autobrun
using dos33autobrun template:
  Apple ][ DOS 3.3 (140K) disk image for binary program development: HELLO sets
  fullscreen HGR and calls BRUN on user-supplied AUTOBRUN binary file
created game.dsk: DOS 3.3 Disk Image (size=143360 (560x256b)
File #0  ( A) 002 HELLO                          003 001

$ atrcopy game.dsk asm -d title.bin@2000 -b game --brun 6000 -f -o AUTOBRUN
game.dsk: DOS 3.3 Disk Image (size=143360 (560x256b)
adding BSAVE data $6000-$6ef3 ($0ef3 @ $0004) from game
setting data for $1ffd - $2000 at index $0004
setting data for $2000 - $4000 at index $0007
setting data for $6000 - $6ef3 at index $4007
total file size: $4efa (20218) bytes
copying AUTOBRUN to game.dskExample on macOSmacOS supplies python with the operating system so you shouldn’t need to
install a framework version from python.org.To prevent overwriting important system files, it’s best to create a working
folder: a new empty folder somewhere and do all your testing in that folder.
For this example, create a folder calledatrtestin yourDocumentsfolder.  Put a few disk images in this directory to use for testing.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 theApplications/Utilitiesfolder in the Finder.  When Terminal opens, it will
put you in your home folder automatically.  Go to theatrtestfolder by
typing:cd Documents/atrtestYou can see the ATR images you placed in this directory by using the
command:ls -lFor example, you might see:mac:~/Documents/atrtest $ ls -l
-rw-r--r-- 1 rob  staff  92176 May 18 21:57 GAMES1.ATRNow, run the program by typingatrcopy GAMES1.ATRand you should
see the contents of theATRimage in the familiar Atari DOS format: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    066See other examples as above.Referenceshttp://www.atariarchives.org/dere/chapt09.phphttp://atari.kensclassics.org/dos.htmhttp://www.crowcastle.net/preston/atari/http://www.atarimax.com/jindroush.atari.org/afmtatr.htmlhttps://archive.org/details/Beneath_Apple_DOS_OCRRelated Atari Projectsfranny: (C, macOS/linux) Command line program to manage Atari DOS 2 and SpartaDOS II image and file systemsdir2atr: (Win) Suite of command line programs to manage Atari disk images and DOS 2/MyDOS file systemsatadim: (Win) Graphical program to manage Atari disk images and DOS 2/MyDOS file systemsRelated Apple ProjectsTurns out there are a ton of Apple ][ disk image viewers and editors! I was pointed to the list from thediskii project, so I’ve included most of that list here.a2disk(Python 3) DOS 3.3 reader and Applesoft BASIC detokenizercppo(Python) a script from thea2serverproject to read DOS 3.3 and ProDOS disk imagesDriv3rs(Python) Apple III SOS DSK image utilityc2d: (C, Win/macOS/linux) Command line program to create bootable Apple disk images (no file system)Apple Commander: (Java) Command line program to manage Apple disk images and file systemsCider Press: (Win) Graphical program to manage Apple disk images and file systemsdiskii: (Go) Command line tool, under developmentCadius(Win) Brutal Deluxe’s commandline toolsdsktool(Ruby)Apple II Disk Tools(C)libA2(Perl)AppleSAWS(Qt, Win/macOS/linux) very cool looking GUIDiskBrowser(Java) GUI tool that even displays Wizardry levels and VisiCalc files!dos33fsprogs(C)apple2-disk-util(Ruby)dsk2nib(C)standard-delivery(6502 assembly) Apple II single-sector fast boot-loader