System unit: what changed

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

Old	New		Line
1	1		In Free Pascal the System unit is the unit that is included by every program. FPC's [[RTL\|run-time library]] comes with a System unit where most, if not all of its functionalities work on every available [[Platform list\|platform]].
2	2
3	3		Also depending on the platform it's not true that no further unit is added, because for example on Windows the SysInit unit is also used, because that contains the entry point for the binary.
4	4
5	5		## Compilation of System unit
6	6
7	7		For quite some time already FPC automatically applies the -Us switch to the unit named System, so you don't need the -Us switch. The -Us switch tells the compiler that only basic type definitions are being made. Types such as [[Integer]] are not yet available.
8	8
9	9		### Mandatory tasks of System unit
10	10
11	11		If you attempt to create your own system unit, you'll incrementally notice what the compiler needs or what the generated code expects. On a Linux target, the minimal system unit has to contain:
12	12
13	13		``` pascal
14	14		unit system;
15	15
16	16		interface
17	17		```
18	18
19	19		The type hresult must be defined, for example:
20	20
21	21		``` pascal
22	22		type
23	23		hresult = LongInt;
24	24		```
25	25
26	26		The identifier operatingsystem_result has to be declared. The data stored at that position are communicated to the operating system as return value. Whether hresult and operatingsystem_result are defined in the "interface" section is irrelevant. However, it is very plausible to put those into the "interface" section, so programs using this system unit can manipulate those.
27	27
28	28		``` pascal
29	29		var
30	30		ExitCode: hresult = 0; export name 'operatingsystem_result';
31	31
32	32		implementation
33	33		```
34	34
35	35		Here comes to light what the system responsibilities are: It has to (or should) initialize units, that means call every unit's [[Initialization]] routines. For that the label FPC_INITIALIZEUNITS has to be defined.
36	36
37	37		``` pascal
38	38		procedure InitializeUnits; alias: 'FPC_INITIALIZEUNITS';
39	39		begin
40	40		end;
41	41		```
42	42
43	43		Also the label FPC_DO_EXIT has to be defined. Here, system unit programmers have the chance to finalize units.
44	44
45	45		``` pascal
46	46		procedure doExit; alias: 'FPC_DO_EXIT';
47	47		begin
48	48		end;
49	49
50	50		end.
51	51		```
52	52
53	53		Furthermore FPC will possibly complain the unit FPIntRes is missing. So create a file fpintres.pas:
54	54
55	55		``` pascal
56	56		unit FPIntRes;
57	57		interface
58	58		implementation
59	59		end.
60	60		```
61	61
62	62		After doing so, you can compile your system unit (flag -Us is not needed), or directly create an empty program and compile it to examine the impact on the binary's size. On a x86-64 Linux target the executable had a size of 2.7 Kbytes. The big trade-off is no convenience. All functionality that can't be “implemented” by the compiler is gone. For example [[Addr]] or [[Ord]] still work, while Sin() or Random() are not available. Confer the procedure create_intern_symbols in "compiler/psystem.pas".
63	63
64	64		> Note: Depending on what your program uses, there might other mandatory tasks, too. Especially OOP won't work without a functional ObjPas unit.
65	65
66	66		### Initialization and finalization of units
67	67
68	68		For those who are curious, how to implement FPC_INITIALIZEUNITS: FPC puts into every program's data section a INITFINAL table. Compiling a program with the "-al" flag will retain the Assembler file "*.s". Examining this Assembler file, you will encounter something like:
69	69
70	70		``` asm
71	71		.section .data.n_INITFINAL
72	72		.balign 8
73	73		.globl INITFINAL
74	74		.type INITFINAL,@object
75	75		INITFINAL:
76	76		.quad 1,0
77	77		.quad INIT$_$SOMEUNIT
78	78		.quad FINALIZE$_$SOMEUNIT
79	79		```
80	80
81	81		For further investigations have a glimpse at an actual implementation: ["rtl/inc/system.inc"](https://gitlab.com/freepascal.org/fpc/source/-/blob/main/rtl/inc/system.inc).
82	82
83	83		> Note: In general, implementing an “own” system unit is a stupid idea. There is “smart-linking” if [[Size Matters\|size matters]].
84	84
85	85		### Other issues with compilation
86	86
87	87		- Q: Now FPC wants to compile the ObjPas unit.
88	88		- A: That is because your project's mode is set to ObjFPC (Lazarus will pass a -MObjFPC parameter to the compiler then) which automatically leads to an insertion of the ObjPas unit. Either change your project's mode in Project Settings -\> Compiler Settings -\> Parsing or add a {\$mode fpc} to your main program file.
89	89
90	90		------------------------------------------------------------------------
91	91
92	92		- Q: Now FPC cannot find this:
93	93
94		-	~~`Unknown compilerproc "fpc_initializeunits". Check if you use the correct run time library.`~~
	94	+	```text
	95	+	Unknown compilerproc "fpc_initializeunits". Check if you use the correct run time library.
	96	+	```
95	97
96	98		- A: You need to add a
97	99
98	100		``` pascal
99	101		procedure fpc_initializeunits; compilerproc;
100	102		```
101	103
102	104		both in the interface and implementation section.
103	105
104	106		------------------------------------------------------------------------
105	107
106	108		- Q: I am stuck, FPC says:
107	109
108		-	~~`Internal type "TEXCEPTADDR" was not found`~~
	110	+	``` pascal
	111	+	Internal type "TEXCEPTADDR" was not found
	112	+	```
109	113
110	114		- A: The compiler expects some system defined types to be defined when parsing a subroutine such as the implementation section of System. This means you have to add some type definitions to System. It appears that this check was added to 3.2.0.
111	115
112	116		## Example of System unit
113	117
114	118		The example is made by user Okoba [at forum](https://forum.lazarus.freepascal.org/index.php?topic=49434.msg367677#msg367677).
115	119
116	120		File system.pas:
117	121
118	122		``` pas
119	123		unit system;
120	124		{$MODE FPC}
121	125		interface
122	126
123	127		type
124	128		hresult = LongInt;
125	129		DWord = LongWord;
126	130		Cardinal = LongWord;
127	131		Integer = SmallInt;
128	132		UInt64 = QWord;
129	133		TTypeKind = (tkUnknown, tkInteger, tkChar, tkEnumeration, tkFloat, tkSet,
130	134		tkMethod, tkSString, tkLString, tkAString, tkWString, tkVariant, tkArray,
131	135		tkRecord, tkInterface, tkClass, tkObject, tkWChar, tkBool, tkInt64, tkQWord,
132	136		tkDynArray, tkInterfaceRaw, tkProcVar, tkUString, tkUChar, tkHelper, tkFile,
133	137		tkClassRef, tkPointer);
134	138
135	139		type
136	140		jmp_buf = packed record
137	141		rbx, rbp, r12, r13, r14, r15, rsp, rip: QWord;
138	142		{$IFDEF win64}
139	143		rsi, rdi: QWord;
140	144		xmm6, xmm7, xmm8, xmm9, xmm10, xmm11, xmm12, xmm13, xmm14, xmm15: record
141	145		m1, m2: QWord;
142	146		end;
143	147
144	148		mxcsr: LongWord;
145	149		fpucw: word;
146	150		padding: word;
147	151		{$ENDIF win64}
148	152		end;
149	153
150	154		Pjmp_buf = ^jmp_buf;
151	155		PExceptAddr = ^TExceptAddr;
152	156		TExceptAddr = record
153	157		buf: Pjmp_buf;
154	158		next: PExceptAddr;
155	159		{$IFDEF CPU16}
156	160		frametype: SmallInt;
157	161		{$ELSE CPU16}
158	162		frametype: LongInt;
159	163		{$ENDIF CPU16}
160	164		end;
161	165
162	166		PGuid = ^TGuid;
163	167		TGuid = packed record
164	168		case Integer of
165	169		1:
166	170		(Data1: DWord;
167	171		Data2: word;
168	172		Data3: word;
169	173		Data4: array [0 .. 7] of byte;
170	174		);
171	175		2:
172	176		(D1: DWord;
173	177		D2: word;
174	178		D3: word;
175	179		D4: array [0 .. 7] of byte;
176	180		);
177	181		3:
178	182		( { uuid fields according to RFC4122 }
179	183		time_low: DWord; // The low field of the timestamp
180	184		time_mid: word; // The middle field of the timestamp
181	185		time_hi_and_version: word;
182	186		// The high field of the timestamp multiplexed with the version number
183	187		clock_seq_hi_and_reserved: byte;
184	188		// The high field of the clock sequence multiplexed with the variant
185	189		clock_seq_low: byte; // The low field of the clock sequence
186	190		node: array [0 .. 5] of byte; // The spatially unique node identifier
187	191		);
188	192		end;
189	193
190	194		var
191	195		ExitCode: hresult = 0; export name 'operatingsystem_result';
192	196
193	197		procedure fpc_initializeunits; compilerproc;
194	198
195	199		procedure fpc_do_exit; compilerproc;
196	200
197	201		implementation
198	202
199	203		procedure fpc_initializeunits;
200	204		begin
201	205		end;
202	206
203	207		procedure fpc_do_exit;
204	208		begin
205	209		end;
206	210
207	211		end.
208	212		```
209	213
210	214		File sysinit.pas:
211	215
212	216		``` Pascal
213	217		unit sysinit;
214	218		{$MODE FPC}
215	219
216	220		interface
217	221
218	222		procedure _FPC_mainCRTStartup; stdcall; public name '_mainCRTStartup';
219	223
220	224		implementation
221	225
222	226		procedure _FPC_mainCRTStartup; stdcall;
223	227		begin
224	228		end;
225	229
226	230		end.
227	231		```
228	232
229	233		File fpintres.pas:
230	234
231	235		``` Pascal
232	236		unit FPIntRes;
233	237		{$MODE FPC}
234	238
235	239		interface
236	240		implementation
237	241		end.
238	242		```
239	243
240	244		## Comparative remarks
241	245
242	246		Other compilers such as [[GNU Pascal]] or [[Delphi]] use similar constructs, but to varying extent, and the file is not necessarily named "system.pas".
243	247
244	248		## See also
245	249
246	250		- FPC RTL System unit reference
247	251		- [[System unit structure]], some explanation about the distributed system unit
248	252		- [[Minimal RTL]]
249	253		- [[RTL development articles]]
250	254
251	255		---
252	256		From the Free Pascal wiki, page "System unit", as it stood on 2022-01-07 after a change by Alextp, 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).
253	257		Category: Code

Back to history