File	Date	Author	Commit
res-system	2013-01-13	Andrew Green	[826073] Added system resources to toolkit.
tools	2013-03-20	Andrew Green	[00412c] Print stderr output if a exec of a tool fails.
README.txt	2013-02-17	Andrew Green	[9f9718] Modified a bit for Windows.

Read Me

1. Introduction

The WaddaFundraiser Toolkit includes tools to make packaging customized 
WaddaFundraiser Android wallpapers easier. The Java JDK is a prerequisite 
to using the toolkit. After that toolkit installation and APK packaging
are a snap. 


2. Prerequisites

The Java JDK must be installed in order to use the WaddaFundraiser toolkit.
The Java JDK can be installed from either www.openjdk.org or
http://www.oracle.com/technetwork/java/javase/downloads
To confirm that the JDK is installed open a command prompt and type the following:
  jarsigner -help
If the command is not found the JDK is not properly installed.


3. Installation

Extract the toolkit into any directory.
For example, on Linux:
  mkdir ~/bin
  unzip wf_toolkit.zip ~/bin

On Windows you can use a GUI to extract the files.


4. APK Packaging

The primary interface to the toolkit is the WFPack.class Java command-line
application in the tools directory. WFPack should be run at a command prompt
while in a WaddaFundraiser Wallpaper Kit directory that contains the desired
customizations.

The only required argument to WFPack is the Android Package name for the
customized wallpaper. This should be a unique designation for the
wallpaper and organization. This is typically specified in a reverse URL
format such as org.yourorganization.thiswallpaper. You can see more
examples by examining the URLs of packages on Google Play.

You should change "thiswallpaper" for each customized wallpaper that you
create so that the wallpapers can be resident on a device at the same
time. Do this even if you create two customizations of the same
WaddaFundraiser wallpaper, e.g. WaddaCube. If you create one WaddaCube
wallpaper for basketball and another for football be sure to give them
two different package names so users can have them both installed and they
won't overwrite each other.

Here is an example of running WFPack:
  ~$ cd ~/mycustomizedwp
  ~/mycustomizedwp$ java -cp ~/bin/wf_toolkit_git/tools WFPack org.someschool.coolwp
    ...<WFPack output>...
  ~/mycustomizedwp$ ls
    bin  res  coolwp.apk  someschool.keystore

The file coolwp.apk is the packaged wallpaper that can be installed on
an Android device. This one command was all it took to package the APK.

Note: You must have a customized wallpaper directory to be packaged. See
WaddaFundraiser Wallpaper Kits for details on customizing a wallpaper.


5. Testing

Before distributing the wallpaper it should be fully tested. One easy way
to get the APK file to a device for testing is to upload it to a cloud
drive (such as Ubuntu One or Google Drive) and then download it to an
Android device. You can use either the web browser or the Android App for
these services. Please refer to these services for more details.

Be sure the device's Settings are set to allow installation of non-market
applications. Not all devices support this, but most do.


6. Destributing

After testing, an APK file can be distributed via Google Play or directly 
from your organizations website, cloud websites, social website, or other
file sharing means.


7. Keystore (Advanced Topic)

Each APK file is signed with a digital signature. The digital signature
or digital key is stored in a keystore file. The toolkit will create a
keystore if one is not provided or found. This is the someschool.keystore
in the example above. This keystore file should be used to sign all future
versions of the wallpaper so that the upgrade process goes smoothly. It
is thus important to safeguard and back up the keystore file. Additionally 
the same keystore can also be used to sign all wallpapers for the
organization. To use one keystore to sign other wallpapers the keystore
file can be specified on the command line to WFPack using the -keystore
option.

Here is an example of rebuilding the wallpaper from the previous example
once some updates have been made. The keystore is found and reused
automatically:
  ~/mycustomizedwp$ java -cp ~/bin/wf_toolkit_git/tools WFPack org.someschool.coolwp
    <...output...>
    Using existing keystore: someschool.keystore
    <...output...>

Here is an example of using the keystore to sign another wallpaper:
  ~/mycustomizedwp$ cd ~/myotherwp
  ~/myotherwp$ java -cp ~/bin/wf_toolkit_git/tools WFPack -keystore ~/mycustomizedwp/someschool.keystore org.someschool.coolwp
    <...output...>
    Using existing keystore: ~/mycustomizedwp/someschool.keystore
    <...output...>

If you have a keystore with different passwords and key aliases those can
be specified on the command line to have WFPack use those. This is advanced
usage, and is the most secure:
   Usage: WFPack [-keystore filename] [-storepass password] [-keyalias alias] [-keypass password] package-name


8. Licenses

The WaddaFundraiser toolkit includes unmodified versions of the following
open source tools. The tools and origins including licensing are listed
below:
  aapt       https://android.googlesource.com/platform/frameworks/base/+/master/tools/aapt/
  zipalign   https://android.googlesource.com/platform/build.git/+/master/tools/zipalign/