docs/DEVELOPMENT.TXT

NDK Development:
----------------

This document describes how one can modify the NDK and generate
new experimental release packages for it.

I. Getting the sources:
=======================

The sources live under the "ndk" and "development/ndk" directories in
the Android source tree:

  - "ndk" contains the main build scripts and documentation
  - "development/ndk" contains platform-specific headers and samples

If you have downloaded the full Android source tree through the "repo"
tool, you can start directly there. Otherwise, you can just get these
two repositories with the following:

  mkdir myndk
  cd myndk
  git clone git://android.git.kernel.org/platform/ndk.git ndk
  git clone git://android.git.kernel.org/platform/development.git development
  export NDK=`pwd`/ndk

II. Building the platforms tree:
================================

You need to do that once if you want to use the content of $NDK to build
samples, tests or anything else:

  $NDK/build/tools/build-platforms.sh

What the script does is populate the $NDK/platforms and $NDK/samples
directories from the content of development/ndk.

What is under development/ndk is segregated by API level. This makes it
easier to add a new platform to the tree, but is not well-suited to building
stuff. The build-platforms.sh script will gather all files appropriately
and place the result inside $NDK/platforms and $NDK/samples.

Note: These directories are listed by $NDK/.gitignore, so they won't appear
      on your git status. You can remove them if you want by running:

        $NDK/build/tools/dev-cleanup.sh

      which also removes all intermediate files and directories from $NDK.

III. Prebuilt binaries:
=======================

The source tree does not contain the prebuilt binaries for the cross-compiler
and other stuff that are necessary to generate machine code with the NDK.

There are several ways to get them:

  1/ From a previous NDK release package:

      Copy them from $PREVIOUS_NDK/build/prebuilt/<system>/ to your
      $NDK/build/prebuilt/<system>, where <system> corresponds to your
      development system. Valid values are: windows, darwin-x86 and linux-x86

  2/ Download and rebuild directly from the internet:

      IMPORTANT: This is *very* long.

      Just launch the following command:

        $NDK/build/tools/rebuild-all-prebuilt.sh

      It will download all source packages from the Internet, unpack, patch
      and build them for you. In the end, the binaries will be located under
      $NDK/build/prebuilt/<system>, ready to be used.

  3/ Download, rebuild, package, then unpack:

      IMPORTANT: This is also *very* long.

      It is a good idea to save the generated toolchain binaries into
      an archive. To do that, use the --package option, as in:

        $NDK/build/tools/rebuild-all-prebuilt.sh --package

      This will generate a package file containing all the prebuilds, that
      can be unpacked directly into your $NDK directory. The package name is
      printed at the end, e.g."android-ndk-prebuild-<date>-<system>.tar.bz2".

      Where <date> is the current date, and <system> is your system name.
      Then, to unpack:

        cd $NDK
        tar xjf /tmp/android-ndk-prebuilt-<date>-<system>.tar.bz2


      The generated package can easily be shared with other people.


IV. Generate new package releases:
==================================

Use the 'build/tools/make-release.sh' script to generate experimental
NDK release packages. You will need prebuilt binaries to do that properly,
and there are two ways to do that:

  1/ Using a previous NDK release package:

    Use the following command:

        cd $NDK
        build/tools/make-release.sh --prebuilt-ndk=<file>

    Where <file> points to a previous NDK release. This will extract
    the prebuilt binaries from it, and copy them to the new package file.

    This method can only be used to generate a single release package
    for the current <system>.


  2/ Using one or more toolchain prebuilt packages:

    Alternatively, you can generate release packages for several
    supported systems if you have generated the appropriate prebuilt
    toolchains, as described in II.3/ above.

    Assuming you have placed the packages under:

      /tmp/ndk/android-ndk-prebuilt-<date>-windows.tar.bz2
      /tmp/ndk/android-ndk-prebuilt-<date>-darwin-x86.tar.bz2
      /tmp/ndk/android-ndk-prebuilt-<date>-linux-x86.tar.bz2

    You can invoke the following command:

        $NDK/build/tools/make-release.sh --prebuilt-prefix=/tmp/ndk/android-ndk-prebuilt-<date>

    This will generate 3 release packages under /tmp/ndk-release/ by default.

  3/ Additionnal options:

    --out-dir=<directory>: 
        Allows you to specify a different output directory for the final
        packages (instead of the default /tmp/ndk-release/)

    --systems=<list>:
        Allows you to limit the number of release packages to a specific list
        of systems. For example, use:

        $NDK/build/tools/make-release.sh --systems='linux-x86 darwin-x86' \
            --prebuilt-prefix=<prefix>

        If you don't have prebuilt packages for the 'windows' platform.

    --no-git:
        By default, the script clones the current git directory to a temporary
        directory before packaging its content. Using --no-git will simply
        copy the content of the current directory, which may contain misc.
        unwanted files (e.g. backup files from text editors, generated
        object files, etc...). Only use this as a last resort.

    --release=<name>:
        By default, the release name is the current <date>. You can change
        this with this option, for example:

        $NDK/build/tools/make-release.sh --release=crazy-experiment ...

        The generated packages will be named android-ndk-<release>-<system>.zip

    Other options are supported, use --help to list them all.