- Lazarus 0.9.31 or later with Free Pascal 2.6.1 (32-bit) or later.
- FPC4Android package 2.5.1.
- Java JDK 6 (JDK 7 is currently not supported by Android).
- Latest version of the Android SDK.
- Latest version of the Android NDK.
- Eclipse Classic 3.7.2 or later.
- A device running Android 2.3 or later.
This guide assumes you will be developing Android apps on Windows. To develop on Linux or OS X you will have to make the appropriate changes.
At the time of this writing, there is no official release of Lazarus 0.9.31
- Free Pascal 2.6.1 or later. But you can download the latest development
Be sure to select the "win32" version of "Lazarus + fpc 2.6.1" (or later).
Once this version becomes official, you should download it here:
Download and install the "Windows 32 bits" package (even if you have a 64-bit Windows version, since you will be building 32-bit executables; 64-bit executables will not work with AGK for Pascal).
- Install AGK for Pascal in the directory C:\AgkPas. You can use a different directory if you want to, but all the templates and support files assume it is installed in this directory. If you use a different directory, then you will have to modify search paths and batch files later on.
- Download and install Lazarus and Free Pascal.
- Download the version 2.5.1 of FPC4Android here and unzip it: http://sourceforge.net/projects/p-tools/files/Free Pascal for ARM/Windows/
- Merge FPC4Android with your Lazarus/FPC installation. Suppose Lazarus is installed in C:\Lazarus and FPC is installed in C:\Lazarus\FPC\2.6.1. Now create a directory C:\Lazarus\FPC\2.5.1\units (that is 2.5.1, not 2.6.1) and move the unzipped unitsarm-linux folder here (so you end up with C:\Lazarus\FPC\2.5.1\units\arm-linux). Now go to C:\Lazarus\FPC\2.6.1\bin\i386-win32 (if you installed a different version of Lazarus+FPC, then the version number in the path will be different). Copy the contents of the unzipped bin\i386-win32 folder here (so there should be a ppcrossarm.exe file in the directory C:\Lazarus\FPC\2.6.1\bin\i386-win32 now).
- Download and install Java JDK 6. Download it here: http://www.oracle.com/technetwork/java/javase/downloads/index.html Scroll down to "Jave SE 6 Update xx" and select the 32-bit Windows package.
- Download the latest version of the Android SDK here: http://developer.android.com/sdk/index.html It is recommended that you install the SDK in the directory C:\Android\android-sdk. If you select a different directory, then you will have to modify some paths in project files later on.
- Start the Android SDK Manager (it is started automatically after the setup). De-select the latest API version (eg. "Android 4.0.3 (API15)") and select the "Obsolete" checkbox. If you cannot see an "Obsolete" checkbox, then open the "Packages" menu and select "Show Obsolete Packages". Check the "Android 2.3.1 (API9)" checkbox. Also, under "Extas", make sure that the "Google USB Driver" is selected. Click the "Install X packages..." button and in the next window select "Accept All" and click "Install".
- Download the latest version of the Android NDK here and unzip it: http://developer.android.com/sdk/ndk/index.html Create a directory C:\Android\android-ndk. Move the contents of the unzipped "android-ndk-rX" to this directory so that you end up with the directories C:\Android\android-ndk\build, C:\Android\android-ndk\docs etc.
- Download Eclipse Classic here and install or unzip it: http://www.eclipse.org/downloads/
- Install the ADT (Android Developer Tools) plugin for Eclipse using these instructions: http://developer.android.com/sdk/installing/installing-adt.html After the plugin is installed and Eclipse is restarted, the "Welcome to Android Development - Configure SDK" window should appear. If so, select the radio button "Use existing SDKs" and browse for the directory where you installed the SDK (eg. C:\Android\android-sdk). If the Welcome window does not appear, then go to "Window | Preferences" and select the Android node. Browse for the SDK location (eg. C:\Android\android-sdk) and click Apply and then OK.
Creating an AGK project
AGK projects for Android consists of 2 parts: a dynamic library (.so file) containing the application code and an Android package (.apk) file that wraps the dynamic library and a Java launcher into a package that can be installed on an Android device.
You create the dynamic library with Lazarus and the Android package with Eclipse.
The easiest way to start a Lazarus AGK application is to use a template. The template can be found in the /Developer/AgkPas/Templates/Android directory.
- Copy the files in the /Developer/AgkPas/Templates/Android directory to your application directory.
- Open the "android_post_build.bat" file that you just copied in a text editor. This batch file is executed every time you build the project in Lazarus. It is used to copy the AGK support files and custom resources to the Android package. If you did not install AGK for Pascal in the directory C:\AgkPas, then you need to modify the batch file accordingly.
- Open the AndroidManifest.xml file (in the "android" subdirectory) in a text editor. This file contains information about your application. You need to at least change the "package" attribute inside the <manifest> element. This must be a value that uniquely identifies your application with all the Android applications in the entire world. That is, you cannot have 2 Android applications with the same package code running on the same device. Usually, to help with uniqueness, you put your company name in the package name.
- Open the ".project" file (in the "android" subdirectory) in a text editor. Change the contents of the <name> element to your project name. This name is used to identify the project in Eclipse.
- Start Lazarus.
- Open the copied project.
- Choose "Project | Save Project As..." and save the project under a new name. You can now delete the copied AgkTemplate_android.lpi, AgkTemplate_android.lpr and AgkTemplate_android.res files.
- Build the library.
- Start Eclipse.
- Choose "File | Import..." and select "General | Existing Projects into Workspace". Browse for the "android" subdirectory of the project directory and click "Finish".
- After you have imported the project, or if you try to run it, you may get an error message like "[project] requires compiler compliance level 5.0 or 6.0. Found '1.4' instead". If you get this error, right-click on the project in the Package Explorer and select "Android Tools | Fix Project Properties".
- Make sure your Android device is attached to your computer using a USB cable and that it is running in Debug Mode. To set your device to Debug Mode, go to its Settings screen and under "Developer Options" enable "USB debugging".
- Select the project in Project Explorer and select "Run | Run As | Android Application". This will create the package, install it on your Android device, and run the application.
- Every time you recompile the project in Lazarus, you need to right-click the project in Eclipse and select "Refresh" so it will load the newly compiled library.
Note that AGK applications (currently) do not work in an emulator due to limitations of the Android emulator. You need to use a real device.
After the AGK for Pascal launch screen, the text "Hello AGK for Pascal!" should appear.
Note: if you want, you can customize the AndroidManifest.xml file for your app. You can also customize the resources in the android\res subdirectory. In particular, you can specify custom icons here and the application title in the android\res\values\strings.xml file.
- if you get a compiler error like "Can't open include file "AGK.inc" then you probably have not installed AGK for Pascal in the C:\AgkPas directory. In that case you will need to modify the search paths. Go to "Project | Options... | Compiler Options | Paths" and update the paths under "Other Unit Files" and "Include Files" to match your installation.
- Also, if you did not install the Android NDK in C:\Android\android-ndk, then you need to modify the Library path as well to match the installation.
- Another possible reason for compilation failure is that your application, or the AGK for Pascal library, is installed in a directory with whitespace characters in its name. Free Pascal doesn't like that.
- If Eclipse has problems compiling the Java part, then you may need to add the Bin directory of your Java JDK installation to the environment PATH variable (for example: C:\Program Files (x86)\Java\jdk1.6.0_22\bin, depending on your installation).
- If Eclipse doesn't recognize your device when you try to run your game, then you may not have the correct USB drivers installed. Make sure you have installed the "Google USB Driver" in the SDK manager. If that does not help, check out this page: http://developer.android.com/tools/extras/oem-usb.html
- If you get any error at run-time, you can check the Android debug log in Eclipse using "Window | Show View | Other...". Then open the "Android | LogCat" window.
Note about application resources
For Android applications, resources (like images, sounds etc.) must be located in the "android\assets" subdirectory of the application directory. You can copy your resources here manually or you can modify the "android_post_build.bat" batch file to copy the resources to this directory. This is the preferred way if your application is multi-platform and you want to make sure the resources stay synchronized. The batch file is executed every time you compile the library in Lazarus and it contains lines like this:
copy agk.png android\assets
This example copies the agk.png file from the source directory to the "android\assets" subdirectory. You can modify the batch file to copy all your resources.
If you want to check out some examples, then look at the Examples directory. It contains a large number of sample applications, categorized in various subdirectories. Each subdirectory contains further subdirectories for each sample application. In those subdirectories you will find 3 Lazarus projects. Open the one with the "_android" suffix (the other ones are for building Windows and Mac OS X applications). Note that each sample has the same "package" value in the manifest, so each time you run a sample app on you device, it will overwrite a previous sample app with the same "package" value. This is intentional to prevent your device from filling up with sample applications.