$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. (
-Fior-Icompiler 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 date of invocation of the compiler
{$include %date%}expands to a string of the form'YYYY/mm/dd', e. g.'2024/04/24'.{$include %dateYear%}expands to'2024'. (Available since FPC trunk revision 38329){$include %dateMonth%}expands to'04'. (Available since FPC trunk revision 38329){$include %dateDay%}expands to'24'. (Available since FPC trunk revision 38329){$include %time%}expands to a string of the form'HH:MM:SS', e. g.'06:55:42'.{$include %timeHour%}expands to'06'. (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)
See also
- § “include file” and § “include compiler info” in the Free Pascal programmer’s guide
