# IDE Window: Compiler Options

Deutsch (de) English (en) español (es) français (fr) 日本語 (ja) русский (ru)

## Paths

Here are the general rules about search paths:

• Relative paths are expanded with the project or package directory (where .lpi/.lpk file is).
• These paths are added to the search paths. They do not replace existing paths.
• The IDE has one set of search paths for every package/project. That means a package can have different search paths than the active project.
"set of search paths" refers to unit search path, include search path, sources search path, ...
• If a package or project uses a package, it will inherit the usage search paths. You can see the inherited search paths in the Inherited page.
• If you do not want to use a search path inherited from a used package you must change the compiler options of the used package.
• Using the Lazarus package system, you hardly ever need to set search paths manually.
• The FreePascal Compiler has a configuration file of its own (default /etc/fpc.cfg) which defines a set of search paths to the FPC ppu files. For example to find the FPC units of the RTL or the FCL like 'classes', 'sysutils'. Do not add search paths to source files (.pas, .inc) in there.
• Search paths are separated by semicolon ';'.
• Leading and trailing spaces are ignored and automatically removed by the IDE. The IDE normalizes search paths and appends the path delimiter (Windows: \, all other: /). Search paths are automatically converted to the current operating system when opening an lpi or lpk file.
• You can use macros. For example $(TargetCPU). See IDE Macros in paths and filenames. • The IDE has one set of paths settings per directory: • Every directory in the unit search path of the project gets all the project search paths. • Every directory in the unit search path of the package gets all the package search paths. • Other directories get the project search paths. If the project search path contains the '.' the directory will see the project directory too. • Using "uses unitname in 'filename'" does not affect any search path. ### Other Unit Files This is the search path for the Pascal units (.ppu, .pp, .pas, .p) of the project or package. See the title of the window to know which. This path is given to the FreePascal Compiler, which adds it to its Unit Path. • Adding and removing units to the project/package will automatically ask to adjust the unit path. • This search path contains the directories of your project (or your package) that contain the .pas, .pp or .p files. • If you want to share some units between your projects, create a package for them. It's easy. Note: Do not add directories of used Lazarus packages to this path. Otherwise FPC will rebuild the .ppu files of the package and put them into your project directory. You will end up with multiple .ppu versions and you will get strange 'Can not find unit' errors. For example: Do not add any FPC or LCL source directory to this search path. ### Include Files This is the search path for the include files (e.g. .inc, .lrs files). This path is given to the FreePascal Compiler, which adds it to its Include Path, which is used by include directives like {$I filename.inc} or {$INCLUDE filename.inc}. ### Other sources This is a search path for Pascal unit sources which is only used by the Lazarus IDE (not by the compiler). Normally you will leave this empty. It is only useful when you build the ppu files without Lazarus. Example: You have a directory with sources and another directory with the corresponding .ppu files and you can't or don't want to create a Lazarus package. You add the .ppu directory to the 'Other Unit Files' path and the .pas directory to the 'Other sources' path. This way the compiler will use the .ppu files and not try to rebuild them every time. Also, the IDE will find the sources and Find Declaration works. ### Libraries This is the search path for libraries (.dll or .so or .a files). These are only used in the compiling/linking phase; e.g. when running your application under the debugger, you need to make sure required libraries are present in the expected place (e.g. - depending on platform - executable directory, PATH, .so/.dylib search path). ### Unit output directory This is the directory where the compiler will put all output, like .ppu, .o, .rst files (it passes this to compiler switch -FU). If you are using the$R directive for the lfm files, it will also copy the lfm files there.

A popular usage example is a output directory named units, and then an extra sub-directory for the CPU and OS target. For example:

units/$(TargetCPU)-$(TargetOS)

Notes:

• If the unit output directory is empty, Lazarus will not pass the -FU switch to the compiler. The compiler will then use the -FE switch. See Project target file
• Packages normally inherit their output directory to other packages via the 'usage' options. You do not need to add package paths manually to your project.

