TARGETD64 AN UNIVERSAL C64 ARCHIVE RELATED CONVERTER TOOL AND EMULATOR FRONTEND TargetD64 homepage: https://targetd64.sourceforge.io Author: Karlheinz Langguth mailto:karlheinz.langguth@web.de ~/MANUAL: TargetD64 user manual ------------------------------- TargetD64 0.5.0 release date: 09.11.19 TABLE OF CONTENT 1 Introduction 2 Installing TargetD64 3 Configuring TargetD64 3.1 Generic Archive Interface 3.2 Make TargetD64 support "Drag & Drop" 4 How TargetD64 works 5 Reporting Bugs 6 Frequently Asked Questions 7 Copyright notice --------------------------------------------------------------------------- 1 Introduction --------------------------------------------------------------------------- There are various C64 emulators available. Supported formats are varying, but they all support D64 format (.d64 file), which comprises the content of a c64 disk. After you have downloaded a C64 program from the internet you usually find that this program is treated by archivers and often by more than one archiver, likely not supported by the C64 emulator as input. The basic idea behind TargetD64 to support as many archives / formats as possible and transform any input to D64 file(s) which are passed to the C64 emulator. Thus TargetD64 is a frontend providing suitable input for the C64 emulator (the backend) in the form of D64 files. Well known examples of presented C64 content are .lnx.gz or .d64.zip format. Normally you are going through a process of dearchiving which needs user interaction (e.g. calling gunzip or launching up WinZip and so on). TargetD64 takes away all this work from the user. TargetD64 recognizes the archive format(s) and dearchives recursively. TargetD64 will finally produce D64 files which are passed to the C64 emulator. Supported archive formats are zip, gz, lha, lnx, rar (< V2.9), [1-4]!, ark, d64, x64, t64, p00. If a file can not be matched to one of these formats it is treated as a raw C64 (PRG) file. TargetD64 will process all horizontal and vertical combinations of the above stated archive formats. Vertical combinations are nested archives (e.g. .lnx in .gz). Horizontal combinations are an arbitrary sequence of archives (e.g. .lnx and .p00 file which are both contained in a .zip archive). The latter also applies to a sequence of archives you can give as command line arguments (in this case the sequence can also be achieved by filename wildcards). Neither nesting level nor sequence size are limited by TargetD64 itself (but they are by system resources). All mentioned archives are builtins. So TargetD64 does not depend on any external applications (except the emulator of course). TargetD64 is implemented in C++ with common sources for Win32 and Linux (distinction is achieved by compile switch). TargetD64, published under the terms of GPL, uses foreign GPL sources as mentioned in the distribution's README. TargetD64 is fully "Drag & Drop" capable for Win32 and Linux's KDE. It is strongly recommended to configure "Drag & Drop" for the ease of use. TargetD64 is pre configured for VICE (Linux) and WinVICE (Win32). It is fully adaptable to other emulators. This can be achieved by editing the profile file (preferably) or by command line options and environment variables. A test suite is ready for download. The test suite is fully automated for Linux (result verification). For Win32 the result verification has to be done manually. TargetD64 is right now available in source and binary distribution for: * Linux on x86-64 compatible processor, glibc-2.26 based. * Windows 10 (Windows 8/7/XP are not tested but are supposed to work). Only a 32 bit version has been tested which has been verified to work on 64bit Windows as well. TargetD64 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. TargetD64 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A copy of the GNU General Public License is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.html. --------------------------------------------------------------------------- 2 Installing TargetD64 --------------------------------------------------------------------------- As you have downloaded TargetD64 as an emulator frontend I assume you have an emulator installed. This binary distribution includes: targetd64.exe the frontend itself targetd64.ini targetd64 profile file targetd64.ico icon for targetd64 README about targetd64 COPYING copyleft notice MANUAL targetd64 user manual sample.lnx.gz sample archive to test configuration sample.zip see above 1. Copy targetd64.exe into a directory on your execution path (see note below). Thus TargetD64 can be found independent of the current directory (when called from command line). 2. Copy targetd64.ini into the SAME directory where you copied targetd64.exe before. 3. Configure "Drag & Drop" as described later in this manual. Now test your installation by dragging one of the demo files that come with this distribution (sample.lnx.gz or sample.zip) from Explorer onto the TargetD64 icon. The emulator should be started with the produced D64 image. Depending on the emulator you have to type RUN or load the first program on disk. If you don’t use WinVICE as emulator you have to configure TargetD64 on your own (insert an own Cmd entry into the [Emulator] section). Use the same syntax as for environment variable TD64_EMU_CMD. Note: Mind that the Cmd entries of the [Emulator] section are NOT using absolute filenames. This means the emulator executable (or batchfile) has to be on the execution path to be found by TargetD64. So expand your execution path or use absolute filenames in the profile file. The execution path is determined by the environment variable PATH. You can take a look at it by executing the command "path" at command prompt. You can expand your execution path by appending a new directory after a ";" character. In Windows 10 the PATH variable is set in a dialog. Right click "This PC" icon in explorer and choose "Properties". Press the button "Advanced System Settings" and click on "Environment Variables…" button. Search for a variable named PATH or Path and edit this variable by adding the directory prepended by semicolon (;). ATTENTION: If you have environment variables set by older configurations those have priority over profile settings. In this case first delete those environment variables to get the profile settings active (or leave them if you are satisfied). If you run into further problems use option "-d" or "-t filename" to get an execution trace. --------------------------------------------------------------------------- 3 Configuring TargetD64 --------------------------------------------------------------------------- If you need to configure TargetD64 you will usually edit the profile file: \targetd64.ini This file is part of the TargetD64 binary distribution and is well commented. So you will not find any further description here. Additionally you may use command line options and environment variables to achieve your configuration. This is quite obsolete and only supported for compatibility to prior releases. In general command line options have priority over environment variables which have priority over profile settings. The command line looks like: targetd64 [-h] [-v] [-n] [-d] [-t tracefile] [-k] [-f imagefilename] [-s formatstring] [-c targetdir] file... Please note that even for Win32 options are indicated by a dash not a slash. TargetD64 processes the files given at command line resulting in one or more D64 image(s) containing unresolvable C64 files. Those D64 images are put into a temporary directory. Dearchiving is executed recursively. Supported archive formats are zip, gz, lha, lnx, rar (< V2.9), [1-4]!, d64, x64, t64, p00. If a file can not be matched to one of these formats it is treated as a raw C64 (PRG) file. Resulting D64 images are named target001.d64 to targetXXX.d64. An emulator is launched with target001.d64. Repository information (like D64 directory) is passed to the emulator. After exiting the emulator all traces of the processing (even the D64 images for the emulator) are deleted. Option -h prints out a help text. Option -v writes out the version of targetd64. Option -n preserves the directory tree built while processing after program termination. The directory tree is located in the temporary directory (see environment variable TMPDIR). Option -d stands for "debug". TargetD64 comes heavily instrumented for the beta releases. This option will provide a runtime trace on stderr (redirect the output of file handle 2 to a file because it will be a lot of information). This is mainly for me as the developer. On the other hand you see every call of external programs. So it can be useful for you, too. Option -t tracefile is the same than -d except that the trace output is dumped into a file named tracefile instead stderr. This is especially introduced for poor command interpreters that are not able to redirect stderr. Use -t stdout to dump the trace output into stdout. This is useful to have a synchronized output of the trace facility and other commands. Even command.com of Win32 can redirect stdout (>file). Option -f imagefilename forces the resulting D64 image(s) to be named imagefilename.d64 where idx is empty string for the first D64 image produced and after that incrementing from zero, neutralizing potential usage of -k. Option -s formatstring assigns formatstring to be used for D64 image formatting. This is the counterpart of 1541 format string used by the format command. Formatstring is written as name,id where name is maximum 16 character name and id is two character ID of the resulting D64 image. Option -c targetdir stands for "conversion only". With targetdir you specify a directory for the resulting D64 images. No emulator will be launched. After processing has finished you will find the resulting D64 images in targetdir. Option -k stands for "keep archive filename". Parts of the filename of the processed archive are used to name the resulting D64 image. This should make it easier to relate the D64 image to its source when specified multiple files for processing. Environment: To set an environment variable to a value use "SET name=value". Look at the result by "SET". If you have to use the % character in value mind that it has a special meaning for command prompt. Possibly you have to quote it by using %%. This is especially the case within batch files. TMPDIR, TMP, TEMP The value of TMPDIR has priority over TMP has priority over TEMP. If none of these are set c:\temp is set as the temporary directory. TargetD64 will create the top of its temporary directory tree in this directory. Do NOT use the top level (root) directory as the temporary directory! TD64_DEFAULT_OPTIONS To make TargetD64 completely configurable by environment variables any option(s) that have to be handled with each call of TargetD64 can be stated in TD64_DEFAULT_OPTIONS. For example if you ALWAYS want to use the "-d" and "-k" option set TD64_DEFAULT_OPTIONS like this: set TD64_DEFAULT_OPTIONS=-d -k The options you give as program arguments are preceded by the options set in TD64_DEFAULT_OPTIONS. TD64_EMU_CMD The command to launch the emulator. This command is passed to the shell so you may use the complete shell syntax in general. Goal's to achieve: 1. Set the emulator's image directory so that the user is able to select one of the produced images WITHOUT changing directories. 2. Set the first produced image as the emulator's default disk image so that the user is able to load a program from it WITHOUT selecting a image. As Win32 command syntax is very restrictive, I have added the semicolon ";" to execute commands in a row. So "echo a; echo b" will first execute "echo a" and afterwards "echo b". Mind that the commands are written into a batchfile which is actually executed. This is important when calling batchfiles. You have to use the "call" command if you don’t want to terminate the processing after the batchfile has been executed (see example below). The following placeholders are replaced by their actual values at runtime: %s1 %s2 %s3 %s4 %l1 %l2 %l3 %l4 %d1 %d2 %d3 %d4 %s1 is replaced by the short (8.3 as DOS executables need it) pathname of the directory where the D64 images reside. In contrast to prior versions there is no trailing "\" at the end of the directory. %s2 is replaced by the short (8.3 as DOS executables need it) pathname of the first emulator image for the emulator. %s3 is replaced by the basename of %s2 which means stripped off directory path. %s4 is replaced by the short (8.3 as DOS executables need it) pathname of temporary directory (see TMPDIR). %l is replaced by the long pathname version of %s as Win32 applications can handle. %d is replaced by the drive info of %s (e.g. 'c:'). Example: mkdir %l4\images; copy %l1\*.d64 %l4\images; call ccs64_95 %s2,0; del %l4\*.d64 Will copy all resulting D64 images into \images, call ccs64_bat (use "call" command otherwise processing will be aborted after the call of batchfile ccs64_95) and delete the D64 images after emulator exit. Mind that this (quite complicated) setting is only a work around for CCS64 V1.09 lacking feature to set the D64 image repository directory by command line option. ATTENTION: I have encountered that filenames with the "+" character are not treated as expected by the copy command. So it is the best choice to quote the filenames like: copy "sourcefilename" "targetfilename" The copy command accepts quotation marks for grouping characters to a single filename. This might not be true for other commands. It is a matter of experiment. Consider this when configuring other emulators. When changing commands by environment variables it is always a good idea to monitor the changes with the "-d" or "-t filename" option as you will see all commands fully expanded. 3.1 Generic Archive Interface --------------------------------------------------------------------------- This is the interface to add non supported archives to TargetD64 and to overwrite builtin dearchivers by external applications. The latter is a replacement for the ancient external helper mode which relied on a set of external applications for dearchiving. To overwrite builtin dearchivers is only necessary when you have run into errors. Adding non supported archives should be the main reason for this feature. To do so there are two prerequisites: 1. The newly added archive can be identified by an extension (e.g. .tar) 2. There is an external application that can extract the archive format in one of TargetD64 natively supported formats. It is not possible to hook in multipart archives like [1-6]!! (sixpack) by this mechanism. Still TargetD64 is "open source" so you may add the support directly on source level. Normally you will edit the [GenericArchives] section of the profile file and insert an ExtCmdCombi entry (see comments in profile). For this entry the same syntax applies as for the TD64_GENERIC_EXTx/ TD64_GENERIC_CMDx environment variables described later. Alternatively to profile modification (although not recommended) you could define a pair of environment variables the first called TD64_GENERIC_EXTx the second called TD64_GENERIC_CMDx where x stands for a number. Mind that x must be a continuation starting with 1 (NO GAPS!). TD64_GENERIC_EXTx The extension to identify the format by. The extension must be specified with a leading dot (e.g. .tar). Mind that this extension is compared case insensitive, that means .tar stands for .TAR and .tar. TD64_GENERIC_CMDx Your goal is to extract the new archive found into files natively supported by TargetD64 (e.g. into a .d64 image). The directory to extract the files into is determined (by %s1). The archive to extract is determined (by %s2). The following placeholders are replaced by their actual values at runtime: %s1 %s2 %s3 %l1 %l2 %l3 %d1 %d2 %d3 %s1 is replaced by the short (8.3) pathname of the directory where the files are put to while extracting the archive. There is no trailing "\". %s2 is replaced by the short (8.3) pathname of the archive to extract. %s3 is replaced by the short (8.3) pathname of the archive to extract without dirname and extension. %l and %d are replaced accordant to TD64_EMU_CMD. Example: hook in tar support set TD64_GENERIC_EXT1=.tar set TD64_GENERIC_CMD1=cd %l1; tar xf %s2 3.2 Make TargetD64 support "Drag & Drop" --------------------------------------------------------------------------- After installing TargetD64 use Explorer to navigate into the installation directory. Select the file targetd64.exe. Use the right mouse button to drag it on the desktop. Drop it and create a shortcut (link) for it (select the appropriate menu item). Now select a C64 archive in Explorer and drag and drop it on the just created icon (representing the shortcut to targetd64.exe). By default WinVICE will start up and autostart the first program found in the generated D64 image. After you have configured "Drag & Drop" it is recommended to configure the "Send To" menu also for the ease of use. The "Send To" menu item appears after selecting files within Explorer and clicking the right mouse button. After navigating onto the "Select To" menu item you are presented a list of applications to send your selection to. To make TargetD64 one of those applications you have to create a shortcut (link) to TargetD64.exe in the SendTo directory of your user profile %AppData%\Microsoft\Windows\SendTo (might be C:\Users\\AppData\Roaming\Microsoft\Windows\SendTo). Executing TargetD64 by clicking on the desktop icon makes no sense as in this case no filename is passed to it. So ALWAYS drag file(s) from your file manager on the TargetD64 icon and processing will start. --------------------------------------------------------------------------- 4 How TargetD64 works --------------------------------------------------------------------------- You do not have to read this to get TargetD64 to work. Still it could be interesting. An original group of files to be processed is passed to TargetD64 via command line. TargetD64 copies those files into a freshly created temporary directory (see environment variable TMPDIR) and scans those files for resolvable archives. Those archives are mainly recognized by extension or other parts of the pathname (e.g. .zip, 1!disk). A few archives are also recognized by specific patterns (e.g. lynx and p00 archives). For each resolvable archive encountered a new temporary directory is created where this archive is extracted to. The directories build up a directory tree. The lastly extracted files are again scanned for resolvable archives (this is the recursion). Resolvable archives are extracted by TargetD64. The original filename and file type of included CBM files is preserved as possible (e.g. for lynx files). Unresolvable files are inserted into a D64 file created by builtin D64 support. If one D64 file is not enough another one is created. Each resolvable (container) archive encountered will lead to one or more separate D64 file(s) (if at least one unresolvable file is contained). Thus there is no merge of D64 files from different resolvable archives. All D64 images which are intended for emulator use are (per default) collected into a directory "images" under the top temporary directory. Example: test.lnx contains: a.lnx contains a.prg b.prg TargetD64 produces the following directory structure for the call "targetd64 test.lnx". (Directories in capital letters). C:\TEMP\targeta00208(top temporary directory) | +-IMAGES (unresolvables of a.lnx) | +- target001.d64 <-----------------------------------+ | +- target002.d64 | <-+ | | | +-MISC | | +-TESTA00208 | | | +-AA00208 | | | | +-a.prg (result proc step 2: extraction of a.lnx) -+ | | | | | +-a.lnx (result proc step 1: | | +-b.prg extraction of test.lnx) -----------------------+ | (unresolvables of test.lnx) +-test.lnx (firstly copied - input file) The last six characters of the directory names are an appendix to make the directory name unique. The front part is deduced by the filename of the processed archive. After exiting the launched emulator the whole directory tree is deleted by default. This description should only give you a clue on how TargetD64 works. The most important thing is that all resulting D64 images are collected into a single directory. There are a few options and environment variables to influence the processing of TargetD64. Especially the target directory and name generation for the resulting D64 images can be changed. --------------------------------------------------------------------------- 5 Reporting Bugs --------------------------------------------------------------------------- There is no error free software ;-). Before you are submitting a bug report to me check if the bug is really within TargetD64. Try to dearchive the files you want to be processed by TargetD64 manually step by step with other conversion tools. In most cases input files would be corrupted. Report bugs via https://sourceforge.net/p/targetd64/tickets. Alternatively you could mailto:karlheinz.langguth@web.de using subject "TargetD64 bugreport". Mention the TargetD64 version and your operating system. You are more than welcome to do the bug fix on your own. TargetD64 is copyrighted under the terms of GPL so the sources are available. Please pass the fix to me. If you have encountered bugs in this manual please report them, too. --------------------------------------------------------------------------- 6 Frequently Asked Questions --------------------------------------------------------------------------- Q: I have created a desktop shortcut (icon) for TargetD64. When (double)clicking on it nothing happens. Why? A: TargetD64 gets the filenames to be processed by command line arguments. This will happen when dragging files from your file manager to the TargetD64 icon. No command line argument is passed when (double)clicking on the icon. Thus no processing will happen in the latter case. If you don't like "Drag & Drop" please use TargetD64 as a command line tool. Q: TargetD64 executes silently without printing out an error message. Still there is no emulator launched. How come? A: The success of an emulator call is not safely checked by TargetD64 as Win32 sometimes does not indicate errors correctly. Probably the needed emulator batchfile or executable is not on your execution path. For CCS64 V1.09 it is ccs64_95.bat for example. May be you are using another emulator than the default configuration expects. In this case configure TargetD64 firstly. To track down the error use the "-d" or "-t filename" option. You will see the command line executed to call the emulator. Q: TargetD64 starts up the emulator with a produced D64 image. Still there should be more D64 images produced. Where are they? A: TargetD64 creates a directory \targetXXXXXX\images. is specified by environment variable (look up the meaning of the environment variable TMPDIR in this manual). XXXXXX is an appendix which makes the directory name unique and which changes from call to call. The whole path could be c:\temp\targeta00208\images for example. TargetD64 can be configured to put the produced D64 images always into a permanent directory. This is needed if the D64 image directory can not be set for the emulator. The CCS64 V1.09 configuration ALWAYS puts the produced images into \images. Use option "-d" or "-t filename" to see if the images are moved from the default location. Q: TargetD64 prints out "Assertion failed in File xxx Line yyy" and terminates. What does this mean? A: Hopefully you will never see such a message. Assertions are there to check TargetD64 internal states for integrity. If there ever will be such a message you have run into a state which has never been expected to occur while processing. You have revealed an internal error. Please do ALWAYS report such errors to me. Q: I have written a batchfile which sets environment variable for TargetD64 and calls TargetD64 afterwards. When I am using this batchfile for "Drag & Drop" and dropping a group of files on it, only a few files are processed. Where did I go wrong? A: First of all please do not use environment variables anymore to configure TargetD64 - use the profile instead. Second, to pass parameters from the batchfile to TargetD64 you will have to use parameter placeholders like "targetd64 %1 %2 %3 ... ". Those parameter placeholders are limited by number. Thus the sequence of input files is cut. So change the profile and use only the TargetD64 executable itself (or a shortcut/link to it) for "Drag & Drop". Q: I have edited TargetD64's profile file. How come my changes do not take effect? A: Check the syntax of your entry (stay as close to the examples as possible). Mind that a semicolon at the beginning of a line comments out the whole line (semicolons within a line do not count as comments). Mind that settings achieved by environment variables or command line options have priority over settings achieved by profile. So check if those settings overload your profile changes. Check if the profile is located in the right directory (see the installation chapter). --------------------------------------------------------------------------- 7 Copyright notice --------------------------------------------------------------------------- TargetD64 (c) 1998-2019 Karlheinz Langguth - Unrar from UniquE RAR File Library (c) 2000-2002 by Christian Scheurer UniquE RAR File Library homepage: http://www.unrarlib.org/ - Explode decompression by ClamAV ClamAV homepage: http://www.clamav.net (C) 2007-2009 Sourcefire, Inc. - Unlynx, C64zip from VICE Copyright © 1993-1994, 1997-1999 Teemu Rantanen Copyright © 1997-1999 Daniel Sladic Copyright © 1998-1999 Andreas Boose Copyright © 1998-1999 Tibor Biczo Copyright © 1993-1996 Jouko Valta Copyright © 1993-1994 Jarkko Sonninen VICE homepage: http://vice-emu.sourceforge.net - Unzip, Gunzip from Zlib (C) 1995-1998 Jean-loup Gailly and Mark Adler Minizip contribution (c) by Gilles Vollant Zlib homepage: http://www.zlib.net/ - Unlha from Lha(rc) for UNIX LHarc for UNIX V 1.02 Copyright(C) 1989 Y.Tagawa LHa for UNIX V 1.00 Copyright(C) 1992 Masaru Oki No homepage for LHA This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.