Macros and Conditionals: what changed

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

Old	New		Line
1	1		# Overview
2	2
3	3		Macros can be used in search paths and file names to let the IDE automatically adapt them to the target platform. Build macros are project/package specific macros. They are not passed to the compiler. A prominent example is the LCLWidgetType, which is defined by the package LCL and allows to choose the widget set (carbon, gtk, qt, win32, wince, ...).
4	4
5	5		Conditionals are rules allowing to set macros depending on the target platform and/or other macros. For example you can use them to define special linker options when compiling for Mac OS X. They use a pascal like scripting language allowing to define even complex rules.
6	6
7	7		You can set the build macros via [[IDE Window: Compiler Options\|Project / Project Options / Compiler Options / Additions and Overrides]].
8	8
9	9		You can set the conditionals via Project / Project Options / Compiler Options / Other / Conditionals.
10	10
11	11		Build macros and conditionals exist since Lazarus 0.9.29.
12	12
13		-	~~<figure>~~
14		-	~~<img src="CompilerAdditionsAndOverrides1.png" title="CompilerAdditionsAndOverrides1.png" />~~
15		-	~~<figcaption>CompilerAdditionsAndOverrides1.png</figcaption>~~
16		-	~~</figure>~~
	13	+	![](/wiki-images/c/cd/CompilerAdditionsAndOverrides1.png)
