FPC JVM Android Development: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(Android only)
2	2
3	3		This page gives you an introduction for developing Android applications using the [[FPC JVM\|JVM Port]] of the FPC compiler. For native development for ARM/Android, please see [[Custom Drawn Interface/Android\|here]].
4	4
5	5		## Prerequisites
6	6
7	7		You need to have the [Android SDK](http://developer.android.com/sdk/index.html) installed (at least version 10 should be sufficient). For more information about installing the SDK please refer to the [Android sites](http://developer.android.com/sdk/installing.html).
8	8
9	9		You also need the JDK (either the Oracle one or OpenJDK) and the JRE. To be more precise: the applications jarsigner and java must be available and depending on the method you choose below javac needs to be available as well.
10	10
11	11		At last you also need the FPC JVM compiler and the Jasmin assembler for which you should follow the guidelines written [[FPC JVM\|here]].
12	12
13	13		## Using Eclipse
14	14
15	15		See <https://macpgmr.github.io/pba/PbaStatus.html>
16	16
17	17		## Using Lazarus
18	18
19	19		### Preparations
20	20
21	21		You should use a trunk version of Lazarus as this already contains a few extensions for language features used and implemented in the JVM port.
22	22
23	23		Also to simplyfy things a bit you might want to patch Lazarus and the compiler driver "fpc":
24	24
25	25		#### Patching Lazarus
26	26
27	27		Apply the following patch to add support for the jvm platform and the android and arm operating systems (this patch is not yet reported, because first the JVM port should be merged back into FPC's trunk):
28	28
29		-	~~`--- ide/frames/compiler_codegen_options.pas 2011-12-24 17:43:38.000000000 +0000`\~~
30		-	~~`+++ /mnt/data/apps/lazarus/0.9.31/ide/frames/compiler_codegen_options.pas 2011-12-25 18:22:32.593788084+0000`\~~
31		-	~~`@@ -166,6 +166,8 @@`\~~
32		-	~~` Add('morphos');`\~~
33		-	~~` Add('embedded');`\~~
34		-	~~` Add('symbian');`\~~
35		-	~~`+ Add('java');`\~~
36		-	~~`+ Add('android');`\~~
37		-	~~` end;`\~~
38		-	~~` ItemIndex := 0;`\~~
39		-	~~` end;`\~~
40		-	~~`@@ -183,6 +185,7 @@`\~~
41		-	~~` Add('powerpc');`\~~
42		-	~~` Add('sparc');`\~~
43		-	~~` Add('x86_64');`\~~
44		-	~~`+ Add('jvm');`\~~
45		-	~~` end;`\~~
46		-	~~` ItemIndex := 0;`\~~
47		-	~~` end;`~~
	29	+	``` pascal
	30	+	--- ide/frames/compiler_codegen_options.pas 2011-12-24 17:43:38.000000000 +0000
	31	+	+++ /mnt/data/apps/lazarus/0.9.31/ide/frames/compiler_codegen_options.pas 2011-12-25 18:22:32.593788084+0000
	32	+	@@ -166,6 +166,8 @@
	33	+	Add('morphos');
	34	+	Add('embedded');
	35	+	Add('symbian');
	36	+	+ Add('java');
	37	+	+ Add('android');
	38	+	end;
	39	+	ItemIndex := 0;
	40	+	end;
	41	+	@@ -183,6 +185,7 @@
	42	+	Add('powerpc');
	43	+	Add('sparc');
	44	+	Add('x86_64');
	45	+	+ Add('jvm');
	46	+	end;
	47	+	ItemIndex := 0;
	48	+	end;
	49	+	```
48	50
49	51		#### Patching FPC
50	52
51	53		While every platform in Free Pascal has it's own compiler binary (e.g. ppc386, ppcarm, etc.) there is the binary fpc which selects the correct compiler by interpreting the -Pxxx argument. To enable support for the jvm platform the source code of the fpc binary needs to be adjusted. For this you can use any source for this binary that's younger than February 2010 (as this is where the last change was made). You can also simply download the source code file from FPC's trunk ([here](http://svn.freepascal.org/cgi-bin/viewvc.cgi/trunk/compiler/utils/fpc.pp?view=markup)) for this and compile that as there are no dependencies besides unit SysUtils.
52	54
53	55		Here is the patch:
54	56
55		-	~~`Index: compiler/utils/fpc.pp`\~~
56		-	~~`===================================================================`\~~
57		-	~~`--- compiler/utils/fpc.pp (Revision 19886)`\~~
58		-	~~`+++ compiler/utils/fpc.pp (Arbeitskopie)`\~~
59		-	~~`@@ -214,7 +214,9 @@`\~~
60		-	~~` cpusuffix:='ia64'`\~~
61		-	~~` else if processorstr='x86_64' then`\~~
62		-	~~` cpusuffix:='x64'`\~~
63		-	~~`- else`\~~
64		-	~~`+ else if processorstr='jvm' then`\~~
65		-	~~`+ cpusuffix:='jvm'`\~~
66		-	~~`+ else `\~~
67		-	~~` error('Illegal processor type "'+processorstr+'"');`\~~
68		-	~~` `\~~
69		-	~~` {$ifndef darwin}`~~
	57	+	``` pascal
	58	+	Index: compiler/utils/fpc.pp
	59	+	===================================================================
	60	+	--- compiler/utils/fpc.pp (Revision 19886)
	61	+	+++ compiler/utils/fpc.pp (Arbeitskopie)
	62	+	@@ -214,7 +214,9 @@
	63	+	cpusuffix:='ia64'
	64	+	else if processorstr='x86_64' then
	65	+	cpusuffix:='x64'
	66	+	- else
	67	+	+ else if processorstr='jvm' then
	68	+	+ cpusuffix:='jvm'
	69	+	+ else
	70	+	error('Illegal processor type "'+processorstr+'"');
	71	+
	72	+	{$ifndef darwin}
	73	+	```
70	74
71	75		After you compiled the fpc binary you can replace your old one with it and copy the ppcjvm to the directory where all other compilers are located. These are for the different platforms:
72	76
73	77		- Windows: %fpcdir%\bin\i386-win32\ (or x86_64-win64 if you have a native 64-Bit installation)
74	78		- Linux: \$fpcdir/lib/fpc/\$fpcversion/ (depending on your installation \$fpcdir could be /, /usr or some directory in your home directory)
75	79		- macOS: WRITE ME
76	80
77	81		Also you should copy the compiled units from your FPC JVM snapshot to the corresponding units directory of your installation:
78	82
79	83		- Windows: from %fpcjvm%\units\jvm-android to %fpcdir%\units\jvm-android
80	84		- Linux: from \$fpcjvm/units/jvm-android to \$fpcdir/lib/fpc/\$fpcversion/units/jvm-android
81	85		- macOS: WRITE ME
82	86
83	87		Also if you don't want to copy the jasmin.jar to the same directory as the ppcjvm, you should adjust your fpc.cfg compiler by adding the following lines:
84	88
85		-	~~`#IFDEF CPUJVM`\~~
86		-	~~`-FD{Directory of jasmin.jar}`\~~
87		-	~~`#ENDIF`~~
	89	+	```text
	90	+	#IFDEF CPUJVM
	91	+	-FD{Directory of jasmin.jar}
	92	+	#ENDIF
	93	+	```
88	94
89	95		#### Generate a Key Store
90	96
91	97		Only signed Android packages can be deployed on any Android device (including the emulator) without exception. The only difference to Windows Phone and iOS is that it is sufficient if you sign them yourself (even if you deploy them to the Android market). This is done by creating a keystore which is later utilized by the jarsigner tool to sign the package.
92	98
93	99		Using the following command you can create such a key store if you haven't one yet:
94	100
95	101		``` bash
96	102		keytool -genkey -v -keystore /path/to/YourKeyStore.keystore -alias YourAlias -keyalg RSA -validity 10000
97	103		```
98	104
99	105		You can freely chose the location and name of the keystore file as well as the alias name. But you need both of the to sign an Android package. The tool will then ask you some questions and for the passwords for keystore and alias (you can use the same password for both or different ones).
100	106
101	107		Note: You should also follow the guidelines written on the [Android developer sites](http://developer.android.com/guide/publishing/app-signing.html) so that your application might be approved for the Android market.
102	108
103	109		### Structure of an Android application
104	110
105	111		An Android applications consists of the source code of the applications, some resources like images and XML files which describe the layout of the GUI (similar to LFMs) and a manifest file which describes options like the minimum SDK version or which activity is the main one.
106	112
107	113		This leads to another difference to e.g. Lazarus applications: an Android applications consists of at least one so called Activity, which can be thought of as a combination of Lazarus' TForm and TApplication. Every activity that can be started must be defined in the manifest file (otherwise an exception occurs if one tries to start that activity). Activities are started using so called intents which tell the activity why they are started and are also used to send parameters to the activity. Thus the main project file of an Android is not a program file, but an unit which will contain at least one class that derives from android.app.Activity or one of its subclasses (like android.app.ListActivity). An activity then consists of a view which contain - depending on their class - one or more additional views which all together make up the GUI of an Android application. These views can either be instantiated at runtime by creating the view classes or by inflating a layout that is part of the resources. Handling events (e.g. reacting on the click of a button) is always done by specifying a class instance that implements the corresponding listener interface (Java does not support procedure/method variables).
108	114
109	115		### Building an Android application
110	116
111	117		#### Summary
112	118
113	119		For building an Android applications multiple tools are necessary. First the resources need to be converted to binaries and added to a "resource package". Also the IDs they have in this resource package need to be added to a resource class (usally called R). Then the source code needs to be compiled (in our case using the FPC JVM compiler). After that the generated .class files need to be converted to the Dalvik's DEX format and combined with the resource package and the manifest these build a unsigned package (extension APK). This package then needs to be signed (using jarsigner*) and can then be installed on the emulator or a device or (hopefully) be deployed to the Android market.
114	120
115	121		#### Used Directories
116	122
117	123		To simplyfy the given commandlines the following conventions are used:
118	124
119	125		- \$platform gives the platforms/android-VERSION/ directory of the Android SDK
120	126		- \$platformtools gives the platform-tools directory of the Android SDK
121	127		- \$tools gives the tools directory of the Android SDK
122	128
123	129		#### Directory layout
124	130
125	131		To avoid clutter in the project's directory the following directory layout is suggested:
126	132
127		-	~~`-\`\~~
128		-	~~` \|- bin (will contain the package files and the *.dex file)`\~~
129		-	~~` \| \|`\~~
130		-	~~` \| \- classes (contains the compiled *.class files and FPC's PPU files`\~~
131		-	~~` \|`\~~
132		-	~~` \|- gen (this will contain the generated R.java file for the resources)`\~~
133		-	~~` \|`\~~
134		-	~~` \|- res (here the resources will be located)`\~~
135		-	~~` \| \|`\~~
136		-	~~` \| \|- drawable(-hdpi/-ldpi/-mdpi) (directories containing icons, images, etc)`\~~
137		-	~~` \| \|`\~~
138		-	~~` \| \|- layout (layouts for the GUI)`\~~
139		-	~~` \| \|`\~~
140		-	~~` \| \|- menu (layouts for the menus (context menu, options menu))`\~~
141		-	~~` \| \|`\~~
142		-	~~` \| \- values (containing for example strings used by the application)`\~~
143		-	~~` \|`\~~
144		-	~~` \- src (the source code of your application)`~~
	133	+	```text
	134	+	-\
	135	+	\|- bin (will contain the package files and the *.dex file)
	136	+	\| \|
	137	+	\| \- classes (contains the compiled *.class files and FPC's PPU files
	138	+	\|
	139	+	\|- gen (this will contain the generated R.java file for the resources)
	140	+	\|
	141	+	\|- res (here the resources will be located)
	142	+	\| \|
	143	+	\| \|- drawable(-hdpi/-ldpi/-mdpi) (directories containing icons, images, etc)
	144	+	\| \|
	145	+	\| \|- layout (layouts for the GUI)
	146	+	\| \|
	147	+	\| \|- menu (layouts for the menus (context menu, options menu))
	148	+	\| \|
	149	+	\| \- values (containing for example strings used by the application)
	150	+	\|
	151	+	\- src (the source code of your application)
	152	+	```
145	153
146	154		#### The manifest file
147	155
148	156		A basic manifest file looks like the following:
149	157
150	158		``` xml
151	159		<?xml version="1.0" encoding="utf-8"?>
152	160		<manifest xmlns:android="http://schemas.android.com/apk/res/android"
153	161		package="org.myname.myapp"
154	162		android:versionCode="1"
155	163		android:versionName="1.0">
156	164		<uses-sdk
157	165		android:minSdkVersion="9"
158	166		android:targetSdkVersion="9" />
159	167		<application android:label="@string/app_name" android:icon="@drawable/icon">
160	168		<activity android:name="TMyAppActivity"
161	169		android:label="@string/app_name">
162	170		<intent-filter>
163	171		<action android:name="android.intent.action.MAIN" />
164	172		<category android:name="android.intent.category.LAUNCHER" />
165	173		</intent-filter>
166	174		</activity>
167	175		<activity android:name="TSomeOtherActivity" />
168	176		</application>
169	177		</manifest>
170	178		```
171	179
172	180		The attribute package gives the class path of your application. This will be used by the generation of the R.java and you should also use this at least for the \$namespace option in units containing activities. The attributes containing "@" are references to resources in the res directory. Hereby the drawable is replaced by drawable-mdpi, drawable-hdpi or drawable-ldpi depending of the screen size at runtime. The value @string/app_name refers to the string app_name in the res/values/strings.xml file. TMyAppActivity is the main activity which will be invoked when started by the launcher. TSomeOtherActivity is for example some second application window. Both need to derive from android.app.Activity or one of its subclasses. Having targetSdkVersion and minSdkVersion set will avoid that compatibilty modules are used if you have a newer SDK version installed as well.
173	181
174	182		#### The resource files
175	183
176	184		The exact contents of your resource directory will depend on your application, but some generic advices can be given:
177	185
178	186		The drawable directories can contain a icon.png in different sizes (ldpi: 36x36, mdpi: 48x48, hdpi: 72x72).
179	187
180	188		For the contents of the layouts in the menu and layout directories I advice you to read the [Android documentation](http://developer.android.com/guide/topics/ui/declaring-layout.html).
181	189
182	190		The values directory contains a strings.xml which looks like the following:
183	191
184	192		``` xml
185	193		<?xml version="1.0" encoding="utf-8"?>
186	194		<resources>
187	195		<string name="app_name">My App</string>
188	196		</resources>
189	197		```
190	198
191	199		#### Generate the resource package
192	200
193	201		To generate the resource package and the R.java you can use the following command:
194	202
195	203		``` bash
196	204		$platformtools/aapt p -f -M AndroidManifest.xml -F bin/myapp.ap_ -I $platform/android.jar -S res -m -J gen
197	205		```
198	206
199	207		This will take all resources from the directory given by -S, the manifest file given by -M and the android.jar given by -I to generate the resource package given by -F and the R.java of which the base directory is given by -J (the remaining class path is extracted from the manifest).
200	208
201	209		#### The resource identifiers
202	210
203	211		The generated R.java file (located in gen/org/myname/myapp according to above shown manifest file) will look like the following (supposing that there is a layout for a dialog in res/layouts, two layouts for menus in res/menu and two more strings in res/values/strings.xml):
204	212
205	213		``` java
206	214		/* AUTO-GENERATED FILE. DO NOT MODIFY.
207	215		*
208	216		* This class was automatically generated by the
209	217		* aapt tool from the resource data it found. It
210	218		* should not be modified by hand.
211	219		*/
212	220
213	221		package org.myname.myapp;
214	222
215	223		public final class R {
216	224		public static final class attr {
217	225		}
218	226		public static final class drawable {
219	227		public static final int icon=0x7f020000;
220	228		}
221	229		public static final class id {
222	230		public static final int dialog_name_cancel=0x7f060002;
223	231		public static final int dialog_name_name=0x7f060000;
224	232		public static final int dialog_name_ok=0x7f060001;
225	233		}
226	234		public static final class layout {
227	235		public static final int dialog_name=0x7f030000;
228	236		}
229	237		public static final class menu {
230	238		public static final int myapp_context=0x7f050000;
231	239		public static final int myapp_options=0x7f050001;
232	240		}
233	241		public static final class string {
234	242		public static final int app_name=0x7f040000;
235	243		public static final int dialog_name_cancel=0x7f040001;
236	244		public static final int dialog_name_ok=0x7f040002;
237	245		}
238	246		}
239	247		```
240	248
241	249		This class then needs to be converted to Pascal code in a unit I decided to call src/resources.pas (this needs to be done everytime you recreate the resources, because ID values might change then). The unit then looks like this:
242	250
243	251		``` pascal
244	252		unit Resources;
245	253
246	254		{$mode objfpc}{$H+}
247	255		{$modeswitch unicodestrings}
248	256		{$namespace org.myname.myapp}
249	257
250	258		interface
251	259
252	260		type
253	261		R = class sealed
254	262		public
255	263		type
256	264		attr = class sealed
257	265
258	266		end;
259	267
260	268		drawable = class sealed
261	269		public
262	270		const
263	271		icon = $7f020000;
264	272		end;
265	273
266	274		id = class sealed
267	275		public
268	276		const
269	277		dialog_name_cancel = $7f060002;
270	278		dialog_name_name = $7f060000;
271	279		dialog_name_ok = $7f060001;
272	280		end;
273	281
274	282		layout = class sealed
275	283		public
276	284		const
277	285		dialog_name = $7f030000;
278	286		end;
279	287
280	288		menu = class sealed
281	289		public
282	290		const
283	291		myapp_context = $7f050000;
284	292		myapp_options = $7f050001;
285	293		end;
286	294
287	295		strings = class sealed
288	296		public
289	297		const
290	298		app_name = $7f040000;
291	299		dialog_name_cancel = $7f040001;
292	300		dialog_name_ok = $7f040002;
293	301		end;
294	302		end;
295	303
296	304		implementation
297	305
298	306		end.
299	307		```
300	308
301	309		You could also use global constants, but this way it looks more like the usual Android development.
302	310
303	311		#### Compiling the source
304	312
305	313		If you've followed the advice above regarding adjusting FPC and Lazarus you should be able to simply compile the code using Lazarus and setting the target to jvm-android. The unit output directory should also be set to bin/classes.
306	314
307	315		If you did not follow the advice you can create a script or a makefile containg the following command (note: you can not simply change the compiler, because Lazarus then does not know the target "android"):
308	316
309	317		``` bash
310	318		/path/to/ppcjvm -n -Tandroid -Fu/path/to/android-rtl -FEbin/classes -FD/directory/of/jasmin-jar myapp.lpr
311	319		```
312	320
313	321		You can then add this script, makefile or also the command itself to Lazarus' pre or post build commands (Project =\> Project Settings =\> Compilation) and uncheck all checkboxes for the compilation command. For error locations you can also check the "FPC" checkbox next to "look for messages" for your command.
314	322
315	323		After the source is compiled you need to convert it to the format understood by Dalvik. For this you also need to copy all .class files provided in the units/jvm-android* directory and subdirectories to the bin/classes directory (it should be possible to put the RTL files into a JAR file as well, but this was not tested by me). Then you simply execute the following command:
316	324
317	325		``` bash
318	326		$platformtools/dx --dex --output=bin/classes.dex bin/classes
319	327		```
320	328
321	329		#### Generating the package
322	330
323	331		Now you need to generate first a unsigned package out of the resources and the dex file. This is done using the following command:
324	332
325	333		``` bash
326	334		$tools/apkbuilder bin/myapp-unsigned.apk -u -z bin/myapp.ap_ -f myapp/classes.dex
327	335		```
328	336
329	337		The file given with -z is the resource package generated earlier.
330	338
331	339		Note: This tools will print a message that it is deprecated (which is true), but for now it still works. Until it is removed a solution for this needs to be found (maybe by developing a custom application around the Java class which does the hard work and which is not deprecated).
332	340
333	341		After the unsigned package is created it needs to be signed so it can be loaded to the emulator or device. For this the following command suffices:
334	342
335	343		``` bash
336	344		jarsigner -keystore /path/to/YourKeyStore.keystore -signedjar bin/myapp.apk bin/myapp-unsigned.apk YourAlias
337	345		```
338	346
339	347		The values /path/to/YourKeyStore.keystore and YourAlias are the same which you created earlier. You are then prompted for the passwords of the two.
340	348
341	349		#### Deploying the package
342	350
343	351		Using the adb tool the package can be directly installed to a running emulator or connected device (for more infos on the latter see [here](http://developer.android.com/guide/developing/device.html)).
344	352
345	353		For the emulator use the following command:
346	354
347	355		``` bash
348	356		$tools/adb -e install -r bin/myapp.apk
349	357		```
350	358
351	359		For the device the following:
352	360
353	361		``` bash
354	362		$tools/adb -d install -r bin/myapp.apk
355	363		```
356	364
357	365		In both cases the -r tells adb to reinstall the application (thus application data like databases is kept).
358	366
359	367		You can uninstall an application (together with its user data) using the following command:
360	368
361	369		``` bash
362	370		$tools/adb -e uninstall org.myname.myapp
363	371		```
364	372
365	373		Use -d instead of -e if you want to do this on a connected device.
366	374
367	375		Hint: The uninstall command gives a good reason why you should use different namespaces for your application.
368	376
369	377		### Finding errors
370	378
371	379		During the development of an Android application you might often see a dialog that informs you that your application has crashed. You can then use the \$tools/adb tool with the "logcat" command which will cat the log of the device or emulator to your console (you need to use Ctrl+C to close it again). There you'll see the name of the Exception class, its message and a stacktrace. You can also use the tool \$tools/ddms which is a GUI application and represents the log to you in a colored way (depending on the severity of the log message). It also allows taking screenshots.
372	380
373	381		You can also write log messages to that log yourself by using the static methods of the class android.utils.Log.
374	382
375	383		Common errors:
376	384
377	385		- using a functionality that is not part of the running version: the current Android unit is generated for SDK version 14. As the compiler does not know what e.g. version 10 might have contained or not contained you are responsible yourself that you only use methods and classes that are available in the corresponding SDK version. Possible exceptions are "FieldNotFoundException" or "ClassDefNotFoundException"
378	386
379	387		---
380	388		From the Free Pascal wiki, page "FPC JVM Android Development", as it stood on 2020-08-03 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
381	389		Category: Android
382	390		Category: JVM

Back to history