Multiplatform Programming Guide: what changed

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

Old	New		Line
1	1		This is a tutorial on writing cross-platform applications with Lazarus and Free Pascal. It will cover the necessary precautions to aid in creating a cross-platform ready program that is ready to [[Deploying Your Application\|deploy]].
2	2
3	3		Most [[LCL]] applications work in a cross-platform way without any extra effort. This principle is called [[Write once compile anywhere\|„write once, compile anywhere“]].
4	4
5	5		## Introduction to Multiplatform (Cross-platform) Programming
6	6
7	7		### How many platforms do you need?
8	8
9	9		To answer this question, you should first determine who your potential users are and how your program will be used. This question depends on where you are deploying your application.
10	10
11	11		If you are developing generic desktop software in 2014, Microsoft Windows may be the most important platform. Note that macOS and/or Linux are gaining in popularity, and may be a significant target for your application.
12	12
13	13		The popularity of the various desktop operating systems differs by country, by the type of software used, and with the target audience; there's no general rule. For example, macOS is quite popular in North America and western Europe, while in South America macOS is mostly restricted to video and sound work.
14	14
15	15		On many contract projects, only one platform is relevant. Free Pascal and Lazarus are quite capable of writing software targeted at a specific platform. You can, for example, access the full Windows API to write a well integrated Windows program.
16	16
17	17		If you're developing software that will run on a web server, a Unix platform in one of its various flavors is commonly used. In this case, perhaps only Linux, Solaris, *BSD and other Unixes make sense as your target platforms, although you may want to add support for Windows for completeness.
18	18
19	19		Once you've addressed any cross-platform issues in your design, you can largely ignore the other platforms, much as you would when developing for a single platform. However, at some point you'll need to test deploying and running your program on the other platforms. For that, it will be helpful to have unrestricted access to machines running the target operating systems. If you don't want multiple physical computers, investigate dual-booting or Virtual Machine (VM) solutions like:
20	20
21	21		- [VMware Fusion for Mac](https://www.vmware.com/products/fusion.html) - Host system must be running Intel macOS (Commercial/Free for non-commercial use).
22	22		- [VMware Workstation Player](https://www.vmware.com/products/workstation-player.html) - Host system running Windows 64 bit or Linux 64 bit (Commercial/Free for personal use).
23	23		- [VMware Workstation Pro](https://www.vmware.com/products/workstation-pro.html) - Host system running Windows 64 bit or Linux 64 bit (Commercial/Free trial).
24	24		- [Parallels Desktop for Mac](https://www.parallels.com/) - Host system must be running Intel macOS (Commercial/Free trial). Note: There is a [Technical Preview](https://b2b.parallels.com/Apple-Silicon) that will run on Apple M1 ARM64 processors which will run the ARM versions of Linux and [Windows 10 Insider Preview](https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewARM64).
25	25		- [VirtualBox](https://www.virtualbox.org/) - Host system can be running Intel macOS, Windows, Linux or Solaris (Open Source).
26	26
27	27		Some, eg Parallels on the Mac, make it trivial to install a desktop Linux operating system with a single click.
28	28
29	29		See also: [[Small Virtual Machines]] and [[Qemu and other emulators]].
30	30
31	31		## Cross-platform Programming
32	32
33	33		### Working with files and folders
34	34
35	35		When working with files and folders, it is important to use non-platform specific path delimiters and [[End of Line\|line ending]] sequences. Here is a list of declared [[Constant\|constants]] in Lazarus to be used when working with files and folders.
36	36
37	37		- PathSep, PathSeparator: path separator when adding many paths together (';', ...)
38	38		- PathDelim, DirectorySeparator: directory separator for each platform ('/', '\\', ...)
39	39		- LineEnding: proper line ending character sequence (#13#10 - CRLF, \#10 - [[Line feed\|LF]], ...)
40	40
41	41		Another important thing to be noted is the case sensitiveness of the file system. On Windows filenames are usually not case sensitive, while they usually are case sensitive on Unix platforms (eg Linux, FreeBSD) but not macOS despite its Unix heritage. But note that if an EXT2, EXT3, etc file system is mounted on Windows, it would be case sensitive. Likewise, a FAT file system mounted on Linux should not be case sensitive.
42	42
43	43		Special attention should be paid to NTFS which is not case sensitive when used in Windows, but is case sensitive when mounted by POSIX OSes. This could cause various problems, including loss of files if files with the same filenames in different cases exist on an NTFS partition mounted in Windows. Using custom functions for checking and preventing creation of several files with the same names on NTFS should be considered by developers.
44	44
45	45		macOS uses case insensitive filenames by default. This can be the cause of annoying bugs, so any portable application should use filenames consistently.
46	46
47	47		The RTL file functions use the system encoding for file names. Under Windows this is one of the Windows code pages, while Linux, BSD and macOS usually use UTF-8. The unit FileUtil of the LCL provides file functions which takes UTF-8 strings like the rest of the LCL.
48	48
49	49		``` pascal
50	50		// AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, macOS
51	51		// but normally these OS use UTF-8 as system encoding so the widestringmanager
52	52		// is not needed.
53	53		function NeedRTLAnsi: boolean;// true if system encoding is not UTF-8
54	54		procedure SetNeedRTLAnsi(NewValue: boolean);
55	55		function UTF8ToSys(const s: string): string; // as UTF8ToAnsi but more independent of widestringmanager
56	56		function SysToUTF8(const s: string): string; // as AnsiToUTF8 but more independent of widestringmanager
57	57		function UTF8ToConsole(const s: string): string; // converts UTF8 string to console encoding (used by Write, WriteLn)
58	58
59	59		// file operations
60	60		function FileExistsUTF8(const Filename: string): boolean;
61	61		function FileAgeUTF8(const FileName: string): Longint;
62	62		function DirectoryExistsUTF8(const Directory: string): Boolean;
63	63		function ExpandFileNameUTF8(const FileName: string): string;
64	64		function ExpandUNCFileNameUTF8(const FileName: string): string;
65	65		function ExtractShortPathNameUTF8(Const FileName : String) : String;
66	66		function FindFirstUTF8(const Path: string; Attr: Longint; out Rslt: TSearchRec): Longint;
67	67		function FindNextUTF8(var Rslt: TSearchRec): Longint;
68	68		procedure FindCloseUTF8(var F: TSearchrec);
69	69		function FileSetDateUTF8(const FileName: String; Age: Longint): Longint;
70	70		function FileGetAttrUTF8(const FileName: String): Longint;
71	71		function FileSetAttrUTF8(const Filename: String; Attr: longint): Longint;
72	72		function DeleteFileUTF8(const FileName: String): Boolean;
73	73		function RenameFileUTF8(const OldName, NewName: String): Boolean;
74	74		function FileSearchUTF8(const Name, DirList : String): String;
75	75		function FileIsReadOnlyUTF8(const FileName: String): Boolean;
76	76		function GetCurrentDirUTF8: String;
77	77		function SetCurrentDirUTF8(const NewDir: String): Boolean;
78	78		function CreateDirUTF8(const NewDir: String): Boolean;
79	79		function RemoveDirUTF8(const Dir: String): Boolean;
80	80		function ForceDirectoriesUTF8(const Dir: string): Boolean;
81	81
82	82		// environment
83	83		function ParamStrUTF8(Param: Integer): string;
84	84		function GetEnvironmentStringUTF8(Index: Integer): string;
85	85		function GetEnvironmentVariableUTF8(const EnvVar: string): String;
86	86		function GetAppConfigDirUTF8(Global: Boolean): string;
87	87
88	88		// other
89	89		function SysErrorMessageUTF8(ErrorCode: Integer): String;
90	90		```
91	91
92	92		### Empty file names and double path delimiters
93	93
94	94		There are differences in file/directory name handling in Windows versus Linux, Unix and Unix like systems.
95	95
96	96		- Windows allows empty file names. That's why FileExistsUTF8('..\\') checks under Windows in the parent directory for a file without name.
97	97		- On Linux/Unix/Unix-like systems, an empty file is mapped to the directory and directories are treated as files. This means that FileExistsUTF8('../') under Unix checks for the existence of the parent directory, which normally results true.
98	98
99	99		Double path delimiters in file names are also treated differently:
100	100
101	101		- Windows: 'C:\\' is not the same as 'C:\\\\'
102	102		- Unix like OS: the path '/usr//' is the same as '/usr/'. If '/usr' is a directory then even all three are the same.
103	103
104	104		This is important when concatenating file names. For example:
105	105
106	106		``` pascal
107	107		FullFilename:=FilePath+PathDelim+ShortFilename; // can result in two PathDelims which gives different results under Windows and Linux
108	108		FullFilename:=AppendPathDelim(FilePath) + ShortFilename; // creates only one PathDelim
109	109		FullFilename:=TrimFilename(FilePath+PathDelim+ShortFilename); // creates only one PathDelim and do some more clean up
110	110		```
111	111
112	112		The function TrimFilename replaces double path delimiters with single ones and shorten '..' paths. For example /usr//lib/../src is trimmed to /usr/src.
113	113
114	114		If you want to know if a directory exists use DirectoryExistsUTF8.
115	115
116	116		Another common task is to check if the path part of a file name exists. You can get the path with ExtractFilePath, but this will contain the path delimiter.
117	117
118	118		- Under Unix like system you can simply use FileExistsUTF8 on the path. For example FileExistsUTF8('/home/user/') will return true if the directory /home/user exists.
119	119		- Under Windows you must use the DirectoryExistsUTF8 function, but before that you must delete the path delimiter, for example with the ChompPathDelim function.
120	120
121	121		Under Unix like systems the root directory is '/' and using the ChompPathDelim function will create an empty string. The function DirPathExists works like the DirectoryExistsUTF8 function, but trims the given path.
122	122
123	123		Note that Unix/Linux uses the '~' (tilde) symbol to stand for the home directory, typically '/home/jim/' for a user called jim. So '~/myapp/myfile' and '/home/jim/myapp/myfile' are identical on the command line and in scripts. However, the tilde is not automatically expanded by Lazarus. It is necessary to use ExpandFileNameUTF8('~/myapp/myfile') to get the full path.
124	124
125	125		### Text encoding
126	126
127	127		Text files are often encoded in the current system encoding. Under Windows this is usually one of the windows code pages, while Linux, BSD, and macOS usually use UTF-8. There is no 100% rule to find out which encoding a text file uses. The LCL unit lconvencoding has a function to guess the encoding:
128	128
129	129		``` pascal
130	130		function GuessEncoding(const s: string): string;
131	131		function GetDefaultTextEncoding: string;
132	132		```
133	133
134	134		And it contains functions to convert from one encoding to another:
135	135
136	136		``` pascal
137	137		function ConvertEncoding(const s, FromEncoding, ToEncoding: string): string;
138	138
139	139		function UTF8BOMToUTF8(const s: string): string; // UTF8 with BOM
140	140		function ISO_8859_1ToUTF8(const s: string): string; // central europe
141	141		function CP1250ToUTF8(const s: string): string; // central europe
142	142		function CP1251ToUTF8(const s: string): string; // cyrillic
143	143		function CP1252ToUTF8(const s: string): string; // latin 1
144	144		...
145	145		function UTF8ToUTF8BOM(const s: string): string; // UTF8 with BOM
146	146		function UTF8ToISO_8859_1(const s: string): string; // central europe
147	147		function UTF8ToCP1250(const s: string): string; // central europe
148	148		function UTF8ToCP1251(const s: string): string; // cyrillic
149	149		function UTF8ToCP1252(const s: string): string; // latin 1
150	150		...
151	151		```
152	152
153	153		For example to load a text file and convert it to UTF-8 you can use:
154	154
155	155		``` pascal
156	156		var
157	157		sl: TStringList;
158	158		OriginalText: String;
159	159		TextAsUTF8: String;
160	160		begin
161	161		sl:=TStringList.Create;
162	162		try
163	163		sl.LoadFromFile('sometext.txt'); // beware: this changes line endings to system line endings
164	164		OriginalText:=sl.Text;
165	165		TextAsUTF8:=ConvertEncoding(OriginalText,GuessEncoding(OriginalText),EncodingUTF8);
166	166		...
167	167		finally
168	168		sl.Free;
169	169		end;
170	170		end;
171	171		```
172	172
173	173		And to save a text file in the system encoding you can use:
174	174
175	175		``` pascal
176	176		sl.Text:=ConvertEncoding(TextAsUTF8,EncodingUTF8,GetDefaultTextEncoding);
177	177		sl.SaveToFile('sometext.txt');
178	178		```
179	179
180	180		### Configuration files
181	181
182	182		You can use the [[doc:rtl/sysutils/getappconfigdir.html\|GetAppConfigDir]] function from SysUtils unit to get a suitable place to store configuration files on different system. The function has one parameter, called Global. If it is True then the directory returned is a global directory, i.e. valid for all users on the system. If the parameter Global is false, then the directory is specific for the user who is executing the program. On systems that do not support multi-user environments, these two directories may be the same.
183	183
184	184		There is also the [[doc:rtl/sysutils/getappconfigfile.html\|GetAppConfigFile]] which will return an appropriate name for an application configuration file. You can use it like this:
185	185
186	186		``` pascal
187	187		ConfigFilePath := GetAppConfigFile(False);
188	188		```
189	189
190	190		Below are examples of the output of default path functions on different systems:
191	191
192	192		``` pascal
193	193		program project1;
194	194
195	195		{$mode objfpc}{$H+}
196	196
197	197		uses
198	198		SysUtils;
199	199
200	200		begin
201	201		WriteLn(GetAppConfigDir(True));
202	202		WriteLn(GetAppConfigDir(False));
203	203		WriteLn(GetAppConfigFile(True));
204	204		WriteLn(GetAppConfigFile(False));
205	205		end.
206	206		```
207	207
208	208		You can notice that global configuration files are stored on the /etc directory and local configurations are stored in a hidden directory in the user's home directory. Directories whose name begin with a dot (.) are hidden on UNIX and UNIX-like operating systems. You can create a directory in the location returned by GetAppConfigDir and then store configuration files there.
209	209
210	210		> Note: Normal users are not allowed to write to the /etc directory. Only users with administration rights can do this.
211	211
212	212		Notice that before FPC 2.2.4 the function was using the directory where the application was to store global configurations on Windows.
213	213
214	214		The output on Windows 98 with FPC 2.2.0:
215	215
216	216		C:\Program Files\PROJECT1
217	217		C:\Windows\Local Settings\Application Data\PROJECT1
218	218		C:\Program Files\PROJECT1\PROJECT1.cfg
219	219		C:\Windows\Local Settings\Application Data\PROJECT1\PROJECT1.cfg
220	220
221	221		The output on Windows XP with FPC 3.0.4:
222	222
223	223		C:\Documents and Settings\All Users\Application Data\project1\
224	224		C:\Documents and Settings\user\Local Settings\Application Data\project1\
225	225		C:\Documents and Settings\All Users\Application Data\project1\project1.cfg
226	226		C:\Documents and Settings\user\Local Settings\Application Data\project1\project1.cfg
227	227
228	228		The output on Windows 7 and Windows 10 and FPC 3.0.4:
229	229
230	230		C:\ProgramData\project1\
231	231		C:\Users\user\AppData\Local\project1\
232	232		C:\ProgramData\project1\project1.cfg
233	233		C:\Users\user\AppData\Local\project1\project1.cfg
234	234
235	235		The output on macOS 10.14.5 with FPC 3.0.4 (violates Apple Guidelines - see below for the correct macOS file locations):
236	236
237	237		/etc/project1/
238	238		/Users/user/.config/project1/
239	239		/etc/project1.cfg
240	240		/Users/user/.config/project1.cfg
241	241
242	242		The output on FreeBSD 12.1 with FPC 3.0.4:
243	243
244	244		/etc/project1/
245	245		/home/user/.config/project1/
246	246		/etc/project1.cfg
247	247		/home/user/.config/project1.cfg
248	248
249	249		The observant will have noticed a difference between the Windows and non-Windows operating systems output - the Windows output for the `WriteLn(GetAppConfigFile(True));` global configuration code includes a subdirectory but the other operating systems do not. To obtain the same results for non-Windows operating systems, you need to include an additional [[Boolean]] parameter: `WriteLn(GetAppConfigFile(True,True));`.
250	250
251	251		> Note: The use of UPX interferes with the use of the GetAppConfigDir and GetAppConfigFile functions.
252	252
253	253		#### macOS
254	254
255	255		In most cases configuration files are preference files, which in macOS should be XML files ending with the ".plist" extension and be stored in /Library/Preferences or ~/Library/Preferences with filenames taken from the "Bundle identifier" field in the [[macOS property list files\|Info.plist]] file of the [[Application Bundle\|application bundle]]. Using .config files in the user directory is a violation of the Apple programming guidelines. See the [[Locating macOS app support, preferences folders]] article for code which handles this in an Apple-compliant manner.
256	256
257	257		### Data and resource files
258	258
259	259		A very common question is where to store data files an application might need, such as Images, Music, XML files, database files, help files, etc. Unfortunately there is no cross-platform function to get the best location to look for data files. The solution is to implement differently on each platform using IFDEFs.
260	260
261	261		#### Windows
262	262
263	263		On Windows, application data that the program modifies should not be put in the application's directory (e.g. C:\Program Files\\) but in a specific location (see e.g. ["Classify Application Data"](http://support.microsoft.com/kb/310294) (link is broken). Windows Vista and newer actively enforce this (users only have write access to these directories when using elevation or disabling UAC) but uses a folder redirection mechanism to accommodate older, wrongly-programmed applications. Just reading, not writing, data from application directories would still work but is not recommended.
264	264
265	265		In short: use such folder:
266	266
267	267		``` pascal
268	268		OpDirLocal:= GetEnvironmentVariableUTF8('appdata')+'\MyAppName';
269	269		```
270	270
271	271		See [[Windows Programming Tips\|Windows Programming Tips - Getting Special Folders]]
272	272
273	273		#### Unix/Linux
274	274
275	275		On most Unixes (like Linux, FreeBSD, OpenBSD, Solaris but not macOS), application data files are located in a fixed location, which can be something like: /usr/local/share/app_name or /opt/app_name.
276	276
277	277		Application data that needs to be written to by the application often gets stored in places like /usr/local/var/app_name, /usr/local/share/app_name or /usr/local/app_name, with appropriate permissions set.
278	278
279	279		Help files (aka man pages) should be stored in /usr/local/man/man\[appropriate manual section number\]/app_name\>, with appropriate permissions set. Note that some FreeBSD and Linux manual sections differ or do not exist.
280	280
281	281		User-specific read/write config/data will normally be stored somewhere under the user's home directory (eg in ~/.config/\<programname\>). Refer to [[Multiplatform Programming Guide\|Configuration Files]] above.
282	282
283	283		#### macOS
284	284
285	285		macOS is an exception among UNIX operating systems. An application is published in a bundle (a directory with ".app" extension) which is treated by the Finder file manager as a file (in a Terminal you can "cd path/myapp.app" or in Finder right click on the app and choose "Show Package Contents"). Your resource files should be located inside the bundle. If the bundle is "path/MyApp.app", then the:
286	286
287	287		- executable file is "path/MyApp.app/Contents/MacOS/myapp"
288	288		- resources directory is "path/MyApp.app/Contents/Resources"
289	289
290	290		Application supplied data and resource files should generally be stored in the Resources directory of the application bundle. For code which handles this in an Apple compliant manner, see the [[Locating the macOS application resources directory]] article.
291	291
292	292		Application data files generated by the user should be stored in the user's '~/Library/Application Support' directory. For code which handles this in an Apple compliant manner, see the [[Locating macOS app support, preferences folders]] article.
293	293
294	294		> Warning: Never use `paramStr(0)`, or any function which uses it, on any UNIX platform to determine the location of the executable, as this is a DOS-Windows-OS/2 convention and has several conceptual problems, which cannot be solved using emulation on other platforms. The only thing `paramStr(0)` is guaranteed to return on UNIX platforms is the name with which the program was started. The directory in which it is located and the name of the actual binary (in case it was started using a symbolic link) are not guaranteed to be available via `paramStr(0)`. For macOS, you can reliably locate the application bundle directory using the native code in [[Locating the macOS application resources directory\|this article]].
295	295
296	296		### 32/64 bit
297	297
298	298		#### Detecting bitness at runtime
299	299
300	300		While you can control whether you compile for 32 or 64 bit with compiler defines, sometimes you want to know what bitness the operating system runs. For example, if you are running a 32 bit Lazarus program on 64 bit Windows, you might want to run an external program in a 32 bit program files directory, or you might want to give different information to users: I need this in my LazUpdater Lazarus installer to offer the user a choice of 32 and 64 bit compilers. Code: [[Detect Windows x32-x64 example]].
301	301
302	302		#### Detecting bitness of external library before loading it
303	303
304	304		When you want to load functions from dynamic library into your program, it has to have same bitness as your application. On 64 bit Windows, your application might be 32-bit or 64-bit, and there can be 32-bit and 64-bit libraries on your system. So you might want to check whether dll's bitness is same as your application's bitness before loading the dll dynamically. Here is a function which tests dll's bitness ([contributed in forum by GetMem](http://forum.lazarus.freepascal.org/index.php/topic,36834.msg245859.html#msg245859)):
305	305
306	306		``` pascal
307	307
308	308		uses {..., } JwaWindows;
309	309
310	310		function GetPEType(const APath: WideString): Byte;
311	311		const
312	312		PE_UNKNOWN = 0; //if the file is not a valid dll, 0 is returned
313	313		// PE_16BIT = 1; // not supported by this function
314	314		PE_32BIT = 2;
315	315		PE_64BIT = 3;
316	316		var
317	317		hFile, hFileMap: THandle;
318	318		PMapView: Pointer;
319	319		PIDH: PImageDosHeader;
320	320		PINTH: PImageNtHeaders;
321	321		Base: Pointer;
322	322		begin
323	323		Result := PE_UNKNOWN;
324	324
325	325		hFile := CreateFileW(PWideChar(APath), GENERIC_READ, FILE_SHARE_READ, nil, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, 0);
326	326		if hFile = INVALID_HANDLE_VALUE then
327	327		begin
328	328		CloseHandle(hFile);
329	329		Exit;
330	330		end;
331	331
332	332		hFileMap := CreateFileMapping(hFile, nil, PAGE_READONLY, 0, 0, nil);
333	333		if hFileMap = 0 then
334	334		begin
335	335		CloseHandle(hFile);
336	336		CloseHandle(hFileMap);
337	337		Exit;
338	338		end;
339	339
340	340		PMapView := MapViewOfFile(hFileMap, FILE_MAP_READ, 0, 0, 0);
341	341		if PMapView = nil then
342	342		begin
343	343		CloseHandle(hFile);
344	344		CloseHandle(hFileMap);
345	345		Exit;
346	346		end;
347	347
348	348		PIDH := PImageDosHeader(PMapView);
349	349		if PIDH^.e_magic <> IMAGE_DOS_SIGNATURE then
350	350		begin
351	351		CloseHandle(hFile);
352	352		CloseHandle(hFileMap);
353	353		UnmapViewOfFile(PMapView);
354	354		Exit;
355	355		end;
356	356
357	357		Base := PIDH;
358	358		PINTH := PIMAGENTHEADERS(Base + LongWord(PIDH^.e_lfanew));
359	359		if PINTH^.Signature = IMAGE_NT_SIGNATURE then
360	360		begin
361	361		case PINTH^.OptionalHeader.Magic of
362	362		$10b: Result := PE_32BIT;
363	363		$20b: Result := PE_64BIT
364	364		end;
365	365		end;
366	366
367	367		CloseHandle(hFile);
368	368		CloseHandle(hFileMap);
369	369		UnmapViewOfFile(PMapView);
370	370		end;
371	371
372	372		//Now, if you compile your application for 32-bit and 64-bit windows, you can check if dll's bitness is same as your application's:
373	373		function IsCorrectBitness(const APath: WideString): Boolean;
374	374		begin
375	375		{$ifdef CPU32}
376	376		Result := GetPEType(APath) = 2; //the application is compiled as 32-bit, we ask if GetPeType returns 2
377	377		{$endif}
378	378		{$ifdef CPU64}
379	379		Result := GetPEType(APath) = 3; //the application is compiled as 64-bit, we ask if GetPeType returns 3
380	380		{$endif}
381	381		end;
382	382		```
383	383
384	384		#### Pointer / Integer Typecasts
385	385
386	386		Pointers under 64bit need 8 bytes instead of 4 on 32bit. The 'Integer' type remains 32bit on all platforms for compatibility. This means you can not typecast pointers into integers and back.
387	387
388	388		FPC defines two types for this: PtrInt and PtrUInt. PtrInt is a 32bit signed integer on 32 bit platforms and a 64bit signed integer on 64bit platforms. The same for PtrUInt, but unsigned integer instead.
389	389
390	390		Use for code that should work with Delphi and FPC:
391	391
392	392		``` pascal
393	393		{$IFNDEF FPC}
394	394		type
395	395		PtrInt = integer;
396	396		PtrUInt = cardinal;
397	397		{$ENDIF}
398	398		```
399	399
400	400		Replace all integer(SomePointerOrObject) with PtrInt(SomePointerOrObject).
401	401
402	402		### Endianess
403	403
404	404		Intel platforms are little endian, that means the least significant byte comes first. For example the two bytes of a word \$1234 is stored as \$34 \$12 on little endian systems. On big endian systems like the powerpc the two bytes of a word \$1234 are stored as \$12 \$34. The difference is important when reading files created on other systems.
405	405
406	406		Use for code that should work on both:
407	407
408	408		``` pascal
409	409		{$IFDEF ENDIAN_BIG}
410	410		...
411	411		{$ELSE}
412	412		...
413	413		{$ENDIF}
414	414		```
415	415
416	416		The opposite is ENDIAN_LITTLE.
417	417
418	418		The system unit provides plenty of endian converting functions, like SwapEndian, BEtoN (big endian to current endian), LEtoN (little endian to current endian), NtoBE (current endian to big endian) and NtoLE (current endian to little endian).
419	419
420	420		#### Libc and other special units
421	421
422	422		Avoid legacy units like "oldlinux" and "libc" that are not supported outside of linux/i386.
423	423
424	424		#### Assembler
425	425
426	426		Avoid [[Assembly language\|assembler]].
427	427
428	428		#### Compiler defines
429	429
430	430		``` pascal
431	431		{$ifdef CPU32}
432	432		...write here code for 32 bit processors
433	433		{$ENDIF}
434	434		{$ifdef CPU64}
435	435		...write here code for 64 bit processors
436	436		{$ENDIF}
437	437		```
438	438
439	439		### Projects, packages and search paths
440	440
441	441		Lazarus projects and packages are designed for multi platforms. Normally you can simply copy the project and the required packages to another machine and compile them there. You don't need to create one project per platform.
442	442
443	443		Some advice to achieve this
444	444
445	445		The compiler creates for every unit a ppu with the same name. This ppu can be used by other projects and packages. The unit source files (e.g. unit1.pas) should not be shared. Simply give the compiler a unit output directory where to create the ppu files. The IDE does that by default, so nothing to do for you here.
446	446
447	447		Every unit file must be part of one project or package. If a unit file is only used by a single project, add it to this project. Otherwise add it to a package. If you have not yet created a package for your shared units, see here: [[Lazarus Packages\|Creating a package for your common units]]
448	448
449	449		Every project and every package should have disjunct directories - they should not share directories. Otherwise you must be an expert in the art of compiler search paths. If you are not an expert or if others who may use your project/package are not experts: do not share directories between projects/packages.
450	450
451	451		#### Platform specific units
452	452
453	453		For example the unit wintricks.pas should only be used under Windows. In the uses section use:
454	454
455	455		``` pascal
456	456		uses
457	457		Classes, SysUtils
458	458		{$IFDEF Windows}
459	459		,WinTricks
460	460		{$ENDIF}
461	461		;
462	462		```
463	463
464	464		If the unit is part of a package, you must also select the unit in the package editor of the package and disable the Use unit checkbox.
465	465
466	466		See also [[Lazarus Packages\|Platform specific units]]
467	467
468	468		#### Platform specific search paths
469	469
470	470		When you target several platforms and access the operating system directly, then you will quickly get tired of endless IFDEF constructions. One solution that is used often in the FPC and Lazarus sources is to use include files. Create one sub directory per target. For example win32, linux, bsd, darwin. Put into each directory an include file with the same name. Then use a macro in the include path. The unit can use a normal include directive.
471	471
472	472		An example for one include file for each LCL widget set:
473	473
474	474		Create one file for each widget set you want to support:
475	475
476		-	~~`win32/example.inc`\~~
477		-	~~`gtk/example.inc`\~~
478		-	~~`gtk2/example.inc`\~~
479		-	~~`carbon/example.inc`~~
	476	+	```text
	477	+	win32/example.inc
	478	+	gtk/example.inc
	479	+	gtk2/example.inc
	480	+	carbon/example.inc
	481	+	```
480	482
481	483		You do not need to add the files to the package or project. Add the include search path \$(LCLWidgetType) to the compiler options of your package or project.
482	484
483	485		In your unit use the directive: {\$I example.inc}
484	486
485	487		Here are some useful macros and common values:
486	488
487	489		- LCLWidgetType: win32, gtk, gtk2, qt, carbon, fpgui, nogui
488	490		- TargetOS: linux, win32, win64, wince, freebsd, netbsd, openbsd, darwin (many more)
489	491		- TargetCPU: i386, x86_64, arm, powerpc, sparc
490	492		- SrcOS: win, unix
491	493
492	494		You can use the \$Env() macro to use environment variables.
493	495
494	496		And of course you can use combinations. For example the LCL uses:
495	497
496		-	~~`$(LazarusDir)/lcl/units/$(TargetCPU)-$(TargetOS);$(LazarusDir)/lcl/units/$(TargetCPU)-$(TargetOS)/$(LCLWidgetType)`~~
	498	+	```text
	499	+	$(LazarusDir)/lcl/units/$(TargetCPU)-$(TargetOS);$(LazarusDir)/lcl/units/$(TargetCPU)-$(TargetOS)/$(LCLWidgetType)
	500	+	```
497	501
498	502		See here the complete list of macros: [[IDE Macros in paths and filenames]]
499	503
500	504		#### Machine / User specific search paths
501	505
502	506		For example you have two windows machines stan and oliver. On stan your units are in C:\units and on oliver your units are in D:\path. The units belong to the package SharedStuff which is C:\units\sharedstuff.lpk on stan and D:\path\sharedstuff.lpk on oliver. Once you opened the lpk in the IDE or by lazbuild, the path is automatically stored in its configuration files (packagefiles.xml). When compiling a project that requires the package SharedStuff, the IDE and lazbuild knows where it is. So no configuration is needed.
503	507
504	508		If you have want to deploy a package over many machine or for all users of a machine (e.g. a pool for students), then you can add a lpl file in the lazarus source directory. See packager/globallinks for examples.
505	509
506	510		### Locale differences
507	511
508	512		Some functions from Free Pascal, like StrToFloat behave differently depending on the current [[locale]]. For example, in the USA the [[DecimalSeparator\|decimal separator]] is usually ".", but in many European and South American countries it is ",". This can be a problem as sometimes it is desired to have these functions behave in a fixed way, independently from the locale. An example is a file format with decimal points that always needs to be interpreted the same way.
509	513
510	514		The next sections explain how to do that.
511	515
512	516		#### macOS
513	517
514	518		Refer to the [[Locale settings for macOS]] article for details of setting the locale on macOS.
515	519
516	520		#### StrToFloat
517	521
518	522		A new set of format settings which set a fixed decimal separator can be created with the following code:
519	523
520	524		``` pascal
521	525		// in your .lpr project file
522	526		uses
523	527		...
524	528		{$IFDEF UNIX}
525	529		clocale
526	530		{ required on Linux/Unix for formatsettings support. Should be one of the first (probably after cthreads?}
527	531		{$ENDIF}
528	532		```
529	533
530	534		and:
531	535
532	536		``` pascal
533	537		// in your code:
534	538		var
535	539		FPointSeparator, FCommaSeparator: TFormatSettings;
536	540		begin
537	541		// Format settings to convert a string to a float
538	542		FPointSeparator := DefaultFormatSettings;
539	543		FPointSeparator.DecimalSeparator := '.';
540	544		FPointSeparator.ThousandSeparator := '#';// disable the thousand separator
541	545		FCommaSeparator := DefaultFormatSettings;
542	546		FCommaSeparator.DecimalSeparator := ',';
543	547		FCommaSeparator.ThousandSeparator := '#';// disable the thousand separator
544	548		```
545	549
546	550		Later on you can use this format settings when calling StrToFloat, like this:
547	551
548	552		``` pascal
549	553		// This function works like StrToFloat, but simply tries two possible decimal separator
550	554		// This will avoid an exception when the string format doesn't match the locale
551	555		function AnSemantico.StringToFloat(AStr: string): Double;
552	556		begin
553	557		if Pos('.', AStr) > 0 then Result := StrToFloat(AStr, FPointSeparator)
554	558		else Result := StrToFloat(AStr, FCommaSeparator);
555	559		end;
556	560		```
557	561
558	562		### Gtk2 and masking FPU exceptions
559	563
560	564		Gtk2 library changes the default value of FPU (floating point unit) exception mask. The consequence of this is that some floating point exceptions do not get raised if Gtk2 library is used by the application. That means that, if for example you develop a LCL application on Windows with win32/64 widgetset (which is Windows default) and plan to compile for Linux (where Gtk2 is default widgetset), you should keep this incompatibilities in mind.
561	565
562	566		After [this forum topic](http://www.lazarus.freepascal.org/index.php/topic,13460.0.html) and answers on [this bug report](https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/19674) it became clear that nothing can be done about this, so we must know what actually these differences are.
563	567
564	568		Therefore, let's do a test:
565	569
566	570		``` pascal
567	571		uses
568	572		..., math,...
569	573
570	574		{...}
571	575
572	576		var
573	577		FPUException: TFPUException;
574	578		FPUExceptionMask: TFPUExceptionMask;
575	579		begin
576	580		FPUExceptionMask := GetExceptionMask;
577	581		for FPUException := Low(TFPUException) to High(TFPUException) do begin
578	582		write(FPUException, ' - ');
579	583		if not (FPUException in FPUExceptionMask) then
580	584		write('not ');
581	585
582	586		writeln('masked!');
583	587		end;
584	588		readln;
585	589		end.
586	590		```
587	591
588	592		Our simple program will get what FPC default is:
589	593
590	594		exInvalidOp - not masked!
591	595		exDenormalized - masked!
592	596		exZeroDivide - not masked!
593	597		exOverflow - not masked!
594	598		exUnderflow - masked!
595	599		exPrecision - masked!
596	600
597	601		However, with Gtk2, only exOverflow is not masked.
598	602
599	603		The consequence is that EInvalidOp and EZeroDivide exceptions do not get raised if the application links to Gtk2 library! Normally, dividing non-zero value by zero raises EZeroDivide exception and dividing zero by zero raises EInvalidOp. For example the code like this:
600	604
601	605		``` pascal
602	606		var
603	607		X, A, B: Double;
604	608		// ...
605	609
606	610		try
607	611		X := A / B;
608	612		// code block 1
609	613		except
610	614		// code block 2
611	615		end;
612	616		// ...
613	617		```
614	618
615	619		will take different direction when compiled in application with Gtk2 widgetset. On win widgetset, when B equals zero, an exception will get raised (EZeroDivide or EInvalidOp, depending on whether A is zero) and "code block 2" will be executed. On Gtk2 X becomes [Infinity](http://www.freepascal.org/docs-html/rtl/math/infinity.html), [NegInfinity](http://www.freepascal.org/docs-html/rtl/math/neginfinity.html), or [NaN](http://www.freepascal.org/docs-html/rtl/math/nan.html) and "code block 1" will be executed.
616	620
617	621		We can think of different ways to overcome this inconsistency. Most of the time you can simply test if B equals zero and don't try the dividing in that case. However, sometimes you will need some different approach. So, take a look at the following examples:
618	622
619	623		``` pascal
620	624		uses
621	625		..., math,...
622	626
623	627		//...
624	628		var
625	629		X, A, B: Double;
626	630		Ind: Boolean;
627	631		// ...
628	632		try
629	633		X := A / B;
630	634		Ind := IsInfinite(X) or IsNan(X); // with gtk2, we fall here
631	635		except
632	636		Ind := True; // in windows, we fall here when B equals zero
633	637		end;
634	638		if Ind then begin
635	639		// code block 2
636	640		end else begin
637	641		// code block 1
638	642		end;
639	643		// ...
640	644		```
641	645
642	646		Or:
643	647
644	648		``` pascal
645	649		uses
646	650		..., math,...
647	651
648	652		//...
649	653		var
650	654		X, A, B: Double;
651	655		FPUExceptionMask: TFPUExceptionMask;
652	656		// ...
653	657
654	658		try
655	659		FPUExceptionMask := GetExceptionMask;
656	660		SetExceptionMask(FPUExceptionMask - [exInvalidOp, exZeroDivide]); // unmask
657	661		try
658	662		X := A / B;
659	663		finally
660	664		SetExceptionMask(FPUExceptionMask); // return previous masking immediately, we must not let Gtk2 internals to be called without the mask
661	665		end;
662	666		// code block 1
663	667		except
664	668		// code block 2
665	669		end;
666	670		// ...
667	671		```
668	672
669	673		Be cautious, do not do something like this (call LCL with still removed mask):
670	674
671	675		``` pascal
672	676		try
673	677		FPUExceptionMask := GetExceptionMask;
674	678		SetExceptionMask(FPUExceptionMask - [exInvalidOp, exZeroDivide]);
675	679		try
676	680		Edit1.Text := FloatToStr(A / B); // NO! Setting Edit's text goes down to widgetset internals and Gtk2 API must not be called without the mask!
677	681		finally
678	682		SetExceptionMask(FPUExceptionMask);
679	683		end;
680	684		// code block 1
681	685		except
682	686		// code block 2
683	687		end;
684	688		// ...
685	689		```
686	690
687	691		But use an auxiliary variable:
688	692
689	693		``` pascal
690	694		try
691	695		FPUExceptionMask := GetExceptionMask;
692	696		SetExceptionMask(FPUExceptionMask - [exInvalidOp, exZeroDivide]);
693	697		try
694	698		X := A / B; // First, we set auxiliary variable X
695	699		finally
696	700		SetExceptionMask(FPUExceptionMask);
697	701		end;
698	702		Edit1.Text := FloatToStr(X); // Now we can set Edit's text.
699	703		// code block 1
700	704		except
701	705		// code block 2
702	706		end;
703	707		// ...
704	708		```
705	709
706	710		In all situations, when developing LCL applications, it is most important to know about this and to keep in mind that some floating point operations can go different way with different widgetsets. Then you can think of an appropriate way to workaround this, but this should not go unnoticed.
707	711
708	712		## Issues when moving from Windows to *nix etc
709	713
710	714		Issues specific to Linux, macOS, Android and other Unixes are described here. Not all subjects may apply to all platforms
711	715
712	716		### On Unix there is no "application directory"
713	717
714	718		Many programmers are used to calling ExtractFilePath(ParamStr(0)) or Application.ExeName to get the location of the executable, and then search for the necessary files for the program execution (Images, XML files, database files, etc) based on the location of the executable. This is wrong on unixes. The string on ParamStr(0) may contain a directory other than the one of the executable, and it also varies between different shell programs (sh, bash, etc).
715	719
716	720		Even if Application.ExeName could in fact know the directory where the executable is, that file could be a symbolic link, so you could get the directory of the link instead (depending on the Linux kernel version, you either get the directory of the link or of the program binary itself).
717	721
718	722		To avoid this read the sections about [[Multiplatform Programming Guide\|configuration files]] and [[Multiplatform Programming Guide\|data files]].
719	723
720	724		### Making do without Windows COM Automation
721	725
722	726		With Windows, COM Automation is a powerful way not only of manipulating other programs remotely but also for allowing other programs to manipulate your program. With Delphi you can make your program both an COM Automation client and a COM Automation server, meaning it can both manipulate other programs and in turn be manipulated by other programs. For examples, see [Using COM Automation to interact with OpenOffice and Microsoft Office](http://wiki.lazarus.freepascal.org/Office_Automation#Using_COM_Automation_to_interact_with_OpenOffice_and_Microsoft_Office).
723	727
724	728		#### macOS alternative
725	729
726	730		Unfortunately, COM Automation isn't available on macOS and Linux. However, you can simulate some of the functionality of COM Automation on macOS using AppleScript.
727	731
728	732		AppleScript is similar to COM Automation in some ways. For example, you can write scripts that manipulate other programs. Here's a very simple example of AppleScript that starts NeoOffice (the Mac version of OpenOffice.org):
729	733
730	734		```applescript
731	735		tell application "NeoOffice"
732	736		launch
733	737		end tell
734	738		```
735	739
736	740		An app that is designed to be manipulated by AppleScript provides a "dictionary" of classes and commands that can be used with the app, similar to the classes of a Windows Automation server. However, even apps like NeoOffice that don't provide a dictionary will still respond to the commands "launch", "activate" and "quit". AppleScript can be run from the macOS Script Editor or Finder or even converted to an app that you can drop on the dock just like any app. You can also run AppleScript from your program, as in this example:
737	741
738	742		``` pascal
739	743		fpsystem('myscript.applescript');
740	744		```
741	745
742	746		This assumes the script is in the indicated file. You can also run scripts on the fly from your app using the macOS OsaScript command:
743	747
744	748		``` pascal
745	749		fpsystem('osascript -e '#39'tell application "NeoOffice"'#39 +
746	750		' -e '#39'launch'#39' -e '#39'end tell'#39);
747	751		{Note use of #39 to single-quote the parameters}
748	752		```
749	753
750	754		However, these examples are just the equivalent of the following Open command:
751	755
752	756		``` pascal
753	757		fpsystem('open -a NeoOffice');
754	758		```
755	759
756	760		Similarly, in macOS you can emulate the Windows shell commands to launch a web browser and launch an email client with:
757	761
758	762		``` pascal
759	763		fpsystem('open -a safari "http://gigaset.com/shc/0,1935,hq_en_0_141387_rArNrNrNrN,00.html"');
760	764		```
761	765
762	766		and
763	767
764	768		``` pascal
765	769		fpsystem('open -a mail "mailto:ss4200@invalid.org"');
766	770		```
767	771
768	772		which assumes, fairly safely, that a macOS system will have the Safari and Mail applications installed. Of course, you should never make assumptions like this, and for the two previous examples, you can in fact just rely on macOS to do the right thing and pick the user's default web browser and email client if you instead use these variations:
769	773
770	774		``` pascal
771	775		fpsystem('open "http://gigaset.com/shc/0,1935,hq_en_0_141387_rArNrNrNrN,00.html"');
772	776		```
773	777
774	778		and
775	779
776	780		``` pascal
777	781		fpsystem('open "mailto:ss4200@invalid.org"');
778	782		```
779	783
780	784		Do not forget to include the Unix unit in your uses clause if you use `fpsystem` or `shell` (interchangeable).
781	785
782	786		The real power of AppleScript is to manipulate programs remotely to create and open documents and automate other activities. How much you can do with a program depends on how extensive its AppleScript dictionary is (if it has one). For example, Microsoft's Office X programs are not very usable with AppleScript, whereas the newer Office 2004 programs have completely rewritten AppleScript dictionaries that compare in many ways with what's available via the Windows Office Automation servers.
783	787
784	788		#### Linux alternatives
785	789
786	790		While Linux shells support sophisticated command line scripting, the type of scripting is limited to what can be passed to a program on the command line. There is no single, unified way to access a program's internal classes and commands with Linux the way they are via Windows COM Automation and macOS AppleScript. However, individual desktop environments (GNOME/KDE) and application frameworks often provide such methods of interprocess communication. On GNOME see Bonobo Components. KDE has the KParts framework, DCOP. OpenOffice has a platform neutral API for controlling the office remotely (google OpenOffice SDK) - though you would probably have to write glue code in another language that has bindings (such as Python) to use it. In addition, some applications have "server modes" activated by special command-line options that allow them to be controlled from another process. It is also possible (Borland did it with Kylix document browser) to "embed" one top-level X application window into another using XReparentWindow (I think).
787	791
788	792		As with Windows, many macOS and Linux programs are made up of multiple library files (.dylib and .so extensions). Sometimes these libraries are designed so you can also use them in programs you write. While this can be a way of adding some of the functionality of an external program to your program, it's not really the same as running and manipulating the external program itself. Instead, your program is just linking to and using the external program's library similar to the way it would use any programming library.
789	793
790	794		### Alternatives for Windows API functions
791	795
792	796		Many Windows programs use the Windows API extensively. In cross-platform applications Win API functions in the Windows unit should not be used, or should be enclosed by a conditional compile (e.g. {\$IFDEF MSWINDOWS} ).
793	797
794	798		Fortunately many of the commonly used Windows API functions are implemented in a multiplatform way in the unit [[lclintf]]. This can be a solution for programs which rely heavily on the Windows API, although the best solution is to replace these calls with true cross-platform components from the LCL. You can replace calls to GDI painting functions with calls to a TCanvas object's methods, for example.
795	799
796	800		### Key codes
797	801
798	802		Fortunately, detecting key codes (e.g. on KeyUp events) is portable: see [[LCL Key Handling]].
799	803
800	804		### Installing your application
801	805
802	806		See [[Deploying Your Application]].
803	807
804	808		## See also
805	809
806	810		- [[Writing portable code regarding the processor architecture]]
807	811		- [[Introduction to platform-sensitive development]]
808	812		- [[Apple-specific UI elements]]
809	813
810	814		## External links
811	815
812	816		- <http://www.midnightbeach.com/KylixForDelphiProgrammers.html> A guide for Windows programmers starting with Kylix. Many of concepts / code snippets apply to Lazarus.
813	817		- <http://www.stack.nl/~marcov/porting.pdf> A guide for writing portable source code, mainly between different compilers.
814	818
815	819		---
816	820		From the Free Pascal wiki, page "Multiplatform Programming Guide", as it stood on 2022-01-27 after a change by Zoran, 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).

Back to history