17	14
18	15		# Conditionals
19	16
20	17		The conditionals use a simple scripting language.
21	18
22	19		## Changing compiler options with conditionals
23	20
24	21		The conditionals script can define some variables which values are used by the IDE for the compiler options:
25	22
26	23		- UnitPath: appended to Other Source Files (-Fu). The / and \\ characters are automatically converted to the current path delimiter. After adding the search path(s) with a semicolon macros are replaced and relative paths are extended by the package/project directory.
27	24		- IncPath: appended to Include Files (-Fi).
28	25		- LibraryPath: appended to Libraries (-Fl).
29	26		- SrcPath: appended to Other sources (not used by compiler, only IDE).
30	27		- DebugPath: appended to Debugger path addition (not used by compiler, not by the codetools, only used by debugger)
31	28		- LinkerOptions: appended to the linker options (-k). Path delimiters are not changed. Relative paths are not extended. Macros are replaced.
32	29		- CustomOptions: appended to the compiler parameters. Path delimiters are not changed. Relative paths are not extended. Macros are replaced.
33	30		- OutputDir: if set it will replace the current output directory. Path delimiters are changed. Relative path is extended. Macros are replaced.
34	31
35	32		For packages there are more variables for the usage options. These paths are inherited, that means appended to all packages/projects using this package, directly or indirectly:
36	33
37	34		- UsageUnitPath: appended to Unit (-Fu) usage path. The / and \\ characters are automatically converted to the current path delimiter. After adding the search path(s) with a semicolon macros are replaced and relative paths are extended by the package/project directory.
38	35		- UsageIncPath: appended to Include (-Fi) usage path.
39	36		- UsageLibraryPath: appended to Library (-Fl) usage path.
40	37		- UsageSrcPath: appended to Source (not used by compiler, only IDE) usage path.
41	38		- UsageDebugPath: appended to Debugger (not used by compiler, not by the codetools, only used by debugger) usage path.
42	39		- UsageLinkerOptions: appended to the usage linker options (-k). Path delimiters are not changed. Relative paths are not extended. Macros are replaced.
43	40		- UsageCustomOptions: appended to the usage compiler parameters. Path delimiters are not changed. Relative paths are not extended.
44	41
45	42		## Conditionals syntax
46	43
47	44		### Supported syntax constructs
48	45
49	46		- If expression then statement;
50	47		- If expression then statement else statement;
51	48		- begin statement; ... statement; end;
52	49		- Variable:=expression;
53	50		- Variable+=expression;
54	51		- Comments //, { }, (* *)
55	52		- Spaces, tabs and line breaks are the same. Like Pascal they are only needed to separate two identifiers/keywords.
56	53
57	54		### Variables
58	55
59	56		Variables are defined simply by assigning a value. There are some predefined variables. See further below for a list.
60	57
61	58		Variables can be defined or undefined:
62	59
63	60		``` pascal
64	61		if defined(Name) then ...
65	62		if undefined(Name) then ...
66	63		undefine(Name);
67	64		```
68	65
69	66		If a Variable is defined it has one of these three types:
70	67
71	68		- none
72	69		- string
73	70		- number (int64)
74	71
75	72		A variable is false if it has the number 0 or the string '0'. Otherwise it is true. That means a variable without a value is true and an undefined variable is true.
76	73
77	74		You can change the type of a variable with:
78	75
79	76		``` pascal
80	77		a := '1'; // string
81	78		a := integer(a); // convert to a number using StrToInt(), on failure 'a' remains a string
82	79		a := int64(a); // convert to a number using StrToInt64(), on failure 'a' remains a string
83	80		a := string(a); // convert to a string
84	81		```
85	82
86	83		### Constants
87	84
88	85		``` pascal
89	86		a := 1234; // decimal
90	87		a := $A1B; // hexadecimal
91	88		a := &127; // octal
92	89		a := %101; // binary
93	90		a := '10'; // string
94	91		a := #123; // character
95	92		```
96	93
97	94		### Operators
98	95
99	96		- +: Two numbers are added, otherwise they are treated as strings and concatenated.
100	97		- \<, \>, \<=, \>=, =, \<\>: Two numbers are compared mathematically, otherwise they are treated as strings and compared lexicographically (case sensitive).
101	98		- not: Unary boolean operator
102	99		- and, or, xor: Boolean operators
103	100		- (,): Group operations
104	101		- :=: Assignment. Not allowed in expressions.
105	102		- +=: Add and assign. Not allowed in expressions.
106	103
107	104		Precedence levels:
108	105
109	106		- 1 Not and unary minus
110	107		- 1 And
111	108		- 2 Or
112	109		- 2 XOr
113	110		- 2 +
114	111		- 4 =
115	112		- 4 \<\>
116	113		- 4 \<
117	114		- 4 \<=
118	115		- 4 \>
119	116		- 4 \>=
120	117
121	118		## Predefined Variables
122	119
123	120		Before the conditionals script is run the IDE initializes a few variables:
124	121
125	122		- TargetOS: the project's target operating system as defined by fpc. e.g. 'linux', 'win32', 'darwin', 'freebsd', 'wince'.
126	123		- TargetCPU: the project's target processor as defined by fpc. e.g. 'i386', 'x86_64', 'arm'
127	124		- SrcOS: the value 'win' for all MS Windows platforms and 'unix' for all unix like platforms. The value depends on the TargetOS.
128	125		- SrcOS2: the value 'bsd' for all BSD like platforms. The value depends on the TargetOS.
129	126		- Laz_FullVersion: same number as laz_fullversion in unit lazversion.
130	127		- True: value 1
131	128		- False: value 0
132	129		- all build macros defined by the current project.
133	130		- all build macros defined by used packages. That means if the project has not defined a value for a package macro the value of the conditionals of the used package will be used.
134	131
135	132		## Predefined Functions
136	133
137	134		- Defined(Variable): returns 1 (true) if the variable is defined otherwise 0 (false). Example if Defined(Macro1) then ;
138	135		- Undefine(Variable): undefine the variable. Example: Undefine(A);
139	136		- Int64(expression): Returns the int64 value of expression. Example: i:=int64('3');
140	137		- Integer(expression): Returns the integer value of expression. Example: i:=integer('3');
141	138		- String(expression): Returns the string value of expression. Example: s:=string(3);
142	139		- GetIDEValue(string): See [[IDE Macros in paths and filenames\|IDE macros]]
143	140		- GetIDEValue('OS'): Returns the OS with which the IDE was compiled. since 1.0.
144	141		- GetIDEValue('CPU'): Returns the CPU with which the IDE was compiled. since 1.0.
145	142		- GetIDEValue('SrcOS'): SrcOS of IDE. since 1.0.
146	143		- GetIDEValue('SrcOS2'): SrcOS2 of IDE. since 1.0.
147	144		- GetIDEValue('LCLWidgeType'): LCL platform of the IDE, which might be different than project. lazbuild returns win32, carbon or gtk2 depending on its OS. since 1.0.
148	145		- GetEnv(string): Returns the environment variable. For example GetEnv('HOME') returns under Linux the user's home directory. since 1.0.
149	146		- GetProjValue(string): Returns a project value.
150	147		- GetProjValue('FPC_FULLVERSION'): Returns the FPC_FULLVERSION fetched from the project compiler. The version is an integer e.g. 20701. since 1.3.
151	148
152	149		# Order of macro computation
153	150
154	151		1. the values of the current project are taken
155	152		2. if the project does not define values for TargetOS, TargetCPU the IDE sets defaults
156	153		3. SrcOS and SrcOS2 are computed from TargetOS
157	154		4. the conditionals of used packages are computed. If package A uses package B, then the conditionals of B are computed before the conditionals of A.
158	155		5. Every conditional script starts with the values of the project.
159	156		- If the project does not define a value for a package macro, the result of the used package is used.
160	157		- A script can alter any macro while it runs, but only the build macros and the built-in macros are used. For example you can set TargetOS to another value, but this has no effect on any other script, nor on any search path using \$(TargetOS), not even the search path of the package itself.
161	158		- If two packages define the same build macro, then both can alter the value (unless the project sets a value). The exact effect depends on the dependency order.
162	159		6. the default IDE macros are used last.
163	160
164	161		# Examples
165	162
166	163		## Adding a compiler flag for target Linux
167	164
168	165		``` pascal
169	166		if TargetOS = 'linux' then
170	167		CustomOptions := '-dUseCThreads';
171	168		```
172	169
173	170		Notes:
174	171
175	172		- TargetOS is a predefined macro by the IDE.
176	173		- CustomOptions is a result variable used by the IDE.
177	174		- The identifiers are case insensitive, but = (equal) operator is not. The TargetOS macro uses the same case as the compiler does, which is currently all lowercase.
178	175		- The IDE adds the first space automatically when adding the custom options.
179	176		- When used in a package the above only will be applied to the options used for compiling the package, not to the project using the package.
180	177
181	178		## Adding a define depending on Lazarus version
182	179
183	180		``` pascal
184	181		if Laz_FullVersion >= 3990000 then
185	182		CustomOptions := '-dHasFeature1';
186	183		```
187	184
188	185		Notes:
189	186
190	187		- Laz_FullVersion is a predefined macro by the IDE having the same value as in unit lazversion and exists since 3.99. On earlier versions it does not exist and so evaluates to 0.
191	188		- see notes in Adding a compiler flag for target Linux
192	189
193	190		## Adding some linker options for target Mac OS X
194	191
195	192		The compiler uses for Mac OS X the value 'darwin' for TargetOS.
196	193
197	194		``` pascal
198	195		if TargetOS = 'darwin' then begin
199	196		LinkerOptions += ' -framework Cocoa';
200	197		if TargetCPU = 'i386' then
201	198		LinkerOptions += ' -framework OpenGL';
202	199		end;
203	200		```
204	201
205	202		Notes:
206	203
207	204		- TargetOS and TargetCPU are predefined macros by the IDE.
208	205		- The += operator appends a string or adds a number.
209	206		- When adding several options you have to add a space between options.
210	207		- The IDE adds the first space automatically when adding the linker options.
211	208		- You can nest begin..end just like Pascal.
212	209		- If both conditions hold LinkerOptions will contain the value ' -framework Cocoa -framework OpenGL'.
213	210		- The IDE automatically prepends the -k option when passing linker options to the compiler.
214	211		- The above only works for project's conditionals.
215	212
216	213		## Adding some linker options for Mac OS X for all projects using a package
217	214
218	215		Packages have two different sets of options. The set used for compiling the package itself and the options added to all projects/packages using the package. You have to change the usage options of the package:
219	216
220	217		``` pascal
221	218		if TargetOS = 'darwin' then begin
222	219		UsageLinkerOptions += ' -framework Cocoa';
223	220		if TargetCPU = 'i386' then
224	221		UsageLinkerOptions += ' -framework OpenGL';
225	222		end;
226	223		```
227	224
228	225		## Adding an option to a package
229	226
230	227		If your package provides some optional parts, for example the ability to use opengl you can define a build macro. The following explains how to set this up step by step:
231	228
232	229		Let's say your package is called Pkg1 and allows to switch on opengl support by compiling it with the flag -dEnableOpenGL. The package should provide a boolean option Pkg1_UseOpenGL with the values 'True' and 'False'.
233	230
234	231		Open the package editor of your package 'pkg1', click on compiler options, select the page IDE Macros.
235	232
236	233		Click on the left + button to add a new macro. It will be called 'Pkg1_Macro1'. Click on the tree node to rename it to 'Pkg1_UseOpenGL'.
237	234
238	235		Click on the middle + button to add a new macro value. It will be called 'Value1'. Click on the tree node to rename it to 'True'. Repeat this for the value 'False'.
239	236
240	237		Add the following code into the Conditionals (Compiler Options / Other / Conditionals) text box:
241	238
242	239		``` pascal
243	240		if Pkg1_UseOpenGL = 'True' then
244	241		CustomOptions := '-dEnableOpenGL';
245	242		```
246	243
247		-	~~<figure>~~
248		-	~~<img src="Compileroptions_buildmacro_example1.png" title="Compileroptions_buildmacro_example1.png" />~~
249		-	~~<figcaption>Compileroptions_buildmacro_example1.png</figcaption>~~
250		-	~~</figure>~~
	244	+	![](/wiki-images/c/c2/Compileroptions_buildmacro_example1.png)
