Developing for Android with Pascal and Eclipse

Contents

Introduction

1. Free Pascal's JVM compiler. This compiler emits Java byte code and creates normal Java .class files when it compiles Pascal source files. A Pascal unit for accessing the android.jar runtime library is included.

2. Pascal Builder for Android (PBA). This is a simple console app that helps integrate Pascal with Eclipse. When Eclipse builds a project, it runs a series of "builders". PBA is just a custom builder that you add to your Android project. When you build an Android project, PBA does the following:
   • For each "activity" that you add to your Android project, PBA creates an equivalent Pascal unit the next time it's run.

   • Parses the Android project's R.java resource file and creates the equivalent Pascal unit (Rjava.pas).

   • Launches FPC's JVM compiler with the appropriate paths and switches to compile your Android project's Pascal files.

Requirements

1. Free Pascal JVM compiler.

   http://wiki.freepascal.org/FPC_JVM

2. Pascal Builder for Android source code.

   pba.zip

3. Android SDK.

   developer.android.com/sdk/index.html

4. Eclipse Classic.

   www.eclipse.org/downloads

Installation

1. FPC JVM compiler.

   Complete build instructions are at wiki.freepascal.org/FPC_JVM/Building, but here's the short version. Note that this assumes you already have a non-JVM FPC compiler installed (for example, stable version 2.6.0).

   • Check out the FPC trunk source from its Subversion repository. Change to the directory where you want to put the checked out source files and enter this:

     svn co http://svn.freepascal.org/svn/fpc/trunk .

   • Download ftp://ftp.freepascal.org/pub/fpc/contrib/jvm/fpcjvmutilities.zip, unzip it, and place jasmin.jar somewhere on your path.

   • Change to the utils/fpcm directory in your FPC checkout and build fpcmake:

     make clean all

     Then move the resulting fpcmake executable to anywhere outside the checkout directory.

   • Build FPC JVM compiler. On my Mac, I put this in a script file (.sh) for ease of running it again later:

     make_path=/Users/Phil/Tools/fpctests/fpcmake
     install_path=/Users/Phil/Tools/fpcjvm
     make FPCMAKE=$make_path CROSSOPT="-O2 -g" CPU_TARGET=jvm OS_TARGET=android INSTALL_PREFIX=$install_path all crossinstall

     When the make is done, you'll have the FPC JVM compiler (ppcjvm), the compiled System unit, and the compiled androidr14 unit that provides access to the entire Android RTL.

2. Pascal Builder for Android.
   • Compile PBA like this using a non-JVM FPC compiler:

     fpc pba

   • If you have Lazarus, you can also compile PBA there. In Lazarus, choose File | Open and select the pba.lpi file. Choose Run | Compile to compile it.

3. Android SDK.

   Both the Android tools and Eclipse assume that you have Java installed on your development computer. If not, download the JDK from www.oracle.com/technetwork/java/index.html. Note that I did not need to install any additional Java software on my Mac; you may not need to download the JDK either.

   Once installed you also have to download some additional pieces. I only downloaded the basics using the SDK's Android SDK Manager:

   • Android SDK Platform-tools
   • SDK Platform
   • ARM EABI v7a System Image
   • Android Support Library (under Extras)

   Tip: While you're at it in the Android SDK Manager, create at least one virtual device (Tools | Manage AVDs) if you want to test your apps in the Android emulator (but be warned, the emulator is dreadfully slow).

4. Eclipse.

   Once you have Eclipse installed, follow the instructions and install the ADT Plugin (developer.android.com/tools/sdk/eclipse-adt.html).

5. Add PBA to Eclipse as an external tool.
   • Start Eclipse and choose Run | External Tools | External Tools Configuration.

   • Select Program and click the New icon (+).

   • In Name, enter something suitable like Pascal Builder.

   • In Location, enter the complete path to pba per installation step 2 above. On my Mac, I entered:

     /Users/phil/Tools/jvmtests/pba

   • In Arguments, enter three items, separated by spaces. The items are (i) path to ppcjvm (see step 1 above), (ii) macro placeholder for path to the Android project, and (iii) the FPC -FD switch with the directory where you placed jasmin.jar. On my Mac, I entered:

     ~/Tools/fpcjvm/lib/fpc/2.7.1/ppcjvm ${project_loc} -FD/usr/local/bin

     Tip: You can include additional FPC switches if necessary (for example, additional -Fu switches).

   You will only have to enter this information once. For each Android project, you will simply import this external tool as an Eclipse "builder".

Getting started

1. In Eclipse, choose File | New | Project.

2. In the New Project dialog, select Android Application Project and click Next.

3. On the New Android Application page, fill in the following:
   • Application Name. For example, Tooltest.

   • Project Name. You can use the supplied default.

   • Package Name. You can use the supplied default for a test app. Normally you would enter the reverse domain name of your company or project plus an application identifier (for example, com.mycompany.myapp). The package name must be unique and is used throughout the project, including as the "namespace" in your project's Pascal units.

   Click Next.

4. Click Next again to skip past the Configure Launcher Icon page.

5. On the Create Activity page, select BlankActivity and click Next.

6. On the New Blank Activity page, accept the defaults for Activity Name (MainActivity) and Layout Name (activity_main) and click Finish.

7. Once Eclipse has created the new Android project, you'll see the project's structure in Package Explorer. It should look like Figure 1.

      Figure 1. Folders and files in a typical Eclipse Android project.

   

   src - this is where the project's Java source files would go, but since we're developing with Pascal you won't use this folder.

   gen - each time you build the project, Eclipse extracts resource identifiers from all of the project's XML resource files and creates a new R.java file; PBA converts R.java to Rjava.pas each time it's updated.

   assets - database files, images, etc. can be placed here for deployment with your app.

   bin - compiled files (.class extension) are placed here under classes; the .apk file that you deploy is created here too.

   libs - place any .jar files that your app needs here; you can create a .jar file from compiled Pascal .class files as well as from compiled Java .class files.

   res - XML resource files go here; note how Eclipse has opened the activity_main.xml resource file in the Graphical Layout designer; you can also switch to a raw XML editor to view and edit a layout (see Figure 2).

   AndroidManifest.xml - project's manifest file; normally you let Eclipse manage this file.
   

      Figure 2. Eclipse layout designer.

   

8. Add PBA as a builder to your project.
   • In Eclipse, choose Project | Properties.

   • In the Properties dialog, select Builders. Note the list of builders that are already part of your project.

   • Click Import and select Pascal Builder that you defined as an external tool above.

   • Select Pascal Builder and click Up to move it above Android Package Builder in the build sequence.

9. Build your project. If you have the Eclipse console open you should see familiar FPC output there.

   Tip: If you get an error message, it may mean that you don't have PBA configured properly as an external tool. If you edit Pascal Builder's configuration, you'll need to delete the project's Pascal Builder and import it again to use the updated configuration.

10. Refresh Eclipse.

    To see your project's Pascal files (created by PBA), select your project in Package Explorer and choose File | Refresh. You should now see a pas folder in Package Explorer. Expand it and select MainActivity.pas. Right-click it and choose Open With | Text Editor to open it in Eclipse. You can also open Rjava.pas to see your project's resource identifiers. Note how MainActivity.pas references two resource identifiers.

    Tip: If you double-click a Pascal file, it will open with whatever program you have associated with the .pas extension. On my Mac, this is TextWrangler. If you prefer, you can then edit your source with a more familiar editor instead of in Eclipse's editor (see Figure 3).

       Figure 3. Pascal boilerplate code for Android "activity" (as viewed in TextWrangler).

    

11. Run app in Android emulator.

    Right-click your project in Package Explorer and choose Run As | Android Application. Eclipse will launch the Android emulator and, after a lengthy delay, your app will start, displaying "Hello world!". Press the Esc key to exit the app in the emulator.

Tips and notes

1. You now have access to practically the entire Eclipse and Android toolsets. This includes not only the complete set of Android widgets and a graphical designer for laying them out, but also access to the complete Android runtime. To get a sense of the magnitude of this runtime, open file androidr14.inc in your FPC checkout folder's rtl/android/jvm directory with a text editor. This file is over 50,000 lines long and it's provided for you with FPC ready to use as the compiled androidr14 unit - you don't have to do anything else except add it to your units' uses statements.

2. Since FPC does not support dot notation for unit names, you'll see in androidr14.inc that Java class names have been abbreviated using the first letter of each package level plus the class name. For example, the Android class SQLiteDatabase in the android.database.sqlite package is named ADSSQLiteDatabase for use with Pascal. If you look at its complete Pascal declaration (in androidr14.inc), you can see the external package and class it refers to:

   ADSSQLiteDatabase = class external 'android.database.sqlite' name 'SQLiteDatabase' (ADSSQLiteClosable)

3. You use a Java class the same way you use Pascal classes. For example, to use the SQLiteDatabase class to open a SQLite database, you would write something like this:

   var
     FileName : string;
     Db       : ADSSQLiteDatabase;
   begin
     FileName := '/data/data/com.mycompany.myapp/databases/mydb.sqlitedb';
     Db := ADSSQLiteDatabase.openDatabase(FileName, nil, ADSSQLiteDatabase.OPEN_READONLY);
   

   In this case, openDatabase is a class function that returns an instance of the SQLiteDatabase class if the specified database is opened successfully.

4. It's a good idea to have androidr14.inc open while programming so you can quickly find an abbreviated class name or see the Pascal signature of a method you want to call.

5. For descriptions of a class's methods, refer to the Android on-line documentation, for example:

   developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html

6. To add another activity to your Android project, in Eclipse choose File | New | Other, then select Android Activity, click Next and follow the steps. The resulting Pascal file will contain the same boilerplate code as your project's main activity - just edit its code and layout as needed.

7. As documented here, you can use the javapp.jar console app (included in FPC's JVM utilities .zip) to create a Pascal interface unit for a Java .jar file. For example, to work with the PhoneGap Plugin class from the org.apache.cordova.api package, run javapp.jar against the cordova.jar file, as in the following example script:

   and_path=~/Tools/android-sdk-macosx/platforms/android-16/android.jar
   cord_path=~/Tools/phonegap-current/lib/android/cordova-2.1.0.jar
   java -jar /usr/local/bin/javapp.jar -bootclasspath $and_path -classpath $cord_path -protected -o cordova_api org.apache.cordova.api.
   

   This creates files cordova_api.pas and cordova_api.inc containing Pascal declarations for the PhoneGap plugin classes.

8. To use a .jar file in an Android project, in Eclipse choose Project | Properties, select Java Build Path, then click the Libraries tab. If you added the .jar file to your project's libs folder, click Add JARs and select it; if the .jar file is external to your project, click Add External JARs and navigate to it.

9. To compile your own Pascal units outside of Eclipse, you can create a simple script that looks like something like this:

   comp_path=~/Tools/fpcjvm/lib/fpc/2.7.1
   rtl_path1=$comp_path/units/jvm-android/rtl
   rtl_path2=$comp_path/units/jvm-android/rtl/org/freepascal/rtl
   $comp_path/ppcjvm -Tandroid -XP -Fu$rtl_path1 -Fu$rtl_path2 -O2 -g someunit.pas
   

   The second RTL path is not strictly needed to compile, but you'll get a warning if you don't include it.

10. Use the Java jar utility to create a .jar file containing your own .class files. For example, if your units have the "myunits" namespace, you would enter something like this:

    jar -cvf myunits.jar myunits

    All of the .class files under the myunits directory would get added to myunits.jar.

11. Both .jar and .apk files are just zip-format archive files, so you can view their contents just like you would any .zip file.

macpgmr (at) icloud (dot) com

First posted Nov. 4, 2012.