IDE Macros in paths and filenames: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | ## Types of Macros | |
| 2 | 2 | ||
| 3 | 3 | There are various types of macros: | |
| 4 | 4 | ||
| 5 | 5 | - **IDE macros**: they can be used in almost all IDE fields, e.g. search paths, custom options, file names, run parameters. They are replaced with their value before calling external tools like the compiler or the debugger. They are case insensitive. | |
| 6 | 6 | - **FPC symbols**: these are either defined (on) or undefined (off). They are passed via the command line option **-d**, which can be set under *Compiler Options / Custom Options*. For example *-dDEBUG -dVerbose* will define the FPC symbols DEBUG and Verbose, so you can use *{\$IFDEF Debug}*. They are case insensitive. | |
| 7 | 7 | - **FPC macros**: they are e.g. specified via code like {\$define MYFPCMACRO:=42}. An example of a predefined macro is FPC_FULLVERSION. | |
| 8 | 8 | - **Build macros**: they are IDE macros with a limited scope. They are defined by projects and packages and are case insensitive. | |
| 9 | 9 | - Some IDE plugins have their own macros. | |
| 10 | 10 | ||
| 11 | 11 | ## IDE macro format | |
| 12 | 12 | ||
| 13 | 13 | IDE macros are used in the following format. Replace the *macro-name* part with one of the macros listed below. | |
| 14 | 14 | ||
| 15 | 15 | `$(macro-name)` | |
| 16 | 16 | ||
| 17 | 17 | For example: This "Unit Output directory" is often used for Lazarus Packages: | |
| 18 | 18 | ||
| 19 | 19 | `lib/$(TargetCPU)-$(TargetOS)` | |
| 20 | 20 | ||
| 21 | 21 | - under a x86 Linux 32-bit system that would equate to: **lib/i386-linux** | |
| 22 | 22 | - under a x86 Linux 64-bit system that would equate to: **lib/x86_64-linux** | |
| 23 | 23 | ||
| 24 | 24 | There are also some **macro functions** that use the following format: | |
| 25 | 25 | ||
| 26 | 26 | `$macro_name(parameters)` | |
| 27 | 27 | ||
| 28 | 28 | For example | |
| 29 | 29 | ||
| 30 | 30 | `$Ext(unit1.pas)` | |
| 31 | 31 | ||
| 32 | 32 | will give *.pas*. | |
| 33 | 33 | ||
| 34 | 34 | ***Windows:*** Compiling to a RamDrive where each project gets its own unit directory (Project\> Options\> Unit Output Directory) | |
| 35 | 35 | ||
| 36 | 36 | ` R:\FPC\$NameOnly($(ProjFile))` | |
| 37 | 37 | ||
| 38 | 38 | ***MacOS:*** A more complex example but very useful, when you want to compile on its name ***\$NameOnly(\$(ProjFile))*** on a specific CPU target ***-\$(TargetCPU)**'' saving the compiled file on the package path***.app/Contents/MacOS/**'' | |
| 39 | 39 | ||
| 40 | 40 | `$NameOnly($(ProjFile))-$(TargetCPU).app/Contents/MacOS/$NameOnly($(ProjFile))-$(TargetCPU)` | |
| 41 | 41 | ||
| 42 | 42 | ## General Purpose | |
| 43 | 43 | ||
| 44 | 44 | - **Col** - current column in source editor | |
| 45 | 45 | - **Row** - current row in source editor (screen, can differ to byte position due to tabs and UTF-8) | |
| 46 | 46 | - **CurToken** - current token at the cursor in the source editor | |
| 47 | 47 | - **EdFile** - current filename in the source editor | |
| 48 | 48 | - **Params** - run parameters of the current project | |
| 49 | 49 | - **Prompt** - ask the user for a value. This is an interactive macro. | |
| 50 | 50 | - **RunCmdLine** - the command to launch the project | |
| 51 | 51 | - **Save** - save current file in source editor | |
| 52 | 52 | - **SaveAll** - save all | |
| 53 | 53 | - **TargetCmdLine** - the project executable (or host / i.e.: "\$TargetFile") plus run parameters | |
| 54 | 54 | ||
| 55 | 55 | ## Filename Parts | |
| 56 | 56 | ||
| 57 | 57 | - **Ext(filename)** - macro function for ExtractFileExt. Example: will return .exe on Windows. | |
| 58 | 58 | - **MakeDir(filename)** - macro function for AppendPathDelim | |
| 59 | 59 | - **MakeFile(filename)** - macro function for ChompPathDelim | |
| 60 | 60 | - **MakeExe(filename)** - change file extension to .exe under Windows, nothing under Linux, BSD, macOS. When cross compiling it will create a file name for the target OS. To get the file name of the host OS use \$MakeExe(ide,filename). To get the file name of a specific OS use \$MakeExe(os,filename). The two parameter variant exists since 1.1. | |
| 61 | 61 | - **MakeLib(filename)** - change file extension to .dll under Windows, under Linux/BSD change to lowercase libname.so, under macOS to libname.so (since 0.9.29) | |
| 62 | 62 | - **Name(filename)** - macro function for ExtractFileName | |
| 63 | 63 | - **NameOnly(filename)** - macro function for ExtractFileNameOnly | |
| 64 | 64 | - **Path(filename)** - macro function for ExtractFilePath | |
| 65 | 65 | ||
| 66 | 66 | ## Paths and Parts | |
| 67 | 67 | ||
| 68 | 68 | - **CompPath** - compiler path. Before 1.3 it returned the value of the IDE option (*Tools / Options ...*). It cannot use the macros FPCVer, FPC_FULLVERSION, because these macros are retrieved from the compiler. You can use the macros TargetOS, TargetCPU, SrcOS **only** if you set them. You can use LazarusDir and Env macros. Since 1.3 the macro returns the compiler of the project. It returns the default IDE option value: | |
| 69 | 69 | - when using the parameter *IDE*: \$CompPath(IDE) | |
| 70 | 70 | - in the project compiler option itself | |
| 71 | 71 | - when the project compiler is disabled (*Build*, *Compile*) | |
| 72 | 72 | - when the project compiler is not fpc or ppcsomething | |
| 73 | 73 | - when the IDE is built | |
| 74 | 74 | - **ConfDir** - directory where the IDE stores its config files (same as PrimaryConfigPath). | |
| 75 | 75 | - **ExeExt** - executable file extension for the operation system, independent of project's target OS. To get the extension for the current project target OS use \$MakeExe(). | |
| 76 | 76 | - **FallbackOutputRoot** - the directory where the IDE puts ppu files if the output directory of a package is not writable. Default: \$(PrimaryConfigPath)/lib. Since 0.9.31. | |
| 77 | 77 | - **FPCSrcDir** - FPC source directory set in environment options | |
| 78 | 78 | - **FPCMsgFile** - compiler messages file set in the Lazarus environment options (since 0.9.31). | |
| 79 | 79 | - **InstantFPCCache** - path of the instantfpccache. Output of running *instantfpc --get-cache* (since 0.9.31). | |
| 80 | 80 | - **LazarusDir** - Lazarus source directory set in Lazarus environment options. No macros allowed. | |
| 81 | 81 | - **Make** - path to the make utility (gmake under BSD) (since 0.9.29) | |
| 82 | 82 | - **PrimaryConfigPath** - the directory of the IDE's configuration files (since 0.9.31). See **SecondaryConfigPath**. | |
| 83 | 83 | - **ProjFile** - the full filename of the main source of the current project (.lpr) | |
| 84 | 84 | - **ProjIncPath** - include path of project directory | |
| 85 | 85 | - **ProjOutDir** - path of project output directory (e.g. where the .ppu files are created) (since 0.9.27) | |
| 86 | 86 | - **ProjPath** - the project directory (the directory of the .lpi file) | |
| 87 | 87 | - **ProjPublishDir** - publishing directory of the current project | |
| 88 | 88 | - **ProjSrcPath** - source path of project directory | |
| 89 | 89 | - **ProjUnitPath** - unit path of project directory | |
| 90 | 90 | - **Project(param)** - macro function for various values: | |
| 91 | 91 | - **Project(UnitPath)** - unit path of project directory | |
| 92 | 92 | - **Project(SrcPath)** - source path of project directory | |
| 93 | 93 | - **Project(IncPath)** - include path of project directory | |
| 94 | 94 | - **Project(InfoFile)** - filename of the project information file (.lpi) (since r15287, 0.9.25) | |
| 95 | 95 | - **Project(OutputDir)** - directory where the project's ppu files are created (since 0.9.27) | |
| 96 | 96 | - **Package macros** - these can be used in the fields of a package. For example in the search paths of a package. To use them elsewhere give a package name as parameter. | |
| 97 | 97 | - **\$(PkgName)** - in a package: gives the package name (since 0.9.31) | |
| 98 | 98 | - **\$PkgName(id)** - macro function for the name of a package ID given as parameter (since 0.9.31) | |
| 99 | 99 | - **\$(PkgDir)** - macro for the directory (location of the .lpk) of the package | |
| 100 | 100 | - **\$PkgDir(id)** - macro function for the directory (location of the .lpk) of a package ID given as parameter | |
| 101 | 101 | - **\$PkgIncPath(id)** - macro function for the include path of a package ID given as parameter | |
| 102 | 102 | - **\$PkgOutDir(id)** - macro function for the output directory of a package (e.g. where the ppu files are created) | |
| 103 | 103 | - **\$PkgSrcPath(id)** - macro function for the source path (unit path + src path) of a package ID given as parameter | |
| 104 | 104 | - **\$PkgUnitPath(id)** - macro function for the unit path of a package ID given as parameter | |
| 105 | 105 | - **SecondaryConfigPath** - the directory of the IDE's configuration templates (since 0.9.31). See **PrimaryConfigPath** | |
| 106 | 106 | - **OutputFile** - the output file (executable or library) of the current project build mode. This is the value from the "[[IDE Window: Project Options|Target file name]]" field of the Project Options (macros and relative paths are expanded). | |
| 107 | 107 | - **TargetFile** - executable file (or script) for launching a project. This is the value of the "[[IDE Window: Run parameters|Host application]]" parameter from the "Run parameters" window (by default it is empty and **OutputFile** is used). | |
| 108 | 108 | - **TestDir** - Test directory set in the Lazarus environment options | |
| 109 | 109 | ||
| 110 | 110 | ## Environment | |
| 111 | 111 | ||
| 112 | 112 | - **BuildMode** - the name of the active build mode (since 1.1) | |
| 113 | 113 | - **Env(name)** - macro function for environment variables given to the IDE (not project nor debugger) (see [GetEnvironmentVariableUTF8](http://lazarus-ccr.sourceforge.net/docs/lcl/fileutil/getenvironmentvariableutf8.html)) (since 0.9.27) | |
| 114 | 114 | - **IDEBuildOptions** - the extra options of the 'Configure Build Lazarus' dialog (since 0.9.29). In Makefile: empty. | |
| 115 | 115 | - **LanguageID** - IDE language, for example en for English, de for German | |
| 116 | 116 | - **LanguageName** - IDE language name, the translated name of the current language. For instance: Deutsch for German. | |
| 117 | 117 | - **LazVer** - Version string of the IDE (since 1.3). | |
| 118 | 118 | - **FPCVer** - FPC version (since 0.9.25). For example '2.4.2'. This version is fetched from the compiler \$(CompPath), which path is set in the Lazarus environment options. **FPCVer** depends on project's compiler path. | |
| 119 | 119 | - **FPC_FULLVERSION** - FPC version as one number (since 1.3). For example *20701*. This version is fetched from the compiler \$(CompPath), which path is set in the Lazarus environment options. **FPC_FullVersion** depends on project's compiler path. | |
| 120 | 120 | - **SrcOS** - 'unix' for linux, darwin, bsd. 'win' for win32, win64, wince. Since 0.9.31: Use **\$SrcOS(SomeOS)** to get the SrcOS of a specific OS, for example **\$SrcOS(\$TargetOS(IDE))** to get the SrcOS of the IDE executable. **SrcOS** depends on *TargetOS*. | |
| 121 | 121 | - **TargetOS** - Target OS of the current project. Since 0.9.31: Use **\$TargetOS(IDE)** to get the OS of the IDE executable. If the project has not set the **TargetOS** the IDE uses the default platform of the project's compiler (1.3 and below uses as default the IDE's platform). In Makefile it is converted to *%(OS_TARGET)*. | |
| 122 | 122 | - **TargetCPU** - similar to *TargetOS*. In Makefile it is converted to *%(OS_TARGET)*. | |
| 123 | 123 | - **Subtarget** - Subtarget of the current project. Since 3.99. | |
| 124 | 124 | - **FPCTarget** - works similar to the FPC config macro *\$fpctarget*. It's a shortform of **\$TargetCPU(param)-\$TargetOS(param)-\$SubTarget(param)**. The -SubTarget is omitted if empty. **\$FPCTarget(IDE)** returns the IDE's target, otherwise the project's target platform. Since Lazarus 3.99. | |
| 125 | 125 | - **LCLWidgetType** - LCL widgetset of the current project. In Makefile it is converted to *%(LCL_PLATFORM)*. | |
| 126 | 126 | ||
| 127 | - | ||
| 128 | - | ||
| 129 | 127 | # Macros in IDE addons | |
| 130 | 128 | ||
| 131 | 129 | Here is an incomplete list of macros added by IDE packages: | |
| 132 | 130 | ||
| 133 | 131 | ## Pas2jsDsgn | |
| 134 | 132 | ||
| 135 | 133 | - **Pas2JS** - Pas2JS executable | |
| 136 | 134 | - **Pas2JSBrowser** - Pas2JS selected Browser executable | |
| 137 | 135 | - **Pas2JSNodeJS** - Pas2JS selected NodeJS excutable | |
| 138 | 136 | - **Pas2JSProjectURL** - Pas2JS current project URL | |
| 139 | 137 | ||
| 140 | 138 | ## ProjectGroups | |
| 141 | 139 | ||
| 142 | 140 | - **PGSrcPaths** - source paths of all targets, i.e. projects, packages, etc. of the project group | |
| 143 | 141 | ||
| 144 | 142 | ## Delphi compiler tool | |
| 145 | 143 | ||
| 146 | 144 | - **DCC** - The delphi compiler executable path, as set in the global settings. | |
| 147 | 145 | - **DCCCONFIG** If the 'Generate compiler configuration' settting is checked, this contains the generated delphi compiler configuration file, prepended with @. If the setting is not set, the macro will be empty. | |
| 148 | 146 | - **DCCARGS** The combined values of the global and project 'Extra compiler arguments' settings. | |
| 149 | 147 | - **DCCCOMPILE** This is equivalent to \$(DCC) \$(DCCCONFIG) \$(DCCARGS). | |
| 150 | 148 | ||
| 151 | 149 | --- | |
| 152 | 150 | *From the Free Pascal wiki, page "IDE Macros in paths and filenames", as it stood on 2024-03-28 after a change by Mattias2, 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](/wiki-contact).* | |
| 153 | 151 | Category: IDE Macros | |
| 154 | 152 | Category: Lazarus |