251	245
252	246		Notes:
253	247
254	248		- The value 'True' is case sensitive. Because the value is usually selected from the combobox, there is no chance of typos.
255	249		- If the user has not set any value for the macro, the Variable 'Pkg1_UseOpenGL' is undefined and the expression results to false.
256	250
257	251		## Add a release/debug mode
258	252
259	253		### A release/debug mode for your project and all your packages
260	254
261	255		Note: This requires Lazarus 0.9.31 or higher.
262	256
263	257		In the project's compiler options (Project / Project Options / Compiler Options / Build modes) add a build mode Release. Adding this build mode will automatically activate it, so all changes to the compiler options are now only done in this build mode.
264	258
265	259		In "Set Macro Values" click on the left column on the last row "(none)". Set it to "MyPackageOptions". Note: It is not listed in the combo box.
266	260
267	261		Set its value to the options. For example "-O3".
268	262
269		-	~~<figure>~~
270		-	~~<img src="Build_mode_release_macro1.png" title="Build_mode_release_macro1.png" />~~
271		-	~~<figcaption>Build_mode_release_macro1.png</figcaption>~~
272		-	~~</figure>~~
	263	+	![](/wiki-images/1/1f/Build_mode_release_macro1.png)
273	264
274	265		This macro is usable in the project compiler options and all packages.
275	266
276	267		For each package do: Open the compiler options of the package, go to the page Other. Add to Custom options the text \$(MyPackageOptions).
277	268
278	269		### A special release/debug mode for one package
279	270
280	271		Let's say the normal mode is the debug mode and you want another mode for the release.
281	272
282	273		Open the package editor of your package 'pkg1', click on compiler options, select the page Build Macros.
283	274
284	275		Under Build macros click on the left + button to add a new macro. It will be called 'Pkg1_Macro1'. Click on the tree node to rename it to 'Pkg1_Release'.
285	276
286	277		Click on the middle + button to add a new macro value. It will be called 'Value1'. Click on the tree node to rename it to 'True'. Repeat this for the value 'False'.
287	278
288	279		Add the following code into the Conditionals text box:
289	280
290	281		``` pascal
291	282		if Pkg1_Release = 'True' then
292	283		// release mode
293	284		CustomOptions := '-O3'
294	285		else
295	286		// debug mode
296	287		CustomOptions := '-Sa Ctroi';
297	288		```
298	289
299	290		Notes:
300	291
301	292		- The value 'True' is case sensitive. Because the value is usually selected from the combobox, there is no chance of typos.
302	293		- If the user has not set any value for the macro, the Variable 'Pkg1_Release' is undefined and the expression results to false.
303	294
304	295		## Adding a macro for search paths to handle different platforms
305	296
306	297		Let's say your package is called Pkg1 and uses the windows GDI on MS Windows and X11 on Linux and BSD. The platform independent units are in the package main directory and you have created two sub directories 'gdi' and 'x11' containing the platform dependent units:
307	298
308	299		/path/of/your/package/pkg1/
309	300		pkg1.lpk
310	301		pkg1.pas
311	302		generalunit.pas
312	303		gdi/
313	304		backend.pas
314	305		x11/
315	306		backend.pas
316	307
317	308		The unit backend in gdi should be used on Win32, Win64 and WinCE, while under Linux and FreeBSD the backend unit in the x11 should be used. This means the Other unit files (-Fu) search path must be adapted depending on the target OS. The following describes how to set this up step by step:
318	309
319	310		Open the package editor of your package 'pkg1', click on compiler options, select the page Build Macros.
320	311
321	312		Click on the left + button to add a new macro. It will be called 'Pkg1_Macro1'. Click on the tree node to rename it to 'Pkg1_Backend'.
322	313
323	314		Click on the middle + button to add a new macro value. It will be called 'Value1'. Click on the tree node to rename it to 'gdi'. Repeat this for the value 'x11'.
324	315
325	316		Add the following code into the Conditionals text box:
326	317
327	318		``` pascal
328	319		// choose a value for Pkg1_Backend depending on the TargetOS
329	320		if undefined(Pkg1_Backend) then begin
330	321		if SrcOS='win' then
331	322		Pkg1_Backend:='gdi'
332	323		else
333	324		Pkg1_Backend:='x11';
334	325		end;
335	326		```
336	327
337	328		The macro \$(Pkg1_Backend) will become usable once you click Ok. So, click 'Ok' to close the compiler options and open it again to use it in the search path Other unit files (-Fu).
338	329
339		-	~~<figure>~~
340		-	~~<img src="Compileroptions_buildmacro_example2.png" title="Compileroptions_buildmacro_example2.png" />~~
341		-	~~<figcaption>Compileroptions_buildmacro_example2.png</figcaption>~~
342		-	~~</figure>~~
	330	+	![](/wiki-images/7/70/Compileroptions_buildmacro_example2.png)
343	331
344	332		Notes:
345	333
346	334		- The user can override the value of Pkg1_Backend. Therefore it is good practice to enclose the setting in if undefined(Pkg1_Backend).
347	335		- Instead of the SrcOS macro you could use if (TargetOS='win32') or (TargetOS='win64') or (TargetOS='wince') then
348	336
349	337		---
350	338		From the Free Pascal wiki, page "Macros and Conditionals", as it stood on 2023-07-28 after a change by Mattias2, 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