Files & Directories
------------------------------------------------------------------------------

  Buildfiles:
    build.xml
    local.properties
    build.properties
    default.properties
      Part of the ant buildsystem. `local.properties' is not part of the
      repository, but must contain a path to the Android SDK. You can generate
      it by calling `android update project' with the appropriate options.

    bootstrap.sh
    build-native.sh
    ndk
      Symlink to the Android NDK directory, generated by bootstrap.sh.
    ndk/ndk-build
      Builds the native code - you can run this script when you make changes to
      native code and only want to build ghanges. Running `bootstrap.sh' would
      trigger a full rebuild every time.

    build-externals.sh
      Finally, `build-externals.sh' builds libraries in the `externals' subdir.
      Since you'll generally not touch those sources, it's invoked once from
      `bootstrap.sh'.

  Documentation:
    design
      The `design' directory contains a few images on which image files used in
      the app itself are based. 
    docs
      The `docs' contains various bits of reference material.

      Lastly, some directories contain a `README.txt' file offering information
      on the directory's contents.

  Sources:
    AndroidManifest.xml
      Contains the application description.
    externals
      Contains sources of third-party libraries used in the project. Their
      respective licenses are described in `externals/README.txt'.
    jni
      Contains native code, both the custom JNI wrapper and the FLAC sources.
    res
      Contains images, layout files, and string resources.
    libs
      Contains JAR files. Some are downloaded as-is, others generated by
      `build-externals.sh'. `libs/README.txt' contains licensing information,
      and describes where JAR files come from.
    src
      The main Java sources.



  Building
------------------------------------------------------------------------------

Building this project requires a few steps due to the fact that it mixes
code from various sources, each of which come with their own build system.
Most steps only need to be performed once.

1.  Project path

    Change the current working directory to the path where AndroidManifest.xml
    resides. That'll be referred to as the project path.


2.  Set up the ant buildsystem.

    Run:
    $ android update project --path $(pwd) --target 4

    The target number may change as Android SDK versions change; you can
    retrieve the list of numbers via the following command:
    $ android list target

    At the time of writing, target number 2 refers to "Android 1.5" API Level 3.
    That API level means only stock APIs are available, e.g. Google Maps is
    not.

    You generally need to run this command only once.


2.  Boostrapping

    Run:
    $ ./boostrap.sh

    Bootstrapping involves creating the `ndk' symlink, running `ndk/ndk-build'
    and `build-externals.sh'.

    You generally need to run this command only once.


3.  Building the App [optional]

    Run:
    $ ant debug
    or
    $ ant release

    Depending on which type of build you want to produce. `ant help' provides
    you with other available target.


4.  Installing

    Run:
    $ ant install
    or, depending on the SDK version:
    $ ant reinstall

    This target will perform a debug build, and try to install the resulting
    artefact on a connected phone or running simulator. You can skip running
    `ant debug' if you use this command during development.


5.  Codesigning & Publishing [optional]

    If you've built a release build, you need to sign it before pushing it to
    the store. You can find all relevant information for that here:
    http://developer.android.com/guide/publishing/app-signing.html

    It may also be of interest to run zipalign before publishing an app. A good
    starting point for that is here:
    http://android-developers.blogspot.com/2009/09/zipalign-easy-optimization.html


6.  Rinse & Repeat

    During development, you're likely to either make changes to the native
    sources, Java sources, or both.

    Rebuild only the modified native sources by running:
    $ ./ndk/ndk-build

    Performing step 3 again builds Java sources.


7.  Troubleshooting

    . ID changes

      Whenever you create new IDs for any layout, drawable or resource during
      development, the file `gen/fm/audioboo/app/R.java' gets updated. Within
      the `fm.audioboo.application' package it's always automatically imported.

      Sometimes adding or removing IDs will cause conflicts, e.g. image files
      may be displayed in the wrong ImageView, or in the worst case the app can
      crash on startup.

      It's generally best to remove both the `gen' and `bin' subdirectories, and
      build the Java code again. Native code does not need to be rebuild when
      this happens.

    . OutOfMemoryError

      Pulling in external libs to the extent that this project does can cause
      one step of the Java build to break with an OutOfMemoryError.

      The simplest way around that is to edit the `dex.bat' or `dx' shell
      script in the Android SDK.

      On Mac OS X, it's located in the following directory:
        <sdk-path>/platforms/android-<target-version>/tools

      The `dx' file contains the declaration of a `javaOpts' environment
      variable. About 3/4 down the problem is documented, and an example line
      granting the `dx' process up to 256MiB of memory is shown, commented out.
      Just comment that in, and everything should work:
        javaOpts="-Xmx256M"