### Syntax Options

• C Style Operators (*=, +=, /= and -=)
• Include Assertion Code
• Allow LABEL and GOTO
• C++ Styled INLINE
• C Style Macros (global)
• Constructor name must be init (destructor must be done)
• Static Keyword in Objects
• Use AnsiStrings

### Assembler style

Sets the value of -R<x> option:

• -Rdefault: use default assembler
• -Ratt: use AT&T style assembler
• -Rintel: use Intel style assembler

## Code

For debug settings, see Debugger_Setup#Project_Options

## Verbosity

See Free Pascal - Online documentation. Note that adding a lot of verbosity slows down the parsing of the compiler output much, even if most of the messages will be hidden in the messages view.

## Messages

(Introduced in Lazarus 0.9.27 version) The page allows to control what compiler output Notes, Hints and Warnings are shown. The feature requires FP compiler to support -m switch (version 2.2.2 or higher).

It's also possible to specify message Language file (file should be Utf-8 encoded), to see compiler messages translated, without need to modify fpc.cfg file.

Samples of the messages translation file can be found at ${LazarusDir}/fpc/${FPCTARGET}/msg, i.e. C:\Lazarus\fpc\2.2.3\msg

## Custom Options

You'll typically define some compiler options here. For example you can define in a build mode something like

-dRELEASE

Then in the build mode, only the code surrounded by the {$IFDEF RELEASE} {$ENDIF} will be compiled. This can be used alternatively to the Macro system, particularly if you come from Delphi.

Spaces at start and end are removed. Line breaks are replaced by a space before passing to the compiler. A leading space is added automatically.

The IDE substitutes IDE macros in custom options and parses the options. Flags like -dRelease are passed to codetools, so the source editor knows them immediately.

Warning: Do not add the path options -Fu, -Fi, -Fl, -FU, -o. Use the fields on the page Paths instead. The IDE ignores the paths in the custom options. It does not update them, when you add or delete files or when you open the project on another host.

The page "Additions and Overrides" exists since 1.1.

### Overview

The page contains a matrix of build options.

The settings "custom options", "output directory", and "IDE Macros" within any target can be switched on and off separately for each build mode.

Thus, for each target, there is a Matrix of enabling check boxes.

The vertical words in the header show all the Build Modes that are currently defined, and by this they denote the column in the matrices.

At the right side of each row of any matrix, the description of the type (such as "Custom", "OutDir", or "IDE Macro" ) and the value of the option to be enabled, is given.

### Types of build options

A build option can

• set an IDE macro. The value must be of the form MacroName:=Value. For instance LCLWidgetType:=qt. You can use IDE macros in the value, but not in the name.
• append some custom compiler options via Custom (e.g. append -O3). You do not need a leading space. That is added automatically. See the notes about Custom options.
• override the output directory (-FU) via OutDir. Note that when you use a relative directory like lib/$(TargetOS) the working directory of the target is added, not the project directory. For example when the option overrides the output directory of the package SynEdit, then the output directory of synedit is changed to <lazarusdir>/components/synedit/lib/$(TargetOS).

You can create a new option by clicking on the Add button above the matrix. You can change the type of an option at any time.

### Enabling build options in build modes

An option can be enabled with the build modes of the project. You can enable the option only in one build mode or several of them. Each build option has a row in the matrix, each build mode has a column in the matrix. Each combination has a checkbox. Build options are applied from top to bottom.

Note that enabling options in build modes of the session (stored in the .lps) does not alter the lpi file. This information is stored in the lps file. That's why these checkboxes have a yellow background.

The currently active build mode and options have a green background.

When you rename a build mode the enabled states of the lpi and lps options are migrated too. The enabled states of IDE options are *not* migrated. For example when an IDE option is enabled for mode debug and you rename the mode to Test, then the IDE option is still enabled for mode debug for other projects.

