Hvscupdate-src

             ===================================================
             HVSC UPDATE TOOL AND HVSC UPDATE SCRIPT DESCRIPTION
             ===================================================

                                   version
                                    2.8.4

AUTHORS:
The Shark <shark()dhp.com>
    (original author of the HVSC Update Tool, maintained it until v2.5)
Michael Schwendt <sidplay()geocities.com>
    (v2.4.x portability fixes, v2.5 - v2.6.1, v2.7.0 GCC v3 patch)
LaLa <LaLa()C64.org>
    (v2.7.0)


INTRODUCTION
============

In order to provide a clean and easy way to update the High Voltage SID
Collection (HVSC - http://www.hvsc.c64.org) from time to time, an HVSC Update
pack is provided to users. It contains an Update script, which describes how
the update should be performed, plus a bunch of SID files in PSID v2NG format
that will be moved to their final location inside HVSC as described in the
Update script. (See the PSID v2NG document for a complete description of that
file format.) The HVSC Update Tool uses the Update script to carry out the
actions described in it.

The Win32 version of the HVSC Update Tool is packaged inside every HVSC Update
pack, since a large percentage of HVSC users are using some flavor of the
Microsoft Windows operating system. Users of other operating systems can find
executables for their systems on the HVSC webpage, or can ask for the HVSC
Update Tool source code from the HVSC Crew to compile an executable
themselves.

The HVSC Update Tool was written by The Shark, the person who brought HVSC
itself into life. Later it was modified by Michael Schwendt to make it more
compatible with many operating systems, and then by LaLa to add PSID v2NG
support to it. Certain source files of the tool were lifted from Michael
Schwendt's libsidplay SID emulator library and were later hacked for PSID v2NG
conformance by LaLa.


UPDATE TOOL
===========

See also 'VERSION DEPENDENCY' later.


DIR HIERARCHY DEPENDENCY
------------------------

The Update Tool checks for the existence of the Hubbard_Rob directory in the
HVSC - if it doesn't exist, a warning is issued stating where the Update
script should be placed and the user is given the choice to quit or continue.

The Update script depends on a presumed HVSC directory hierarchy and thus, the
Update Tool assumes the Update script is placed in a directory inside the HVSC
(usually named 'update') before performing the update. Filenames relative to
the main directory of the HVSC therefore are actually relative to the parent
directory of this 'update' directory.


MODIFYING SID FILES
-------------------

Any file that is modified with the Update Tool (i.e. modified by keywords that
change bits, bytes or characters inside a PSID file) is always saved as a
valid PSID v2NG file, even if it wasn't such before. This means that, for
example, any bits that might have been set in the 'reserved' field of the file
before will be zeroed out by the Update Tool, since this field is defined as
such in the PSID v2NG specification.


AFTER THE UPDATE
----------------

If the Update Tool encounters errors during an update, it logs them to a file
named 'ErrorXX.hvs', where XX is the same number that is found in the filename
of the Update script.

If no errors are encountered, there will be no ErrorXX.hvs file produced and
the UpdateXX.hvs script itself will be moved to the DOCUMENTS directory of
HVSC.


UPDATE SCRIPT
=============

Below is a complete description of the format of the Update script. When in
doubt, the UpdateXX.hvs files found in the DOCUMENTS directory of HVSC always
provide good examples.


FILENAME
--------

The name of the Update script must follow the convention 'UpdateXX.hvs', where
'XX' is a 2-digit decimal number that is usually one larger than the number of
the most recent Update script found in the DOCUMENTS directory inside HVSC. If
an Update script with the same filename already exists in the DOCUMENTS
directory, the Update Tool quits immediately with an error, since it's assumed
that the user wants to apply an update to an already updated collection.


FILE FORMAT
-----------

The HVSC Update script is a plain text file.

Lines starting with a ``#'' or ``;'' character as the first non-space
character are treated as comments unless they belong to a block of parameter
lines. Comment lines can be everywhere except between successive parameter
lines.

Empty or blank lines are ignored, i.e. skipped.

Leading white-space characters of a line are skipped unless the line belongs
to a block of parameter lines which are meant to be copied into the sidtune
file directly (see description of TITLE, AUTHOR, COPYRIGHT, CREDITS keywords).


VERSION DEPENDENCY
------------------

The first few lines of every update script must contain these lines which
reflect the Update Tool's dependency on the version of HVSC to be updated with
the Update script:

# Resulting Version: 4.6
#  Previous Version: 4.5

The Update Tool will fetch the version numbers from these lines. The number of
white-space between the words can be arbitrary.

The HVSC version is fetched directly from the main HVSC documentation file
found inside the HVSC as /DOCUMENTS/hv_sids.txt. The first few lines of that
file must contain a line which contain nothing else than the word "release"
followed by a real value. White-space is ignored. Example:

  release 4.5

Note that due to the difference between the PSID v2NG and v2 file
specification, if the version of HVSC being updated with this version of the
tool is lower than 3.9, the 'startPage', 'pageLength', 'psidSpecific', 'clock'
and 'sidModel' fields will be automatically zeroed out when saving PSID files!


KEYWORDS
--------

Actions to be performed during an update are described by keywords. Each
keyword selects a mode for actions and can be followed by one or more blocks
of parameters - or another keyword (i.e. no parameters). Thus, repeated
statement of the same keyword in front of successive parameter blocks is not
necessary.

Keywords are case-sensitive.

Parameter blocks consist of one or more lines of text.

This version of the tool recognizes the following keywords (sometimes also
called directives):

AUTHOR:    2
CLOCK:     2
COPYRIGHT: 2
CREDITS:   4
DELETE:    1
FIXLOAD:   1
FLAGS:     5
FREEPAGES: 2
INITPLAY:  2
MKDIR:     1
MOVE:      2
MUSPLAYER: 2
PLAYSID:   2
REPLACE:   2
SIDMODEL:  2
SONGS:     2
SPEED:     2
TITLE:     2

The numbers after the keywords describe the number of parameter lines that
are taken in the mode selected by the given keyword.


HVSC-RELATIVE PATHNAMES
-----------------------

Every keyword above takes at least one parameter which is a pathname that is
relative to the HVSC's main directory and must contain the slash (/) or back-
slash (\) characters as file/directory separators. In this document all
pathnames are so-called HVSC-relative pathnames unless explicitly stated
otherwise.

Destination directories must end with a / or \ character in order to be
recognized as a directory unless they exist already. To improve readability of
the script, it is recommended that all directories end with a / or \
character.

Filenames, directory names, and pathnames are all case-insensitive. The HVSC
Update Tool examines each directory to determine the correct case of a full
path name. This is done to be file-system independent, archiver independent,
and to allow for small typos in the script.

These all name the same file:

/Galway_Martin/Wizball.sid
/GALWAY_Martin/Wizball.SID
/galway_martin/wizball.sid

The intended case for new files and directories is specified in form of
destination pathnames (or the files in the HVSC Update pack). The precedence
of file naming is the following in decreasing order of priority:

1.) Take case of the destination file name (if specified).
2.) Take case of the source file name (if specified).
3.) Take case of file name found in the HVSC Update pack.

