                              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.2 release date: 27.04.1999

TABLE OF CONTENT

1	Introduction	
2	Installing TargetD64	
3	Configuring TargetD64	
3.1	Adding non supported archives to TargetD64	
3.2	Where to define environment variables	
3.3	Usage of external helper applications with the -x option	
4	Make TargetD64 support "Drag & Drop"	
5	How TargetD64 works	
6	Reporting Bugs	
7	Frequently Asked Questions	
8	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 by command line options and 
environment variables.

With the Win32 binary distribution of TargetD64 there come configurations 
for CCS64 V2.0 beta DOS/Win32 and C64S V2.25.

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 (12th of April 1999) 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 :-). TargetD64 needs to call a batchfile or 
executable which starts up the emulator. MAKE SURE THIS BATCHFILE OR 
EXECUTABLE IS ON YOUR EXECUTION PATH, which means it can be called from any 
location within the filesystem. TargetD64 will rely on this!

TargetD64 is pre configured for the use of VICE V0.16.x. Download the VICE 
distribution at http://www.cs.cmu.edu/~dsladic/vice/vice.html. Make sure 
that x64 lies on your execution path.

This binary distribution includes:

targetd64         the frontend itself
targetd64.xpm     KDEs icon for targetd64
README            about targetd64
COPYING           copyleft notice
MANUAL            targetd64 user manual
generic.sh        sample configuration of the generic archive interface
sample.lnx.gz     sample archive to test configuration
sample.zip        see above

Copy targetd64 into a directory on your execution path.

If you have x64 (part of VICE) installed test your installation with 
"targetd64 sample.lnx.gz". x64 comes up. You should load and run the first 
program from unit 8 (LOAD"*",8,1).

If you run into problems use option "-d" or "-t filename" to get an 
execution trace.

If you want to launch another emulator read the appropriate sections.

---------------------------------------------------------------------------
3 Configuring TargetD64
---------------------------------------------------------------------------

If you are not satisfied with the defaults you can apply a variety of 
configuration features to TargetD64.

targetd64 [-h] [-v] [-n] [-d] [-t tracefile] [-k] [-x]
          [-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 (> character).

Option -c targetdir stands for "conversion only". With targetdir you 
specify a directory for the resulting D64 images. No emulator will be 
launched. After finished processing 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.

Option -x activates the OBSOLETE "external helper application" mode. That 
means that most of the supported formats are treated by external 
applications (which have to be located on the execution path). See the 
appropriate manual chapter for details. Usage of this option is NOT 
recommended. ONLY use this option if you run into errors when extracting an 
archive file.

Environment:

TMPDIR
TMPDIR sets the temporary directory for TargetD64. If it is not set /tmp is 
used 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:
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 this goal (maybe because of 
lacking command line options like CCS64 V1.09).

The following placeholders are replaced by their actual values at runtime:
%s1 %s2 %s3 %s4
%s1 is replaced by the 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 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 temporary directory (see TMPDIR).

Example:
cd '%s1' && x64 -8 '%s2'

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 Adding non supported archives to TargetD64
---------------------------------------------------------------------------

TargetD64 is able to hook in other archive formats by the generic archive 
interface. 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.

To handle a new archive format you have to 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
%s1 is replaced by the pathname of the directory where the files are put to 
while extracting the archive. There is no trailing "/".
%s2 is replaced by the pathname of the archive to extract.
%s3 is replaced by the pathname of the archive to be extracted without
dirname and extension. E.g. "/tmp/test.zip" will be replaced by "test".

Example: hook in tar support
TD64_GENERIC_EXT1=.tar
TD64_GENERIC_CMD1="cd '%s1'; tar xf '%s2'"

3.2 Where to define environment variables
---------------------------------------------------------------------------

Mind that the complete TargetD64 configuration can be achieved by 
environment variables. This is even true for default command line options 
which can be set by the TD64_DEFAULT_OPTIONS environment variable.

Use the usual startup scripts like .bashrc, .profile to set environment 
variables. It depends on the shell you are using. And do not forget the 
export command (maybe another command for other shells than bash).

3.3 Usage of external helper applications with the -x option
---------------------------------------------------------------------------

The usage of external helper applications for TargetD64 natively supported 
archives is OBSOLETE and NOT recommended. Only do so if you ever run into 
errors while extracting an archive. If this is not the case, please skip 
the following explanations.

Linux distributions usually come with a version of lha, gunzip and unzip. 
Install the appropriate packages. The program is tested with versions:
LHA for UNIX V1.00 (execute lha without parameters for version string)
Unzip V5.12 (execute unzip without parameters for version string)
Gunzip V1.2.4 (gunzip -V)


---------------------------------------------------------------------------
4 Make TargetD64 support "Drag & Drop"
---------------------------------------------------------------------------

This description only applies to KDE for linux. I am convinced that other 
desktops and WMs will provide "Drag & Drop", too.

1. Copy the TargetD64 icon targetd64.xpm into your KDE icon directory which 
will be by default $HOME/.kde/share/icons.
2. Press the right mouse button somewhere on the desktop. Select New-
>Program in the popped up context menu.
3. Now there pops up a window prompting for the name of the link. Name it 
TargetD64.kdelnk.
4. Somewhere on the desktop there appears a "gear wheel" icon named 
TargetD64. Click on this icon with the right mouse button.
5. Choose the Properties menu item. Choose the execute tab.
6. Click on the browse button and select the targetd64 executable. Add %f 
after the TargetD64 pathname (this will launch targetd64 with the files 
dropped on the icon). You may enter any TargetD64 options before %f.
7. Check the "Run in terminal" check button to watch potential TargetD64 
error messages when executing.
8. Click on the "gear wheel" button. Select your private icon repository 
$HOME/.kde/share/icons from the combo box. Now select the formerly 
copied TargetD64 icon from the list box.

Now you are ready to go. Launch KDE's file manager kfm. Navigate to and 
select one or more C64 archives. Drag the selection to the prepared 
TargetD64 icon and drop it on the icon. TargetD64 will process the dropped 
files and bring up VICE (x64) by default.

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.

To configure another emulator set the appropriate environment variables. 
Make sure the environment variables are set at startup. After this is 
established "Drag & Drop" will work for another emulator as well.

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

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

---------------------------------------------------------------------------
7 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: What are environment variables and how does TargetD64 make use of them?

A: Each program that is executed has access to environment variables. So it 
is a good media to pass information to programs. Once you have set the 
value of an environment variable all programs started with the affected 
environment can access the variable. In practice you will provide a set of 
environment variables which are set at OS startup time. This will 
guarantee, that all programs called after system startup will see the right 
values of those environment variables. Mind that the memory space of the 
environment may be limited. Sometimes you can expand this memory area 
(Win95/98: see the SHELL command for config.sys and the /e option of 
command.com).

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 what command line is 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: 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. Set the environment variables for TargetD64 at system startup and use 
only the TargetD64 executable itself (or a shortcut/link to it) for "Drag & 
Drop".

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