Sign in Join
Wiki copytemporary

$include: what changed

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

OldNewLine
1-The [[Compiler directive|compiler directive]]
2-
3-``` pascal
4-{$include}
5-```
6-
7-is used to:
1+The [[Compiler directive|compiler directive]] `{$include}` is used to:
82
93- read and parse a file, virtually inserting its contents at the location the directive was encountered,
104- insert compiler information, or
115- insert the value of an environment variable.
126
13-The
14-
15-``` pascal
16-{$I}
17-```
18-
19-directive, case-*sensitive*, is shorthand for the same directive.
7+The `{$I}` directive, case-*sensitive*, is shorthand for the same directive.
208
219## Sourcing files
2210
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-.
11+Further tokens can be read from a file using the `{$include}` directive to virtually substitute the file’s contents for the directive. A file to be substituted for the directive is specified like this `{$include magic.pas}`.
3612
3713Files are searched for in the following order:
3814
39151. at the path specified;
40162. 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.)
17+3. in all include file paths. (`-Fi` or `-I` compiler parameters.)
5318
5419When specifying a file name, a file type hint suffix can be omitted. If you omit a suffix, the following suffixes are tried out:
5520
56211. *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-
22+2. `.inc`
23+3. `.pp`
24+4. `.pas`
70255. (trailing dot stripped)
7126
7227This strategy applies to every directory in the search path as described above, and the first match is taken.
7328
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-```
29+For Delphi compatibility, the special file name [[Asterisk|*]] 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: `{$include *.dat}` will look for a file bearing same name as the source file, but the suffix (if applicable) will be replaced by (or augmented with) `.dat`. The suffix is the *last* component of a file name separated by a [[period|. (dot)]] (thus `{$I *.foo.bar.dat}` is effectively the same as `{$I *.dat}`). 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.
12930
130-denotes the “current directory”).
31+If a file name contains blank characters, the file name needs to be surrounded by [[&|' (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 `{$I ./%wage.pas}` (on UNIX-like platforms `./` denotes the “current directory”).
13132
13233Not finding a specified file constitutes a [[compile-time error|fatal error]].
13334
13435## Insertion of certain information
13536
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-```
37+The compiler can be instructed to insert certain information at a specific spot. For that, a word is surrounded by [[Percent sign|%]] like in `{$include %internalVariable%}`.
15538
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.
39+This directive always inserts [[String|strings]] (except `{$include %lineNum%}`). 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.
15740
15841The set of predefined variables are (case-insensitive):
15942
16043- 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.
44+ - `{$include %currentRoutine%}` expands to the current routine’s name. (available since FPC trunk revision 30873; FPC 3.2.0)
45+ - `{$include %file%}` expands to the file’s name the directive is found in.
46+ - `{$include %line%}` expands to the line number (starting at 1) where the directive is found at.
47+ - `{$include %lineNum%}` is the same as `{$I %line%}` but of an integer type.
19048- [[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- \]\].
49+ - `{$include %FPCTargetCPU%}` expands to the target’s CPU name, e. g. `'x86_64'`.
50+ - `{$include %FPCTargetOS%}` expands to the target’s [[Operating System|OS]] name, e. g. [[Linux|'Linux']].
21451- 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- .
52+ - `{$include %FPCVersion%}` expands to the version number of the used [[FPC]], e. g. `'3.0.4'`.
22653- 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-```
54+ - `{$include %date%}` expands to a string of the form `'YYYY/mm/dd'`, e. g. <span class="s">`'//'`</span>.
55+ - `{$include %dateYear%}` expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
56+ - `{$include %dateMonth%}` expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
57+ - `{$include %dateDay%}` expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
58+ - `{$include %time%}` expands to a string of the form `'HH:MM:SS'`, e. g. <span class="s">`':42'`</span>.
59+ - `{$include %timeHour%}` expands to <span class="s">`''`</span>. (Available since FPC trunk revision 38329)
60+ - `{$include %timeMinute%}` expands to the minute part of `{$I %time%}`. (Available since FPC trunk revision 38329)
61+ - `{$include %timeSecond%}` expands to the seconds part of `{$I %time%}`. (Available since FPC trunk revision 38329)
31662
317-\], a macro preprocessor program.
63+Historical remark: Previously *some* information like `{$include %FPCVersion%}` and `{$include %date%}` could be included with the long deprecated utility [`fpcsubst`](https://gitlab.com/freepascal.org/fpc/source/-/tree/3.3.1/utils/fpcsubst.pp), a macro preprocessor program.
31864
31965## See also
32066
32167- [§ “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*
32268
32369---
32470*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