Wednesday, June 15, 2011

Android Monkey Script

Monkey: The Monkey is a program that runs on your emulator or device and generates pseudo-random streams of user events such as clicks, touches, or gestures, as well as a number of system-level events. You can use the Monkey to stress-test applications that you are developing, in a random yet repeatable manner.

Monkey script is unfortunately poorly documented but it is pretty easy to write monkey script after looking at the Monkey Script Java source code itself. The Java Source code is the code in charge of parsing the monkey script and dispatching all monkey script event in a timely manner.

development/cmds/monkey/src/com/android/commands/monkey/MonkeySourceScript.java

/*
* Copyright (C) 2008 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.android.commands.monkey;

import android.os.SystemClock;
import android.view.KeyEvent;

import java.io.BufferedReader;
import java.io.DataInputStream;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.LinkedList;
import java.util.StringTokenizer;

/**
* monkey event queue. It takes a script to produce events
*
* sample script format:
* type= raw events
* count= 10
* speed= 1.0
* start data >>
* captureDispatchPointer(5109520,5109520,0,230.75429,458.1814,0.20784314,
* 0.06666667,0,0.0,0.0,65539,0)
* captureDispatchKey(5113146,5113146,0,20,0,0,0,0)
* captureDispatchFlip(true)
* ...
*/
public class MonkeySourceScript implements MonkeyEventSource {
private int mEventCountInScript = 0; //total number of events in the file
private int mVerbose = 0;
private double mSpeed = 1.0;
private String mScriptFileName;
private MonkeyEventQueue mQ;

private static final String HEADER_TYPE = "type=";
private static final String HEADER_COUNT = "count=";
private static final String HEADER_SPEED = "speed=";

private long mLastRecordedDownTimeKey = 0;
private long mLastRecordedDownTimeMotion = 0;
private long mLastExportDownTimeKey = 0;
private long mLastExportDownTimeMotion = 0;
private long mLastExportEventTime = -1;
private long mLastRecordedEventTime = -1;

private static final boolean THIS_DEBUG = false;
// a parameter that compensates the difference of real elapsed time and
// time in theory
private static final long SLEEP_COMPENSATE_DIFF = 16;

// maximum number of events that we read at one time
private static final int MAX_ONE_TIME_READS = 100;

// number of additional events added to the script
// add HOME_KEY down and up events to make start UI consistent in each round
private static final int POLICY_ADDITIONAL_EVENT_COUNT = 2;

// event key word in the capture log
private static final String EVENT_KEYWORD_POINTER = "DispatchPointer";
private static final String EVENT_KEYWORD_TRACKBALL = "DispatchTrackball";
private static final String EVENT_KEYWORD_KEY = "DispatchKey";
private static final String EVENT_KEYWORD_FLIP = "DispatchFlip";

// a line at the end of the header
private static final String STARTING_DATA_LINE = "start data >>";
private boolean mFileOpened = false;

FileInputStream mFStream;
DataInputStream mInputStream;
BufferedReader mBufferReader;

public MonkeySourceScript(String filename, long throttle) {
mScriptFileName = filename;
mQ = new MonkeyEventQueue(throttle);
}

/**
*
* @return the number of total events that will be generated in a round
*/
public int getOneRoundEventCount() {
//plus one home key down and up event
return mEventCountInScript + POLICY_ADDITIONAL_EVENT_COUNT;
}

private void resetValue() {
mLastRecordedDownTimeKey = 0;
mLastRecordedDownTimeMotion = 0;
mLastExportDownTimeKey = 0;
mLastExportDownTimeMotion = 0;
mLastRecordedEventTime = -1;
mLastExportEventTime = -1;
}

private boolean readScriptHeader() {
mEventCountInScript = -1;
mFileOpened = false;
try {
if (THIS_DEBUG) {
System.out.println("reading script header");
}

mFStream = new FileInputStream(mScriptFileName);
mInputStream = new DataInputStream(mFStream);
mBufferReader = new BufferedReader(
new InputStreamReader(mInputStream));
String sLine;
while ((sLine = mBufferReader.readLine()) != null) {
sLine = sLine.trim();
if (sLine.indexOf(HEADER_TYPE) >= 0) {
// at this point, we only have one type of script
} else if (sLine.indexOf(HEADER_COUNT) >= 0) {
try {
mEventCountInScript = Integer.parseInt(sLine.substring(
HEADER_COUNT.length() + 1).trim());
} catch (NumberFormatException e) {
System.err.println(e);
}
} else if (sLine.indexOf(HEADER_SPEED) >= 0) {
try {
mSpeed = Double.parseDouble(sLine.substring(
HEADER_SPEED.length() + 1).trim());

} catch (NumberFormatException e) {
System.err.println(e);
}
} else if (sLine.indexOf(STARTING_DATA_LINE) >= 0) {
// header ends until we read the start data mark
mFileOpened = true;
if (THIS_DEBUG) {
System.out.println("read script header success");
}
return true;
}
}
} catch (FileNotFoundException e) {
System.err.println(e);
} catch (IOException e) {
System.err.println(e);
}

if (THIS_DEBUG) {
System.out.println("Error in reading script header");
}
return false;
}

private void processLine(String s) {
int index1 = s.indexOf('(');
int index2 = s.indexOf(')');

if (index1 < 0 || index2 < 0) {
return;
}

StringTokenizer st = new StringTokenizer(
s.substring(index1 + 1, index2), ",");

if (s.indexOf(EVENT_KEYWORD_KEY) >= 0) {
// key events
try {
long downTime = Long.parseLong(st.nextToken());
long eventTime = Long.parseLong(st.nextToken());
int action = Integer.parseInt(st.nextToken());
int code = Integer.parseInt(st.nextToken());
int repeat = Integer.parseInt(st.nextToken());
int metaState = Integer.parseInt(st.nextToken());
int device = Integer.parseInt(st.nextToken());
int scancode = Integer.parseInt(st.nextToken());

MonkeyKeyEvent e = new MonkeyKeyEvent(downTime, eventTime,
action, code, repeat, metaState, device, scancode);
mQ.addLast(e);

} catch (NumberFormatException e) {
// something wrong with this line in the script
}
} else if (s.indexOf(EVENT_KEYWORD_POINTER) >= 0 ||
s.indexOf(EVENT_KEYWORD_TRACKBALL) >= 0) {
// trackball/pointer event
try {
long downTime = Long.parseLong(st.nextToken());
long eventTime = Long.parseLong(st.nextToken());
int action = Integer.parseInt(st.nextToken());
float x = Float.parseFloat(st.nextToken());
float y = Float.parseFloat(st.nextToken());
float pressure = Float.parseFloat(st.nextToken());
float size = Float.parseFloat(st.nextToken());
int metaState = Integer.parseInt(st.nextToken());
float xPrecision = Float.parseFloat(st.nextToken());
float yPrecision = Float.parseFloat(st.nextToken());
int device = Integer.parseInt(st.nextToken());
int edgeFlags = Integer.parseInt(st.nextToken());

int type = MonkeyEvent.EVENT_TYPE_TRACKBALL;
if (s.indexOf("Pointer") > 0) {
type = MonkeyEvent.EVENT_TYPE_POINTER;
}
MonkeyMotionEvent e = new MonkeyMotionEvent(type, downTime, eventTime,
action, x, y, pressure, size, metaState, xPrecision, yPrecision,
device, edgeFlags);
mQ.addLast(e);
} catch (NumberFormatException e) {
// we ignore this event
}
} else if (s.indexOf(EVENT_KEYWORD_FLIP) >= 0) {
boolean keyboardOpen = Boolean.parseBoolean(st.nextToken());
MonkeyFlipEvent e = new MonkeyFlipEvent(keyboardOpen);
mQ.addLast(e);
}
}

private void closeFile() {
mFileOpened = false;
if (THIS_DEBUG) {
System.out.println("closing script file");
}

try {
mFStream.close();
mInputStream.close();
} catch (IOException e) {
System.out.println(e);
}
}

/**
* add home key press/release event to the queue
*/
private void addHomeKeyEvent() {
MonkeyKeyEvent e = new MonkeyKeyEvent(KeyEvent.ACTION_DOWN,
KeyEvent.KEYCODE_HOME);
mQ.addLast(e);
e = new MonkeyKeyEvent(KeyEvent.ACTION_UP, KeyEvent.KEYCODE_HOME);
mQ.addLast(e);
}

/**
* read next batch of events from the provided script file
* @return true if success
*/
private boolean readNextBatch() {
String sLine = null;
int readCount = 0;

if (THIS_DEBUG) {
System.out.println("readNextBatch(): reading next batch of events");
}

if (!mFileOpened) {
if (!readScriptHeader()) {
closeFile();
return false;
}
resetValue();

/*
* In order to allow the Monkey to replay captured events multiple times
* we need to define a default start UI, which is the home screen
* Otherwise, it won't be accurate since the captured events
* could end anywhere
*/
addHomeKeyEvent();
}

try {
while (readCount++ < MAX_ONE_TIME_READS &&
(sLine = mBufferReader.readLine()) != null) {
sLine = sLine.trim();
processLine(sLine);
}
} catch (IOException e) {
System.err.println(e);
return false;
}

if (sLine == null) {
// to the end of the file
if (THIS_DEBUG) {
System.out.println("readNextBatch(): to the end of file");
}
closeFile();
}
return true;
}

/**
* sleep for a period of given time, introducing latency among events
* @param time to sleep in millisecond
*/
private void needSleep(long time) {
if (time < 1) {
return;
}
try {
Thread.sleep(time);
} catch (InterruptedException e) {
}
}

/**
* check whether we can successfully read the header of the script file
*/
public boolean validate() {
boolean b = readNextBatch();
if (mVerbose > 0) {
System.out.println("Replaying " + mEventCountInScript +
" events with speed " + mSpeed);
}
return b;
}

public void setVerbose(int verbose) {
mVerbose = verbose;
}

/**
* adjust key downtime and eventtime according to both
* recorded values and current system time
* @param e KeyEvent
*/
private void adjustKeyEventTime(MonkeyKeyEvent e) {
if (e.getEventTime() < 0) {
return;
}
long thisDownTime = 0;
long thisEventTime = 0;
long expectedDelay = 0;

if (mLastRecordedEventTime <= 0) {
// first time event
thisDownTime = SystemClock.uptimeMillis();
thisEventTime = thisDownTime;
} else {
if (e.getDownTime() != mLastRecordedDownTimeKey) {
thisDownTime = e.getDownTime();
} else {
thisDownTime = mLastExportDownTimeKey;
}
expectedDelay = (long) ((e.getEventTime() -
mLastRecordedEventTime) * mSpeed);
thisEventTime = mLastExportEventTime + expectedDelay;
// add sleep to simulate everything in recording
needSleep(expectedDelay - SLEEP_COMPENSATE_DIFF);
}
mLastRecordedDownTimeKey = e.getDownTime();
mLastRecordedEventTime = e.getEventTime();
e.setDownTime(thisDownTime);
e.setEventTime(thisEventTime);
mLastExportDownTimeKey = thisDownTime;
mLastExportEventTime = thisEventTime;
}

/**
* adjust motion downtime and eventtime according to both
* recorded values and current system time
* @param e KeyEvent
*/
private void adjustMotionEventTime(MonkeyMotionEvent e) {
if (e.getEventTime() < 0) {
return;
}
long thisDownTime = 0;
long thisEventTime = 0;
long expectedDelay = 0;

if (mLastRecordedEventTime <= 0) {
// first time event
thisDownTime = SystemClock.uptimeMillis();
thisEventTime = thisDownTime;
} else {
if (e.getDownTime() != mLastRecordedDownTimeMotion) {
thisDownTime = e.getDownTime();
} else {
thisDownTime = mLastExportDownTimeMotion;
}
expectedDelay = (long) ((e.getEventTime() -
mLastRecordedEventTime) * mSpeed);
thisEventTime = mLastExportEventTime + expectedDelay;
// add sleep to simulate everything in recording
needSleep(expectedDelay - SLEEP_COMPENSATE_DIFF);
}

mLastRecordedDownTimeMotion = e.getDownTime();
mLastRecordedEventTime = e.getEventTime();
e.setDownTime(thisDownTime);
e.setEventTime(thisEventTime);
mLastExportDownTimeMotion = thisDownTime;
mLastExportEventTime = thisEventTime;
}

/**
* if the queue is empty, we generate events first
* @return the first event in the queue, if null, indicating the system crashes
*/
public MonkeyEvent getNextEvent() {
long recordedEventTime = -1;

if (mQ.isEmpty()) {
readNextBatch();
}
MonkeyEvent e = mQ.getFirst();
mQ.removeFirst();

if (e.getEventType() == MonkeyEvent.EVENT_TYPE_KEY) {
adjustKeyEventTime((MonkeyKeyEvent) e);
} else if (e.getEventType() == MonkeyEvent.EVENT_TYPE_POINTER ||
e.getEventType() == MonkeyEvent.EVENT_TYPE_TRACKBALL) {
adjustMotionEventTime((MonkeyMotionEvent) e);
}
return e;
}
}

