Retropak 0.1, (c) 2014 Ali Campbell.

- v0.1, 30th November 2014

LICENCE
-------
Retropak is open source software licensed under the zlib licence. For details,
see the file licence.txt, which you should have received with this software.

The Windows and Mac OS X executable versions of retropak include a binary
copy of the LZO library, which is covered separately under the GNU General
Public License (GPL). See the file COPYING in the lzo-2.08 directory provided
with these two versions.

WHAT IS RETROPAK?
-----------------
Retropak is a cross-platform command-line utility written in C for the purpose
of unpacking and repacking PAK files from the GameCube Metroid Prime games.
It is particularly intended to be helpful to other people writing their own
repacking solutions.

This version of retropak currently only supports PAK files with 32-bit file
IDs. It should be fine for unpacking PAKs from any GameCube retail version
of Prime or Echoes.

FEATURES
--------
* Open source. Self-documents the PAK format. Permissive zlib licence -- use
  this code in your own projects.  
* Cross-platform. Plain C implementation should make ports straightforward.
* Bash-based unit tests.
* Automatic PAK file recognition via database of header CRCs.
* Fast unpacking. Skips duplicated files in PAKs rather than blindly
  extracting them. In my tests, typically 30% to 50% faster than PakTool 0.86
  when unpacking an entire game.
* Uses name table information from the PAK file (where available) to create
  longer, more descriptive filenames for extracted data files. (This feature
  can be switched off for compatibility with PakTool.)
* Robust. Produces useful error messages for many different forms of mangled
  input, and tries hard not to crash. Intended to be useful to other people
  writing their own repacking solutions.
* Optionally will perform CRC checking on payloads of duplicated files within
  a PAK, to check that all payloads with the same ID do indeed contain
  identical data.
* Automatic directory creation, lower case filename support, file overwrite
  protection, and other convenient minifeatures.

GETTING RETROPAK
----------------
Binary builds of retropak (and needed runtime libraries) for Windows and Mac
OS are available:

http://chexum.co.uk/retropak/retropak-0.1-win32.zip
http://chexum.co.uk/retropak/retropak-0.1-macosx.zip

For other architectures (i.e. Linux), a source-only release is provided:

http://chexum.co.uk/retropak/retropak-0.1-source.zip

Because the Windows and Mac OS versions contain a precompiled copy of LZO,
they must also include a full copy of the LZO source code for compliance with
the GPL 2 under which LZO is licenced. (This is why the Windows and OS X
versions are a megabyte each but the source version is only 80K. Blame Richard
Stallman.)

RUNNING RETROPAK
----------------
Retropak is a command-line application intended to be run under your OS's
command-line environment.

The PAK files used by Prime 1 and 2 use common compression algorithms --
specifically zlib (for Metroid Prime 1) and LZO1X (for Metroid Prime 2).
Retropak requires dynamically-linked copies of these libraries at runtime in
order to be able to compress and decompress the payloads within PAK files:

- Windows
  In the Windows distribution, precompiled copies of lzo2.dll and zlib1.dll
  are provided along with retropak.exe. When running retropak from a command
  prompt, Windows will expect the DLLs to be found in the same directory as
  retropak.exe.

- Mac OS X
  In the Mac OS distribution, a precompiled copy of liblzo2.2.dylib is
  provided along with the retropak executable. The retropak executable expects
  to find this file in the current working directory when it is executed. If
  you would rather put LZO somewhere else (say a fixed location) you can set
  the DYLD_LIBRARY_PATH environment variable to point to a directory
  containing the dylib. (Mac OS X provides its own system zlib, so there was
  no need to bundle a precompiled zlib).

  You may need to set execution permissions on the retropak executable before
  Mac OS will let you run it:
  
  chmod u+x retropak

- Source Only
  For the source code-only distribution, neither external library is provided.
  This release is aimed mainly at Linux users whom it is assumed will link
  against distribution-installed system versions of zlib and LZO.

