Android Interface

Architecture (Executable vs JNI)

As of August 2011 (and Android 3.0), the Android platform can only execute Java Android applications, but these applications can load native libraries and can also run native executables. Therefore, to create Pascal applications in Android one can use one of these methods:

• method 1> Write the Pascal application as a library connected to the Java application via JNI
• method 2> Write the Pascal application as an executable and connect it to Java via pipes or sockets

Running the LCL application as a library and communicating with Java via JNI to create a native interface would generate several serious issues:

1. The main project file would need to be different for Android apps
2. Free Pascal has some issues with DLLs
3. The FPC arm-linux cross-compiler needs some changes to support building Android libraries, but it works fine as is for Android executables
4. The Java Native Interface is complex and hard to work with.

To avoid these issues it was preferred to create instead a native executable for the Lazarus applications and let it communicate with the auxiliary Java application only for indispensable things. This might, however, be changed in the future into using JNI.

Architecture (Native vs Custom Drawn)

For the GUI, one can freely mix in Android native and custom drawn widgets, and that's how the LCL will be built: With some native widgets and some custom drawn ones.

• For the current implementation, see: Android Interface/Native Android GUI

Other ideas which are not being implemented by anyone:

• For an older, abandoned idea, see: Android Interface/OpenGL ES GUI
• For an idea from someone to use Qt see: Android Qt port

Roadmap

1. Build the set of Lazarus Custom Drawn Controls
2. Initial bindings for the Android APIs
3. Create an application to automatically generate the bindings
4. Write the new android widgetset
5. Implement support for JNI

Using the Android SDK, Emulator and Phones

Android Interface/Using the Android SDK, Emulator and Phones

Android Programming

Android Interface/Android Programming

Configuring the Free Pascal Compiler for Android

Building the compiler yourself

See Setup_Cross_Compile_For_ARM and make sure to use the option OPT="-dFPC_ARMEL" for building the compiler.

Using the pre-compiled compiler

A pre-compiled compiler is provided for convenience for users. The following steps were tested in Mandriva Linux 2010.0 and 2010.1:

Required Environment

• The latest stable FPC installed in the system via the RPM / DEB / TAR package

Step 1 - Install the cross-binutils

For Mandriva Linux the RPM package containing arm-linux-as, arm-linux-ld, etc, which are the cross-binutils can be found here: http://rpm.pbone.net/index.php3/stat/4/idpl/14252825/dir/mandriva_2010/com/cross-arm-binutils-2.20.51.0.4-2mnb2.i586.rpm.html

Just download the RPM package and install it using:

rpm -ivh cross-arm-binutils-2.20.51.0.4-2mnb2.i586.rpm 

In Mandriva Linux 2010.0 the dependencies won't match, as the package is for 2010.1, but one can simply ignore this problem and it works fine using --nodeps:

rpm -ivh --nodeps cross-arm-binutils-2.20.51.0.4-2mnb2.i586.rpm 

For other distributions use the corresponding package, or else read the instructions for building the cross-binutils yourself at Setup_Cross_Compile_For_ARM

Step 2 - Configure the cross-binutils

The assembler needs a parameter to tell it which ARM ABI to use. A choice which works good is EABI-5, which is compatible with all Android devices available as of Jan 2011. To set this, we will rename the original assembler and substitute it with a shell script which passes the desired parameter. These commands will do it:

su
mv /usr/bin/arm-linux-as /usr/bin/arm-linux-as_org
gedit /usr/bin/arm-linux-as

Now paste into the editor this code:

#!/bin/sh
/usr/bin/arm-linux-as_org -meabi=5 $@

And don't forget to then make it executable:

chmod 755 /usr/bin/arm-linux-as

Step 3 - Install Free Pascal

At this point the pre-compiled FPC can be download from here: http://sourceforge.net/projects/p-tools/files/Free%20Pascal%20for%20ARM/

Then use these commands to install the pre-compiled Free Pascal cross-compiler into /usr:

[felipe@localhost Programas]$ ls -l
total 20664
-rw-rw-r--  1 felipe felipe 17098552 2010-10-25 08:17 fpc-2.5.1.arm-linux.tar.gz
[felipe@localhost Programas]$ su
Password: 
[root@localhost Programas]# cp fpc-2.5.1.arm-linux.tar.gz /usr/
[root@localhost Programas]# cd /usr/
[root@localhost usr]# tar -xvf fpc-2.5.1.arm-linux.tar.gz 
[root@localhost usr]# ln -s lib/fpc/2.5.1/ppcrossarm bin/ppcrossarm

Now we are ready to compile Android applications using the Lazarus IDE! Configuring the fpc.cfg file isn't necessary, the compiled will automatically find the new compiler and it's object files.

Compiling the example LCL-Android Application

Step 1 - Download the source code

From the command line it is:

svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/examples/androidlcl androidlcl

Step 2 - Build it using the Lazarus IDE

Step 3 - Build the APK

Go to the command line and issue these commands:

 cd lazarus-ccr/examples/androidlcl/android
 ant debug

The APK will be located in lazarus-ccr/examples/androidlcl/android/bin

Step 4 - Install the APK in your phone and run it

You should see this:

How to create an LCL-Android Application

To create a new LCL-Android application simply copy all of the file structure and build and java files from the example project called "androidlcl". This example can be obtained here:

svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/examples/androidlcl androidlcl

How to build an LCL-Android application

Always build an LCL-Android app in this order:

1> First of all, build the Pascal executable without debug information. This debug information is useless and just makes the executable larger. Open the menu Project->Project Options and set the build mode, widgetset, architecture and operating system targets, as shown in these screenshots:

