$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}, case-sensitive, is shorthand for the same directive.

sourcing files

Further tokens can be read from a file, to the effect that the {$include} directive is virtually substituted by the file’s contents. In order to do so, one specifies a file name as the first argument, like this {$include magic.pas}. The suffix .pp can be omitted.

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

Files are searched in the following order:

1. At the path specified.
2. In the directory where the current source file is.
3. In all include files path. (-Fi or -I compiler parameters.)

Not being able to find a file constitutes a fatal error.

insertion of an internal date

The compiler can be instructed to insert a single date at a specific spot. For that, a word is surrounded by % like in {$include %internalVariable%}.

This directive always inserts strings (except {$include %lineNum%}). Primarily a set of predefined variables are consulted. Secondarily, if there is no predefined variable of a given name, the value of the environment variable of the given name is tried to retrieved. If everything fails, an empty string is inserted in order to provide a consistent behavior.

The set of predefined variables are (case-insensitive):

• LOC information
  • {$include %currentRoutine%} expands to the current routine’s name. (available since FPC trunk revision 34525)
  • {$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/05/7'.
  • {$include %dateYear%} expands to '2024'. (Available since FPC trunk revision 38329)
  • {$include %dateMonth%} expands to '05'. (Available since FPC trunk revision 38329)
  • {$include %dateDay%} expands to '7'. (Available since FPC trunk revision 38329)
  • {$include %time%} expands to a string of the form 'HH:MM:SS', e. g. '00:55: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