NOTE: The old HVSC Update Tool (version 2.4.x and older) did not do this
properly!

See the REPLACE keyword below for examples.


DESCRIPTION OF KEYWORDS
-----------------------

Below is a listing of each keyword, the parameters they take and a detailed
description of what they do. Since many of the keywords change specific fields
inside PSID v2NG files, the reader is advised to become familiar with the PSID
file format before reading further.

The format of parameter lines is as follows:

- <dir> is a place-holder for an HVSC-relative path to a directory.
- <file> is a place-holder for an HVSC-relative path to a file.
- <32-bit hex> indicates a 32-bit hexadecimal value (with no prefix).
- <16-bit hex> indicates a 16-bit hexadecimal value (with no prefix).
- <8-bit hex> indicates an 8-bit hexadecimal value (with no prefix).
- <dec> indicates a decimal value.
- <text> indicates plain text that is max. 31 characters long, end-of-string
  delimiter excluded.
- <PAL | NTSC> indicates the possible case-sensitive (!) values for the given
  parameter, in this case only two, PAL and NTSC.

Note that repeated statement of command keywords in the examples below is
redundant.


MKDIR
-----

Creates the last directory in the specified pathname which is the only
parameter it takes. Causes an error if the path leading to that directory does
not exist.

NOTE: This keyword is almost obsolete since MOVE and REPLACE can create the
last sub-dir in a path on the fly.

Format:

