-------------------------------------------------------------------------------
                          MAMEDiff v1.24 - 23/01/2004

                   Written by Logiqx (http://www.logiqx.com/)
-------------------------------------------------------------------------------

1. Introduction
---------------

MAMEDiff makes it easy to identify ROM related changes in a new release of MAME.
Sometimes sets can just be 'rebuilt' but other times you will need to download
new or fixed ROMs. MAMEDiff will tell you what needs to be done and also gives
instructions specific to merged/split/non-merged sets. It will cut down on
unnecessary ROM downloading and makes it easier to see what sets need fixing.
It also makes it possible to completely fix+update your sets with one pass of
your favorite ROM manager... just rebuild the ZIPs that MAMEDiff tells you and
both the changes and additions can done together. :)

MAMEDiff is far more powerful than a simple text comparison and is even useful
alongside a good ROM manager. It can spot game renames and will not regard them
as one game deleted and another added. When ROMs or games are renamed (or if
there is a change in the way that sets are merged), MAMEDiff will just tell you
how to rebuild the affected sets (i.e. no downloading required). Even if every
game and ROM were renamed, MAMEDiff would know that you don't need to download
a thing. It only takes a fraction of a second to work it out too!

MAMEDiff is not intended as a "what new games can I leech?" tool.

The purpose of MAMEDiff is to assist in keeping your ROM sets working with the
minimum of effort. It is also good to see what has changed in the new release
(it has even found game additions that aren't mentioned in whatsnew.txt).

MAMEDiff was developed using MinGW and is free to use. But... you use MAMEDiff
at your own risk. I take no responsibility for any loss/damage caused as a
result of it's use.


2. Distribution
---------------

The home page for MAMEDiff is http://www.logiqx.com/


3. Using MAMEDiff
-----------------

There are two ways that you may want to use MAMEDiff; one will give a general
overview of changes and the other will tell you how to fix your sets.

Before you use MAMEDiff you will need the listinfo output from the versions of
MAME that you are comparing. You can do this with the following command:

mame -listinfo >listinfo.txt


3.1. To generate a summary of changes
-------------------------------------

Use the command:

mamediff listinfo.1 listinfo.2      (using whatever file names you chose)


This will save a report to mamediff.log containing up to 4 sections:

- Game removals. Occasionally this will be a false alarm and there will be a
  corresponding game addition. This problem is explained later in this document.
- General set changes. These include ROM renames, ROM removals, remerging and
  game renames (where the 8 character name changes but not the ROMs themselves).
- Games requiring new/fixed ROMs. These are existing games that need extra ROMs.
- Game additions. These are totally new games to MAME.

If you want a detailed summary (this shows the ROM changes for all the sections
above), use the '-v' option (verbose mode). This gives a deeper insight into the
changes and also says whether the new ROMs can already be found elsewhere in
MAME sets.

i.e. mamediff -v listinfo.1 listinfo.2

Handy tip: Wildcards can also be used to specify the filenames.


3.2. To generate a customised report for your ROM set type
----------------------------------------------------------

Use the m, s or n options (m=merged sets, s=split sets, n=non-merged sets).

e.g. mamediff -m listinfo.1 listinfo.2


This will save a report to mamediff.log containing 3 sections:

- Set changes. A list of the ZIP files affected by the new MAME release (this
  is an amalgamation of sections 1 and 2 from the standard report but how they
  effect your set type). Run these ZIPs through your ROM manager's rebuild
  option. It may be that there is a more efficient way to implement the changes
  but a rebuild is by far the easiest.
- Games requiring new/fixed ROMs. These are existing games that need patches.
  It may be that these ROMs are already available in MAME so use the verbose
  option to check.
- Game additions. These are totally new games to MAME.


4. How to use the reports
-------------------------

The syntax of the reports should be fairly self explanatory but I'll give a
couple of examples.

e.g. a game rename looks like this:

< Pole Position II (Atari set 2) [name: poleps2a - parent: polepos2]
> Pole Position II (Atari bootleg 2) [name: poleps2c - parent: polepos2]

e.g. a ROM rename looks like this:

< rom ( name la02 size 2048 crc 43bc65c5 )
> rom ( name spcewarl.2 size 2048 crc 43bc65c5 )

A removal or addition is shown by a line beginning '<' or '>'.


5. Alternative reports and dat creation (added in v1.06)
--------------------------------------------------------

5.1 Using the -M, -S and -N options to report 'ZIPs to change'
--------------------------------------------------------------

The M, S and N options can be used to list changes at ZIP level (the m, s and
n options do clever game level comparisons). Use the option suitable for your
set type (M=merged sets, S=split sets, N=non-merged sets) and MAMEDiff will
list 'ZIPs Removed', 'ZIPs Changed' and 'ZIPs Added'. It will also create a
CMPro dat that can be used to build these sets in isolation (for speed or
archiving). If you prefer ROMCenter to CMPro then convert the dat using DatUtil
(available at http://www.logiqx.com/).

This option is ideal for webmasters as it will allow them to build just the new
and changed ROM sets that need uploading to their website following a new MAME
release.


5.2 Using the -t and -T options to produce (tiny) supplementary dats (v1.09)
-----------------------------------------------------------------------------

In addition to the -M, -S and -N options that produce CMPro dats of changed
ZIPs, you can produce a 'tiny' versions of the dats. This allows you to create
a small supplementary dat for the new emulator that when added to the original
set is 100% suitable for the new emulator (i.e. for emulators that support
multiple ROM paths).

The difference between -t and -T is that -t ensures that ROMs of the required
name+size+crc exist in the relevant ZIPs whilst -T doesn't insist on the ROM
names matching (i.e. for emulators that can load ROMs by CRC).

Not only can these options be used when upgrading from one version of an emu
to another but they can even be used when trying to use ROMs of one emulator
with another (e.g. trying to use MAME ROMs with RAINE, Kawaks or Nebula). When
used in this way you can use a standard MAME ROM set and a small emulator
specific 'supplementary' ROM set for the emulator of your choice.

In order for this facility to work correctly it uses the clrmamepro header item
'forcemerging' from the second dat (to identify the styles of ROM merging that
are supported by the emulator). Absense of this item is taken to mean that all
types of merging are supported (i.e. ROMs can be in either parent or clone).


6. Limitations
--------------

A good tip is to check that for each game removal there isn't a similar game
addition in the last section. This can happen when the 8 character name for a
game is changed at the same time as the ROM content itself. MAMEDiff can spot
game renames by their ROM content. However if both the name and content change
at once then it won't know that the old and new games are related so it comes
up as a deletion and an addition.

The logic that decides on necessary rebuilds is intended to make life simple. It
does not differentiate between simple renames and ROMs physically moving from
one ZIP to another. It just says which ZIPs need rebuilding to fix all of the
ZIPs.

Other than that, I think I've covered most things pretty well...


7. Source
---------

I have included source for anyone who is interested but don't look at it for too
long. Getting your head around it is liable to give you a headache... you have
been warned! :)


8. Bug reports
--------------

If you find any bugs please let me know about them.

If a set change fails to appear in the summary output then it is a bug. If an
action isn't given to fix an issue reported in the summary output then it could
also be a bug. Having said that, I've done a fair bit of testing... every MAME
release from v0.36 b15 to v0.37 beta 1. That was most tedious!


9. Thanks
---------

Thanks to Pi for beta testing MAMEDiff and suggesting some little ideas (like
tiny dat generation). Guru-Choc for doing beta testing of v1.13.


10. History
-----------

23/01/2004  v1.24  Increased the maximum number of games from 5000 to 6000.
                   Added support for the 0x syntax used in some data files.
                   Fixed a small glitch in -S/-N/-M (used by 'MAME Changes')
                   where resources containing changes may not get output.
                   Note: This only used to happen when the resource was not
                   required by any of the games in the output data file.
                   I finally got around to making a change so that new MAME
                   resources don't need to be added to MAMEDiff ever again.
                   I guess I was being lazy and never expected so many of them!

20/01/2004  v1.23  Internal 'fix merging' runs twice now so that it propagates
                   to all clones.
                   Minor adjustment to the routine that decides if a ROM lives
                   in a resource. This fixes the handling of shootgal/sg-01-0
                   and lots of unrequired games in a 'split-merged changes'
                   datafile.

31/12/2003  v1.22  Added knowledge of the atpsx resource.

28/12/2003  v1.21  Added knowledge of the 2 new resources added in MAME v0.78.
                   Increased the maximum ROM size to 9 digits (for sfish2).

17/08/2003  v1.20  Added knowledge of the 7 new resources added in MAME v0.72.

20/05/2003  v1.19  Found a small glitch while testing the non-public v1.18.

20/05/2003  v1.18  Fixed memory addressing bug (triggered by the many apparent
                   [but not really] merge related changes in MAME v0.58).
                   Included 'fix merging' logic in the listinfo parser because
                   MAME listinfo no longer includes merge details.

19/05/2003  v1.17  Fixed so that the missing konamigx resource in MAME v0.67
                   doesn't cause a crash!
                   Added support for the new 'nodump' syntax of MAME v0.68.

07/04/2003  v1.16  Added knowledge of the Konami GX BIOS.

18/01/2003  v1.15  Increased line buffer size to 32KB (for those people who end
                   up with MAME history in their listinfo).
                   Added knowledge of the Sega ST-V BIOS.

14/11/2002  v1.14  Required some improvements for MAME v0.62:
                   Added support for the SKNS resource.
                   Improved merge handling (required by European SKNS games).
                   Does not output empty year information to mamediff.dat.
                   Made a minor change to improve compatibility with MSVC++.

20/05/2002  v1.13  Automatically detects and handles new resource ROMs.
                   New resource ROMs are now included in the -t/-T output.

22/04/2002  v1.12  Minor improvement to log for supplements.
                   Added support for the PGM BIOS.

04/04/2002  v1.11  Made internal 'fix-merging' logic check CRC as well as name.
                   Increased maximum ROM name length to 20 (for neopong).
                   Minor fix relating to ROM names that are too long.
                   Exits gracefully when the maximum no of games/ROMs reached.

17/03/2002  v1.10  Fixed bug with last version where standard compare refused
                   to start (affected -v as well).

14/03/2002  v1.09  Added the -t and -T options (see section 5.2 above).
                   Made CRCs case insensitive.
                   Minor fix to -v output.

08/02/2002  v1.08  Improved the -M, -S and -N options:
                   - The dats generated now include resource information so
                     that CMPro can separate out Standard/Neo-Geo games etc.
                   - The non-merged dat now doesn't include 'merge' information
                     in games where the parent isn't included in the dat.
                   Modified source to compile easily with CygWin (and FreeBSD?).

07/05/2001  v1.07  Minor fix: Removes unneeded 'romof' details with -S and -N.
                   Now compiled with MinGW (just like the new Windows MAME).
                   Can also be compiled with Microsoft Visual C++.

24/03/2001  v1.06  Added three new modes (-M, -S and -N) to show newly required
                   ZIPs (see section 5 of the documentation for more details).
                   Now ignores RAINE and clrmamepro headers.
                   Compiled with -Wall (fixed all warnings it uncovered).

11/03/2001  v1.05  Tiny fix to exclude resources from the game and ROM totals.

31/12/2000  v1.04  Increased game name length from 8 to 20 (for Modeler dat).
                   Prefixes Neo-Geo titles with 'Neo-Geo' (so they stand out).
                   ROMs added to parent set are also reported for clone too.
                   Now spots merge changes at the same time as CRC complement.
                   Added '-c' option to assist with the maintenance of CAESAR.
                   Included source, do not abuse!
                   Internal change: max of 32 flags instead of 16 (int->long).
                   Internal change: strcpy->strncpy to avoid memory problems.

28/07/2000  v1.03  Added complemented CRC handling.

23/05/2000  v1.02  Added support for MESS (just a minor modification).
                   Added RAINE support too (since it was so easy).

24/04/2000  v1.01  Minor bug fixed (SIGSEGV crash in pure DOS).

15/04/2000  v1.0   Initial Release.
