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.
• The IDE has one set of search paths for every directory. That means a package can have different search paths than the active project.
• 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.
• Using the Lazarus package system, you hardly 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 a lpi or lpk file.
• You can use macros. For example $(TargetCPU). See IDE Macros in paths and filenames.
• 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.
• 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.
• BEWARE: 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.

• If you want to share some units between your projects, create a package for them. It's easy.

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 the search path for pascal unit sources, that is only used by the IDE and 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. And the IDE will find the sources and Find Declaration works.

Libraries

This is the search path for libraries (.dll or .so or .a files).

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.

Target file name

Note: Only projects have this. This option is not available for packages.

Set here the filename of the generated executable. If the file is relative it will be expanded with the project directory (where the .lpi file is). If no file is given the executable is put into the unit output directory and has the name of the main source file name (usually the .lpr file) without the extension. If no extension is given, the default extension for the platform is added (e.g. .exe for MS Windows, none for others). When a new project was not yet saved and is built the IDE saves the files to the test directory. The relative files are then relative to this directory.

Lazarus passes the compiler switch

• -o to define the target file name.
• -FE if the target file name is not in the project directory (where the lpi file is)
• -FU if the unit output directory is not empty

If the target file name is in another directory (not the directory of the .lpi file), Lazarus will pass the -FE switch to the compiler to make sure that the secondary files, like .o and .rst are put into the same directory. If you cleared the unit output directory then the IDE will not pass the -FU switch and the compiler will generate the .ppu/.o files of the units in the target directory too.

If you cleared the unit output directory and your project target file is in the project directory, then neither -FU nor -FE is passed to the compiler and the compiler will work Delphi compatible and generate the .ppu/.o file of each unit in the same directory as the unit.

Apply Conventions

Enable this to apply various naming conventions depending on the target platform.

• Windows: If it is program append the '.exe' extension, if it is a library it appends '.dll'.
• Unix (e.g. Linux, BSD, Darwin/OS X): If it is a library the name is lowercased and if the name does not start with 'lib' it prepends 'lib'.
• Linux, BSD: If it is a library it appends '.so'.
• Darwin/OS X: If it is a library it appends '.dylib'.

Debugger path addition

These directories are added to the search path of the IDE debugger, when it searches for sources (units and include files).

LCL widget type (pre Lazarus 1.0)

In older Lazarus releases: this is the used LCL widget set. Normally the default widget set is used. If you want to try another or you are cross compiling, select another widget set here.

• The default widget set of a package is the widget set of the current project.
• The default widget set of the current project depends on the current operating system. For example: win32 for windows 2000.
• You should not set the widget set for a package, because then the project cannot override it. Only set it, if the package is part of a set of packages - one for each widget set.

In Lazarus 1.0 and later, the "Select another LCL widget set (macro LCLWidgetType)" redirects you to the Build Modes page, where you can select the widget set.

Build modes

Adding, deleting, activating build modes

Only projects have this page. A package does not have this page.

Build modes allow to define sets of compiler options and to quickly switch between these sets. For example you can define a mode for debugging which compiles your project with range checking, while your default mode does not.

Note: If you want to pass some options depending on the platform, for example passing some extra linker options under OS X, please take a look at Build Macros.

The first grid on the top of the page contains the list of build modes with three columns.

The first column shows which mode is currently active. When you activate another mode, all compiler options pages will load the settings of the new mode, including the macro values on the build modes page. There is always only one mode active and you can only edit the properties of one mode at a time. Which mode is active is stored in the session file (lps). The default mode is the first mode.

If your project stores the session in a separate lps file (see Project options / Session / Save session info in), you can store extra modes in the session, so that each developer can have her own set of modes. In this case the second column shows where the mode is stored, in the lpi or the lps (in session). Keep in mind that the first mode is the default mode for the project, so it must be stored in the project, not in the session file.

The last column is the name of the mode. It is an arbitrary string, so you can give it a short name or a whole sentence.

• The plus button adds a new mode, by duplicating the currently active one and activates it.
• The minus button delete the currently selected mode. There must be at least one mode. If you delete the first mode, which is the default mode, the second mode automatically becomes the default mode.
• The up, down buttons allows to reorder the modes.
• The rightmost button shows the differences between build modes.