Building an LCL-Android application with debug info

It is useful to add another Android build mode which has debug info. Use all of the same options as shown above, except for the debug information:

Oh no! My LCL-Android application doesn't work

There are various reasons why the app may not work. The most important thing to do when an app doesn't work is to open the logcat and see what the log says. This can be done by running this command line command:

./adb logcat

And then test one of the hipotesis in the next subsections.

The Pascal executable was compiled for a wrong architecture, operating system and/or widgetset

This is the leading cause of executables not running. Always verify that you compiled the program to the "android" widgetset, "linux" operating system and "arm" architecture. This is done by going into the menu Project->Project Options. Then set these in the dialog as shown in these images:

My Pascal application crashed. How to get a stacktrace?

If a Pascal application crashes you will get a log similar to this in adb logcat:

V/AndroidPipesComm:(18912): amkJavaLang_New_String
V/AndroidPipesComm:(18912): amkUICommand
V/AndroidPipesComm:(18912): amkUI_TAlertDialog_Builder_setTitle_3
V/AndroidPipesComm:(18912): amkJavaLangCall
V/AndroidPipesComm:(18912): amkJavaLang_New_String
V/AndroidPipesComm:(18912): amkUICommand
V/AndroidPipesComm:(18912): amkUI_TAlertDialog_Builder_setMessage_2
V/AndroidPipesComm:(18912): amkUICommand
V/AndroidPipesComm:(18912): amkUI_TEditText_Create_0
V/AndroidPipesComm:(18912): amkUICommand
V/AndroidPipesComm:(18912): amkUI_TAlertDialog_Builder_setView_4
V/AndroidPipesComm:(18912): amkUICommand
V/AndroidPipesComm:(18912): amkUI_TAlertDialog_Builder_create_1
V/AndroidPipesComm:(18912): amkJavaLangCall
V/AndroidPipesComm:(18912): amkJavaLang_New_String
V/AndroidPipesComm:(18912): [WaitAndProcessPascalMessage] Unknown Pascal message!!! 54
V/AndroidPipesComm:(18912): TApplication.HandleException Access violation
V/AndroidPipesComm:(18912):   Stack trace:
V/AndroidPipesComm:(18912):   $000EB1C8
V/AndroidPipesComm:(18912):   $000EAF60
V/AndroidPipesComm:(18912):   $000E8664
V/AndroidPipesComm:(18912):   $00138ECC
V/AndroidPipesComm:(18912):   $00138F08
V/AndroidPipesComm:(18912):   $00138E94
V/AndroidPipesComm:(18912):   $000328AC
V/AndroidPipesComm:(18912):   $001113EC
V/AndroidPipesComm:(18912):   $0013597C
V/AndroidPipesComm:(18912):   $001360FC
V/AndroidPipesComm:(18912):   $0013674C
V/AndroidPipesComm:(18912):   $00135844
V/AndroidPipesComm:(18912):   $000171D0
V/AndroidPipesComm:(18912):   $00103C30
V/AndroidPipesComm:(18912):   $000EE0B0
V/AndroidPipesComm:(18912):   $000EF3FC
V/AndroidPipesComm:(18912):   $000EBF24
V/AndroidPipesComm:(18912): [FORMS.PP] ExceptionOccurred 
V/AndroidPipesComm:(18912):   Sender=EAccessViolation
V/AndroidPipesComm:(18912):   Exception=Access violation
V/AndroidPipesComm:(18912):   Stack trace:
V/AndroidPipesComm:(18912):   $00138398
V/AndroidPipesComm:(18912):   $001395C0
V/AndroidPipesComm:(18912):   $0013A588
V/AndroidPipesComm:(18912):   $0003ACF4
V/AndroidPipesComm:(18912):   $000E82D8
V/AndroidPipesComm:(18912):   $00138E10
V/AndroidPipesComm:(18912):   $001381E4
V/AndroidPipesComm:(18912):   $0002CC40
V/AndroidPipesComm:(18912):   $0002FD70
V/AndroidPipesComm:(18912):   $0002F080
V/AndroidPipesComm:(18912):   $000EE130
V/AndroidPipesComm:(18912):   $000EF3FC
V/AndroidPipesComm:(18912):   $000EBF24
V/AndroidPipesComm:(18912):   $000ECE78
V/AndroidPipesComm:(18912):   $000ED65C
V/AndroidPipesComm:(18912):   $000EABF4
V/AndroidPipesComm:(18912):   $0002F5D8
V/AndroidPipesComm:(18912): TApplication.HandleException: there was another exception during showing the first exception
V/AndroidPipesComm:(18912):   Stack trace:
V/AndroidPipesComm:(18912):   $00138398
V/AndroidPipesComm:(18912):   $001395C0
V/AndroidPipesComm:(18912):   $0013A588
V/AndroidPipesComm:(18912):   $0003ACF4
V/AndroidPipesComm:(18912):   $000E82D8
V/AndroidPipesComm:(18912):   $00138E10
V/AndroidPipesComm:(18912):   $001381E4
V/AndroidPipesComm:(18912):   $0002�

To obtain a valid stacktrace from this information copy all of this into the clipboard and execute the lazstacktrace application, which is located in the lazarus-ccr svn in the directly lazarus-ccr/applications/lazstacktrace

You can download the lazarus-ccr like this:

svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/ lazarus-ccr

Or only lazstacktrace like this:

svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/applications/lazstacktrace lazstacktrace

And here is how lazstackstrace looks like after you copy the stackstrace in it's window:

And now you should click the button "Resolve Symbols" and you will get the symbol names, like this: