$include: what changed
Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 1 | + | The [[Compiler directive|compiler directive]] `{$include}` is used to: | |
| 2 | 2 | ||
| 3 | - | ||
| 4 | - | ||
| 5 | - | ||
| 3 | + | * read and parse a file, virtually inserting its contents at the location the directive was encountered, | |
| 4 | + | * insert compiler information, or | |
| 5 | + | * insert the value of an environment variable. | |
| 6 | 6 | ||
| 7 | - | ||
| 7 | + | The `{$I}` directive, case-_sensitive_ , is shorthand for the same directive. | |
| 8 | 8 | ||
| 9 | 9 | ## Sourcing files | |
| 10 | 10 | ||
| 11 | - | ||
| 11 | + | 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}`. | |
| 12 | 12 | ||
| 13 | - | ||
| 13 | + | Files are searched for in the following order: | |
| 14 | 14 | ||
| 15 | - | ||
| 16 | - | ||
| 17 | - | ||
| 15 | + | 1. at the path specified; | |
| 16 | + | 2. in the directory containing the current source file; | |
| 17 | + | 3. in all include file paths. (`-Fi` or `-I` compiler parameters.) | |
| 18 | 18 | ||
| 19 | - | ||
| 19 | + | When specifying a file name, a file type hint suffix can be omitted. If you omit a suffix, the following suffixes are tried out: | |
| 20 | 20 | ||
| 21 | - | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 21 | + | 1. _none_ , meaning the exact name as specified (_without_ any suffix) | |
| 22 | + | 2. `.inc` | |
| 23 | + | 3. `.pp` | |
| 24 | + | 4. `.pas` | |
| 25 | + | 5. (trailing dot stripped) | |
| 26 | 26 | ||
| 27 | - | ||
| 27 | + | This strategy applies to every directory in the search path as described above, and the first match is taken. | |
| 28 | 28 | ||
| 29 | - | ||
| 29 | + | For Delphi compatibility, the special file name [[Asterisk|`*`]] 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 [[period|`.` (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. | |
| 30 | 30 | ||
| 31 | - | ||
| 31 | + | 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”). | |
| 32 | 32 | ||
| 33 | - | ||
| 33 | + | Not finding a specified file constitutes a [[compile-time error|fatal error]]. | |
| 34 | 34 | ||
| 35 | 35 | ## Insertion of certain information | |
| 36 | 36 | ||
| 37 | - | ||
| 37 | + | The compiler can be instructed to insert certain information at a specific spot. For that, a word is surrounded by [[Percent sign|`%`]] like in `{$include %internalVariable%}`. | |
| 38 | 38 | ||
| 39 | - | ||
| 39 | + | This directive always inserts [[String|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. | |
| 40 | 40 | ||
| 41 | - | ||
| 41 | + | The set of predefined variables are (case-insensitive): | |
| 42 | 42 | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 54 | - | ||
| 55 | - | ||
| 56 | - | ||
| 57 | - | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 43 | + | * location information | |
| 44 | + | * `{$include %currentRoutine%}` expands to the current routine’s name. (available since FPC trunk revision 30873; FPC 3.2.0) | |
| 45 | + | * `{$include %file%}` expands to the file’s name the directive is found in. | |
| 46 | + | * `{$include %line%}` expands to the line number (starting at 1) where the directive is found at. | |
| 47 | + | * `{$include %lineNum%}` is the same as `{$I %line%}` but of an integer type. | |
| 48 | + | * [[Free Pascal supported targets|target]] information | |
| 49 | + | * `{$include %FPCTargetCPU%}` expands to the target’s CPU name, e. g. `'x86_64'`. | |
| 50 | + | * `{$include %FPCTargetOS%}` expands to the target’s [[Operating System|OS]] name, e. g. [[Linux|`'Linux'`]]. | |
| 51 | + | * compiler information | |
| 52 | + | * `{$include %FPCVersion%}` expands to the version number of the used [[FPC]], e. g. `'3.0.4'`. | |
| 53 | + | * regarding time/date of processing the directive | |
| 54 | + | * `{$include %date%}` expands to a string of the form `'YYYY/mm/dd'`, e. g. `'2025/05/16'`. | |
| 55 | + | * `{$include %dateYear%}` expands to `'2025'`. (Available since FPC trunk revision 38329) | |
| 56 | + | * `{$include %dateMonth%}` expands to `'05'`. (Available since FPC trunk revision 38329) | |
| 57 | + | * `{$include %dateDay%}` expands to `'16'`. (Available since FPC trunk revision 38329) | |
| 58 | + | * `{$include %time%}` expands to a string of the form `'HH:MM:SS'`, e. g. `'02:33:42'`. | |
| 59 | + | * `{$include %timeHour%}` expands to `'02'`. (Available since FPC trunk revision 38329) | |
| 60 | + | * `{$include %timeMinute%}` expands to the minute part of `{$I %time%}`. (Available since FPC trunk revision 38329) | |
| 61 | + | * `{$include %timeSecond%}` expands to the seconds part of `{$I %time%}`. (Available since FPC trunk revision 38329) | |
| 62 | 62 | ||
| 63 | - | ||
| 63 | + | Historical remark: Previously _some_ information like `{$include %FPCVersion%}` and `{$include %date%}` could be included with the long deprecated utility [`fpcsubst`](<https://gitlab.com/freepascal.org/fpc/source/-/tree/3.3.1/utils/fpcsubst.pp>), a macro preprocessor program. | |
| 64 | 64 | ||
| 65 | 65 | ## See also | |
| 66 | 66 | ||
| 67 | - | ||
| 67 | + | * [§ include file](<https://www.freepascal.org/docs-html/prog/progsu40.html>) and | |
| 68 | + | * [§ include compiler info](<https://www.freepascal.org/docs-html/prog/progsu41.html>) in the _Free Pascal programmer’s guide_ | |
| 69 | + | * [[LCL Defines]] | |
| 68 | 70 | ||
| 69 | 71 | --- | |
| 70 | - | ||
| 72 | + | *From the Free Pascal wiki, page "$include", as the Internet Archive kept it on 2025-09-11, last changed on 2024-10-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](/wiki-contact).* |