To write monkey script the first thing you have to do is write a small JAVA application. You can use hello world sample application. You can build it using Eclipse Java IDE and Android Windows SDK. Inside your sample application open the main activity JAVA file and add some code to enumerate the activity of an APK of your choice assuming this application is not presently running. If the application you'd like to automate is running, then use getPackageInfo(), instead of getPackageArchiveInfo().

See code bellow. Run the "rever engineering" application in the debugger with the device attached to your PC/Laptop with USB cable so that you can step into the code.


import android.app.Activity;
import android.content.ComponentName;
import android.content.Context;
import android.content.pm.ActivityInfo;
import android.content.pm.ApplicationInfo;
import android.content.pm.PackageInfo;
import android.content.pm.PackageManager;
import android.util.Log;

public class ReverseEngineering extends Activity
{
static final String TAG = "ReverseEngineering:Log";

/** onStart() is called when the application is on the foreground.
* We shouldn't use onCreate() which is called only once in the phone's process life cycle.
* This function will override what is available in the parent Activity class. */
@Override
public void onStart()
{
// Keep on starting.
super.onStart();
setContentView(R.layout.main);

PackageManager pm = getPackageManager();

PackageInfo info = pm.getPackageArchiveInfo("/data/app/com.company.application-1.apk", PackageManager.GET_ACTIVITIES);
if(info != null){
ApplicationInfo appInfo = info.applicationInfo;
String appName = pm.getApplicationLabel(appInfo).toString();
String packageName = appInfo.packageName;
Log.d(TAG, " appName =" + appName);
Log.d(TAG, " packageName =" + packageName);
}

ActivityInfo[] list = pm.getPackageArchiveInfo("/data/app/com.company.application-1.apk", PackageManager.GET_ACTIVITIES).activities;
for(int i = 0;i< list.length; i++){
String strName = list[i].getClass().getName();
Log.d(TAG, " ActivityInfo =" + strName);
}


Once you know the name of the activity you can invoke, write a small script.
The following script named monkey_script.txt will execute a package and
its activity.

captureDispatchPointer is a tap down action followed by a tap up action at the coordinate x and y EG X 146 and Y 165 as if you were using the touch screen with your finger. To find out the coordinate for a particular screen on the device you need to capture the screen using ddms (android tool) and open the screen with your favorites image editor. Mine is PhotoShop CS5 or Gimp if you don't have that much $ to spend. Development on Android is free after all.

# KEYEVENT http://developer.android.com/reference/android/view/KeyEvent.html# Start of Script
type= user
count= 49
speed= 1.0
start data >>
LaunchActivity(com.company.application.Activity, com.company.application.Activity)
UserWait(2000)
# first screen
captureDispatchPointer(5109520,5109520,0,146,165,0,0,0,0,0,0,0);
captureDispatchPointer(5109521,5109521,1,146,165,0,0,0,0,0,0,0);
UserWait(5000)
# second screen
captureDispatchPointer(5109520,5109520,0,117,268,0,0,0,0,0,0,0);
captureDispatchPointer(5109521,5109521,1,117,268,0,0,0,0,0,0,0);
# second screen selection dialog autoclose on selection
UserWait(2000)
# now access an other screen
captureDispatchPointer(5109520,5109520,0,117,358,0,0,0,0,0,0,0);
captureDispatchPointer(5109521,5109521,1,117,358,0,0,0,0,0,0,0);
UserWait(2000)
# access a selection dialog with only a cancel button. Dialog will autoclose on tap down
captureDispatchPointer(5109520,5109520,0,117,177,0,0,0,0,0,0,0);
captureDispatchPointer(5109521,5109521,1,117,177,0,0,0,0,0,0,0);
UserWait(2000)

A more complex script with android keypad input

# KEYEVENT http://developer.android.com/reference/android/view/KeyEvent.html
# Start of Script
type= user
count= 49
speed= 1.0
start data >>
LaunchActivity(com.mpowerlabs.coin.android, com.mpowerlabs.coin.android.LoginActivity)
# 3120021258
DispatchPress(KEYCODE_3)
UserWait(200)
DispatchPress(KEYCODE_1)
UserWait(200)
DispatchPress(KEYCODE_3)
UserWait(200)
DispatchPress(KEYCODE_5)
UserWait(200)
DispatchPress(KEYCODE_0)
UserWait(200)
DispatchPress(KEYCODE_2)
UserWait(200)
DispatchPress(KEYCODE_1)
UserWait(200)
DispatchPress(KEYCODE_2)
UserWait(200)
DispatchPress(KEYCODE_5)
UserWait(200)
DispatchPress(KEYCODE_8)
UserWait(200)
# Pin 12345
DispatchPress(KEYCODE_DPAD_DOWN)
UserWait(250)
DispatchPress(KEYCODE_1)
UserWait(200)
DispatchPress(KEYCODE_2)
UserWait(200)
DispatchPress(KEYCODE_3)
UserWait(200)
DispatchPress(KEYCODE_4)
UserWait(200)
DispatchPress(KEYCODE_5)
UserWait(200)
# Down and enter
DispatchPress(KEYCODE_DPAD_DOWN)
UserWait(250)
DispatchPress(KEYCODE_ENTER)

To execute the script on the device you need to create a batch file.

1 to make sure the application is deploy on the device
2 push the script
3 execute the script

adb root
adb install com.company.application.apk
adb push monkey_script.txt /sdcard/monkey_script.txt
adb shell monkey -p com.company.application -v -v -v -f /sdcard/monkey_script.txt 1

Hope you'll find this tutorial usefull !

Tuesday, June 14, 2011

Android.mk

Android.mk file syntax specification

Introduction:
-------------

This document describes the syntax of Android.mk build file
written to describe your C and C++ source files to the Android
NDK. To understand what follows, it is assumed that you have
read the docs/OVERVIEW.TXT file that explains their role and
usage.

Overview:
---------

An Android.mk file is written to describe your sources to the
build system. More specifically:

- The file is really a tiny GNU Makefile fragment that will be
parsed one or more times by the build system. As such, you
should try to minimize the variables you declare there and
do not assume that anything is not defined during parsing.

- The file syntax is designed to allow you to group your
sources into 'modules'. A module is one of the following:

- a static library
- a shared library

Only shared libraries will be installed/copied to your
application package. Static libraries can be used to generate
shared libraries though.

You can define one or more modules in each Android.mk file,
and you can use the same source file in several modules.

- The build system handles many details for you. For example, you
don't need to list header files or explicit dependencies between
generated files in your Android.mk. The NDK build system will
compute these automatically for you.

This also means that, when updating to newer releases of the NDK,
you should be able to benefit from new toolchain/platform support
without having to touch your Android.mk files.

Note that the syntax is *very* close to the one used in Android.mk files
distributed with the full open-source Android platform sources. While
the build system implementation that uses them is different, this is
an intentional design decision made to allow reuse of 'external' libraries'
source code easier for application developers.

Simple example:
---------------

Before describing the syntax in details, let's consider the simple
"hello JNI" example, i.e. the files under:

apps/hello-jni/project

Here, we can see:

- The 'src' directory containing the Java sources for the
sample Android project.

- The 'jni' directory containing the native source for
the sample, i.e. 'jni/hello-jni.c'

This source file implements a simple shared library that
implements a native method that returns a string to the
VM application.

- The 'jni/Android.mk' file that describes the shared library
to the NDK build system. Its content is:

---------- cut here ------------------
LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE := hello-jni
LOCAL_SRC_FILES := hello-jni.c

include $(BUILD_SHARED_LIBRARY)
---------- cut here ------------------

Now, let's explain these lines:

LOCAL_PATH := $(call my-dir)

An Android.mk file must begin with the definition of the LOCAL_PATH variable.
It is used to locate source files in the development tree. In this example,
the macro function 'my-dir', provided by the build system, is used to return
the path of the current directory (i.e. the directory containing the
Android.mk file itself).

include $(CLEAR_VARS)

The CLEAR_VARS variable is provided by the build system and points to a
special GNU Makefile that will clear many LOCAL_XXX variables for you
(e.g. LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...),
with the exception of LOCAL_PATH. This is needed because all build
control files are parsed in a single GNU Make execution context where
all variables are global.

LOCAL_MODULE := hello-jni

The LOCAL_MODULE variable must be defined to identify each module you
describe in your Android.mk. The name must be *unique* and not contain
any spaces. Note that the build system will automatically add proper
prefix and suffix to the corresponding generated file. In other words,
a shared library module named 'foo' will generate 'libfoo.so'.

IMPORTANT NOTE:
If you name your module 'libfoo', the build system will not
add another 'lib' prefix and will generate libfoo.so as well.
This is to support Android.mk files that originate from the
Android platform sources, would you need to use these.

LOCAL_SRC_FILES := hello-jni.c

The LOCAL_SRC_FILES variables must contain a list of C and/or C++ source
files that will be built and assembled into a module. Note that you should
not list header and included files here, because the build system will
compute dependencies automatically for you; just list the source files
that will be passed directly to a compiler, and you should be good.

Note that the default extension for C++ source files is '.cpp'. It is
however possible to specify a different one by defining the variable
LOCAL_DEFAULT_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx'
will work, but not 'cxx').

include $(BUILD_SHARED_LIBRARY)

The BUILD_SHARED_LIBRARY is a variable provided by the build system that
points to a GNU Makefile script that is in charge of collecting all the
information you defined in LOCAL_XXX variables since the latest
'include $(CLEAR_VARS)' and determine what to build, and how to do it
exactly. There is also BUILD_STATIC_LIBRARY to generate a static library.

There are more complex examples under apps/, with commented
Android.mk files that you can look at.

Reference:
----------

This is the list of variables you should either rely on or define in
an Android.mk. You can define other variables for your own usage, but
the NDK build system reserves the following variable names:

- names that begin with LOCAL_ (e.g. LOCAL_MODULE)
- names that begin with PRIVATE_, NDK_ or APP_ (used internally)
- lower-case names (used internally, e.g. 'my-dir')

If you need to define your own convenience variables in an Android.mk
file, we recommend using the MY_ prefix, for a trivial example:

---------- cut here ------------------
MY_SOURCES := foo.c
ifneq ($(MY_CONFIG_BAR),)
MY_SOURCES += bar.c
endif

LOCAL_SRC_FILES += $(MY_SOURCES)
---------- cut here ------------------

So, here we go:

NDK-provided variables:
- - - - - - - - - - - -

These GNU Make variables are defined by the build system before
your Android.mk file is parsed. Note that under certain circumstances
the NDK might parse your Android.mk several times, each with different
definition for some of these variables.

CLEAR_VARS
Points to a build script that undefines nearly all LOCAL_XXX variables
listed in the "Module-description" section below. You must include
the script before starting a new module, e.g.:

include $(CLEAR_VARS)

BUILD_SHARED_LIBRARY
Points to a build script that collects all the information about the
module you provided in LOCAL_XXX variables and determines how to build
a target shared library from the sources you listed. Note that you
must have LOCAL_MODULE and LOCAL_SRC_FILES defined, at a minimum before
including this file. Example usage:

include $(BUILD_SHARED_LIBRARY)

note that this will generate a file named lib$(LOCAL_MODULE).so

BUILD_STATIC_LIBRARY
A variant of BUILD_SHARED_LIBRARY that is used to build a target static
library instead. Static libraries are not copied into your
project/packages but can be used to build shared libraries (see
LOCAL_STATIC_LIBRARIES and LOCAL_STATIC_WHOLE_LIBRARIES described below).
Example usage:

include $(BUILD_STATIC_LIBRARY)

Note that this will generate a file named lib$(LOCAL_MODULE).a

TARGET_ARCH
Name of the target CPU architecture as it is specified by the
full Android open-source build. This is 'arm' for any ARM-compatible
build, independent of the CPU architecture revision.

TARGET_PLATFORM
Name of the target Android platform when this Android.mk is parsed.
For now, only 'android-3' is supported, which corresponds to the
Android 1.5 platform.

TARGET_ARCH_ABI
Name of the target CPU+ABI when this Android.mk is parsed.
For now, only 'arm' is supported, which really means the following:

ARMv5TE or higher CPU, with 'softfloat' floating point support

Other target ABIs will be introduced in future releases of the NDK
and will have a different name. Note that all ARM-based ABIs will
have 'TARGET_ARCH' defined to 'arm', but may have different
'TARGET_ARCH_ABI'

TARGET_ABI
The concatenation of target platform and abi, it really is defined
as $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you want
to test against a specific target system image for a real device.

By default, this will be 'android-3-arm'

NDK-provided function macros:
- - - - - - - - - - - - - - -

The following are GNU Make 'function' macros, and must be evaluated
by using '$(call )'. They return textual information.

my-dir
Returns the path of the current Android.mk's directory, relative
to the top of the NDK build system. This is useful to define
LOCAL_PATH at the start of your Android.mk as with:

LOCAL_PATH := $(call my-dir)

all-subdir-makefiles
Returns a list of Android.mk located in all sub-directories of
the current 'my-dir' path. For example, consider the following
hierarchy:

sources/foo/Android.mk
sources/foo/lib1/Android.mk
sources/foo/lib2/Android.mk

If sources/foo/Android.mk contains the single line:

include $(call all-subdir-makefiles)

Then it will include automatically sources/foo/lib1/Android.mk and
sources/foo/lib2/Android.mk

This function can be used to provide deep-nested source directory
hierarchies to the build system. Note that by default, the NDK
will only look for files in sources/*/Android.mk

this-makefile
Returns the path of the current Makefile (i.e. where the function
is called).

parent-makefile
Returns the path of the parent Makefile in the inclusion tree,
i.e. the path of the Makefile that included the current one.

grand-parent-makefile
Guess what...

Module-description variables:
- - - - - - - - - - - - - - -

The following variables are used to describe your module to the build
system. You should define some of them between an 'include $(CLEAR_VARS)'
and an 'include $(BUILD_XXXXX)'. As written previously, $(CLEAR_VARS) is
a script that will undefine/clear all of these variables, unless explicitely
noted in their description.

LOCAL_PATH
This variable is used to give the path of the current file.
You MUST define it at the start of your Android.mk, which can
be done with:

LOCAL_PATH := $(call my-dir)

This variable is *not* cleared by $(CLEAR_VARS) so only one
definition per Android.mk is needed (in case you define several
modules in a single file).

LOCAL_MODULE
This is the name of your module. It must be unique among all
module names, and shall not contain any space. You MUST define
it before including any $(BUILD_XXXX) script.

The module name determines the name of generated files, e.g.
lib.so for a shared library module named . However
you should only refer to other modules with their 'normal'
name (e.g. ) in your NDK build files (either Android.mk
or Application.mk)

LOCAL_SRC_FILES
This is a list of source files that will be built for your module.
Only list the files that will be passed to a compiler, since the
build system automatically computes dependencies for you.

Note that source files names are all relative to LOCAL_PATH and
you can use path components, e.g.:

LOCAL_SRC_FILES := foo.c \
toto/bar.c

NOTE: Always use Unix-style forward slashes (/) in build files.
Windows-style back-slashes will not be handled properly.

LOCAL_CPP_EXTENSION
This is an optional variable that can be defined to indicate
the file extension of C++ source files. The default is '.cpp'
but you can change it. For example:

LOCAL_CPP_EXTENSION := .cxx

LOCAL_C_INCLUDES
An optional list of paths, relative to the NDK *root* directory,
which will be appended to the include search path when compiling
all sources (C, C++ and Assembly). For example:

LOCAL_C_INCLUDES := sources/foo

Or even:

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo

These are placed before any corresponding inclusion flag in
LOCAL_CFLAGS / LOCAL_CPPFLAGS

LOCAL_CFLAGS
An optional set of compiler flags that will be passed when building
C *and* C++ source files.

This can be useful to specify additionnal macro definitions or
compile options.

IMPORTANT: Try not to change the optimization/debugging level in
your Android.mk, this can be handled automatically for
you by specifying the appropriate information in
your Application.mk, and will let the NDK generate
useful data files used during debugging.

NOTE: In android-ndk-1.5_r1, the corresponding flags only applied
to C source files, not C++ ones. This has been corrected to
match the full Android build system behaviour. (You can use
LOCAL_CPPFLAGS to specify flags for C++ sources only now).

LOCAL_CXXFLAGS
An alias for LOCAL_CPPFLAGS. Note that use of this flag is obsolete
as it may disappear in future releases of the NDK.

LOCAL_CPPFLAGS
An optional set of compiler flags that will be passed when building
C++ source files *only*. They will appear after the LOCAL_CFLAGS
on the compiler's command-line.

NOTE: In android-ndk-1.5_r1, the corresponding flags applied to
both C and C++ sources. This has been corrected to match the
full Android build system. (You can use LOCAL_CFLAGS to specify
flags for both C and C++ sources now).

LOCAL_STATIC_LIBRARIES
The list of static libraries modules (built with BUILD_STATIC_LIBRARY)
that should be linked to this module. This only makes sense in
shared library modules.

LOCAL_SHARED_LIBRARIES
The list of shared libraries *modules* this module depends on at runtime.
This is necessary at link time and to embed the corresponding information
in the generated file.

Note that this does not append the listed modules to the build graph,
i.e. you should still add them to your application's required modules
in your Application.mk

LOCAL_LDLIBS
The list of additional linker flags to be used when building your
module. This is useful to pass the name of specific system libraries
with the "-l" prefix. For example, the following will tell the linker
to generate a module that links to /system/lib/libz.so at load time:

LOCAL_LDLIBS := -lz

See docs/STABLE-APIS.TXT for the list of exposed system libraries you
can linked against with this NDK release.

LOCAL_ALLOW_UNDEFINED_SYMBOLS
By default, any undefined reference encountered when trying to build
a shared library will result in an "undefined symbol" error. This is a
great help to catch bugs in your source code.

However, if for some reason you need to disable this check, set this
variable to 'true'. Note that the corresponding shared library may fail
to load at runtime.

LOCAL_ARM_MODE
By default, ARM target binaries will be generated in 'thumb' mode, where
each instruction are 16-bit wide. You can define this variable to 'arm'
if you want to force the generation of the module's object files in
'arm' (32-bit instructions) mode. E.g.:

LOCAL_ARM_MODE := arm

Note that you can also instruct the build system to only build specific
sources in arm mode by appending an '.arm' suffix to its source file
name. For example, with:

LOCAL_SRC_FILES := foo.c bar.c.arm

Tells the build system to always compile 'bar.c' in arm mode, and to
build foo.c according to the value of LOCAL_ARM_MODE.

NOTE: Setting APP_OPTIM to 'debug' in your Application.mk will also force
the generation of ARM binaries as well. This is due to bugs in the
toolchain debugger that don't deal too well with thumb code.

Friday, June 03, 2011

PDF Processing with Perl to include in Electric Cloud

I personally love Electric Commander from Electric cloud when it comes to run automated build. Electric Commander comes with a very good Procedure and Steps engine which can integrate on Multiple agent node and be able to execute perl script.
At the end of the build it is always recommanded to generate a nice report sometimes after running complex automation test.


PDF Packages

I like PDF::Reuse, but there are several other options for PDF creation and manipulation on the CPAN.

PDF::API2, by Alfred Reibenschuh, is actively maintained. It is the package of choice if creating new PDF documents from scratch.
PDF::API2::Simple, by Red Tree Systems, is a wrapper over the PDF::API2 module for users who find the PDF::API2 module to difficult to use.
Text::PDF, by Martin Hosken, can work on more than PDF file at the same time and has Truetype font support.
CAM::PDF, by Clotho Advanced Media, is like PDF::Reuse more focused on reading and manipulating existing PDF documents. However, it can work on multiple files at the same time. Use it if you need more features than PDF::Reuse actually provides.
Conclusions
PDF::Reuse is a well-written and well-documented package, which makes it easy to create, combine, and change existing PDF documents. The two sample applications show some of its capabilities. Two limitations should be mentioned however, PDF::Reuse can't reuse existing bookmarks, and after combining different PDF documents some of the inner document hyperlinks might stop working properly.