docs/DEVELOPMENT.html - platform/ndk.git - Git at Google

 <html><body><pre>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 workdir
   cd workdir
   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 NDK requires several prebuilt binary executables to work properly, these
 include the following:

   - toolchain binaries for the cross-compiler and associated tools
   - gdbserver binaries required for native debugging

 These are not provided in the NDK's git repositories. However, there are
 several ways to get them:

   1/ From a previous NDK release package:

       By far the easiest thing to do is to copy the binaries from a previous
       NDK installation. You can do that with a command like the following one:

             cp -r $PREVIOUS_NDK/toolchains/* $NDK/toolchains/

       NOTE: The binaries are listed in $NDK/.gitignore and will not appear
             in your git status.


   2/ Download and rebuild directly from the internet:

       IMPORTANT: This is *very* long.

       The NDK comes with several scripts that can be used to rebuild the
       binaries from scratch, after downloading their sources from
       android.git.kernel.org.

       There are several ways to do that, the most naive one, which will
       always work but will be *very* long (expect a few hours on a typical
       dual-core machine) is to do the following:

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

       This will perform all the steps required to rebuild the binaries,
       which include:

         - downloading the sources from android.git.kernel.org
         - patching them with appropriate changes, if needed
         - rebuilding everything from scratch
         - copying the generated binaries to the proper location under $NDK

       You will need about 30G of free space in your /tmp directory to be
       able to do that, and *plenty* of free time.

       IMPORTANT: If you plan to generate NDK release packages, even
       experimental ones, we strongly suggest you to use the individual
       steps described in 3/ below.

       IMPORTANT:
           Since NDK r5, Windows binaries can be built on Linux by using the
           --mingw option, which requires that you have the "mingw32" package
           installed on your system. For example:

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

           We do not officially support building these binaries directly on
           Windows (either through Cygwin or MSys) anymore, due to the vast
           number of problems these environments create when trying to do so.


   3/ Download, rebuild, package, install in separate steps:

       If you plan to generate your own NDK release packages, it is better
       to rebuild your binaries using separate steps, as in:

          - Download the sources from the Internet, patch them, then
            package the result in a simple tarball.

          - For every target system (linux-x86, darwin-x86 and windows),
            rebuild the binaries from the same source tarball.

          - Package and collect all prebuilt binaries into a single
            directory that will be used when packaging NDK releases.

       Here are more details on how to do that:

       3.a/ Download + patching + packaging sources:

         Use the following command to download, patch and package the
         sources:

            $NDK/build/tools/download-toolchain-sources.sh --package

         This will create a large tarball containing all sources ready to be
         used by the following step. The generated file path will be dumped at
         the script when it completes its operation and should be something
         like:

           /tmp/android-ndk-toolchain-&lt;date&gt;.tar.bz2

         Note that if you don't use the --package option, you will need to
         provide the name of a directory where the patched sources will be
         copied instead, as in:

             $NDK/build/tools/download-toolchain-sources.sh &lt;target-src-dir&gt;


        3.b/ Build the binaries:

         Use the following command to rebuild the binaries from the source
         tarball that was created in the previous section with the --package
         option:

             $NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-pkg=&lt;file&gt;

         Where &lt;file&gt; points to the package generated by the
         download-toolchain-sources.sh script.

         In the case where you downloaded the sources to a directory instead,
         use the --toolchain-src-dir option instead, as with:

             $NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-src-dir=&lt;path&gt;

         This will rebuild all the prebuilt binaries for your host platforms
         and place them in a directory named:

              /tmp/ndk-prebuilt/prebuilt-&lt;date&gt;/

         These binary packages include the following:

             - host-specific toolchain binaries. e.g.
                 arm-eabi-4.4.0-linux-x86.tar.bz2

             - toolchain specific device binaries, e.g.
                 arm-eabi-4.4.0-gdbserver.tar.bz2

         IMPORTANT:
             To generate Windows binaries on Windows, install the "mingw32"
             package on your system, then use the --mingw option, as in:

                $NDK/build/tools/rebuild-all-prebuilt.sh --mingw --toolchain-pkg=&lt;file&gt;

             Note that device-specific binaries (e.g. gdbserver) cannot be
             rebuilt with this option.

        3.c/ Copy the binaries to your NDK tree:

         Simply go to your NDK tree, and unpack the binary tarballs in place,
         for example:

             cd $NDK
             tar xjf &lt;path&gt;/*.tar.bz2

         Where &lt;path&gt; is a directory containing all the tarballs (e.g. it
         could be simply /tmp/ndk-prebuilt/prebuilt-&lt;date&gt;)

         This will put the corresponding files at the correct location.


        3.c/

       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 prebuilts, that
       can be unpacked directly into your $NDK directory. The package name is
       printed at the end, e.g."android-ndk-prebuild-&lt;date&gt;-&lt;system&gt;.tar.bz2".

       Where &lt;date&gt; is the current date, and &lt;system&gt; is your system name.
       Then, to unpack:

         cd $NDK                               k
         tar xjf /tmp/android-ndk-prebuilt-&lt;date&gt;-&lt;system&gt;.tar.bz2


       The generated package can easily be shared with other people.


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

 You can generate new experimental NDK release packages once you're satisfied
 with your changes, in order to share them with other people. There are two
 ways to do that:

   1/ Using the 'make-release.sh' script:

     The simplest, and also the slowest way, to generate a new NDK release
     is to invoke this script, with:

         $NDK/build/tools/make-release.sh

     NOTE: THIS WILL BE VERY VERY LONG. The script will do all the steps
           described in section III *from* scratch, and this can take several
           hours on a dual-core machine.

     You should only use it in case of desperation, or if you don't want
     to deal with all the details exposed in section III or below.


   1/ Using a previous NDK release package:

     This is the second simplest way to generate a new package, and it will
     be extremely quick because it will pick the prebuilt binaries directly
     from the previous package.

     Do the following:

         cd $NDK
         build/tools/package-release.sh --prebuilt-ndk=&lt;file&gt;

     Where &lt;file&gt; points to a previous NDK package (i.e. archive file).

     NOTE: This method can only be used to generate a single release package
           for the current host system.

   2/ Using prebuilt tarballs:

     If you have generated prebuilt binary tarballs with the steps described
     in section III.3 above, you can use these to generate release packages
     as well.

     Assuming that you have collected prebuilt tarballs for all three supported
     host systems (i.e. linux-x86, darwin-x86 and windows) under a directory,
     do the following:

         cd $NDK
         build/tools/package-release.sh --prebuilt-dir=&lt;path&gt;

     The generated NDK package release will have a name that looks like:

         /tmp/ndk-release/android-ndk-&lt;release&gt;-&lt;system&gt;.zip

     Where &lt;release&gt; is by default the current date in ISO format
     (e.g. 20100915), and &lt;system&gt; corresponds to the host system where the
     NDK release is supposed to run.

     The script 'package-release.sh' provides a few additional options:

         --release=&lt;name&gt;       Change the name of the release

         --systems=&lt;list&gt;       Change the list of host systems to package for

         --platforms=&lt;list&gt;     List of API levels to package in the NDK

         --out-dir=&lt;path&gt;       Specify a different output directory for the
                                final packages (instead of /tmp/ndk-release)

     Use --help to list them all.

 </pre></body></html>
	<html><body><pre>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 workdir
	cd workdir
	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 NDK requires several prebuilt binary executables to work properly, these
	include the following:

	- toolchain binaries for the cross-compiler and associated tools
	- gdbserver binaries required for native debugging

	These are not provided in the NDK's git repositories. However, there are
	several ways to get them:

	1/ From a previous NDK release package:

	By far the easiest thing to do is to copy the binaries from a previous
	NDK installation. You can do that with a command like the following one:

	cp -r $PREVIOUS_NDK/toolchains/* $NDK/toolchains/

	NOTE: The binaries are listed in $NDK/.gitignore and will not appear
	in your git status.


	2/ Download and rebuild directly from the internet:

	IMPORTANT: This is very long.

	The NDK comes with several scripts that can be used to rebuild the
	binaries from scratch, after downloading their sources from
	android.git.kernel.org.

	There are several ways to do that, the most naive one, which will
	always work but will be very long (expect a few hours on a typical
	dual-core machine) is to do the following:

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

	This will perform all the steps required to rebuild the binaries,
	which include:

	- downloading the sources from android.git.kernel.org
	- patching them with appropriate changes, if needed
	- rebuilding everything from scratch
	- copying the generated binaries to the proper location under $NDK

	You will need about 30G of free space in your /tmp directory to be
	able to do that, and plenty of free time.

	IMPORTANT: If you plan to generate NDK release packages, even
	experimental ones, we strongly suggest you to use the individual
	steps described in 3/ below.

	IMPORTANT:
	Since NDK r5, Windows binaries can be built on Linux by using the
	--mingw option, which requires that you have the "mingw32" package
	installed on your system. For example:

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

	We do not officially support building these binaries directly on
	Windows (either through Cygwin or MSys) anymore, due to the vast
	number of problems these environments create when trying to do so.



	3/ Download, rebuild, package, install in separate steps:

	If you plan to generate your own NDK release packages, it is better
	to rebuild your binaries using separate steps, as in:

	- Download the sources from the Internet, patch them, then
	package the result in a simple tarball.

	- For every target system (linux-x86, darwin-x86 and windows),
	rebuild the binaries from the same source tarball.

	- Package and collect all prebuilt binaries into a single
	directory that will be used when packaging NDK releases.

	Here are more details on how to do that:

	3.a/ Download + patching + packaging sources:

	Use the following command to download, patch and package the
	sources:

	$NDK/build/tools/download-toolchain-sources.sh --package

	This will create a large tarball containing all sources ready to be
	used by the following step. The generated file path will be dumped at
	the script when it completes its operation and should be something
	like:

	/tmp/android-ndk-toolchain-<date>.tar.bz2

	Note that if you don't use the --package option, you will need to
	provide the name of a directory where the patched sources will be
	copied instead, as in:

	$NDK/build/tools/download-toolchain-sources.sh <target-src-dir>


	3.b/ Build the binaries:

	Use the following command to rebuild the binaries from the source
	tarball that was created in the previous section with the --package
	option:

	$NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-pkg=<file>

	Where <file> points to the package generated by the
	download-toolchain-sources.sh script.

	In the case where you downloaded the sources to a directory instead,
	use the --toolchain-src-dir option instead, as with:

	$NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-src-dir=<path>

	This will rebuild all the prebuilt binaries for your host platforms
	and place them in a directory named:

	/tmp/ndk-prebuilt/prebuilt-<date>/

	These binary packages include the following:

	- host-specific toolchain binaries. e.g.
	arm-eabi-4.4.0-linux-x86.tar.bz2

	- toolchain specific device binaries, e.g.
	arm-eabi-4.4.0-gdbserver.tar.bz2

	IMPORTANT:
	To generate Windows binaries on Windows, install the "mingw32"
	package on your system, then use the --mingw option, as in:

	$NDK/build/tools/rebuild-all-prebuilt.sh --mingw --toolchain-pkg=<file>

	Note that device-specific binaries (e.g. gdbserver) cannot be
	rebuilt with this option.

	3.c/ Copy the binaries to your NDK tree:

	Simply go to your NDK tree, and unpack the binary tarballs in place,
	for example:

	cd $NDK
	tar xjf <path>/*.tar.bz2

	Where <path> is a directory containing all the tarballs (e.g. it
	could be simply /tmp/ndk-prebuilt/prebuilt-<date>)

	This will put the corresponding files at the correct location.


	3.c/

	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 prebuilts, 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 k
	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:
	==================================

	You can generate new experimental NDK release packages once you're satisfied
	with your changes, in order to share them with other people. There are two
	ways to do that:

	1/ Using the 'make-release.sh' script:

	The simplest, and also the slowest way, to generate a new NDK release
	is to invoke this script, with:

	$NDK/build/tools/make-release.sh

	NOTE: THIS WILL BE VERY VERY LONG. The script will do all the steps
	described in section III from scratch, and this can take several
	hours on a dual-core machine.

	You should only use it in case of desperation, or if you don't want
	to deal with all the details exposed in section III or below.


	1/ Using a previous NDK release package:

	This is the second simplest way to generate a new package, and it will
	be extremely quick because it will pick the prebuilt binaries directly
	from the previous package.

	Do the following:

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

	Where <file> points to a previous NDK package (i.e. archive file).

	NOTE: This method can only be used to generate a single release package
	for the current host system.

	2/ Using prebuilt tarballs:

	If you have generated prebuilt binary tarballs with the steps described
	in section III.3 above, you can use these to generate release packages
	as well.

	Assuming that you have collected prebuilt tarballs for all three supported
	host systems (i.e. linux-x86, darwin-x86 and windows) under a directory,
	do the following:

	cd $NDK
	build/tools/package-release.sh --prebuilt-dir=<path>

	The generated NDK package release will have a name that looks like:

	/tmp/ndk-release/android-ndk-<release>-<system>.zip

	Where <release> is by default the current date in ISO format
	(e.g. 20100915), and <system> corresponds to the host system where the
	NDK release is supposed to run.

	The script 'package-release.sh' provides a few additional options:

	--release=<name> Change the name of the release

	--systems=<list> Change the list of host systems to package for

	--platforms=<list> List of API levels to package in the NDK

	--out-dir=<path> Specify a different output directory for the
	final packages (instead of /tmp/ndk-release)

	Use --help to list them all.

	</pre></body></html>