                              TARGETD64
AN UNIVERSAL C64 ARCHIVE RELATED CONVERTER TOOL AND EMULATOR FRONTEND

TargetD64 homepage:
http://skyscraper.fortunecity.com/quadra/251/targetd64.html
Author: Karlheinz Langguth mailto:klangguth@netscape.net

~/MANUAL: TargetD64 user manual
-------------------------------

TargetD64 V0.3 release date: 18.10.99

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
---------------------------------------------------------------------------

To understand what TargetD64 actually is you need knowledge about the 
commodore C64 emulation scene. There is a newsgroup comp.emulators.cbm 
where you can get a few hints. There should also be a comp.emulators.cbm 
FAQ on the web. Please use a search engine to find it.

The basic idea behind TargetD64 is to shift as much processing as possible 
from the user to the computer before a particular program (or a group of 
programs) is executed by an emulator. After you have downloaded a program 
from the internet you usually find that this program is treated by 
archivers and often by more than one archiver. Well known examples should 
be the .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 archives which are passed 
to an emulator.

Supported archive formats are zip, gz, lha, lnx, [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.

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 CCS64 V1.09 DOS (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.

With the Win32 binary distribution of TargetD64 there come configurations 
for CCS64 V2.0 beta DOS/Win32, C64S V2.52 and WinVICE V1.1.

A test suite is ready for download (there you can see what TargetD64 can do 
for you and compare it to other tools). 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 i386-compatible processor, glibc2 based
Windows NT
Windows 95/98

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.

Right now (29-Sep-99) a copy of the GNU General Public License is available 
at http://www.gnu.org/copyleft/gpl.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. Edit the profile file targetd64.ini. Usually all you have to do is go 
through the [Emulator] section and comment in the Cmd entry for the 
emulator of your choice.
4. 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 your emulator is not mentioned in the [Emulator] section of the profile 
file you have to configure TargetD64 on your own (insert an own Cmd entry 
into the 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" in a dos command 
interpreter. You can expand your execution path by appending a new 
directory after a ";" character.

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 directory>\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] 
          [-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, [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 -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.com. 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.
There are emulators that can not achieve these goals (maybe because of 
lacking command line options like CCS64 V1.09).

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<n> is replaced by the long pathname version of %s<n> as Win32 
applications can handle.
%d<n> is replaced by the drive info of %s<n> (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 <TMPDIR>\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:
Even for such a badly designed shell like command.com there are special 
characters. 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<n> and %d<n> 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 CCS64 
V1.09 will start up and load the first program found on the generated D64 
image. Type "RUN" within the emulator to start the program.

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 Windows system directory (might be 
C:\WINDOWS\SendTo). Mind that you could have a personal copy of the SendTo 
directory for WinNT (in your profile).

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.

For bug reports preferably use the form at 
http://skyscraper.fortunecity.com/quadra/251/td64bugreport.html. 
Alternatively you could mailto:klangguth@netscape.net 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 surely 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 an directory <TMPDIR>\targetXXXXXX\images. <TMPDIR> 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 <TMPDIR>\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, 1999 Karlheinz Langguth

- 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://www.cs.cmu.edu/~dsladic/vice/vice.html

- Unzip, Gunzip from Zlib

 (C) 1995-1998 Jean-loup Gailly and Mark Adler
 Minizip contribution (c) by Gilles Vollant

Zlib homepage: http://www.cdrom.com/pub/infozip/zlib/zlib.html

- 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. 