GETTING STARTED
---------------
The first thing you will need will be an image file of your chosen game. This
can be generated by ripping a retail disc of the game using a soft-modded Wii
running CleanRip. Please do not download image files.

Once you have the image file transferred to a computer, you will need to
extract the files within this image (some of which are PAK files). There
are various tools available to do this, including wit and my own PHP script,
mkiso.php.

wit:   http://wit.wiimm.de/
mkiso: http://chexum.co.uk/entry.php?eid=44

A number of Windows-specific solutions are also available.

Once you finally have some PAK files to work with, you can try using retropak
to extract one:

retropak unpack -p Metroid1.pak

This will create a directory called Metroid1 in the current working directory
and extract the contents of Metroid1.pak into this directory. It will also
generate a metafile containing information which will be required should
you want to repack the directory into a new PAK file later on. In this example
the metafile would be saved to Metroid1/retropak.txt.

Repacking the Metroid1 directory to a new PAK file would be accomplished like
this:

retropak pack -d Metroid1 -p newpak.pak

(By default, retropak would try to repack the Metroid1 directory to the file
Metroid1.pak. Since Metroid1.pak probably already exists, the -p option is
used to specify a different filename for the new PAK. Retropak will refuse to
overwrite existing files, unless it is run with the -o option).

For more information on retropak's various modes and options, run it from the
command line with no arguments; its built-in help should be clear enough.

UNIT TESTS
----------
The "tests" directory contains a series of unit tests to confirm that retropak
is working as expected. The tests take the form of a hacky bash script and
assume the availability of some standard Unix utilities (grep, sed, dd etc.)
If you wish to run these tests on Windows you will therefore need to install
MSYS/MinGW, and run the tests from within that environment.

To run the tests, simply cd to the tests directory and run tests.sh. The
script will exit on the first test that does not succeed, so look for the
completion message to confirm that all tests have succeeded. Some tests
(those involving symbolic links) will be skipped on Windows.

BUILDING RETROPAK
-----------------
Retropak has been successfully built with gcc and with Microsoft Visual Studio
2010. Clang may work, but has not been tested in a while.

- Source-only Release

  The source-only release contains a trivial bash script called build.sh
  which will work for e.g. a typical Linux setup using gcc.

- Mac OS X

  The Mac OS X release contains a bash script called build_osx.sh which calls
  gcc. This script will expect to find the LZO source and the bundled LZO
  dylib in its current working directory, and build against these resources.
  This will produce a copy of retropak that looks for the LZO dylib in its
  current working directory, as the bundled executable does. If you have a
  system-installed LZO, and would rather link against that, try using the
  build.sh from the source-only distribution instead.
  
  Mac OS X provides its own zlib so nothing special needs to be done for that.

- Windows

  The Windows release is intended to be built using Visual Studio 2010. Other
  versions of VS may work, but no others have been tested. Building under
  MSYS/MinGW will probably work but has also never been tested.
  
  You will need .lib files for linking against the two compression libraries.
  An appropriate .lib file for the bundled lzo2.dll is provided as part of
  this release. Meanwhile, a suitable .lib file for zlib may be obtained from
  the zlib "compiled DLL" package, which is available from zlib.net. 

  I have not provided a Visual Studio project but the only significant detail
  when creating one is to remember to set up include paths to the zlib and
  LZO header files. These are bundled for LZO thanks to the GPL but you will
  need to get the zlib source code independently so the compiler can access
  the header files for zlib. To set up these paths in Visual Studio 2010:
  
  - right click on the project name in "Solution Explorer" (the tree on the
    left);
  - in the resulting window, in the tree on the left, select "C/C++" under
    Configuration Properties;
  - add the LZO and ZLIB include directories to "Additional Include
    Directories" at the top, separating the two paths with a semicolon.
  
  DLLs and .libs can simply be dragged into the VS project, as can retropak.c.
  