MKDIR
<dir>

Examples:

# Creates the Example directory, provided that /VARIOUS/AMJ/ exists.
MKDIR
/VARIOUS/A-F/AMJ/Example/

# Causes an error if directory Blubb1 does not exist.
MKDIR
/VARIOUS/S-Z/Zardax/Blubb1/Blubb2/


DELETE
------

Deletes the file or directory specified by the pathname on the single
parameter line. The given file must exist or an error is produced. The
directory to be deleted must be empty or an error is produced. Only the last
directory in the pathname is deleted.

Formats:

DELETE
<file>

DELETE
<dir>

Examples:

# File must exist.
# Why, if we want to get rid of it anyway? :)
DELETE
/DRAX/Worktunes/Bad_Rip.sid

# Deletes the UNKOWN directory inside the DEMOS directory if it's empty,
# leaves the DEMOS directory untouched.
DELETE
/DEMOS/UNKNOWN/


MOVE
----

Probably the most complex keyword found in Update scripts since it can take
many forms, although its usage should be fairly intuitive. This keyword always
takes two parameter lines, where both parameter lines contain a pathname: the
first parameter line is always the source and the second is always the
destination.

Formats:

MOVE
<dir>
<dir>

Non-recursive copy of directory contents, i.e. it does not include sub-
directories and their contents. It deletes the files in the source directory
(but not the directory itself). Creates the destination directory if it
doesn't exist, yet.

MOVE
<file>
<file>

Copies the source file to the destination file. Gives an error if the
destination file already exists. Gives an error if the directory of the
destination file does _not_ exist (this prevents creating unwanted dirs on the
fly). Deletes the source file when done.

MOVE
<file>
<dir>

Copies the source file to the destination directory. If the destination
directory does not exist, it creates it. Note that this will not create the
full path, but just the last directory component like MKDIR. Deletes the
source file when done.

Examples:

# Moves the given SID file from the update directory to its final destination
# in HVSC.
MOVE
/update/Crowther_Antony/Gryphon.sid
/Crowther_Antony/

# Moves the non-recursive contents of the Olsen directory from the update
# directory to its final destination in HVSC.
MOVE
/update/VARIOUS/A-F/Amorphis/Olsen/
/VARIOUS/A-F/Amorphis/Olsen/

# Renames Gyroscope_loader.sid to Gyroscope_3_crack.sid as it moves it to its
# new location in HVSC.
MOVE
/GAMES/G-L/Gyroscope_loader.sid
/DEMOS/Gyroscope_3_crack.sid

# The next two parameter blocks show a plaform-independent safe way of
# changing the case of one or more characters of a filename.
MOVE
/GAMES/M-R/Rings_N_Up.sid
/GAMES/M-R/Rings_n_Up_.sid

/GAMES/M-R/Rings_n_Up_.sid
/GAMES/M-R/Rings_n_Up.sid

# Moves the new file to its new location and deletes the old file (which
# was likely a bad rip).
MOVE
/update/GAMES/A-F/Boom_title.sid
/GAMES/A-F/
DELETE
/DEMOS/Boom.sid

# Note, this is the prefered way of doing the above two actions, since other
# scripts scanning the Update script will be able to deduce the new filename
# this way, unlike in the previous case.
MOVE
/DEMOS/Boom.sid
/GAMES/A-F/Boom_title.sid
REPLACE
/update/GAMES/A-F/Boom_title.sid
/GAMES/A-F/


REPLACE
-------

Probably the second most complex keyword found in Update scripts. :-) Like
MOVE, this keyword also takes two parameter lines, where both parameter lines
contain a pathname: the first parameter line is always the source and the
second is always the destination.

Formats:

REPLACE
<dir>
<dir>

Non-recursive merge of directory contents, i.e. it does not include sub-
directories and their contents. Creates the last destination directory if it
doesn't exist. Note that this will not create the full path, but just the last
directory component like MKDIR. Overwrites any destination file that already
exists. Deletes the source files (but not the directory that contains them).

REPLACE
<file>
<file>

Replaces the destination file with the source file. Overwrites the destination
file if it already exists. Deletes the source file when done. Gives no error
if destination file does _not_ exist.

REPLACE
<file>
<dir>