### Storage location of build options

An option can be stored in

• the project (.lpi)
• the project session (.lps)
• or in the IDE configuration (environmentoptions.xml), then it is available to all projects

Build options are applied from top to bottom. That means first the options stored in the IDE, then the options stored in the .lpi and last the options stored in the session.

You can move build options and whole targets via the Up and Down button above the matrix to other storage groups.

Note: An option in the IDE configuration for mode debug is applied to all projects with this mode. For instance when you open a third party project having the build mode debug the option will be applied and there will be no warning. This might break the project.

### Targets of build options

A build option can be applied to the project and/or to one or more packages. You can limit the scope of the build options to only apply to specific targets (project, packages). Build options are grouped by Targets. The targets are case insensitive and allow the asterisk "*" for any number of arbitrary characters and the question mark "?" for one arbitrary character. You can exclude targets by prepending a minus "-". To edit a target click behind the 'Targets:'.

Examples of targets:

• *: The asterisk "*" means fits all. The option is applied to the project and all packages. This is the default.
• LCL,Lazutils: Apply it only to package "LCL" and "LazUtils"
• *dsgn,-syneditdsgn: Apply it to all packages ending with "dsgn", except "syneditdsgn".
• #project: This fits the project itself. The option is applied only to the project, not to the used packages.
• #ide: This fits the IDE. The option is applied only to the IDE, not to installed packages.

You can have any number of targets. You can create a new target via the the Add button above the matrix. You can move targets via the up and down buttons to other storages. All build options of the target group are moved as well.

### Colors in the matrix

• Green: currently active mode and options
• Yellow: stored in session, not altering the lpi
• Red: syntax error

### Examples for additions and overrides

• Append compiler options to packages without touching the lpk. For example you can append range checking -Cr via custom option under Targets: *.
• Changing the output directory of packages without touching the lpk. For example add a OutDir under Targets: *.
• Define IDE macros only for some packages or only for the project. For example compile the LCL with flag -dQT_NATIVE_DIALOGS, add a new target Targets: LCL, then add a custom option.
• Append compiler options to all projects with build mode "debug" by adding options to the IDE storage group.
• Change the package(s) output directory for all projects with build mode "release". Add the build option to the options stored in the IDE.
• Combine the above with sessions and you can alter third party projects and packages without touching them.

#### Changing the LCLWidgetType in Version 1.1 and above

This setting is only available when the project uses the package LCL.

Go to Project > Project Options > Comiler Options > Additions and Overrides > Set "LCLWidgetType".

#### Add a flag to project and all packages

Note: This modifies the project (.lpi). It does not alter the package files (.lpk), but it effects them when you build the project. It also effects building the IDE.

Go to Additions and Overrides. Click on the Add button and select Custom Option:

You should now see a "Targets: *" and the new option. It is enabled for the currently active build mode and disabled for all other. The Targets: * means it applies to the project and all packages.

Click in the value cell behind the option and add your flag. For example: -dSomeFlag.

That's it.

#### Add a flag to all projects and packages

The flag from the previous paragraph is only active when the project is loaded. To set the flag for all projects, select the option and click on the up button (green arrow up). This moves the option to the "Stored in IDE" group.

Note: The IDE uses the options of build mode "default".

#### Change the output directory of project and all packages

Go to Additions and Overrides. Click on the Add button and select Output Directory (-FU).

You should now see a "Targets: *" and the new option "OutDir" with the default value lib/$(TargetCPU)-$(TargetOS)/$(BuildMode). It is enabled for the currently active build mode and disabled for all other. The Targets: * means it applies to the project and all packages. For example: Click in the value cell behind the option and change it to lib/$(FPCVer)/$(TargetCPU)-$(TargetOS). This will use different output directories for each Free Pascal compiler version.

If you want to use the same output directories for all your projects, you can put the option under Stored in IDE. Click in the value cell of the OutDir option to select the row. Then use the Up (arrow up) button to move the option.