Hint:: Once you added another build mode there will be a new button in the IDE main bar to quickly switch the currently active mode.

Note:: When opening a new project with an old IDE, you will only see the default mode. If you save the project with the old IDE you will loose all other modes, all macros and conditionals.

Build modes exist since 0.9.31.

Adding a release and debug build modes

The most common task for projects will be adding a simple release and a simple debug build modes. Remember to always use the debug build mode, because debugging will not work in the release build mode, and then only use the release build mode in the final release of the application.

The first step to add these build modes is going to the project options dialog of the project and make sure you have 2 build modes there. One named release and another named debug. By default there will always be one build mode there so you can click once in the + button in this dialog to add another one and you can rename the build modes by double clicking their names. Next make sure you select the debug build mode so that we can configure it.

Once we select the debug build mode, all configurations from the project options dialog will be specific to this build mode. The most important configuration to set for this build mode is the Linking options, which should enable GDB debugging, as is the default for Lazarus projects, like in this screenshot:

To configure the release build mode we should go back to the Build Modes section and activate the release build mode:

And for this build mode also go to the linking section and deactivate generating debug info:

Now just remember to go back to the Build Modes tab and set the debug build mode as the active one while developing the application and only use the release when making releases.

Selecting the active build mode

One can select the currently active build mode either in the "Project Options" dialog or in the main IDE Window, in a special button with a drop down which will appear only if the project has more then 1 build mode, as one can see in this screenshot:

Project macros

The second grid at the bottom of the page shows the project macro values. Note: these are Lazarus macros, not FPC macros.

They are simple name, value pairs. Macros can be used in all file names and search paths of the project. Almost all macros have default values so you will only define macros here if you want to override the default. For example a macro macro1 can be used in the Other unit files by inserting the text $(macro1). This macro will then be replaced by the value.

Packages can define macros which can be set (overriden) by the project.

Default value: Setting a macro value to an empty value is not the same as using the default value. To use the default value of a macro, delete the macro from the list.

Delete a macro: A macro can be deleted from the list by changing the name to (none) or empty.

You can set macros depending on other macros on the page Build Macros.

For more details about build macros and conditionals see Macros and Conditionals.

Project macros exist since 0.9.29.

Widget type

In Lazarus 1.0 and later, you use macros to change the widget set of the project. Click on the combo box in the Macro name cell and select LCLWidgetType. The Macro value then shows a combobox where you can select the desired widgetset. If you want to revert to the default widget type, you can delete the two cells again.

The screenshot below shows how to select qt widgetset:

Parsing

See Free Pascal - Online documentation

Syntax mode

Choose the default mode. If a unit does not contain a {$mode somemode} directive, this is used as the default.

See Free Pascal - Online documentation

Syntax Options

See FPC Programmer's guide.

• 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 Ansi Strings

Assembler style

• -R<x> assembler reading style:
• -Rdefault use default assembler
• -Ratt read AT&T style assembler
• -Rintel read Intel style assembler

Code

See Free Pascal - Online documentation

Linking

See Free Pascal - Online documentation

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.

The page has been renamed to Verbosity, starting from 0.9.27 version.

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

Other

See Free Pascal - Online documentation

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 in alternative to the Macro system, particularly if you come from Delphi.

• Custom Options: Spaces at start and end are removed. Line breaks are replaced by a space before passing to the compiler.

IDE Macros

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.

IDE macros and conditionals exist since 0.9.29.

Inherited

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.

Compilation

Create Makefile

Enable this, if the IDE should create a Makefile and a Makefile.fpc before each build. This is currently only supported for packages, not for projects.

Execute before

Setup here a command to execute before running the compiler.

Call on:

• Compile - execute when normally compiling (F9).
• Build - execute when rebuilding all. This could for example a script to clean up.
• Run - execute when quick compiling. When running a project, the IDE checks if rebuild is needed. If no rebuild is needed the IDE skips the compile step. Set this option to always execute the command, even if the compile step is skipped.

The IDE can parse and filter the output of the command and stop on errors. Check the boxes for which messages the IDE should watch.

Compiler

This is compiler path used by the project or package. Default is the macro $(CompPath), which is replaced with the compiler filename in the environment options.

Execute after

Setup here a command to execute after running the compiler. See above 'Execute before' for details.

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.