Copies the destination file to the destination directory. Overwrites the
destination file if it already exists. Deletes the source file when done. If
the destination directory does not exist, it is created. Note that this will
not create the full path, but just the last directory component like MKDIR.

Examples:

# Example to demonstrate case-insensitivity.
#
# The following example overwrites any file named ``example.sid'',
# disregarding case, and calls it ``eXaMpLe.SID'', disregarding the case of
# the actual file in the HVSC Update pack.

REPLACE
/update/DEMOS/eXaMpLe.SID
/DEMOS/

# The following overwrites any file named ``example.sid'', disregarding case,
# and calls it ``Example.sid'', disregarding the case of the actual file in
# the HVSC Update pack.

REPLACE
/update/DEMOS/eXaMpLe.SID
/DEMOS/Example.sid


TITLE, AUTHOR, COPYRIGHT
------------------------

These keywords take a destination file name as the first and a credit line as
the second parameter line. A credit line must not be an empty or blank line
and is limited to 31 characters, end-of-string delimiter excluded. TITLE
changes the 'name' field inside a PSID file, AUTHOR the 'author' and COPYRIGHT
the 'copyright' field.

Note that these keywords _always_ change the destination file to a valid PSID
v2NG file!

Format:

TITLE
<file>
<name - text>

AUTHOR
<file>
<author - text>

COPYRIGHT
<file>
<copyright - text>

Example:

# This is a comment inside an Update script.
# Below example changes the 'name' field inside Amtrak.sid.
TITLE
/20CC/Amtrak.sid
Amtrak


CREDITS
-------

This keyword provides an easier way to change the 3 credit lines inside a PSID
file at once. The CREDITS keyword takes a path to a file and three successive
lines as parameters. A parameter line consisting of nothing but an
asterisk (*) leaves the corresponding credit line in the given PSID file
untouched. See also TITLE, AUTHOR and COPYRIGHT above.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

NOTE: HVSC Update #10 has a parameter block which lacks the third credit line.
Since old versions of the Update Tool did not detect this and hence did not
cause an error, empty credit lines either must be allowed or the update
version must be checked and Update #10 treated differently.

Format:

CREDITS
<file>
<* = don't change | name - text>
<* = don't change | author - text>
<* = don't change | copyright - text>

Examples:

CREDITS
/20CC/Amtrak.sid
Amtrak
Edwin van Santen
1989 20th Century Composers

# Another example. Don't change author name.
# Next blank line will be skipped, these set of comments are ignored.

/20CC/Amtrak.sid
Amtrak
*
1989 20th Century Composers


SPEED
-----

Changes the 'speed' field inside a PSID file. It takes a destination file name
as the first and a hexadecimal value as the second parameter line. The
hexadecimal value shouldn't be bigger than 32 bits. If the number of bits set
this way is more than the number of songs in a PSID file, only the relevant
bits will be set by the Update Tool.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

SPEED
<file>
<speed - 32-bit hex>

Example:

# Changes the 'speed' field to 0x0000007F.
SPEED
/GAMES/A-F/Bird_Mother.sid
7F


SONGS
-----

Changes the 'songs' and 'startSong' fields inside a PSID file. It takes a
destination file name as the first and two comma separated decimal values as
the second parameter line: the first one changes the 'songs' field, the second
the 'startSong' field. The decimal values should be less than 256 and the
second value should be less than the first. There should be no whitespace
around the comma.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

SONGS
<file>
<songs - dec>,<startSong - dec>

Example:

# Changes the number of songs to 6 and the 'startSong' to 3.
SONGS
/Brooke_Jason/Pi_r_Squared.sid
6,3


INITPLAY
--------

Changes the 'initAddress' and 'playAddress' fields inside a PSID file. It
takes a destination file name as the first and two comma separated hexadecimal
values as the second parameter line: the first one changes the 'initAddress'
field, the second the 'playAddress' field. Since these refer to C64 addresses,
the values should be maximum 16 bits large. There should be no whitespace
around the comma.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

INITPLAY
<file>
<initAddress - 16-bit hex>,<playAddress - 16-bit hex>

Example:

# Changes the 'initAddress' to $107E and the 'playAddress' to $1078.
INITPLAY
/20CC/Airwolf_Mix.sid
107E,1078


MUSPLAYER
---------

