Building
========

* First 'make' the top level ccn project
* cd android
* make (or make with-bcp)
* make install (to install all apps to a connected device or emulator)

Supported SDK Versions:
* Android NDK >= r7
* Android SDK >= r15 (with minimum API level 7 installed)

We have tested with the minimum required SDKs listed above, as well as with
newer versions up to ANDROID SDK r21 and NDK r8d.

(Please see "Android Build System Notes" below for extended details on building CCN for Android.)

Android Apps for CCNx
=====================

CCNx-Android-Services
  This is an Android app that manages the lifecycle of CCND and
  a REPO as a service.  One can build a standalone application
  to utlize the CCNx services made available by this application.
  
CCNx-Android-Lib
  This is an Android library.  It has helpers for the ccnd and 
  Repo services, among other things.  No build is done here, as
  Android libraries are included in source form.

Before you use any CCNx library calls:
- Call CCNxConfiguration.config(Context)
- Call CCNxServiceControl.startAll() or startAllBackround()

Once you have configured your environment (config()) and started
ccnd and Repo (startAll()), you can then use the CCNx library.

Your application needs these permissions:
         # Always need this:
    android.permission.INTERNET

	   	# If your keystore is on /sdcard
    android.permission.WRITE_EXTERNAL_STORAGE

Important Notes
===============
- User keys are stored in /sdcard/ccnx/user
  Because this is on the SD card, it may become unavailable if you
  plug in your USB and use the SD card for storage.  

  The user keystore is on the sdcard so multiple apps from different packages
  can share the same identity.

  If your app wants to use a private keystore, call
 
- Repo directory is /sdcard/ccnx/repo
  See User note about /sdcard

- Ccnd directory is under the apk:
  /data/data/org.ccnx.android.services/app_ccnd


Android Build System Notes
===========================

The build system is centered on gnu Make.  For Android projects, the
Makefile wraps the ant commands.

The android code depends on ccn.jar, so you must have run make in
the top level directory before building here.

Ccnd and the c-client library require OpenSSL library, which we need
to include in the build, as one cannot depend on the version distributed with
the Android OS.

You must set the environment variables ANDROID_SDK and ANDROID_NDK.
These must point to the root of the SDK Tools and NDK directories.


Supported Target Android Devices:
Android 2.1
Android 2.2
Android 2.3
Android 3.x
Android 4.x

Your Android SDK should have installed at a minimum API target 14, though
it may be possible Google will only have later versions available in the 
SDK Manager tool.  We will still run on older Eclair devices but
compilation now requires a newer API target in the SDK.  Runtime detection
ensures that the correct classes are used with regards to fallinb back
to older UI widgets if newer ICS widgets are not available in the OS.

Newer tablet oriented versions of Android, such as 3.x and 4.x have 
been tested and verified.  These will be the focus platforms going forward,
though we will continue to support older release targets for the near 
future.

For example (Use the path to desired tools for your platform):

	export ANDROID_SDK=~/android-sdk-linux_x86
	export ANDROID_NDK=~/android-ndk-r8

Android is not built as part of the top-level make.  You must run
make in this directory.

Eclipse IDE isn't currently supported as a tool to *build* the Android CCNx project.  It can be used as an IDE to view and edit files.

What happens
============

When you run "make" in the android directory, the build process takes
these steps:

- Build "external".
  This downloads the OpenSSL source, configures it for armv5, and
  does a patch.  It then puts Android.mk files in to the OpenSSL
  source directories.  There is no actual compiling done.

  IF YOU DO NOT HAVE AN INTERNET CONNECTION
  You will need to download openssl-1.0.0d.tar.gz from 
	http://www.openssl.org/source/openssl-1.0.0d.tar.gz
  and put it in the directory external/downloads.

- Build CCNx-Android-Services
  This wraps the ccnd and Repo services.  Because ccnd is C code,
  it is included as JNI code, along with OpenSSL.

  Doing a "make clean" will erase the C object code for CCNx-Android-Services and CCNx.  Only
  a "make distclean" will remove external object files, for OpenSSL for example.

  The CCNx csrc/ folder now has Android.mk files in it already, so
  the CCNx-Android-Services/jni folder has a link to csrc/.  We have
  also include csrc/ccnd/android_{main,msg}.c.  android_main.c replaces
  ccnd_main.c in Android.mk and is used to startup ccnd procedurally
  rather than from a main() method.  android_main.c is now used to 
  send ccnd log messages to the Android log.

  Take a look in jni/controller/ctl_ccnd.c for the JNI bindings to
  the ccnd code.

- Build the apps/ directory

Honeycomb and Ice Cream Sandwich
================================
Android 3.x & 4.x devices (and possibly some 2.x) include a subset of the Bouncy Castle library.  See: http://redmine.ccnx.org/issues/100589 for details.  As a result, the 3.x & 4.x devices we tested failed with ClassNotFoundException trying to resolve the BouncyCastleProvider.  To work around this, we include the Bouncy Castle provider jar file if you specify in the top level of the android project directory:

make with-bcp

This change affects CCNx-Android-Services, CCNx-Android-Chat, and CCNx-Android-StartupExamples.  Because of the size of the jar file (around 1.5mb) we are interested in a better solution long term, though there is no indication Google has changed their approach, except to enhance the android crypto library to rely upon functionality delivered through OpenSSL.

Installing
===========

"make install" will install the Services and Chat applications.  You
might need to "make uninstall" before "make install" if the applications
were previously installed with a different signing key (i.e. you use
the phone with builds from multiple computers).

Upgrading
=========

After Android SDK r13, the tools and build.xml diverged significantly from prior version.  It disrupted some functioning of tools (ant targets vanished and moved into binary tool) and the build.xml from older generations of the SDK got marked as depricated.  If you are migrating up to Android SDK r13 or greater, you should delete the build.xml files within the android CCNx project folder.  By removing the old build.xml, any cryptic error messages will disappear, and newer build.xmls will be generated.

Routing
=======

To set up routing, utilize this set of commands with a USB-tethered Android Device:
adb forward localfilesystem:/tmp/.ccnd.sock.9699 tcp:9695
adb forward tcp:9699 tcp:9695

and then run regular ccn commands, with CCN_LOCAL_PORT=9699 including ccndc, ccnputfile, ccnlsrepo, etc.  Note, ccndc commands issued will require the phone to point at an IP address reachable from the phone.