Macro internals: what changed

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

Old	New		Line
1	1		## Implementation of macros in FPC
2	2
3	3		Compile time symbols (a k a defines), substitution macros and compile time variables, are all internally refered to as macros.
4	4
5	5		Each macro is stored in an object of type TMacro. Macro objects belonging to the same scope are collected in a macro symbol table. When a macro is defined, a macro object is created. If it later on is undefined, it is not deleted, instead its defined flag is set to false. If again defined, its defined flag is set to true.
6	6
7	7		Since several scopes of macro symbols might be in effect, their corresponding macro symbol tables are arranged in a macrosymbolstack, in a fashion in parallell with ordinary symbol tables.
8	8
9	9		When a macro is used, the stack is searched top-down for the macro. If an existing macro is changed in any way, and the macro is not found on the top of the stack, a new macro object is created and put in the macrosymtable on the top of the stack. This is the case even if the macro is undefined, in which case the defined flag of the newly created macro object is set to false.
10	10
11	11		Each module always has a localmacrosymtable. If its macros should be exported (happends in MODE MACPAS), it will also have a globalmacrosymtable. There is also the internalmacrosymtable, which is immutable, and is used by every module. It contains all predefined macros, both by the compiler and given on the command line.
12	12
13	13		For a unit which do not export and import macros, the macrosymbolstack look like this:
14	14
15		-	~~` <top>`\~~
16		-	~~` localmacrosymtable`\~~
17		-	~~` internalmacrosymtable`~~
	15	+	```text
	16	+	<top>
	17	+	localmacrosymtable
	18	+	internalmacrosymtable
	19	+	```
18	20
19	21		And for a unit which do export and import macros, it look like this (at the end of the parsing):
20	22
21		-	~~` <top>`\~~
22		-	~~` localmacrosymtable`\~~
23		-	~~` globalmacrosymtable`\~~
24		-	~~` globalmacrosymtables for used unit 1`\~~
25		-	~~` globalmacrosymtables for used unit 2`\~~
26		-	~~` ...`\~~
27		-	~~` internalmacrosymtable`~~
	23	+	``` pascal
	24	+	<top>
	25	+	localmacrosymtable
	26	+	globalmacrosymtable
	27	+	globalmacrosymtables for used unit 1
	28	+	globalmacrosymtables for used unit 2
	29	+	...
	30	+	internalmacrosymtable
	31	+	```
28	32
29	33		### System macros
30	34
31	35		A system macro is a macro which is defined by the compiler, it often has FPC_ prepended to it. Although it is not a good programming practice, system macros can be overridden by the user.
32	36
33	37		Most system macros are in initialsymboltable, but those which are specific to a unit are put in the localmacrosymtable of the unit instead. Examples are FPC_\<mode\> and FPC_THREADING.
34	38
35	39		System macros are not exported, even if they are available in the interface part of a unit, although if they are redefined there, they will be exported.
36	40
37	41		### Compilation of a module with regard to macros
38	42
39	43		When a unit is about to be compiled, its localmacrosymtable is created, and it is pushed on the stack (which initially contains initialmacrosymtable). At this moment we do not know if macros should be exported.
40	44
41	45		Macros should be exported if it is a) a unit and b) it is MODE MACPAS.
42	46
43	47		Only one \$MODE \<xxx\> declaration is allowed when a module is parsed. This ensures that when a \$MODE \<xxx\> is encountered, we know for sure what the mode of the file should be. So, if a \$MODE MACPAS is encountered, the globalmacrosymtable is immediatelly created.
44	48
45	49		If -Mmacpas is given on the command line, and no \$MODE has been encountered when UNIT is encountered, the globalmacrosymtable is created, and further \$MODE switch is forbidden.
46	50
47	51		For other modes given on the command line, or if no mode is given, \$MODE is forbidden at the point where the first pascal construct is encountered after the UNIT or PROGRAM clause. In this case, or in all cases if it is a PROGRAM, the module has only a localmacrosymtable, and none of what is described below will happen. Thus the following apply to MODE MACPAS units only.
48	52
49	53		Between the beginning of the file and until the globalmacrosymtable is created, the localmacrossymtable is available for macros which are declared by the user or for local system macros. They will of course not be exported.
50	54
51	55		When there is a globalmacrosymtable, user macros are declared there, but system macros are declared in localmacrosymtable (so they are not exported). If some of the macros declared in the localmacrosymtable part is overriden, this is ok, and the override is then put in globalmacrosymtable.
52	56
53	57		At IMPLEMENTATION the stack positions of globalmacrosymtable and localmacrotable is swapped. Macros existing in the localmacrosymtable, which has been overriden in globalmacrosymtable is deleted from localmacrosymtable (otherwise it would appear for the user as the macro sudenly has changed).
54	58
55	59		Caveat: If \$MODE MACPAS is given before UNIT, the macros defined between this point and UNIT is exported, if the unit is compiled as part of a program or other unit, but is not exported if the unit is compiled from the commandline (at top level). Remedy: Do not put macros before UNIT.
56	60
57	61		NOTE: In macpas, globalmacrosymtable is saved only if it contains anything.
58	62
59	63		---
60	64		From the Free Pascal wiki, page "Macro internals", as it stood on 2016-01-18 after a change by Skalogryz, 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).
61	65		Category: FPC internals

Back to history