First version of the README and ant build.xml

This is the first commit of this branch. It contains the README file
with instructions for different user targets (Compiling, Running on the
emulator and Debugging from console), and the ant build.xml file.

debug.sh is an experimental script, because it uses "sleep" to
synchronize between Emulator and adb install and run. If you want to use
it, please look for that "sleep" lines and update their numbers
according to your experience.

1 files changed, 55 insertions, 26 deletions

diff --git a/README.txt b/README.txt
index f6690f5a..badaaf54 100644
--- a/README.txt
+++ b/README.txt
@@ -1,43 +1,72 @@
-This is my first Android project, so some things may be done in a completely stupid way.
+Compiling
+=========
 
-See  the file todo.txt for ideas/not yet implemented features (and the bug tracker).
+Preconditions
+----------------
 
-Build instraction:
+1. Android SDK installed (follow instructions from http://developer.android.com/sdk/index.html)
+2. API version 16 or version installed.
+2. Ant 1.6 or greater
 
-Checkout google breakcode:
+Instructions to compile
+-----------------------
 
-svn co http://google-breakpad.googlecode.com/svn/trunk/ google-breakpad
+1. cd $PROJECT_LOCATION/leap_android
+2. android update project --path $PROJECT_LOCATION/leap_android/
+3. ant debug
 
-- Install sdk
-- Install ndk
+Postconditions
+--------------
 
-Do ./build-native.sh in the root directory of the project.
+1. $PROJECT_LOCATION/leap_android/bin/LEAP Android-debug.apk exists
 
-Use eclipse with android plugins to build the project.
+Running on the emulator
+=========================
 
-Optional: Copy minivpn from lib/ to assets (if you want your own compiled version)
+Preconditions
+-----------------
 
+1. Android SDK is installed, and its tools are in the PATH.
+2. leap_android has been compiled.
+3. An avd exists in ~/.android/avd/ (if you do not have one, follow instructions from http://developer.android.com/tools/devices/managing-avds-cmdline.html)
 
+Instructions to run on the emulator
+-----------------------------------
 
+1. Run emulator: emulator @AVD-NAME (avd names are the names of the files in ~/.android/avd with extension .avd).
+	- If you want to test the app from scratch, run emulator -wipe-data @AVD-NAME
+2. Run app: adb shell am start se.leap.leapclient/.Dashboard
 
-Starting a VPN by name from an external app:
+Postconditions
+--------------
 
-public class StartOpenVPNActivity extends Activity {
-    @Override
-    public void onCreate(Bundle savedInstanceState) {
-        super.onCreate(savedInstanceState);
-        setContentView(R.layout.main);
-        
-    	final String EXTRA_NAME = "se.leap.openvpn.shortcutProfileName";
+1. LEAP Android is running.
 
-        Intent shortcutIntent = new Intent(Intent.ACTION_MAIN);
-		shortcutIntent.setClassName("se.leap.openvpn", "se.leap.openvpn.LaunchVPN");
-		shortcutIntent.putExtra(EXTRA_NAME,"upb ssl");
-		startActivity(shortcutIntent);
-    }
-}
+Debugging from console
+======================
 
-or from the shell:
+Preconditions
+-----------------
 
-am start -a android.intent.action.VPNLEGACY -n se.leap.openvpn/.LaunchVPN -e se.leap.openvpn.shortcutProfileName Home
+1. Android SDK is installed, and its tools are in the PATH.
+2. leap_android has been compiled.
+3. An avd exists in ~/.android/avd/ (if you do not have one, follow instructions from http://developer.android.com/tools/devices/managing-avds-cmdline.html).
+4. jdb is installed (this program is part of OpenJDK 7)
 
+Instructions to debug from the console
+-----------------------------------
+
+1. emulator @AVD-NAME # (avd names are the names of the files in ~/.android/avd with extension .avd).
+	- emulator -wipe-data @AVD-NAME # If you want to test the app from scratch
+2. adb install -r $PROJECT_LOCATION/leap_android/bin/LEAP\ Android-debug.apk # Install the new version of the application
+3. adb shell am start -D se.leap.leapclient/.Dashboard # Run app
+4. pid=`adb shell ps | grep leap | awk '{print $2}'` # Identify the process id (pid) of the current leapclient process instance
+5. localport=`expr $RANDOM % 65536`
+6. adb forward tcp:$localport jdwp:$pid
+7. jdb -sourcepath $PROJECT_LOCATION/leap_android/src/ -attach localhost:$localport
+
+Postconditions
+--------------
+
+1. LEAP Android is running.
+2. LEAP Android does not show the message "Application LEAP for Android (process se.leap.leapclient) is waiting for the debugger to attach".