$include
│
Deutsch (de) │
English (en) │
The compiler directive {$include}
is used to:
- read and parse a file, virtually inserting its contents at the location the directive was encountered,
- insert compiler information, or
- insert the value of an environment variable.
The {$I}
directive, case-sensitive, is shorthand for the same directive.
Sourcing files
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}
.
Files are searched for in the following order:
- at the path specified;
- in the directory containing the current source file;
- in all include file paths. (
-Fi
or-I
compiler parameters.)
When specifying a file name, a file type hint suffix can be omitted. If you omit a suffix, the following suffixes are tried out:
- none, meaning the exact name as specified (without any suffix)
.inc
.pp
.pas
- (trailing dot stripped)
This strategy applies to every directory in the search path as described above, and the first match is taken.
For Delphi compatibility, the special file name *
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 .
(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.
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”).
Not finding a specified file constitutes a fatal error.
Insertion of certain information
The compiler can be instructed to insert certain information at a specific spot.
For that, a word is surrounded by %
like in {$include %internalVariable%}
.
This directive always inserts 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.
The set of predefined variables are (case-insensitive):
- location information
{$include %currentRoutine%}
expands to the current routine’s name. (available since FPC trunk revision 30873; FPC 3.2.0){$include %file%}
expands to the file’s name the directive is found in.{$include %line%}
expands to the line number (starting at 1) where the directive is found at.{$include %lineNum%}
is the same as{$I %line%}
but of an integer type.
- target information
- compiler information
{$include %FPCVersion%}
expands to the version number of the used FPC, e. g.'3.0.4'
.
- regarding time/date of processing the directive
{$include %date%}
expands to a string of the form'YYYY/mm/dd'
, e. g.'2024/10/26'
.{$include %dateYear%}
expands to'2024'
. (Available since FPC trunk revision 38329){$include %dateMonth%}
expands to'10'
. (Available since FPC trunk revision 38329){$include %dateDay%}
expands to'26'
. (Available since FPC trunk revision 38329){$include %time%}
expands to a string of the form'HH:MM:SS'
, e. g.'09:26:42'
.{$include %timeHour%}
expands to'09'
. (Available since FPC trunk revision 38329){$include %timeMinute%}
expands to the minute part of{$I %time%}
. (Available since FPC trunk revision 38329){$include %timeSecond%}
expands to the seconds part of{$I %time%}
. (Available since FPC trunk revision 38329)
Historical remark:
Previously some information like {$include %FPCVersion%}
and {$include %date%}
could be included with the long deprecated utility fpcsubst
, a macro preprocessor program.
See also
- § include file and
- § include compiler info in the Free Pascal programmer’s guide
- LCL Defines