$include

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:

1. at the path specified;
2. in the directory containing the current source file;
3. 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:

1. none, meaning the exact name as specified (without any suffix)
2. .inc
3. .pp
4. .pas
5. (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
  • {$include %FPCTargetCPU%} expands to the target’s CPU name, e. g. 'x86_64'.
  • {$include %FPCTargetOS%} expands to the target’s OS name, e. g. 'Linux'.
• 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. '//'.
  • {$include %dateYear%} expands to ''. (Available since FPC trunk revision 38329)
  • {$include %dateMonth%} expands to ''. (Available since FPC trunk revision 38329)
  • {$include %dateDay%} expands to ''. (Available since FPC trunk revision 38329)
  • {$include %time%} expands to a string of the form 'HH:MM:SS', e. g. ':42'.
  • {$include %timeHour%} expands to ''. (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

---

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.