$include: what changed

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

Title: $include

New		Line
1	+	The [[Compiler directive\|compiler directive]]
2	+
3	+	``` pascal
4	+	{$include}
5	+	```
6	+
7	+	is used to:
8	+
9	+	- read and parse a file, virtually inserting its contents at the location the directive was encountered,
10	+	- insert compiler information, or
11	+	- insert the value of an environment variable.
12	+
13	+	The
14	+
15	+	``` pascal
16	+	{$I}
17	+	```
18	+
19	+	directive, case-sensitive, is shorthand for the same directive.
20	+
21	+	## Sourcing files
22	+
23	+	Further tokens can be read from a file using the
24	+
25	+	``` pascal
26	+	{$include}
27	+	```
28	+
29	+	directive to virtually substitute the file’s contents for the directive. A file to be substituted for the directive is specified like this
30	+
31	+	``` pascal
32	+	{$include magic.pas}
33	+	```
34	+
35	+	.
36	+
37	+	Files are searched for in the following order:
38	+
39	+	1. at the path specified;
40	+	2. in the directory containing the current source file;
41	+	3. in all include file paths. (
42	+	``` bash
43	+	-Fi
44	+	```
45	+
46	+	or
47	+
48	+	``` bash
49	+	-I
50	+	```
51	+
52	+	compiler parameters.)
53	+
54	+	When specifying a file name, a file type hint suffix can be omitted. If you omit a suffix, the following suffixes are tried out:
55	+
56	+	1. none, meaning the exact name as specified (without any suffix)
57	+
58	+	2. ```text
59	+	.inc
60	+	```
61	+
62	+	3. ```text
63	+	.pp
64	+	```
65	+
66	+	4. ```text
67	+	.pas
68	+	```
69	+
70	+	5. (trailing dot stripped)
71	+
72	+	This strategy applies to every directory in the search path as described above, and the first match is taken.
73	+
74	+	For Delphi compatibility, the special file name \[\[Asterisk\\|
75	+
76	+	``` bash
77	+	*
78	+	```
79	+
80	+	\]\] will attempt to include a file of the current file’s base name. The suffix is supplemented as described above. You can, however, specify a (different) suffix too:
81	+
82	+	``` pascal
83	+	{$include *.dat}
84	+	```
85	+
86	+	will look for a file bearing same name as the source file, but the suffix (if applicable) will be replaced by (or augmented with)
87	+
88	+	```text
89	+	.dat
90	+	```
91	+
92	+	. The suffix is the last component of a file name separated by a \[\[period\\|
93	+
94	+	``` bash
95	+	.
96	+	```
97	+
98	+	(dot)\]\] (thus
99	+
100	+	``` pascal
101	+	{$I *.foo.bar.dat}
102	+	```
103	+
104	+	is effectively the same as
105	+
106	+	``` pascal
107	+	{$I *.dat}
108	+	```
109	+
110	+	). Note, if you are reading a file via a symbolic link, the supplied unresolved name is the source code file’s name, not the target file name.
111	+
112	+	If a file name contains blank characters, the file name needs to be surrounded by \[\['\\|
113	+
114	+	``` pascal
115	+	'
116	+	```
117	+
118	+	(typewriter quotes)\]\]. If a file name starts with a percent sign or asterisk, you must either use straight quotes as in the case of blanks, or specify an absolute or relative path like
119	+
120	+	``` pascal
121	+	{$I ./%wage.pas}
122	+	```
123	+
124	+	(on UNIX-like platforms
125	+
126	+	``` bash
127	+	./
128	+	```
129	+
130	+	denotes the “current directory”).
131	+
132	+	Not finding a specified file constitutes a [[compile-time error\|fatal error]].
133	+
134	+	## Insertion of certain information
135	+
136	+	The compiler can be instructed to insert certain information at a specific spot. For that, a word is surrounded by \[\[Percent sign\\|
137	+
138	+	``` pascal
139	+	%
140	+	```
141	+
142	+	\]\] like in
143	+
144	+	``` pascal
145	+	{$include %internalVariable%}
146	+	```
147	+
148	+	.
149	+
150	+	This directive always inserts [[String\|strings]] (except
151	+
152	+	``` pascal
153	+	{$include %lineNum%}
154	+	```
155	+
156	+	). A set of predefined variables are consulted first. If there is no predefined variable of a given name, the value of the environment variable of the given name is tried to be retrieved. If this process fails, an empty string is inserted in order to provide a consistent behavior.
157	+
158	+	The set of predefined variables are (case-insensitive):
159	+
160	+	- location information
161	+	- ``` pascal
162	+	{$include %currentRoutine%}
163	+	```
164	+
165	+	expands to the current routine’s name. (available since FPC trunk revision 30873; FPC 3.2.0)
166	+
167	+	- ``` pascal
168	+	{$include %file%}
169	+	```
170	+
171	+	expands to the file’s name the directive is found in.
172	+
173	+	- ``` pascal
174	+	{$include %line%}
175	+	```
176	+
177	+	expands to the line number (starting at 1) where the directive is found at.
178	+
179	+	- ``` pascal
180	+	{$include %lineNum%}
181	+	```
182	+
183	+	is the same as
184	+
185	+	``` pascal
186	+	{$I %line%}
187	+	```
188	+
189	+	but of an integer type.
190	+	- [[Free Pascal supported targets\|target]] information
191	+	- ``` pascal
192	+	{$include %FPCTargetCPU%}
193	+	```
194	+
195	+	expands to the target’s CPU name, e. g.
196	+
197	+	``` pascal
198	+	'x86_64'
199	+	```
200	+
201	+	.
202	+
203	+	- ``` pascal
204	+	{$include %FPCTargetOS%}
205	+	```
206	+
207	+	expands to the target’s [[Operating System\|OS]] name, e. g. \[\[Linux\\|
208	+
209	+	``` pascal
210	+	'Linux'
211	+	```
212	+
213	+	\]\].
214	+	- compiler information
215	+	- ``` pascal
216	+	{$include %FPCVersion%}
217	+	```
218	+
219	+	expands to the version number of the used [[FPC]], e. g.
220	+
221	+	``` pascal
222	+	'3.0.4'
223	+	```
224	+
225	+	.
226	+	- regarding time/date of processing the directive
227	+	- ``` pascal
228	+	{$include %date%}
229	+	```
230	+
231	+	expands to a string of the form
232	+
233	+	``` pascal
234	+	'YYYY/mm/dd'
235	+	```
236	+
237	+	, e. g. <span class="s">`'//'`</span>.
238	+
239	+	- ``` pascal
240	+	{$include %dateYear%}
241	+	```
242	+
243	+	expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
244	+
245	+	- ``` pascal
246	+	{$include %dateMonth%}
247	+	```
248	+
249	+	expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
250	+
251	+	- ``` pascal
252	+	{$include %dateDay%}
253	+	```
254	+
255	+	expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
256	+
257	+	- ``` pascal
258	+	{$include %time%}
259	+	```
260	+
261	+	expands to a string of the form
262	+
263	+	``` pascal
264	+	'HH:MM:SS'
265	+	```
266	+
267	+	, e. g. <span class="s">`':42'`</span>.
268	+
269	+	- ``` pascal
270	+	{$include %timeHour%}
271	+	```
272	+
273	+	expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
274	+
275	+	- ``` pascal
276	+	{$include %timeMinute%}
277	+	```
278	+
279	+	expands to the minute part of
280	+
281	+	``` pascal
282	+	{$I %time%}
283	+	```
284	+
285	+	. (Available since FPC trunk revision 38329)
286	+
287	+	- ``` pascal
288	+	{$include %timeSecond%}
289	+	```
290	+
291	+	expands to the seconds part of
292	+
293	+	``` pascal
294	+	{$I %time%}
295	+	```
296	+
297	+	. (Available since FPC trunk revision 38329)
298	+
299	+	Historical remark: Previously some information like
300	+
301	+	``` pascal
302	+	{$include %FPCVersion%}
303	+	```
304	+
305	+	and
306	+
307	+	``` pascal
308	+	{$include %date%}
309	+	```
310	+
311	+	could be included with the long deprecated utility \[<https://gitlab.com/freepascal.org/fpc/source/-/tree/3.3.1/utils/fpcsubst.pp>
312	+
313	+	``` pascal
314	+	fpcsubst
315	+	```
316	+
317	+	\], a macro preprocessor program.
318	+
319	+	## See also
320	+
321	+	- [§ “include file”](https://www.freepascal.org/docs-html/prog/progsu40.html) and [§ “include compiler info”](https://www.freepascal.org/docs-html/prog/progsu41.html) in the Free Pascal programmer’s guide
322	+
323	+	---
324	+	From the Free Pascal wiki, page "$include", as it stood on 2022-10-04 after a change by Kai Burghardt, 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