$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}, 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}. The suffix .pas or .pp can be omitted.

The special file name * will attempt to include a file of the current module’s name.

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.)

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 date of invocation of the compiler
  • {$include %date%} expands to a string of the form 'YYYY/mm/dd', e. g. '2024/04/26'.
  • {$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 '26'. (Available since FPC trunk revision 38329)
  • {$include %time%} expands to a string of the form 'HH:MM:SS', e. g. '00:16:42'.
  • {$include %timeHour%} expands to '00'. (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