File	Date	Author	Commit
examples	2014-01-13	Groboclown	[5496a9] Add in the new shrinker (soot), and fix a long-...
launcher	2013-11-19	albrechtm	[abb00c] Update the applet list of sources.
resources	2014-01-14	Groboclown	[b7b3b9] Update flags so the build runs what it is suppo...
tools	2014-01-14	Groboclown	[735e7b] Add default index.html page on a / request
.hgignore	2013-11-13	Groboclown	[de7cf6] Add a new attirbute to the zip2gz task which be...
readme.txt	2014-01-13	Groboclown	[5496a9] Add in the new shrinker (soot), and fix a long-...

Read Me

Java 4k Build Tools
===========================================================================


This project contains a collection of Ant build scripts and Java tools to aid
with constructing a Java 4k game contest entry.  This allows for a repeatable
process for constructing the final file.

It provides a basic framework to compile the Java game file, and any tools used
to construct that file.

Note that a full build with kzip can run for hours as it performs an exhaustive
search to squeeze every byte out of the final pack200 gzip file.

Effort has been made to allow this project to work on a range of platforms.
However, it has only been tested on Windows and Linux.  One of the tools
supported by this framework (DeflOpt) is Windows-only, so extra effort must be
made to allow it to run on Linux (described below).


How To Use
==========================================================================

Setup Environment
--------------------------------------------------------------------------

Before you get started, make sure you have have Ant (http://ant.apache.org)
and a Java JDK installed on your computer.

The framework can take advantage of some additional tools:
    * yguard:
        http://www.yworks.com/en/products_yguard_about.htm
        A free-to-use Java library that can shrink class files.  The license
        prohibits it from being distributed with this package.
    * jshrink:
        http://www.e-t.com/jshrink.html
        Another class file shrinker.  This one has a trial license version,
        but if it's used with this framework, then you'll have to manually
        configure and run the tool during the build process.  Registered
        versions of the tool will run without the need for user input.
    * 7-Zip
        http://www.7-zip.org/
        A compression tool that has some descent results.  Download the
        version appropriate for your platform (it's a native application).
        It has versions for Windows and Linux.
    * kzip
        http://advsys.net/ken/utils.htm
        A compression tool that creates incredibly tight zip files.  It
        has Linux and Windows native clients.
    * DeflOpt
        http://www.walbeehm.com/download
        Tries additional compression techniques to squeeze even more bytes out
        of zip files.  It has a Windows-only client.

The java4k build framework also ships with several versions of proguard, but
it is setup to only run with one version.  Different versions of proguard
create different minimized class files, so you may want to experiment with
these to find the right one for your project.

DeflOpt is Windows only, but you can setup your system to run it on Linux.
This requires creating a shell script that will run DeflOpt through Wine.
Additional steps may be required in the script to ensure that all paths are
reachable through Wine.

Create Build Structure
--------------------------------------------------------------------------

Your game project can be located anywhere on your computer, but it will need to
be layed out in this format.  Replace "gamedir" with the name of your project.

gamedir\build.xml
    - The build file that references the java4k framework files, and possibly
        extends it.
gamedir\project.properties
    - Properties file that defines some project specific settings for the
        game.
gamedir\src
    - This directory contains the game source file.  It can contain multiple
        source files, but only one will actually be used (see below).
        This directory can be overridden (see
gamedir\tools
    - If you have some Java source files that you use for generating or
        modifying the base source files, the sources are placed here.  They
        will be compiled as part of the build process.
gamedir\resources
    - Additional resources used by the game.  These can be input files used by
        tools to generate or augment the source file, or the HTML page
        used to display the applet.

You should create a "local.properties" file in your game directory, or its
parent, to define your local setup.

The build will generate the directories "gamedir\work" and "gamedir\exports".


Configuring Your Build
--------------------------------------------------------------------------

At a minimum, you will need to define in your project.properties, the
property "project.active-class" to the name of the fully-qualified class name.
This should be just a single letter (you don't want to waste bytes on the
class name, or on a package).

In addition to this, you can override the properties defined in
"resources/global.properties" by setting them in your local.properties file.
Note that the "src" property should be set per project, and not globally,
as this is used when generating source files.

The "examples" directory contains some examples and templates to get you
started building a Java 4k game.



Running The Build
--------------------------------------------------------------------------

Run "ant" in your build to construct the final jar file.  This can take a
very long time, especially when kzip is included (the build exhaustively
uses kzip to squeeze out that last byte).

If you want to just quickly compile and test the application, then you
can run "ant test".

If you have a pack200 compressed file you want to try out, you can run
"ant httpd" to start a simple web server.  You can use the property "httpd.port"
to set the desired listening web server port (default is 8080), and "pack200"
to set which pack200 file to use.  For example:

    > ant httpd -Dhttpd.port=1811 -Dpack200=ready-for-publish/my.pack.gz

By default, the "pack200" property will look in the "work/jars" directory for
the pack200 file.

Advanced users may want to trim down the list of combinations of
shrinkers and optimizers.  The list of combinations of optimizers and
shrinkers is defined by the ant property "shrink-targets" - a
comma-separated list of combinations of the shrinkers.  The full list
is defined in the "ant-basic.xml" file.

How It Works
--------------------------------------------------------------------------

Magic!