If you want to apply the output directory to all packages, but not projects, change the Targets value from * to *,-#project.

Note: If a package does not support your output directory, append to Targets value -packagename. For example: *,-chmhelp.

### Execute after

Provide an (optional) command to execute after running the compiler. See above 'Execute before' for details.

One handy usage might be to automatically copy your cross-compiled executable from your PC onto your target device, e.g. a Raspberry:

scp "$TargetFile()" pi@raspberry:/home/pi/bin (And yes, this works even without a password, if you create a key pair with ssh-keygen and then add it to sour target's authorized_keys file via "ssh-copy-id [remoteuser@]remotehost"; for details see here) ## Inherited Note: This was moved in Lazarus 1.1 to the Show Options dialog. This page shows all the compiler options inherited from packages. Packages inherit options via their usage options. The topmost node shows all inherited options, that is the sum of all used packages. The nodes below show the inherited options of each used package. You can see/edit the set the used packages for the project in the project inspector. You can see/edit the set of used packages for a package in the package editor. For information about packages in general see Lazarus Packages. ## Use these settings as default for new projects Check this checkbox and click Ok. The settings will be saved to ~/.lazarus/compileroptions.xml (or whatever you have as primary config path). When you create a new project this file will be loaded to initialize the compiler options. This feature exists since 0.9.29. ## Buttons ### Test This will run various test and detects common configurations mistakes. For fpc 2.2.0 it will warn about some double units. The warnings are correct, but you can ignore them, if you don't use these units. ### Show Options Opens a dialog and presents the current command line parameters. ### Load/Save Opens a dialog to save and/or load the current compiler options from/to a xml file. ### Ok This will apply the changes and then exit the dialog. ### Cancel This will undo all changes and exits the dialog. ## IDE Macros ### For 0.9.29 to 1.0.x This page allows to define your project/package specific macros and conditionals. The IDE already provides a lot of macros. You can add your own macros that are valid when the project/package is loaded. Conditionals allow to set macro values depending on target platform and other macros. For example you can add a linker option when compiling for Mac OS X. Use the left + button to add a new macro for the project/package. Select a macro and click on the middle + button to add a new possible value. The actual value of a macro is set in the conditionals below, or by the current project on the build modes page (IDE menu / Project / Project Options / Compiler options / Build Modes). To delete a value or a macro, select it and click on the - button. The conditionals use a scripting language similar to pascal and are edited in the text editor at the bottom of the page. Many short cuts work like in the source editor, including word/identifier completion (default: Ctrl+Space). For more details about build macros and conditionals see Macros and Conditionals. This page exists since version 0.9.29. ### For 1.1 and above This page is only available for packages. It lets packages define their own IDE macros. The IDE already provides a lot of macros itself. Use the left + button to add a new macro for the project/package. Select a macro and click on the middle + button to add a new possible value. The actual value of a macro is set in the conditionals below, or by the current project on the build modes page (IDE menu / Project / Project Options / Compiler options / Build Modes). To delete a value or a macro, select it and click on the - button. For more details about build macros and conditionals see Macros and Conditionals. ## Other You'll typically define some compiler options here. For example you can define in a build mode something like -dRELEASE Then in the build mode, only the code surrounded by the {$IFDEF RELEASE} {\$ENDIF} will be compiled. This can be used alternatively to the Macro system, particularly if you come from Delphi.

Spaces at start and end are removed. Line breaks are replaced by a space before passing to the compiler. A leading space is added automatically.

The IDE substitutes IDE macros in custom options and parses the options. Flags like -dRelease are passed to codetools, so the source editor knows them immediately.

Warning: Do not add the path options -Fu, -Fi, -Fl, -FU, -o. Use the fields on the page Paths instead. The IDE ignores the paths in the custom options. It does not update them, when you add or delete files or when you open the project on another host.

Clicking the All options... button allows you to set FPC options easily: