Contents
Introduction
Requirements
Installation
Getting started
Tip and notes
Introduction
These notes describe how to set up Eclipse to do Android development with
Pascal. Two additional tools provide the Pascal support:
- 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.
- 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
- Free Pascal JVM compiler.
http://wiki./FPC_JVM
- Pascal Builder for Android source code.
web./~MacPgmr/pba/pba.zip
- Android SDK.
developer./sdk/index.html
- Eclipse Classic.
www./downloads
Installation
- FPC JVM compiler.
Complete build instructions are at wiki./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./svn/fpc/trunk .
- Download ftp://ftp./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.
- 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.
- 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).
- Eclipse.
Once you have Eclipse installed, follow the instructions and install the ADT Plugin
(developer./tools/sdk/eclipse-adt.html).
- Add PBA to Eclipse as an external tool.
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
To test your installation, create a simple Android app. You won't have to do
any coding for this test.
- In Eclipse, choose File | New | Project.
- In the New Project dialog, select Android Application Project and
click Next.
- 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.
- Click Next again to skip past the Configure Launcher Icon page.
- On the Create Activity page, select BlankActivity and click Next.
- On the New Blank Activity page, accept the defaults for Activity Name
(MainActivity) and Layout Name (activity_main) and click Finish.
- 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.
- 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.
- 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.
- 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).
- 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
- 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.
- 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)
- 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.
- 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.
- For descriptions of a class's methods, refer to the Android on-line
documentation, for example:
developer./reference/android/database/sqlite/SQLiteDatabase.html
- 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.
- 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.
- 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.
- 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.
- 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.
- Both .jar and .apk files are just zip-format archive files, so you can
view their contents just like you would any .zip file.
|