Changes the 'musPlayer' field (bit 0 of the 'flags' field) inside a PSID file.
It takes a destination file name as the first and a binary value as the second
parameter line. A 0 indicates a built-in player, a 1 that Compute's Sidplayer
is required to play the given SID tune.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

MUSPLAYER
<file>
<0 = built-in player | 1 = Compute's Sidplayer is required>

Example:

# Changes bit 0 of 'flags' to indicate a built-in player is present in the SID
# file.
MUSPLAYER
/Hubbard_Rob/Commando.sid
0


PLAYSID
-------

Changes the 'psidSpecific' field (bit 1 of the 'flags' field) inside a PSID
file. It takes a destination file name as the first and a binary value as the
second parameter line. A 0 indicates the 'data' portion of the PSID file is
C64 compatible, a 1 indicates that it's PlaySID specific (requiring special
extensions introduced by the Amiga PlaySID program, like sample support,
random value support, etc.)

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

PLAYSID
<file>
<0 = C64 compatible | 1 = PlaySID specific>

Example:

# Changes bit 1 of 'flags' to indicate this SID file is PlaySID specific.
PLAYSID
/Tel_Jeroen/Hotrod.sid
1


CLOCK
-----

Changes the 'clock' field (bits 2-3 of the 'flags' field) inside a PSID file
which indicate the video standard to be used to play the included SID tune,
basically determining its speed. The keyword takes a destination file name as
the first and a case-sensitive textual value as the second parameter line.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

CLOCK
<file>
<UNKNOWN | PAL | NTSC | ANY or EITHER>

Example:

# Changes bits 2-3 of 'flags' to indicate this is an NTSC tune.
CLOCK
/GAMES/G-L/Into_the_Eagles_Nest_USA.sid
NTSC


SIDMODEL
--------

Changes the 'sidModel' field (bits 3-4 of the 'flags' field) inside a PSID
file which indicate the SID model the tune inside the given PSID file was
intended for. The keyword takes a destination file name as the first and a
case-sensitive textual value as the second parameter line.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

SIDMODEL
<file>
<UNKNOWN | 6581 | 8580 | ANY or EITHER>

# Changes bits 3-4 of 'flags' to indicate this tune was intended for an 8580
# SID chip.
SIDMODEL
/VARIOUS/A-F/Agemixer/Azmagutah_8580.sid
8580


FLAGS
-----

Similar to the CREDITS keyword it makes it easier to change all bitfields
found in the 'flags' field of a PSID file at once. It takes a destination file
name as the first parameter line and 4 other parameter lines that are
identical to the ones described in the  MUSPLAYER, PLAYSID, CLOCK and SIDMODEL
keywords above (in the same order). A parameter line consisting of nothing but
an asterisk (*) leaves the corresponding bitfield in the given PSID file
untouched.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

FLAGS
<file>
<* = don't change | 0 = built-in player | 1 = Compute's Sidplayer is required>
<* = don't change | 0 = C64 compatible | 1 = PlaySID specific>
<* = don't change | UNKNOWN | PAL | NTSC | ANY or EITHER>
<* = don't change | UNKNOWN | 6581 | 8580 | ANY or EITHER>

Example:

# Changes the 'clockSpeed' to indicate PAL and the 'sidModel' to indicate
# 8580 SID chip, leaves the other bits in 'flags' untouched.
FLAGS
/VARIOUS/A-F/Agemixer/Azmagutah_8580.sid
*
*
PAL
8580


FREEPAGES
---------

Changes the 'startPage' and 'pageLength' fields inside a PSID file. It takes a
destination file name as the first and two comma separated hexadecimal values
as the second parameter line: the first one changes the 'startPage' field, the
second the 'pageLength' field. The values should be maximum 8 bits large.
There should be no whitespace around the comma.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

FREEPAGES
<file>
<startPage - 8-bit hex>,<pageLength - 8-bit hex>

# Indicates that the SID tune doesn't use the memory area $C000-$D000.
FREEPAGES
/Hubbard_Rob/Commando.sid
C0,10


FIXLOAD
-------

Increases load address of the C64 'data' inside a PSID file by 2. It is used
to drop the first two bytes of C64 data to get rid of a duplicate load address
($0FFE instead of $1000, for example). It takes one parameter line only, which
should be the filename to be modified.

Note that this keyword _always_ changes the destination file to a valid PSID
v2NG file!

Format:

FIXLOAD
<file>