Difference between revisions of "Installing Lazarus on macOS"

From Lazarus wiki
Jump to navigationJump to search
m (Added link to Legacy information)
 
(282 intermediate revisions by 13 users not shown)
Line 1: Line 1:
{{Platform only|macOS|macOS|macOS}}
+
{{Installing Lazarus on macOS}}
{{Installing Lazarus on MacOS X}}
 
  
Installing Lazarus on a Mac is not particularly difficult but it is critical that you do the install in the correct order.  Skipping steps will almost certainly lead to tears. In brief, here is what you do -
+
Installing Lazarus on a Mac is not particularly difficult but it is critical that you do the install in the correct order.  Skipping steps will almost certainly end in tears. In brief, here is what you need to do:
  
# Download and install Xcode.
+
# Download and install Xcode (optional depending on your needs - see below for details).
# Install the global command line tools for Xcode.
+
# Install the global command line tools for Xcode. Definitely required.
# Install Free Pascal Compiler and FPC Source
+
# Download and install the Free Pascal Compiler (FPC) binaries package and the FPC source package from the [https://sourceforge.net/projects/lazarus/files/ Lazarus IDE file area] ('''Important''' do this ''before'' you install the Lazarus IDE)
# Install Lazarus
+
# Download and install the Lazarus IDE  from the [https://sourceforge.net/projects/lazarus/files/ Lazarus IDE file area] or, perhaps more useful, download and compile Lazarus source code, eg [https://gitlab.com/freepascal.org/lazarus/lazarus/-/tree/fixes_3_0?ref_type=heads Lazarus Fixes 3.0]
# Configure LLDB - the Apple supplied (and signed) debugger from within Lazarus.
+
# Configure LLDB - the Apple supplied (and signed) debugger from within the Lazarus IDE.
  
 
+
These steps are explained in more detail below.
Note : if installing versions of Lazarus prior to 2.0.0 you almost certainly also need gdb, refer to the [[#Install_gdb|Legacy section]].
 
  
 
== Installation ==
 
== Installation ==
  
The detailed instructions assume a recent version of macOS on you Mac, a recent version of Xcode from Apple and recent version of Lazarus. Further down the page, under Legacy Documentation, you will see older information that may be relevant if you are using older components. You can assist by replacing out of date info, either deleting it, or, if it may help someone working with a legacy project, moving it to the bottom of the page.
+
The detailed instructions assume a recent version of macOS on your Mac, a recent version of Xcode and/or Xcode command line tools from Apple and a recent version of Lazarus. On the [[#Legacy_Information|Legacy Information]] page, you will see older information that may be relevant if you are using older components. You can assist by replacing out of date information, either deleting it, or, if it may help someone working with a legacy project, moving it to the [[Legacy_Information:_Installing_Lazarus_on_Mac|legacy information]] page.
  
In general, this is about using both the '''Carbon''' and '''Cocoa''' Widget Set. While Carbon may still be seen as a little more stable, as of release 2.0.0 the 64bit Cocoa is very close and certainly should be considered. Carbon is intentionally (by Apple) limited to 32 bits and we know the next release of MacOSX will probably not support it.  
+
In general, this is about using both the '''Carbon''' and '''Cocoa''' Widget Sets. While Carbon was once seen as a little more stable, with the release Lazarus 2.0.8 the 64 bit Cocoa Widget Set has now surpassed Carbon and should be considered seriously for any new projects. Carbon was intentionally limited to 32 bits by Apple and you should be aware that it and the ability to run 32 bit executables have been removed completely from macOS 10.15 Catalina and later versions which now only support 64 bit executables using Cocoa.  
  
=== Step 1. Download Xcode. ===  
+
=== Step 1: Download Xcode (optional) ===
You need the Apple Developer tools, which are a part of the Xcode development environment.
 
  
Xcode 11.1 for use on MacOSX Catalina 10.15 can be installed from the Apps store, but you must first move any old Xcode versions from the Applications folder into the trash.
+
Xcode is a 12GB download which will take up 16GB of disk space. You '''only''' need to download and install the full Xcode development environment '''if''' you need:
  
Older systems:
+
* the SDKs for '''iOS''', '''iPadOS''', watchOS and tvOS; or
They can be installed from the original macOS installation disks or a newer copy downloaded from the Apple Developer Connection (ADC), which requires free registration: http://developer.apple.com/ Download the Xcode file, it will end up in your Downloads directory as a zip file. September 2017 it is Xcode_9_beta_6.xip, about 5G. Click it. It is unarchived into your Downloads directory. You may be happy with it there but maybe not. Other users will see the path to it but be unable to use it. And it is untidy there. So I moved mine and then told xcode-select where it was moved to (in a terminal) -
+
* to validate and upload apps to the Mac App Store; or
 +
* to [[Notarization for macOS 10.14.5+|notarise]] apps for distribution outside of the Mac App Store.  
  
<syntaxhighlight lang="bash">mv Downloads/Xcode-beta.app /Developer/.
+
Xcode 11.3.1 for use on macOS 10.14 Mojave must now be installed by downloading it from [http://developer.apple.com/ Apple Developer Connection] (ADC), which requires free registration.  Xcode 12.4.x for use on macOS 10.15 Catalina and later versions can be installed from the [https://apps.apple.com/us/genre/mac-developer-tools/id12002?mt=12 Mac App store]. Note that you must first move any old Xcode versions from the Applications folder into the trash or rename the Xcode app (eg Xcode.app to Xcode_1014.app). You can then select which version of Xcode to use with the command line utility <tt>xcode-select</tt>. Open an Applications > Utilities > Terminal and type <tt>man xcode-select</tt> for this utility's manual page.
sudo xcode-select -s /Developer/Xcode-beta.app/Contents/Developer </syntaxhighlight>
 
  
=== Step 2. Xcode Command Line Tools ===
+
'''Older systems:'''
This is shown here as a separate step because it really is a separate step in addition to Step 1. Don't confuse this with the internal Xcode command line tools that the Xcode GUI will tell you are already installed. Lazarus cannot use those Xcode internal command line tools, so do the following (it is quick and easy)-
 
  
<syntaxhighlight lang="bash">xcode-select --install</syntaxhighlight>
+
The Xcode developer tools can be installed from the original macOS installation disks or a newer copy downloaded from the [http://developer.apple.com/ Apple Developer Connection] (ADC), which requires free registration. Download the Xcode file, it will end up in your Downloads directory as a zip file. Click it. It is unarchived into your Downloads directory. You may be happy with it there but maybe not. Other users will see the path to it but be unable to use it. And it is untidy there. So I moved mine and then told xcode-select where it was moved to (in a terminal) -
  
=== Step 3 FPC, FPC Source ===
+
<syntaxhighlight lang="bash">mv Downloads/Xcode.app /Developer/.
Get and install FPC and FPC Source. A compatible fpc (and source) must be installed before you install Lazarus, you have a number of options.  
+
sudo xcode-select -s /Developer/Xcode.app/Contents/Developer </syntaxhighlight>
  
==== Source Forge ====
+
=== Step 2: Xcode Command Line Tools ===
  
To install the Free Pascal Compiler (FPC), get the installer and source from the [https://www.freepascal.org/download.var official Free Pascal website]. Lazarus mirrors these installers, but their copies are sometimes outdated. In particular, if you have macOS Mojave (10.14), make sure that you use the FPC 3.0.4a installer (which is missing from the Lazarus mirror at this time). Earlier installers (including the original FPC 3.0.4 installer) will not be able to identify the fact that you installed the command line tools.
+
This is shown here as a separate step because it really is a separate step. Don't confuse these standalone command line tools with the internal Xcode command line tools that the Xcode GUI will tell you are already installed if you installed the full Xcode package in Step 1. FPC cannot use those Xcode internal command line tools without configuration changes (see [[Xcode]] for details).
  
Get the other files (Lazarus installer) from the [https://sourceforge.net/projects/lazarus/files official Lazarus website]. These binary install kits are built by the FPC/Lazarus developers and track formal releases. As these install kits are not approved by Apple, you need to hold down the Control key, click the package and choose Open and confirm you want to install from an Unknown Developer.
+
Do the following, it is quick and easy for all macOS versions up to and including Catalina 10.15:
  
For authoritative/more detailed instructions for FPC, please go to [https://www.freepascal.org/down/i386/macosx-hungary.var]
+
<syntaxhighlight lang="bash">
 +
sudo xcode-select --install
 +
sudo xcodebuild -license accept
 +
</syntaxhighlight>
  
You might like to apply a simple and quick test of FPC at this stage - [[Installing_Lazarus_on_Linux#Testing_FPC_installation|Testing FPC installation]]
+
For Big Sur 11.x and later, you only need to enter the first of the two commands above unless you have also installed the full Xcode package. If you have only installed the command line tools, you should omit entering the ''xcodebuild'' command.
  
==== Other FPC Options ====
+
If you have problems installing the command line tools using this command line method (eg the installer freezes while "finding Software"), you can also download and install the command line tools package by logging in to the [https://developer.apple.com/download/more/?=for%20Xcode Apple Developer Site] and downloading and installing the ''Command Line Tools for Xcode'' disk image.
  
You could also consider using fpcupdeluxe to install fpc and, perhaps Lazarus, [[ fpcupdeluxe | fpcupdeluxe]]
+
=== Step 3: FPC binaries and FPC source code ===
  
Alternatively, you can use [http://finkproject.org/ fink], a package manager for macOS to install fpc. Note at the time of writing (Early 2019) fink offers Lazarus 1.8.4 and its generally agreed that versions later than 2.0.0 (ie non-release) are required so probably unsuited for Cocoa development. The extra bonus of fink is easy installation as well as clean removal of a huge number of other open source software packages, including [[Cross_compiling#From_Darwin_to_Windows.2C_Linux_and_others | FreePascal crosscompilers ]] for many processors and systems. The choice for lazarus is between a carbon look of lazarus (preferred by most), a gtk2 look, a Qt4-based and a Qt5-based version:
+
{{Note| For Apple Silicon/AArch64/M1 installations, if you are installing FPC 3.2.2 (with Lazarus 2.2.0 or later) you don't need to compile a native Apple Silicon version of FPC because FPC 3.2.2 for macOS is a universal binary containing both Intel and aarch64 executables. If you are installing a version of FPC earlier than 3.2.2, then please refer to [[macOS_Big_Sur_changes_for_developers#ARM64.2FAArch64.2FApple_Silicon_Support|these instructions]] for building a native Apple Silicon Free Pascal Compiler after installing the 64 bit Intel binary and source packages for FPC.}}
  
<syntaxhighlight lang="bash">$ fink install lazarus-aqua
+
Download and install the official FPC binaries package and the separate FPC source package from the [https://sourceforge.net/projects/lazarus/files/ Lazarus IDE file area].
// or
 
$ fink install lazarus-gtk2
 
// or
 
$ fink install lazarus-qt4
 
// or
 
$ fink install lazarus-qt5</syntaxhighlight>
 
  
You will be asked, whether to install a number of dependencies, including the FreePascal compiler, the lazarus sources. Simply hit RETURN at the prompt and go for a coffee. It may take quite some time to build all packages, in particular on older Macs.
+
When you arrive at the Lazarus IDE file area:
  
After installation, Lazarus can be started from the folder /Applications/Fink/. The actual details of fpc and lazarus are in subdirectories of /sw
+
# Choose the correct version of your operating system. The vast majority of Mac users should now choose the 64 bit packages in the Lazarus macOS x86-64 directory. Every Mac computer since late 2006 has been 64 bit capable and Apple has completely dropped all 32 bit support from macOS 10.15 Catalina and beyond.
 +
 +
# Choose the version of Lazarus you wish to install and you will be presented with the two FPC binary and source packages to download.
  
With any lazarus package from fink, these widget sets are supported for your program on macOS:
+
These installation packages are built by the FPC/Lazarus developers and track formal releases. As these installation packages are not approved by Apple, you need to hold down the Control key, click the package and choose Open and confirm you want to install from an Unknown Developer.
  
carbon (Aqua), gtk2, qt4 (Aqua), qt5 (Aqua), nogui, win32, win64 and wince.
+
You might like to try a simple and quick test of FPC at this stage - [[Installing_the_Free_Pascal_Compiler#Testing_the_FPC_Install|Testing FPC installation]].
  
If you install fpc from fink, you will be fine downloading Lazarus source and compiling as detailed below. However, its possibly not a good idea to mix fink fpc with the sourceforge binary install of Lazarus.
+
=== Step 4: Binary Install of the Lazarus IDE ===
  
=== Install Lazarus ===
+
It is critical that a compatible Free Pascal Compiler (FPC) and its source be installed ''before you install'' the Lazarus IDE. 
  
At time of writing (early 2019), there are a number of reasons why you may be better off using a non release version of Lazarus, specifically, fixes_2_0. Particularly -
+
{{Note| there are two versions of this step. The first is to install a binary package that someone else has already compiled for you. As Lazarus evolves, especially so on the Mac, that may be a confining limitation. The second approach is to compile your own, you already have FPC installed and obviously intend to compile your own project, why not do the same for Lazarus ?  This will get you access to the newer bug fixes, LCL code in your own disk space (avoiding many "read only" errors) and give you control of whats happening.}}
* You almost  certainly need to target Cocoa, its likely the next release of MacOSX will not support 32bit Carbon.
 
* You almost certainly want to use lldb instead of gdb - far easier install.
 
* The Cocoa is steadily improving and lldb interface is rapidly improving since even 2.0.0.
 
* Fixes_2_0 is a safer and more stable than trunk but gets the new stuff much faster than release version.
 
  
Precompiled binaries based on fixes_2_0 are not available from SourceForge but can be obtained from [[fpcupdeluxe]] . But here we will discuss downloading source and building. An little slow initially but very reliable and a great test of your compiler install ! You will need svn (its not pre installed on early MacOS, use brew or fink to install).
 
  
<syntaxhighlight lang="bash">
 
cd ~
 
mkdir -p bin/lazarus
 
cd bin/lazarus
 
svn checkout https://svn.freepascal.org/svn/lazarus/branches/fixes_2_0 laz_fixes
 
// wait some time ....
 
cd laz_fixes
 
make LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
 
// wait some time .....
 
open startlazarus.app --args "--pcp=~/.laz_fixes"
 
</syntaxhighlight>
 
  
* Note I pass a parameter to use a config directory thats based on the name of the actual install directory. It makes some scripting easy.
+
'''Binary Install''' Download and install the Lazarus IDE from the [https://sourceforge.net/projects/lazarus/files/ Lazarus IDE file area]. When you arrive at that file area, choose the correct version of your operating system. The vast majority of Mac users should now choose the 64 bit packages in the Lazarus macOS x86-64 directory. Every Mac computer since late 2006 has been 64 bit capable. The fact that Apple has completely dropped all 32 bit support from macOS 10.15 Catalina (released in October 2019) is another reason to choose the 64 bit packages.
  
* Its also quite feasible at present (and perhaps a touch safer) to build a 32bit Carbon Lazarus IDE and use it to build 64bit Cocoa applications. Replace above make line with "''make LCL_PLATFORM=carbon CPU_TARGET=i386 bigide'' " and setup your project as mentioned in the [[Installing_Lazarus_on_MacOS_X#Carbon_and_Cocoa|Carbon_and_Cocoa]] section below.
+
'''Source Install''' For installing from source, please refer to the [[#Installing Lazarus from Source|Installing Lazarus from Source]] instructions below to build a native Lazarus IDE. This applies to both x86_64 and Apple Silicon/aarch64 systems. You can use this approach to install a release version, a Fixes version or the development version, "main".
  
You might like to put a small script in your $HOME/bin directory and even set a path to it (very unix!)
+
=== Step 5: Configure the Debugger ===
  
<syntaxhighlight lang="bash">
+
In versions of Lazarus 1.8.4 and earlier, you needed to use <tt>gdb</tt> as a debugger, slow to install and hard to sign. Since Lazarus 2.0.0 you can (and should) use <tt>lldb</tt>, a debugger provided by Apple, no signing required.
#!/bin/bash
 
LAZDIR="laz_fixes"
 
cd ~/bin/lazarus/"$LAZDIR"
 
open ~/bin/lazarus/"$LAZDIR"/lazarus.app --args "--pcp=~/.$LAZDIR"
 
</syntaxhighlight>
 
  
=== Configure the Debugger ===
+
Assuming you have installed what is necessary and started Lazarus, all that remains is configuring the debugger. If you don't do this now, Lazarus will try to use <tt>gdb</tt> and fail.
  
In versions of Lazarus 1.8.4 and earlier, you needed to use gdb as a debugger, slow to install and hard to sign. Since Lazarus 2.0.0 you can (and should) use LLDB, a debugger provided by Apple, no signing required.
+
* Lazarus version 2.2.0: First, click Lazarus > Preferences > Debugger - Debugger Backend;
  
Assuming you have installed whats necessary and started Lazarus, all that remains is configuring the debugger. If you don't do this now, Lazarus will try to use GDB and fail.
+
* Lazarus before version 2.2.0: First, click Tools > Options > Debugger.  
  
First, click Tools->Options->Debugger.  Top right of the window now open has a label, "Debugger type and path", you must set both. Select "LLDB debugger (with fpdebug) (Beta)".  
+
Top right of the window now open has a label, "Debugger type and path", you must set both the type and the path. Select the type "LLDB debugger (with fpdebug) (Beta)" and select or type the path <tt>/usr/bin/lldb</tt>.
  
[[File:Set_Debugger.png|none]]
+
[[File:Set_Debugger2.png|none]]
  
If its not show in the selection list, see below (Installing LazDebuggerFpLLdb".) Note that the image above has a path to LLDB that may well be different to yours, depends on where the XCode tools were installed, in my case /Library . Save those settings and you can now try to compile the almost nothing programme that Lazarus has kindly provided for you. (click the small green triangle near top left.)
+
If "LLDB debugger (with fpdebug) (Beta)" is not shown in the selection list, see [[#Installing_LazDebuggerFpLLdb|Installing LazDebuggerFpLLdb]] below. The XCode command line tools install <tt>lldb</tt> to the <tt>/usr/bin</tt> directory. Save those settings and you can now try to compile the almost nothing program that Lazarus has kindly provided for you (click the small green triangle near top left).
  
Next you see a puzzeling question, see image below. Choose a "Debug Format" from one of the offered -
+
Next you see a puzzling question, see image below. Choose a "Debug Format" from one of those offered -
  
 
[[File:Set_Dwarf.png|none]]
 
[[File:Set_Dwarf.png|none]]
  
Martin_fr, the person who has given us this interface between Lazarus and LLDB, suggests you use "dwarf3". Then, you need to enter your password, a MacOSX cuteness because one application appears to be interfering with another. In this case, thats fine !
+
Martin_fr, the person who has given us this interface between the Lazarus IDE and <tt>lldb</tt>, suggests you use ''' "dwarf3" '''. Then, you need to enter your password, a macOS cuteness because one application appears to be interfering with another. In this case, that's fine!
 +
 
 +
When running the debugger from time to time you will be asked for your password to allow debugging. This is for your own safety.
  
==== Extra Information on using LLDB ====
+
==== Extra Information on using lldb ====
A great deal of information about using LLDB appears in this forum thread https://forum.lazarus.freepascal.org/index.php/topic,42869.0.html Here is a few gems, again, from Martin_fr :
+
 
 +
A great deal of information about using lldb appears in [https://forum.lazarus.freepascal.org/index.php/topic,42869.0.html this forum thread]. Here are a few gems, again, from Martin_fr:
  
 
In the unexpected case of problems, it may be worth trying "dwarf with sets" instead of just "dwarf3".  
 
In the unexpected case of problems, it may be worth trying "dwarf with sets" instead of just "dwarf3".  
  
The "debug info" setting only affects the units directly in your project. However units in packages may have debug info too. This can be
+
The "debug info" setting only affects the units directly in your project. However, units in packages may have debug info too. This can be:
 +
 
 
* set per package
 
* set per package
* for many, but not all packages in menu Tools > Configure build Lazarus
+
* for many, but not all packages in the menu Tools > Configure "Build Lazarus"
* project settings > [[IDE_Window:_Compiler_Options#Additions_and_Overrides|Additions and Overrides]]
+
* Project > Project Options > [[IDE_Window:_Compiler_Options#Additions_and_Overrides|Additions and Overrides]]
  
If you change settings for package, you may as well check into which package you expect to step. Package you do not step into, do not need debug info.
+
If you change settings for a package, you might want to check which package you expect to step into when debugging. Packages you do not step into, do not need debug info.
If you use a type from a package (such as TForm from LCL) it is enough that your unit (in which you declare the variable / must declare and use a variable to include the type) has debug info. Reducing the amount of packages with debug info (including those that default to have debug info), can shorten the debuggers start-up time.
 
  
Also it may be worth comparing (its not been tested) the debuggers start up time for the same settings, only changing the checkbox "use external debug info".
+
If you use a type from a package (such as TForm from LCL) it is enough that your unit (in which you declare the variable / must declare and use a variable to include the type) has debug info. Reducing the number of packages with debug info (including those that default to have debug info), can shorten the debuggers start-up time.
This needs to be only set in your project. If set in your project it will affect all packages. (If set in a package it will do nothing / at least should...)
 
  
==== Installing LazDebuggerFpLLdb" ====
+
Also it may be worth comparing (it has not been tested) the debuggers start up time for the same settings, only changing the checkbox "use external debug info".
If you installed from source and used the bigide parameter to make, then the correct debugger will be installed, as a package, and ready to go. If, however, you installed in another way, it may, or may not be there. From the main IDE screen, click Packages->Install/UninstallPackages. Show is two lists of packages, the list on the left is installed, the list on the right is available to install. Look for LazDebuggerFpLldb (exactly that, there are some similar named but less suitable packages). If its on the right hand side, click it, press "Install Selection" and then "Save and rebuild IDE". This will take a little time, the IDE will shutdown and restart and all should be well. Now jump back up the page and continue configuring the debugger.
 
  
== Compatibility ==
+
This needs to be only set in your project. If set in your project it will affect all packages. (If set in a package it should have no affect.)
Not every combination of Lazarus and Free Pascal is compatible with every installation of macOS. Please refer to the following table in order to find the correct version for your development environment:
 
{{Template:Compatibility matrix of Lazarus for Mac}}
 
  
== Cocoa 64 bit vs Carbon 32 bit ==
+
==== Installing LazDebuggerFpLLdb ====
  
At present (mid 2019) Lazarus using the Apple 64 bit Cocoa framework will meet the needs of many users. The Apple 32 bit Carbon framework works pretty much as expected but you are advised to try Cocoa first, because Apple has dropped support for 32 bit applications and the Carbon framework from the next macOS version, Catalina, which is to be released in the Northern Hemisphere Fall of 2019.  
+
If you installed from source and used the [[#What does the bigide make argument do?|<tt>bigide</tt>]] parameter to <tt>make</tt>, then the correct debugger will be installed, as a package, and ready to go. If, however, you installed in another way, it may, or may not be there.  
  
Alternatives include QT and GTK2+, both requiring additional libraries and GTK2+ on the Mac appears to get little attention these days. QT on the Mac does have some strong supporters on the [https://forum.lazarus.freepascal.org/index.php/board,22.0.html Lazarus forum].
+
From the main IDE screen, click Packages->Install/UninstallPackages. Shown is two lists of packages, the list on the left is installed, the list on the right is available to install. Look for LazDebuggerFpLldb (exactly that, there are some similar named but less suitable packages). If it is on the right hand side, click it, press "Install Selection" and then "Save and rebuild IDE". This will take a little time, the IDE will shutdown and restart and all should be well. Now jump back up the page and continue configuring the debugger.
  
'''Cocoa''' is now undeniably the future on the Mac. It is possible to build an all Cocoa version of Lazarus with release 2.0.0 and later.  It is also possible to make a Carbon install of Lazarus and use that to generate Cocoa 64 bit binaries. In a Carbon IDE, you need to set the Target to the 64 bit processor and select the Cocoa Widget set:
+
== Installing Lazarus from Source ==
  
*Open your project with Lazarus and click Project/Project Options
+
{{Note|When building Lazarus from source, Apple very kindly add a quarantine attribute to your *.app files that ensures they will not run.  '''xattr -drv com.apple.quarantine *''' will solve this for you. }}
*In the "Config and Target" panel set the "Target CPU family" to be "x86_64"
 
*In the "Additions and Overrides" panel click on "Set LCLWidgetType" pulldown and set the value to "Cocoa"
 
*In the past, for some reason Lazarus kept setting the compiler to "/usr/local/bin/ppc386" - which results in 32 bit apps. Make sure under Tools->Options that "Compiler Executable" is set to "/usr/local/bin/fpc" to get 64 bit apps.
 
*Now compile your project - and please feed back any problems you experience.
 
  
== Download the sources via svn ==
+
{{Note|This process can be seen as an alternative to step 4 above, you still need to install [[#Step_2:_Xcode_Command_Line_Tools|Xcode Command Line Tools]] and Free Pascal Compiler and its Source.}}
  
The sources are kept in a version control system called subversion or short '''svn''':
+
This chapter focuses of Fixes but the same process applies to Lazarus Main (ie the development version) and other branches or tags in gitlab. At present (November 2023) Fixes_3.0 makes sense and examples below assume that. Later, newer version numbers may be needed.
  
*10.5 and higher already contains svn clients. Users of earlier versions must install SVN for macOS. A good package is provided by [http://www.codingmonkeys.de/mbo/ Martin Ott]. You can also use fink. SVN clients with GUI (graphical user interface) are available from [http://www.versiontracker.com Versiontracker]. A quite handy client, which integrates in Finder, is [http://scplugin.tigris.org SCPlugin].
+
There are a number of reasons why you may be better off building from Source (particularly, in this case, Fixes_3.0).  
  
Create a directory, where you would like to put the sources. You don't need to be root to do this. Any normal user can do this.  
+
* It gives you access to the 'newest and best' or, perhaps, the 'bleeding edge'. Fixes and main are not usually available as binary installs.
First create a directory for fpc
+
* The MacOS side of Lazarus changes rapidly, this is particularly so with respect to the debugger and Apple Silicon / aarch64. At the time of writing, for example, Fixes_3.0 has improvements to the debugger that are not present in the 3.0 Release Candidates.
: (e.g. /Users/username/freepascal)
+
* Fixes of any version is usually a safer and more stable option than the development branch, but still gets the new features much faster than the release version.
then open a terminal and do the following:
+
* [[Lazarus_3.0_fixes_branch|Fixes included in fixes 3.0]]
[]$ svn co http://svn.freepascal.org/svn/fpc/trunk fpc
 
This will create a directory called 'fpc', which can be later used in the IDE.
 
Hint: To download/update the latest changes you can simply do
 
[]$ cd /Users/username/freepascal/fpc
 
[]$ svn up
 
  
Building fpc
+
{{Apple Silicon Lazarus Build Notes}}
[]$ make clean all
 
[]$ sudo make install
 
  
Then download lazarus
+
==== Downloading Lazarus source ====
[]$ svn co http://svn.freepascal.org/svn/lazarus/trunk lazarus
 
This will create a directory called 'lazarus'.
 
To update the latest changes:
 
[]$ cd /Users/username/freepascal/lazarus
 
[]$ svn up
 
  
Building lazarus
+
As always, you have several choices when it comes to downloading Lazarus Source.
[]$ make clean all
 
  
Then start lazarus either via command line or by double click in the finder:
+
* Browse to the [https://gitlab.com/freepascal.org/lazarus/lazarus Lazarus source repository] and select the branch you are interested in. Download a zip or tar file. This is quick and (relatively) small and suits a 'one off' install.
  open lazarus.app
+
* Use git, its bigger and slower but a good solution if you are already a git user or expect to be sending in patches to contribute to Lazarus. In this case, you need main, Lazarus does not accept patches for other branches. Advantage of git (or svn) is that its easily and quickly updated and if you plan to track the frequent updates that happen (to non-release) versions its worthwhile. This wiki has good instructions on using [[FPC_git|git]]. Typically <code>git clone https://gitlab.com/freepascal.org/lazarus/lazarus.git</code> to get Lazarus Main.
 +
* If you have wget installed and know the url you want, its all too easy. Some examples, firstly the current (Nov 2023) Fixes_3.0 and then main. 
 +
<syntaxhighlight lang="bash">
 +
$> wget  https://gitlab.com/freepascal.org/lazarus/lazarus/-/archive/fixes_3_0/lazarus-fixes_3_0.zip
 +
$>
 +
$> wget https://gitlab.com/freepascal.org/lazarus/lazarus/-/archive/main/lazarus-main.zip
 +
</syntaxhighlight>
  
== Download stable sources ==
+
The zip or tarballs are about 60Meg, git (or svn) bigger because they hold all the history as well. In all cases, ensure your source ends up in a directory by it self, remember you may end up with several installs so make a reasonable directory structure. This (very un Mac like) author keeps such things in (eg) $HOME/bin/Lazarus/lazarus-fixes_3.0.
  
Source code of stable versions is available in the [http://sourceforge.net/projects/lazarus/files/Lazarus%20Zip%20_%20GZip/ Lazarus Zip - GZip] archives. This is e.g. an option for users, who want to run the latest official Lazarus versions on "unsupported" machines, e.g. PPC-based Macs. Provided that you have installed the latest stable FPC version together with sources, it is sufficient to download and unpack the zip archive. Move it to the desired location (e.g. your /Developer folder), open a terminal window and change the shell's path to this folder (the easiest way to do this is to type "cd " and then to drag the icon of the freshly unpacked Lazarus folder to the position after this command in the Terminal window). If necessary enter <return> and then
+
==== Building source ====
[]$ make clean bigide
 
  
and <return> again. Subsequently, FreePascal will use the makefile in this folder to build the Lazarus IDE. This may take a few minutes, but the process is fully automated. Therefore, you might want to look for a cup of coffee, while FPC is working. If the compiler is ready it prints the number of processed lines and the required time to the shell's output.
+
Assuming some things here, you may make different choices, adjust accordingly -
 +
* you have Lazarus Fixes source (from either tar, zip or git)
 +
* you have the directory structure mentioned above
 +
* you are using an x86_64 box (use CPU_TARGET=aarch64 otherwise)
 +
* you want to keep your Lazarus configs in their own specified place (essential if you will have multiple installs, a very good idea other wise).
  
The last step is to right-klick on the Lazarus bundle icon and to select "Show Package Contents" from the context menu. Then drag the executable "lazarus" to the folder "Contents/MacOS" of the bundle. That's it.
+
<syntaxhighlight lang="bash">
 +
$> cd bin/Lazarus/lazarus-fixes_3.0
 +
$> make clean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
 +
//-wait some time...
 +
$> xattr -drv com.apple.quarantine *
 +
</syntaxhighlight>
  
= Legacy Information =
+
If this is a rebuild and all you have downloaded is an update to a not too old version, you can restore your installed packages and configuration by using "make useride" after a successful "make clean ..." step, possibly even instead off if its recent enough. Does no harm if you fail.
  
=== Install gdb ===
+
* The xattr command removes a quarantine attribute from your app directories kindly added by Apple to prevent them from working.
  
As of the Lazarus 2.0.0 release this is entirely optional. The IDE now supports LLDB directly. See http://forum.lazarus-ide.org/index.php/topic,42869.0.html and http://wiki.lazarus.freepascal.org/Lazarus_2.0.0_release_notes#LLDB_based_Debugger_.28New.29
+
* On older macOS versions supporting 32 bit applications, replace the above make line with "''make LCL_PLATFORM=carbon CPU_TARGET=i386 bigide'' " and set up your project as mentioned in the [[#Cocoa_64_bit_vs_Carbon_32_bit|Carbon and Cocoa]] section below.
 +
 +
==== Setup a Config Directory Structure ====
 +
This step is not necessary if you will be happy with just this one Lazarus install. Lazarus will make a config directory if it needs to but will not make any directories about that. So, here we make a single directory to hold all our Lazarus configs. Before we do that, while we are still in the lazarus-fixes_3.0 directory, we create a lazarus.cfg file that will tell this Lazarus where to store its config. You do this only once for each Lazarus install.
  
Getting gdb to run can be a bit tedious but is worthwhile in the end if using Lazarus < V2.0 or have some specific requirement for gdb. You probably don't !
+
<syntaxhighlight lang="bash">
 +
$> cat > lazarus.cfg <enter>
 +
--pcp='~/bin/Lazarus/LazConfigs/lazarus-fixes_3.0 <enter>
 +
Press Ctrl D
  
This step should be done after installing XCode and before installing FPC/Lazarus.
+
$> mkdir ../LazConfigs
 +
</syntaxhighlight>
 +
 +
==== Starting Lazarus ====
  
# Install fink or brew and use them to install gdb- http://wiki.freepascal.org/GDB_on_OS_X_Mavericks_and_Xcode_5
+
You must start Lazarus using the "app bundle", that is, typically startlazarus.app or lazarus.app in this case. Don't use the lazarus or startlazarus binary, described in the Finder as 'unix binaries'. If you get that wrong, directly starting a Lazarus binary will result in no menu or mouse interaction. Its an Apple thing.
# Self sign the gdb binary using tools already on your Mac - https://sourceware.org/gdb/wiki/BuildingOnDarwin This is the tedious part. The instructions are clear except, perhaps they could have mentioned that after you have set the Keychain to ’System’ you need click ‘Create’ and ‘Done’ on the next screen. Then go and find the cert in your overall list of certs to do the next instruction “using the contextual menu…”. Don’t worry about step “2.1.4 Disable starting the debuggee…”, we’ll address that once Lazarus itself is installed and working.
 
# Once Lazarus is installed and fired up, tell it how it should start gdb, that is step 5.
 
  
'''Note''' that as of April 2018, there may be issues with newest gdb and High Sierra. https://forum.lazarus.freepascal.org/index.php/topic,40874.0.html
+
* '''From the command line''' that means for example 'open lazarus.app'. You will probably cd to the directory containing the Lazarus install and just type <code>open ./lazarus.app</code> or, if you want pass the name of a Config Dir and start from anywhere, something like <code>open startlazarus.app --args "--pcp=~/bin/Lazarus/LazConfigs/lazarus-fixes_3.0"</code>
''According to https://stackoverflow.com/questions/49001329/gdb-doesnt-work-on-macos-high-sierra-10-13-3, gdb 8.1 does not work on High Sierra, but 8.0.1 does.''
+
* '''Using the Finder''' is, perhaps, a bit more "mac like". Navigate to the directory where your Lazarus install is, double click on the lazarus.app (or startlazarus.app) entry and all is good. However, by default, the Finder does not show the ".app" part of the name, its hard to tell the difference between "lazarus" and "lazarus.app". You want the one with a caricature of a leopard's face, Finder describes it as an Application.
  
'''Part 2 of gdb install, Tell Lazarus about starting gdb'''
+
* Thirdly, depending on how you like to work, maybe '''make a bash script to start Lazarus''' ? Note I pass a parameter to define the config directory, that is unnecessary if you have put the suggested lazarus.cfg file in place.
  
Again, this step is not necessary with Lazarus V2.0 and Later. See http://wiki.lazarus.freepascal.org/Lazarus_2.0.0_release_notes#LLDB_based_Debugger_.28New.29 If you do install (and use) gdb, you must tell Lazarus about how to call gdb. Obviously, this step happens after Lazarus is installed.
+
<syntaxhighlight lang="bash">
+
#!/bin/bash
OK, now you should be able to start Lazarus, it should display the various parts and paths it needs (including gdb) in the little opening screen. You will get an alert there if you chose to not use a debugger. Proceed to the IDE and we now need to tell Lazarus to tell gdb to not open a shell, as noted by a number of Forum people (http://forum.lazarus.freepascal.org/index.php/topic,37310.0.html). Within Lazarus, click Tools->Options->Debugger->General
+
LAZDIR="lazarus-fixes_3.0"
In the “Debugger specific Options” there is a field labeled Debugger_Startup_Options. Type in "--eval-command=set startup-with-shell off" (including the inverted commas) AND press the return key, click OK. Note you cannot copy and paste into this box (##$!). See screen shot.
+
cd ~/bin/Lazarus/"$LAZDIR"
<gallery>
+
open ~/bin/lazarus/"$LAZDIR"/lazarus.app --args "--pcp=~/bin/Lazarus/LazConfigs/$LAZDIR"
Image:Debug_Startup_Options_01.png
+
</syntaxhighlight>
</gallery>
 
  
 +
=== What does the bigide make argument do? ===
  
=== Xcode Compatability ===
+
{{BigIDE}}
Information relating to older versions of FPC, Lazarus and Apple Developer Tools
 
  
==== Compatibility with Xcode 5.0 and newer versions (Mac OS X 10.8, 10.9, 10.10 and 10.11) ====
 
Like Xcode 4.3+, Xcode 5 and subsequent versions no longer install the command line tools by default. These are required by FPC/Lazarus, however. Unlike in Xcode 4 the installation option is no longer accessible in Xcode 5 via the Downloads tab. Additionally, the "Locations" tab of the preferences dialog may be confusing, as it mentions that the command line tools are installed:
 
  
<gallery>
+
=== Managing your Config Directory ===
Image:xcode5 misleading screenshot.png|Default location of command line tools in Xcode 5.
+
Further up, in this section, we mentioned the Lazarus Config Directory. Maybe a few words about it here will help, especially if you are having some problems.
Image:xcode select.png|Installation of command line tools with the xcode-select command part 1...
+
* The config dir can have any name you like but, as is frequently the case with low level stuff, best not to have spaces in the directory name nor in the path to it. In practise, its a good idea to give the config dir a name that hints at the install of Lazarus that uses it.
Image:command line tools installation on mavericks.png|...and part 2.
+
* The config dir can be anywhere you like as long as you have write access to it.
</gallery>
+
* The config dir must be used by only one install of Lazarus. If you install a new version of Lazarus, not too far from your old one, Lazarus will offer to upgrade it but there is no going back to the old one.
 +
* The config dir holds a whole lot of information about what you are doing with Lazarus. For example, things you set when Lazarus first started up, Options such as tab spacing, where the help files are and, importantly, any package you may have installed. For users who have Lazarus (initially) installed in read only disk space, Lazarus keeps anything of itself that has been altered in the config dir too. (That's just one reason its better to build from source.)
 +
* Given the above point, if you remove the Lazarus Config Directory, its a bit like doing a factory reset on your smart phone. All your settings and additions will be discarded and Lazarus will startup fresh, will want to know where things like fps are, what debugger you are using etc, fortunately, new versions of lazarus are pretty good at finding sensible defaults, older version might need a bit of help.
  
The first dialog box shows that by default the command line tools are only installed inside the Xcode.app bundle itself. To install them globally, as required by FPC/Lazarus, execute the following terminal command:
+
Ok, so, the Lazarus Config directory is clearly important and probably best not fiddled with by the inexperienced but it is a quite reasonable thing to just delete it to go (right) back to a known good install.
 +
* If you have '''selected a config directory of your own''' (with a lazarus.cfg file or a command line parameter) then you know where it is and you can delete it using either the Finder or Command Line.
 +
* If you have '''allowed Lazarus to choose''' where to put the config dir then Lazarus will make and use a directory called .lazarus in your home directory. The dot makes it a hidden directory, both the Finder and ls command will ignore it unless instructed to display hidden files. But you don't need to see it, you know it is in your home directory, delete it with -
  
<syntaxhighlight lang="bash">
+
<code>rm -Rf ~/.lazarus <enter></code>
xcode-select --install
 
</syntaxhighlight>
 
  
Depending from your Xcode version alternative steps to install the command line developer tools may be to download them directly in the Xcode preferences window (see screenshots above) or to download them from [http://developer.apple.com developer.apple.com] (please take care to install the command line tools that are correct exactly for your Xcode version).
+
I am sure I don't need to be warn about the danger of the rm command but I will, be careful ! Never use <code>rm -Rf</code> without an explicit directory name to delete !
  
*You can compile and install the normal gdb. See [[GDB on OS X Mavericks and Xcode 5]].
+
== Installing non-release versions of FPC ==
  
==== Xcode 4.3+ compatibility (Mac OS X 10.7/10.8) ====
+
{{macOS FPC Source Installation}}
Xcode 4.3 and later no longer install the command line tools by default. These are required by FPC/Lazarus.
 
  
To install them manually, open Xcode, go to Preferences, select "Downloads;" and install the "Command Line Tools". Afterwards, FPC will install and function correctly.
+
== Cocoa 64 bit vs Carbon 32 bit ==
  
<gallery>
+
Using the Apple 64 bit Cocoa framework is now undeniably the future on the Mac. The Apple 32 bit Carbon framework, while no longer being developed, works pretty much as expected, but you are advised to try Cocoa first because Apple dropped all support for 32 bit applications and the 32 bit Carbon framework in macOS 10.15 Catalina (October 2019).
Image:install command line tools 1.png
 
Image:install command line tools 2.png
 
Image:install command line tools 3.png
 
</gallery>
 
  
It will be necessary to reinstall the command line tools after each upgrade of Xcode (especially when it's a new major version, the installer may delete the old copies of the command line tools), and also after switching to a new major version of the system software (idem). You may also download the command line tools from [https://developer.apple.com/download/more/?=command%20line%20tools Apple Developer].
+
It is possible to build a Carbon version of the Lazarus IDE (unless you are running macOS 10.15 Catalina or later) and use that to generate Cocoa 64 bit binaries.  
  
==== Xcode 3.2.x compatibility (Mac OS X 10.6) ====
+
To produce Cocoa applications in the Carbon or Cocoa IDE, you need to set the Target to the 64 bit processor and select the Cocoa widgetset:
FPC 2.6.0: there is an issue when compiling dynamic libraries with FPC under Mac OS X 10.6 due to a bug in the Xcode 3.2.x linker. This bug has been fixed in Xcode 4. You can work around the bug in Xcode 3.2.x by using the -k-no_order_inits command line parameter when compiling a dynamic library.
 
  
==== Xcode 3.1.x compatibility (Mac OS X 10.5) ====
+
* Open your project with Lazarus and from the menu select Project > Project Options
Most versions of Lazarus and FPC are compatible with Xcode 3.1 (see the [[#Compatibility|compatibility]] matrix for detailed reference). The Xcode integration kit is provided as an optional install to allow for developing with Free Pascal directly from Xcode. It is not required for development with Lazarus, however.
+
* In the "Config and Target" panel set the "Target CPU family" to be "x86_64" (Intel) or "aarch64" (Apple M1)
 +
* In the "Config and Target" panel, if the "Current LCL widgetset" is not set to Cocoa, click "Select another LCL widgetset" which will take you to the "Additions and Overrides" panel where you can click on "Set LCLWidgetType" pulldown and set the value to "Cocoa"
 +
* Make sure under Tools > Options (Lazarus > Preferences in v2.2.0 and later) that "Compiler Executable" is set to "/usr/local/bin/fpc" to get 64 bit applications.
 +
* Now compile your project - and please feed back any problems you experience.
  
==== Xcode 2.x compatibility (Mac OS X 10.4) ====
 
Most versions of Lazarus and FPC are compatible with Xcode 2.3 or newer (see the [[#Compatibility|compatibility]] matrix for detailled reference). The Xcode integration kit is provided as an optional install to allow for developing with Free Pascal directly from Xcode. It is not required for development with Lazarus, however. Xcode 2.0 was compatible with Lazarus 0.9.x, but it is no longer supported by newer versions of the Lazarus IDE.
 
  
== Install Packages / Released version ==
+
== FPC + Lazarus Compatibility Matrix ==
  
=== Installation from disk images ===
+
Not every combination of Lazarus and Free Pascal is compatible with every installation of macOS. Please refer to the following table in order to find the correct version for your development environment:
  
Download the three disk images (.dmg files) for fpc, fpcsrc and lazarus from either of the following links:
+
{{Template:Compatibility matrix of Lazarus for Mac}}
  
* [http://sourceforge.net/projects/lazarus/files/Lazarus%20Mac%20OS%20X%20i386/ Intel-based Macs]
 
* [http://sourceforge.net/projects/lazarus/files/Lazarus%20Mac%20OS%20X%20powerpc/ PowerPC-based Macs]
 
  
Open up each disk image and install in this order:
+
== Known issues and solutions ==
# fpc
 
# fpcsrc
 
# Lazarus
 
  
After installation the Lazarus application can be found in /Developer/lazarus/, the FPC source files in /usr/local/share/fpcsrc.
+
=== Lazarus IDE v2.2.0 - rebuilding issue ===
  
If you receive a "Can't find unit Interfaces used by Project1" error on trying to compile a blank form, check the following settings in Lazarus (should be set by default):
+
<div class="mw-collapsible mw-collapsed">
  
Environment Options
+
Any attempt to rebuild the Lazarus IDE from within itself fails with permission errors because the files and directories are owned by a user with the id of 503 whereas most users will find that their id is 501. The solution is to open an Applications > Utilities> Terminal and:
  Lazarus directory: /Developer/lazarus
 
  Compiler path: /usr/local/bin/ppc386 (PowerPC Macs: /usr/local/bin/ppcppc)
 
  FPC Source: /usr/local/share/fpcsrc
 
  
Project | Options
+
<div class="mw-collapsible-content">
  All paths blank
+
cd /Applications
  LCL Widget Type: default (Carbon beta)
+
sudo chown -R your_username Lazarus
  
Project | Inspector
+
=== Rebuilding errors do not happen on Intel computers ===
  Required Packages
 
      LCL
 
 
Note - different versions of Lazarus depend on particular versions of the FreePascal compiler and will not work with other versions.
 
  
Another common problem is that the versions of fpc and fpcsrc are different.
+
The next error that occurs is that the resource compiler "fpcres" is not found. The solution is to create a <tt>.fpc.cfg</tt> (note the initial dot) file in your home directory and add these lines to it:
  
This is the easiest way to install Lazarus on Mac OS X.
+
#include /etc/fpc.cfg
 +
-FD/usr/local/bin
  
== Install from Source / Development version ==
+
so that "fpcres" can be found where it was installed.
  
You need the latest stable released FPC installed in order to compile the development version.
+
The next error complains of an unsupported target architecture <tt>-Paarch64</tt>, with the advice to invoke the "fpc" compiler driver instead - except that is what we are doing already. The solution is to go to Lazarus > Preferences > Compiler executable which is set to <tt>/usr/local/bin/fpc</tt> and change that to <tt>/usr/local/lib/fpc/3.2.2/ppca64</tt> instead.
  
=== Download and install a compiler ===
+
The IDE will now be successfully rebuilt but will not restart automatically. Trying to then start Lazarus from either the <tt>startlazarus.app</tt> icon or the <tt>lazarus.app</tt> icon in <tt>/Applications/Lazarus</tt> still results in the original Intel lazarus binary being launched. The correct aarch64 binary can be found in <tt>~/.lazarus/bin/aarch64-darwin/lazarus</tt>. So the final solution is to open an Application > Utilities > Terminal and:
  
Download and install the FPC package: https://sourceforge.net/project/showfiles.php?group_id=89339
+
mv /Applications/Lazarus/lazarus /Applications/Lazarus/lazarus.old
 +
mv  ~/.lazarus/bin/aarch64-darwin/lazarus /Applications/Lazarus/
  
There are two development versions of the compiler: 2.6.x is stable version without new features - only bug fixes. The unstable version 2.7.x comes with lots of new features but sometimes also with bugs. Best is to download and install fpc 2.6.x. Some daily snapshots can be found [http://snapshots.lazarus.shikami.org/lazarus/ here]. Keep in mind that these are daily snapshots and that you can have bad luck and get a buggy version. The probability is about 1:30. So if the version is buggy try another day or use the released packages instead.
+
You can then start the IDE with either the <tt>startLazarus.app</tt> or <tt>lazarus.app</tt> icons. When you do restart lazarus, it is worth returning to the Lazarus > Preferences > Compiler executable which is set to <tt>/usr/local/lib/fpc/3.2.2/ppca64</tt> and changing it back to <tt>/usr/local/bin/fpc</tt> so that you can compile both aarch64 and Intel binaries to, for example, make a [[macOS_Big_Sur_changes_for_developers#Creating_a_universal_binary_for_aarch64_and_x86_64|Universal Binary]] which will run on both Intel and aarch64 machines.
 +
</div></div>
  
= Uninstalling Lazarus and Free Pascal =
+
=== Lazarus IDE - Unable to "run without debugging" ===
  
== Installed using fink ==
+
<div class="mw-collapsible mw-collapsed">
  
The complete uninstall of all fpc and lazarus packages is done with:
+
If you are using the Lazarus IDE 2.0.10 and the ''Run > Run without debugging'' menu option fails with a dialog similar to:
  
<syntaxhighlight lang="bash">
+
<div class="mw-collapsible-content">
fink purge --recursive fpc-config
 
</syntaxhighlight>
 
  
If you want to preserve changes to the preference file /sw/etc/fpc.cfg, do:
+
[[file:run_dialog_fail.png|350px]]
  
<syntaxhighlight lang="bash">
+
then you need to patch the Lazarus 2.0.10 source code ({{MantisLink|37324}} and {{MantisLink|36780}}). Specifically, patch <tt>../ide/main.pp</tt> as below (unpatched lines shown first, patched lines shown second):
fink remove --recursive fpc-config
 
</syntaxhighlight>
 
  
For the removal of the Lazarus preference folder and files in your home directory, see below ([[#Lazarus preference folder .lazarus in the home directory | Lazarus preference folder]]).
+
  7243,7245c7243,7245
 +
  <    if RunAppBundle
 +
  <        and FileExistsUTF8(Process.Executable)
 +
  <    and FileExistsUTF8('/usr/bin/open') then
 +
  ---
 +
  >    if RunAppBundle then
 +
  >    //    and FileExistsUTF8(Process.Executable)
 +
  >    //and FileExistsUTF8('/usr/bin/open') then
  
== Installed from disk images or sources ==
+
and recompile the Lazarus IDE.
  
Normally you uninstall an application on OS X simply by dragging it from the Applications folder to the trash. But because Lazarus and Free Pascal are development tools, they're installed in several folders that you don't normally see in Finder.
+
Alternatively, you can omit patching the source code and simply recompile Lazarus 2.0.10 with FPC 3.0.4.
  
You can copy and save the commands below to file uninstallLaz.sh and run it if you need to uninstall Lazarus and Free Pascal. You can usually install newer versions of Lazarus and Free Pascal over older versions, but as with most software it's not a bad idea to clean out everything before you install a newer version. This list of commands should also give you a sense of where the various pieces of Lazarus and Free Pascal are located.
+
A similar patching exercise and recompiling, or simply recompiling with FPC 3.0.4, needs to be done for Lazarus 2.0.8 if it has been compiled with FPC 3.2.0.
 +
</div></div>
  
<syntaxhighlight lang="bash">
+
=== Upgrading from Mojave (10.14) to Catalina (10.15) ===
bin=/usr/local/bin
 
share=/usr/local/share
 
lib=/usr/local/lib
 
receipts=/Library/Receipts
 
private=/private/etc
 
  
rm -fv $bin/ppcppc
+
<div class="mw-collapsible mw-collapsed">
rm -fv $bin/ppc386
 
rm -fv $bin/bin2obj
 
rm -fv $bin/data2inc
 
rm -fv $bin/delp
 
rm -fv $bin/fd2pascal
 
rm -fv $bin/fpc
 
rm -fv $bin/fpcmake
 
rm -fv $bin/fpcmkcfg
 
rm -fv $bin/fpcsubst
 
rm -fv $bin/fpdoc
 
rm -fv $bin/fprcp
 
rm -fv $bin/h2pas
 
rm -fv $bin/h2paspp
 
rm -fv $bin/makeskel
 
rm -fv $bin/mkxmlrpc
 
rm -fv $bin/plex
 
rm -fv $bin/postw32
 
rm -fv $bin/ppdep
 
rm -fv $bin/ppudump
 
rm -fv $bin/ppufiles
 
rm -fv $bin/ppumove
 
rm -fv $bin/ptop
 
rm -fv $bin/pyacc
 
rm -fv $bin/rstconv
 
rm -fv $bin/unitdiff
 
rm -r $private/lazarus
 
rm -r $bin/lazarus
 
rm -r $share/lazarus
 
rm -r $share/fpcsrc
 
rm -r $share/doc/fpc-2.2.2
 
rm -r $share/examples/fpc-2.2.2
 
  
rm -r $lib/fpc
+
* Run <code>sudo xcode-select --install</code>
  
rm -r $receipts/lazarus-*.pkg
+
<div class="mw-collapsible-content">
rm -r $receipts/fpcsrc-*.pkg
 
rm -r $receipts/fpc-*.pkg
 
  
rm -fv /etc/fpc.cfg
+
* To enable Lazarus to locate the <tt>crt1.10.5.o</tt> file change in <tt>/etc/fpc.cfg</tt> the -Fl behind "#ifdef cpux86_64" from
</syntaxhighlight>
+
-Fl/Applications/Xcode.app/Contents/Developer/Toolchain...
 +
to
 +
-Fl/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/lib/
 +
</div></div>
  
Note that this assumes you have version 2.2.2 snapshot of Free Pascal installed. If you have a different version, change the two relevant commands to specify your version.
+
=== Building the FPC compiler from Mojave (10.14) onwards ===
  
To run this script, change to the directory where it's stored and enter:
+
<div class="mw-collapsible mw-collapsed">
  
<syntaxhighlight lang="bash">
+
* To find the crt1.10.5.o file when building a later Free Pascal Compiler version from source, you need to specify:
chmod +x uninstallLaz.sh
 
sudo ./uninstallLaz.sh
 
</syntaxhighlight>
 
  
Then enter your password when prompted.
+
<div class="mw-collapsible-content">
  
=== Lazarus preference folder .lazarus in the home directory ===
+
  OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
  
'''''Note:'''''  Lazarus also creates a .lazarus folder in your home directory where it stores environment settings and a list of recently opened projects and files. You can leave this folder alone if you want the new version of Lazarus you're installing to use your old settings. macOS normally doesn't show files or folders whose names start with a dot (.). To see this folder and its contents, enter the following in a terminal window:
+
on the make command line because FPC ignores the <tt>/etc/fpc.cfg</tt> configuration file during builds of itself.
 +
</div></div>
  
<syntaxhighlight lang="bash">
+
=== Mac Installation FAQ ===
cd ~/
 
ls -al
 
cd .lazarus
 
ls
 
</syntaxhighlight>
 
  
To remove it, execute the following commands:
+
* See the [[Mac Installation FAQ]] for solutions to other common problems that may arise during (and after) installation of Lazarus and Free Pascal on macOS.
 
 
<syntaxhighlight lang="bash">
 
cd ~/
 
rm -rv .lazarus
 
</syntaxhighlight>
 
  
= Known issues =
+
== Uninstalling Lazarus and Free Pascal ==
  
* FPC 2.4.4 has a bug. You can not compile the IDE with the range check flag '''-Cr'''.
+
Refer to [[Uninstalling Lazarus on macOS]] for uninstallation options.
* On OS X 10.4 you have to manually uninstall any previous version before installing a new dmg. Delete the following files and folders:
 
** /Developer/lazarus
 
** /Library/Receipts/lazarus.pkg
 
** /etc/lazarus
 
** /usr/local/bin/lazbuild
 
  
* If installing FPC on macOS Mojave (10.14) with an FPC Installer before v3.0.4a you need to also manually install the SDK headers.
+
== Legacy Information ==
** open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
 
  
= See Also =
+
See [[Legacy Information: Installing Lazarus on Mac|Legacy Information]] for details of:
  
* [[Mac Installation FAQ]]
+
* Installing Lazarus on Mac OS X 10.4 (Tiger), Mac OS X 10.5 (Leopard), OS X 10.8 (Mountain Lion)
 +
* Installing Lazarus 2.0.8, 2.0.10 with FPC 3.2.0 for macOS 10.10 and earlier
 +
* Installing Lazarus 2.0.8 with FPC 3.2.0 for macOS 10.11+
 +
* Installing Lazarus on PowerPC-based Macs
 +
* Old Xcode versions
 +
* Installing the gdb debugger
 +
* Compatibility matrix for Lazarus 1.0.0 through 1.6.4 and FPC 2.6.0 through 3.0.2.
  
==Other Interfaces==
+
== See also ==
{{Interfaces}}
 
  
===Platform specific Tips===
+
* [[Xcode]].
*[[OS X Programming Tips]] - Lazarus installation, useful tools, Unix commands, and more...
+
* [[Other macOS installation options]].
*[[WinCE Programming Tips]] - Using the telephone API, sending SMSes, and more...
+
* [[Multiple Lazarus|Installing multiple Lazarus versions]].
*[[Windows Programming Tips]] - Desktop Windows programming tips.
+
* [[Portal:Mac|Mac Portal]] for an overview of development for macOS with Lazarus and Free Pascal.
 +
* [[Mac Installation FAQ]] for solutions to the most frequent problems that may arise during (and after) installation of Lazarus and Free Pascal on macOS.
  
===Interfaces Development Articles===
+
== External links ==
*[[Cocoa Internals]] - If you want to help improving the Cocoa 64 bit interface
 
*[[Carbon interface internals]] - If you want to help improving the Carbon 32 bit interface
 
*[[Windows CE Development Notes]] - For Pocket PC and Smartphones
 
*[[Adding a new interface]] - How to add a new widget set interface
 
*[[LCL Defines]] - Choosing the right options to recompile LCL
 
*[[LCL Internals]] - Some info about the inner workings of the LCL
 
  
[[Category:Mac OS X]]
+
* [https://sourceforge.net/projects/macos-lazarus-snapshots/files/intel/ Lazarus daily development version download] (Intel x86_64)
[[Category:Install]]
+
* [https://sourceforge.net/projects/macos-lazarus-snapshots/files/arm64/ Lazarus + FPC daily development version downloads] (M1, ARM64, aarch64)
[[Category:Lazarus]]
+
* [https://www.syncfusion.com/succinctly-free-ebooks/git GIT Succinctly] - Free Ebook (PDF, MOBI, EPUB) from SyncFusion.

Latest revision as of 05:34, 12 November 2023

English (en) español (es) 한국어 (ko) русский (ru)

macOSlogo.png

This article applies to macOS only.

See also: Multiplatform Programming Guide


Installing Lazarus on a Mac is not particularly difficult but it is critical that you do the install in the correct order. Skipping steps will almost certainly end in tears. In brief, here is what you need to do:

  1. Download and install Xcode (optional depending on your needs - see below for details).
  2. Install the global command line tools for Xcode. Definitely required.
  3. Download and install the Free Pascal Compiler (FPC) binaries package and the FPC source package from the Lazarus IDE file area (Important do this before you install the Lazarus IDE)
  4. Download and install the Lazarus IDE from the Lazarus IDE file area or, perhaps more useful, download and compile Lazarus source code, eg Lazarus Fixes 3.0
  5. Configure LLDB - the Apple supplied (and signed) debugger from within the Lazarus IDE.

These steps are explained in more detail below.

Installation

The detailed instructions assume a recent version of macOS on your Mac, a recent version of Xcode and/or Xcode command line tools from Apple and a recent version of Lazarus. On the Legacy Information page, you will see older information that may be relevant if you are using older components. You can assist by replacing out of date information, either deleting it, or, if it may help someone working with a legacy project, moving it to the legacy information page.

In general, this is about using both the Carbon and Cocoa Widget Sets. While Carbon was once seen as a little more stable, with the release Lazarus 2.0.8 the 64 bit Cocoa Widget Set has now surpassed Carbon and should be considered seriously for any new projects. Carbon was intentionally limited to 32 bits by Apple and you should be aware that it and the ability to run 32 bit executables have been removed completely from macOS 10.15 Catalina and later versions which now only support 64 bit executables using Cocoa.

Step 1: Download Xcode (optional)

Xcode is a 12GB download which will take up 16GB of disk space. You only need to download and install the full Xcode development environment if you need:

  • the SDKs for iOS, iPadOS, watchOS and tvOS; or
  • to validate and upload apps to the Mac App Store; or
  • to notarise apps for distribution outside of the Mac App Store.

Xcode 11.3.1 for use on macOS 10.14 Mojave must now be installed by downloading it from Apple Developer Connection (ADC), which requires free registration. Xcode 12.4.x for use on macOS 10.15 Catalina and later versions can be installed from the Mac App store. Note that you must first move any old Xcode versions from the Applications folder into the trash or rename the Xcode app (eg Xcode.app to Xcode_1014.app). You can then select which version of Xcode to use with the command line utility xcode-select. Open an Applications > Utilities > Terminal and type man xcode-select for this utility's manual page.

Older systems:

The Xcode developer tools can be installed from the original macOS installation disks or a newer copy downloaded from the Apple Developer Connection (ADC), which requires free registration. Download the Xcode file, it will end up in your Downloads directory as a zip file. Click it. It is unarchived into your Downloads directory. You may be happy with it there but maybe not. Other users will see the path to it but be unable to use it. And it is untidy there. So I moved mine and then told xcode-select where it was moved to (in a terminal) -

mv Downloads/Xcode.app /Developer/.
sudo xcode-select -s /Developer/Xcode.app/Contents/Developer

Step 2: Xcode Command Line Tools

This is shown here as a separate step because it really is a separate step. Don't confuse these standalone command line tools with the internal Xcode command line tools that the Xcode GUI will tell you are already installed if you installed the full Xcode package in Step 1. FPC cannot use those Xcode internal command line tools without configuration changes (see Xcode for details).

Do the following, it is quick and easy for all macOS versions up to and including Catalina 10.15:

sudo xcode-select --install
sudo xcodebuild -license accept

For Big Sur 11.x and later, you only need to enter the first of the two commands above unless you have also installed the full Xcode package. If you have only installed the command line tools, you should omit entering the xcodebuild command.

If you have problems installing the command line tools using this command line method (eg the installer freezes while "finding Software"), you can also download and install the command line tools package by logging in to the Apple Developer Site and downloading and installing the Command Line Tools for Xcode disk image.

Step 3: FPC binaries and FPC source code

Light bulb  Note: For Apple Silicon/AArch64/M1 installations, if you are installing FPC 3.2.2 (with Lazarus 2.2.0 or later) you don't need to compile a native Apple Silicon version of FPC because FPC 3.2.2 for macOS is a universal binary containing both Intel and aarch64 executables. If you are installing a version of FPC earlier than 3.2.2, then please refer to these instructions for building a native Apple Silicon Free Pascal Compiler after installing the 64 bit Intel binary and source packages for FPC.

Download and install the official FPC binaries package and the separate FPC source package from the Lazarus IDE file area.

When you arrive at the Lazarus IDE file area:

  1. Choose the correct version of your operating system. The vast majority of Mac users should now choose the 64 bit packages in the Lazarus macOS x86-64 directory. Every Mac computer since late 2006 has been 64 bit capable and Apple has completely dropped all 32 bit support from macOS 10.15 Catalina and beyond.
  1. Choose the version of Lazarus you wish to install and you will be presented with the two FPC binary and source packages to download.

These installation packages are built by the FPC/Lazarus developers and track formal releases. As these installation packages are not approved by Apple, you need to hold down the Control key, click the package and choose Open and confirm you want to install from an Unknown Developer.

You might like to try a simple and quick test of FPC at this stage - Testing FPC installation.

Step 4: Binary Install of the Lazarus IDE

It is critical that a compatible Free Pascal Compiler (FPC) and its source be installed before you install the Lazarus IDE.

Light bulb  Note: there are two versions of this step. The first is to install a binary package that someone else has already compiled for you. As Lazarus evolves, especially so on the Mac, that may be a confining limitation. The second approach is to compile your own, you already have FPC installed and obviously intend to compile your own project, why not do the same for Lazarus ? This will get you access to the newer bug fixes, LCL code in your own disk space (avoiding many "read only" errors) and give you control of whats happening.


Binary Install Download and install the Lazarus IDE from the Lazarus IDE file area. When you arrive at that file area, choose the correct version of your operating system. The vast majority of Mac users should now choose the 64 bit packages in the Lazarus macOS x86-64 directory. Every Mac computer since late 2006 has been 64 bit capable. The fact that Apple has completely dropped all 32 bit support from macOS 10.15 Catalina (released in October 2019) is another reason to choose the 64 bit packages.

Source Install For installing from source, please refer to the Installing Lazarus from Source instructions below to build a native Lazarus IDE. This applies to both x86_64 and Apple Silicon/aarch64 systems. You can use this approach to install a release version, a Fixes version or the development version, "main".

Step 5: Configure the Debugger

In versions of Lazarus 1.8.4 and earlier, you needed to use gdb as a debugger, slow to install and hard to sign. Since Lazarus 2.0.0 you can (and should) use lldb, a debugger provided by Apple, no signing required.

Assuming you have installed what is necessary and started Lazarus, all that remains is configuring the debugger. If you don't do this now, Lazarus will try to use gdb and fail.

  • Lazarus version 2.2.0: First, click Lazarus > Preferences > Debugger - Debugger Backend;
  • Lazarus before version 2.2.0: First, click Tools > Options > Debugger.

Top right of the window now open has a label, "Debugger type and path", you must set both the type and the path. Select the type "LLDB debugger (with fpdebug) (Beta)" and select or type the path /usr/bin/lldb.

Set Debugger2.png

If "LLDB debugger (with fpdebug) (Beta)" is not shown in the selection list, see Installing LazDebuggerFpLLdb below. The XCode command line tools install lldb to the /usr/bin directory. Save those settings and you can now try to compile the almost nothing program that Lazarus has kindly provided for you (click the small green triangle near top left).

Next you see a puzzling question, see image below. Choose a "Debug Format" from one of those offered -

Set Dwarf.png

Martin_fr, the person who has given us this interface between the Lazarus IDE and lldb, suggests you use "dwarf3" . Then, you need to enter your password, a macOS cuteness because one application appears to be interfering with another. In this case, that's fine!

When running the debugger from time to time you will be asked for your password to allow debugging. This is for your own safety.

Extra Information on using lldb

A great deal of information about using lldb appears in this forum thread. Here are a few gems, again, from Martin_fr:

In the unexpected case of problems, it may be worth trying "dwarf with sets" instead of just "dwarf3".

The "debug info" setting only affects the units directly in your project. However, units in packages may have debug info too. This can be:

  • set per package
  • for many, but not all packages in the menu Tools > Configure "Build Lazarus"
  • Project > Project Options > Additions and Overrides

If you change settings for a package, you might want to check which package you expect to step into when debugging. Packages you do not step into, do not need debug info.

If you use a type from a package (such as TForm from LCL) it is enough that your unit (in which you declare the variable / must declare and use a variable to include the type) has debug info. Reducing the number of packages with debug info (including those that default to have debug info), can shorten the debuggers start-up time.

Also it may be worth comparing (it has not been tested) the debuggers start up time for the same settings, only changing the checkbox "use external debug info".

This needs to be only set in your project. If set in your project it will affect all packages. (If set in a package it should have no affect.)

Installing LazDebuggerFpLLdb

If you installed from source and used the bigide parameter to make, then the correct debugger will be installed, as a package, and ready to go. If, however, you installed in another way, it may, or may not be there.

From the main IDE screen, click Packages->Install/UninstallPackages. Shown is two lists of packages, the list on the left is installed, the list on the right is available to install. Look for LazDebuggerFpLldb (exactly that, there are some similar named but less suitable packages). If it is on the right hand side, click it, press "Install Selection" and then "Save and rebuild IDE". This will take a little time, the IDE will shutdown and restart and all should be well. Now jump back up the page and continue configuring the debugger.

Installing Lazarus from Source

Light bulb  Note: When building Lazarus from source, Apple very kindly add a quarantine attribute to your *.app files that ensures they will not run. xattr -drv com.apple.quarantine * will solve this for you.
Light bulb  Note: This process can be seen as an alternative to step 4 above, you still need to install Xcode Command Line Tools and Free Pascal Compiler and its Source.

This chapter focuses of Fixes but the same process applies to Lazarus Main (ie the development version) and other branches or tags in gitlab. At present (November 2023) Fixes_3.0 makes sense and examples below assume that. Later, newer version numbers may be needed.

There are a number of reasons why you may be better off building from Source (particularly, in this case, Fixes_3.0).

  • It gives you access to the 'newest and best' or, perhaps, the 'bleeding edge'. Fixes and main are not usually available as binary installs.
  • The MacOS side of Lazarus changes rapidly, this is particularly so with respect to the debugger and Apple Silicon / aarch64. At the time of writing, for example, Fixes_3.0 has improvements to the debugger that are not present in the 3.0 Release Candidates.
  • Fixes of any version is usually a safer and more stable option than the development branch, but still gets the new features much faster than the release version.
  • Fixes included in fixes 3.0


  • When working with an Apple Silicon M1 processor Mac ensure you use the FPC 3.2.2 or later as it provides a universal binary with both a native aarch64 and Intel compiler. If you must use an earlier FPC than 3.2.2 see Apple Silicon Support for how to do this. When building the Lazarus IDE, change the CPU_TARGET in the instructions below from x86_64 (Intel 64 bit) to aarch64 (ARM 64 bit - Apple Silicon M1).

Downloading Lazarus source

As always, you have several choices when it comes to downloading Lazarus Source.

  • Browse to the Lazarus source repository and select the branch you are interested in. Download a zip or tar file. This is quick and (relatively) small and suits a 'one off' install.
  • Use git, its bigger and slower but a good solution if you are already a git user or expect to be sending in patches to contribute to Lazarus. In this case, you need main, Lazarus does not accept patches for other branches. Advantage of git (or svn) is that its easily and quickly updated and if you plan to track the frequent updates that happen (to non-release) versions its worthwhile. This wiki has good instructions on using git. Typically git clone https://gitlab.com/freepascal.org/lazarus/lazarus.git to get Lazarus Main.
  • If you have wget installed and know the url you want, its all too easy. Some examples, firstly the current (Nov 2023) Fixes_3.0 and then main.
$> wget  https://gitlab.com/freepascal.org/lazarus/lazarus/-/archive/fixes_3_0/lazarus-fixes_3_0.zip
$>
$> wget https://gitlab.com/freepascal.org/lazarus/lazarus/-/archive/main/lazarus-main.zip

The zip or tarballs are about 60Meg, git (or svn) bigger because they hold all the history as well. In all cases, ensure your source ends up in a directory by it self, remember you may end up with several installs so make a reasonable directory structure. This (very un Mac like) author keeps such things in (eg) $HOME/bin/Lazarus/lazarus-fixes_3.0.

Building source

Assuming some things here, you may make different choices, adjust accordingly -

  • you have Lazarus Fixes source (from either tar, zip or git)
  • you have the directory structure mentioned above
  • you are using an x86_64 box (use CPU_TARGET=aarch64 otherwise)
  • you want to keep your Lazarus configs in their own specified place (essential if you will have multiple installs, a very good idea other wise).
$> cd bin/Lazarus/lazarus-fixes_3.0
$> make clean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
//-wait some time...
$> xattr -drv com.apple.quarantine *

If this is a rebuild and all you have downloaded is an update to a not too old version, you can restore your installed packages and configuration by using "make useride" after a successful "make clean ..." step, possibly even instead off if its recent enough. Does no harm if you fail.

  • The xattr command removes a quarantine attribute from your app directories kindly added by Apple to prevent them from working.
  • On older macOS versions supporting 32 bit applications, replace the above make line with "make LCL_PLATFORM=carbon CPU_TARGET=i386 bigide " and set up your project as mentioned in the Carbon and Cocoa section below.

Setup a Config Directory Structure

This step is not necessary if you will be happy with just this one Lazarus install. Lazarus will make a config directory if it needs to but will not make any directories about that. So, here we make a single directory to hold all our Lazarus configs. Before we do that, while we are still in the lazarus-fixes_3.0 directory, we create a lazarus.cfg file that will tell this Lazarus where to store its config. You do this only once for each Lazarus install.

$> cat > lazarus.cfg <enter>
--pcp='~/bin/Lazarus/LazConfigs/lazarus-fixes_3.0 <enter>
Press Ctrl D

$> mkdir ../LazConfigs

Starting Lazarus

You must start Lazarus using the "app bundle", that is, typically startlazarus.app or lazarus.app in this case. Don't use the lazarus or startlazarus binary, described in the Finder as 'unix binaries'. If you get that wrong, directly starting a Lazarus binary will result in no menu or mouse interaction. Its an Apple thing.

  • From the command line that means for example 'open lazarus.app'. You will probably cd to the directory containing the Lazarus install and just type open ./lazarus.app or, if you want pass the name of a Config Dir and start from anywhere, something like open startlazarus.app --args "--pcp=~/bin/Lazarus/LazConfigs/lazarus-fixes_3.0"
  • Using the Finder is, perhaps, a bit more "mac like". Navigate to the directory where your Lazarus install is, double click on the lazarus.app (or startlazarus.app) entry and all is good. However, by default, the Finder does not show the ".app" part of the name, its hard to tell the difference between "lazarus" and "lazarus.app". You want the one with a caricature of a leopard's face, Finder describes it as an Application.
  • Thirdly, depending on how you like to work, maybe make a bash script to start Lazarus ? Note I pass a parameter to define the config directory, that is unnecessary if you have put the suggested lazarus.cfg file in place.
#!/bin/bash
LAZDIR="lazarus-fixes_3.0"
cd ~/bin/Lazarus/"$LAZDIR"
open ~/bin/lazarus/"$LAZDIR"/lazarus.app --args "--pcp=~/bin/Lazarus/LazConfigs/$LAZDIR"

What does the bigide make argument do?

The bigide make argument adds a bunch of packages to Lazarus that many find useful and cannot do without. The packages that are added are:

  • cairocanvas
  • chmhelp
  • datetimectrls
  • externhelp
  • fpcunit
  • fpdebug
  • instantfpc
  • jcf2
  • lazcontrols
  • lazdebuggers
  • lclextensions
  • leakview
  • macroscript
  • memds
  • onlinepackagemanager
  • pas2js
  • PascalScript
  • printers
  • projecttemplates
  • rtticontrols
  • sdf
  • sqldb
  • synedit
  • tachart
  • tdbf
  • todolist
  • turbopower_ipro
  • virtualtreeview

The above list is sourced from the [Lazarus source directory]/IDE/Makefile.fpc and may be subject to change.

Note that if you have not compiled your own Lazarus IDE with the bigide argument, you can install any of these packages yourself using the Lazarus IDE Package > Install/Uninstall Packages... dialog.


Managing your Config Directory

Further up, in this section, we mentioned the Lazarus Config Directory. Maybe a few words about it here will help, especially if you are having some problems.

  • The config dir can have any name you like but, as is frequently the case with low level stuff, best not to have spaces in the directory name nor in the path to it. In practise, its a good idea to give the config dir a name that hints at the install of Lazarus that uses it.
  • The config dir can be anywhere you like as long as you have write access to it.
  • The config dir must be used by only one install of Lazarus. If you install a new version of Lazarus, not too far from your old one, Lazarus will offer to upgrade it but there is no going back to the old one.
  • The config dir holds a whole lot of information about what you are doing with Lazarus. For example, things you set when Lazarus first started up, Options such as tab spacing, where the help files are and, importantly, any package you may have installed. For users who have Lazarus (initially) installed in read only disk space, Lazarus keeps anything of itself that has been altered in the config dir too. (That's just one reason its better to build from source.)
  • Given the above point, if you remove the Lazarus Config Directory, its a bit like doing a factory reset on your smart phone. All your settings and additions will be discarded and Lazarus will startup fresh, will want to know where things like fps are, what debugger you are using etc, fortunately, new versions of lazarus are pretty good at finding sensible defaults, older version might need a bit of help.

Ok, so, the Lazarus Config directory is clearly important and probably best not fiddled with by the inexperienced but it is a quite reasonable thing to just delete it to go (right) back to a known good install.

  • If you have selected a config directory of your own (with a lazarus.cfg file or a command line parameter) then you know where it is and you can delete it using either the Finder or Command Line.
  • If you have allowed Lazarus to choose where to put the config dir then Lazarus will make and use a directory called .lazarus in your home directory. The dot makes it a hidden directory, both the Finder and ls command will ignore it unless instructed to display hidden files. But you don't need to see it, you know it is in your home directory, delete it with -

rm -Rf ~/.lazarus <enter>

I am sure I don't need to be warn about the danger of the rm command but I will, be careful ! Never use rm -Rf without an explicit directory name to delete !

Installing non-release versions of FPC

Installing from source

There are two current non-release branches of the Free Pascal Compiler: the development (trunk) branch and the Fixes 3.2 branch which includes additional fixes to the released 3.2.2 version. Developers, and those who like living on the bleeding edge and testing new features and fixes, will choose the development version; more normal users, who wish to use a stable branch with some additional fixes since the latest release version, will choose the Fixes branch. The instructions below cover both these branches.

The source code is kept in a version control system called git:

  • macOS 10.5 and higher already contain a command line git client if you have installed the Xcode command line utilities.
  • You also need the latest released Free Pascal Compiler version (3.2.2 as of March 2022) installed in order to be able to successfully compile the development (trunk) version.
Light bulb  Note: When building a native aarch64 Free Pascal Compiler (ppca64) for an Apple Silicon M1 processor Mac, change the CPU_TARGET in the instructions below from x86_64 (Intel 64 bit) to aarch64 (ARM 64 bit - Apple Silicon M1) and change any reference to ppcx64 to ppca64

FPC development version

Note that since the development version of FPC (was known as "trunk" in SVN; now known as "main" in GIT) is by definition still under development, some of the features may still change before they end up in a release version.

Create a directory where you would like to put the source (eg fpc_main in your home directory). You don't need to be root to do this. Any normal user can do this. Open an Applications > Utilities > Terminal and do the following:

 []$ git clone -b main https://gitlab.com/freepascal.org/fpc/source.git fpc_main

This will create a directory called fpc_main and download the FPC main source to it.

To subsequently update your local source repository with the latest source changes you can simply do:

 []$ cd
 []$ cd fpc_main
 []$ git clean -f -d
 []$ git pull

To build and install FPC (the highlighted text should be all on one line):

 []$ cd
 []$ cd fpc_main
 []$ make distclean all FPC=/usr/local/lib/fpc/3.2.2/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 []$ sudo make install FPC=$PWD/compiler/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64

You will also need to update the links for the compiler in /usr/local/bin which will be pointing to the previous FPC version. For example:

 []$ cd /usr/local/bin
 []$ sudo rm ppc386
 []$ sudo rm ppcx64
 []$ sudo ln -s /usr/local/lib/fpc/3.3.1/ppc386
 []$ sudo ln -s /usr/local/lib/fpc/3.3.1/ppcx64

Note that you will need to build a new ppc386 compiler if you want to continue to compile 32 bit applications by replacing these lines (this is not be possible after Xcode 11.3.1 and macOS 10.14.6 Mojave because of Apple's removal of the 32 bit frameworks):

 []$ make clean all FPC=/usr/local/lib/fpc/3.2.2/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 []$ sudo make install FPC=$PWD/compiler/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64

with these two lines:

 []$ make clean all FPC=/usr/local/lib/fpc/3.2.2/ppc386 OS_TARGET=darwin CPU_TARGET=i386 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 []$ sudo make install FPC=$PWD/compiler/ppc386 OS_TARGET=darwin CPU_TARGET=i386

FPC Fixes 3.2

Create a directory where you would like to put the source (eg fpc_fixes32 in your home directory). You don't need to be root to do this. Any normal user can do this. Open an Applications > Utilities > Terminal and do the following:

 []$ git clone -b fixes_3_2 https://gitlab.com/freepascal.org/fpc/source.git fpc_fixes32

This will create a directory called fpc_fixes32 and download the FPC source to it.

To subsequently update your local copy of the repository source with the latest source changes you can simply do:

 []$ cd fpc_fixes32
 []$ git clean -f -d
 []$ git pull

To build and install FPC (the highlighted text should be all on one line):

 []$ cd
 []$ cd fpc_fixes32
 []$ make distclean all FPC=/usr/local/lib/fpc/3.2.2/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 []$ sudo make install FPC=$PWD/compiler/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64

You will also need to update the links for the compiler in /usr/local/bin which will be pointing to the previous FPC version. For example:

 []$ cd /usr/local/bin
 []$ sudo rm ppc386
 []$ sudo rm ppcx64
 []$ sudo ln -s /usr/local/lib/fpc/fixes-3.2/ppc386
 []$ sudo ln -s /usr/local/lib/fpc/fixes-3.2/ppcx64

Note that you will need to build a new ppc386 compiler if you want to continue to compile 32 bit applications by replacing these lines (this may not be possible after Xcode 11.3.1 and macOS 10.14.6 Mojave because of Apple's removal of the 32 bit frameworks):

 []$ make clean all FPC=/usr/local/lib/fpc/3.2.2/ppc386 OS_TARGET=darwin CPU_TARGET=i386 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 []$ sudo make install FPC=$PWD/compiler/ppc386 OS_TARGET=darwin CPU_TARGET=i386

Cocoa 64 bit vs Carbon 32 bit

Using the Apple 64 bit Cocoa framework is now undeniably the future on the Mac. The Apple 32 bit Carbon framework, while no longer being developed, works pretty much as expected, but you are advised to try Cocoa first because Apple dropped all support for 32 bit applications and the 32 bit Carbon framework in macOS 10.15 Catalina (October 2019).

It is possible to build a Carbon version of the Lazarus IDE (unless you are running macOS 10.15 Catalina or later) and use that to generate Cocoa 64 bit binaries.

To produce Cocoa applications in the Carbon or Cocoa IDE, you need to set the Target to the 64 bit processor and select the Cocoa widgetset:

  • Open your project with Lazarus and from the menu select Project > Project Options
  • In the "Config and Target" panel set the "Target CPU family" to be "x86_64" (Intel) or "aarch64" (Apple M1)
  • In the "Config and Target" panel, if the "Current LCL widgetset" is not set to Cocoa, click "Select another LCL widgetset" which will take you to the "Additions and Overrides" panel where you can click on "Set LCLWidgetType" pulldown and set the value to "Cocoa"
  • Make sure under Tools > Options (Lazarus > Preferences in v2.2.0 and later) that "Compiler Executable" is set to "/usr/local/bin/fpc" to get 64 bit applications.
  • Now compile your project - and please feed back any problems you experience.


FPC + Lazarus Compatibility Matrix

Not every combination of Lazarus and Free Pascal is compatible with every installation of macOS. Please refer to the following table in order to find the correct version for your development environment:

Lazarus Compatibility Matrix
Lazarus 1.8.x Lazarus 2.0.y Lazarus 2.0.8 Lazarus 2.0.10 Lazarus 2.0.12 Lazarus 2.2.y
FPC 3.0.4 FPC 3.2.0 FPC 3.2.2
PPC processors
Mac OS X 10.4 (Tiger) Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible
Mac OS X 10.5 (Leopard) Not tested Not tested Incompatible Incompatible Incompatible Incompatible Incompatible
Intel processors
Mac OS X 10.4 (Tiger) Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible
Mac OS X 10.5 (Leopard) Not tested Compatible^ Not tested Compatible^** Not tested Not tested Not tested
Mac OS X 10.6 (Snow Leopard) Compatible Compatible^^ Not tested Not tested Not tested Not tested Not tested
Mac OS X 10.7 (Lion) Compatible Not tested Not tested Not tested Not tested Not tested Not tested
OS X 10.8 (Mountain Lion) Compatible^^ Compatible Compatible**# Compatible**# Compatible**# Compatible# Compatible
OS X 10.9 (Mavericks) Compatible^^ Compatible Compatible** Compatible** Not tested Not tested Not tested
OS X 10.10 (Yosemite) Compatible^^ Compatible Compatible** Compatible** Not tested Not tested Not tested
OS X 10.11 (El Capitan) Compatible^^ Compatible Compatible*** Compatible Compatible Compatible Comptaible
macOS 10.12 (Sierra) Compatible^^ Compatible Compatible*** Compatible Compatible Compatible Compatible
macOS 10.13 (High Sierra) Not tested Compatible Compatible*** Compatible Compatible Compatible Comptaible
macOS 10.14 (Mojave) Not tested Compatible Compatible*** Compatible Compatible Compatible Compatible
macOS 10.15 (Catalina) Not tested Compatible Compatible*** Compatible Compatible Compatible Compatible
macOS 11 (Big Sur) Not tested Compatible Compatible*** Compatible Compatible Compatible Compatible
macOS 12 (Monterey) Not tested Not tested Not tested Not tested Not tested Not tested Compatible
macOS 13 (Ventura) Not tested Not tested Not tested Not tested Not tested Not tested Compatible
macOS 14 (Sonoma) Not tested Not tested Not tested Not tested Not tested Not tested Compatible
Apple Silicon M series processors
macOS 11 (Big Sur) Not tested Not tested Not tested Compatible†† Compatible†† Compatible††† Compatible*
macOS 12 (Monterey) Not tested Not tested Not tested Compatible†† Compatible†† Compatible††† Compatible*
macOS 13 (Ventura) Not tested Not tested Not tested Compatible†† Compatible†† Compatible††† Compatible*
macOS 14 (Sonoma) Not tested Not tested Not tested Compatible†† Compatible†† Compatible††† Compatible*

x = 0, 2 or 4; y = 0, 2, 4 or 6

^ Carbon interface compiles - Cocoa does not.

^^ Restrictions apply to debugging with gdb.

* Lazarus 2.2.0 installs universal binaries for FPC 3.2.2, but an Intel Lazarus IDE binary which you can use or recompile the IDE from within itself for a native aarch64 version.

** See Installing Lazarus 2.0.8, 2.0.10 with FPC 3.2.0 for macOS 10.10 and earlier for instructions.

*** See Installing Lazarus 2.0.8 with FPC 3.2.0 for macOS 10.11+ for instructions.

# Cannot run without debugging in the IDE. Can run compiled application outside of the IDE. See Issue #37324. Choose the gdb debugger, change timeout option to false or click through five "timeout" dialogs to run with debugging in the IDE.

Cannot "run without debugging" in the IDE. Can run compiled application outside of the IDE. See Lazarus IDE - Unable to "run without debugging" for workaround. See Issue #36780.

†† You need to compile a native aarch64 version of FPC 3.3.1 (trunk) and Lazarus 2.0.12 from source to support an Apple Silicon M series processor. Refer to these instructions for FPC and these instructions for the Lazarus IDE.

††† After installing FPC 3.2.2, you need to compile a native aarch64 version of Lazarus from source to support an Apple Silicon M series processor. Refer to these instructions for compiling the Lazarus IDE.

See the legacy version of this compatibility matrix for recommended installs on very old versions of macOS.


Known issues and solutions

Lazarus IDE v2.2.0 - rebuilding issue

Any attempt to rebuild the Lazarus IDE from within itself fails with permission errors because the files and directories are owned by a user with the id of 503 whereas most users will find that their id is 501. The solution is to open an Applications > Utilities> Terminal and:

cd /Applications
sudo chown -R your_username Lazarus

Rebuilding errors do not happen on Intel computers

The next error that occurs is that the resource compiler "fpcres" is not found. The solution is to create a .fpc.cfg (note the initial dot) file in your home directory and add these lines to it:

#include /etc/fpc.cfg
-FD/usr/local/bin

so that "fpcres" can be found where it was installed.

The next error complains of an unsupported target architecture -Paarch64, with the advice to invoke the "fpc" compiler driver instead - except that is what we are doing already. The solution is to go to Lazarus > Preferences > Compiler executable which is set to /usr/local/bin/fpc and change that to /usr/local/lib/fpc/3.2.2/ppca64 instead.

The IDE will now be successfully rebuilt but will not restart automatically. Trying to then start Lazarus from either the startlazarus.app icon or the lazarus.app icon in /Applications/Lazarus still results in the original Intel lazarus binary being launched. The correct aarch64 binary can be found in ~/.lazarus/bin/aarch64-darwin/lazarus. So the final solution is to open an Application > Utilities > Terminal and:

mv /Applications/Lazarus/lazarus /Applications/Lazarus/lazarus.old
mv  ~/.lazarus/bin/aarch64-darwin/lazarus /Applications/Lazarus/

You can then start the IDE with either the startLazarus.app or lazarus.app icons. When you do restart lazarus, it is worth returning to the Lazarus > Preferences > Compiler executable which is set to /usr/local/lib/fpc/3.2.2/ppca64 and changing it back to /usr/local/bin/fpc so that you can compile both aarch64 and Intel binaries to, for example, make a Universal Binary which will run on both Intel and aarch64 machines.

Lazarus IDE - Unable to "run without debugging"

If you are using the Lazarus IDE 2.0.10 and the Run > Run without debugging menu option fails with a dialog similar to:

run dialog fail.png

then you need to patch the Lazarus 2.0.10 source code (Issue #37324 and Issue #36780). Specifically, patch ../ide/main.pp as below (unpatched lines shown first, patched lines shown second):

 7243,7245c7243,7245
 <     if RunAppBundle
 <         and FileExistsUTF8(Process.Executable)
 <     and FileExistsUTF8('/usr/bin/open') then
 ---
 >     if RunAppBundle then
 >     //    and FileExistsUTF8(Process.Executable)
 >     //and FileExistsUTF8('/usr/bin/open') then

and recompile the Lazarus IDE.

Alternatively, you can omit patching the source code and simply recompile Lazarus 2.0.10 with FPC 3.0.4.

A similar patching exercise and recompiling, or simply recompiling with FPC 3.0.4, needs to be done for Lazarus 2.0.8 if it has been compiled with FPC 3.2.0.

Upgrading from Mojave (10.14) to Catalina (10.15)

  • Run sudo xcode-select --install
  • To enable Lazarus to locate the crt1.10.5.o file change in /etc/fpc.cfg the -Fl behind "#ifdef cpux86_64" from
-Fl/Applications/Xcode.app/Contents/Developer/Toolchain...

to

-Fl/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/lib/

Building the FPC compiler from Mojave (10.14) onwards

  • To find the crt1.10.5.o file when building a later Free Pascal Compiler version from source, you need to specify:
 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"

on the make command line because FPC ignores the /etc/fpc.cfg configuration file during builds of itself.

Mac Installation FAQ

  • See the Mac Installation FAQ for solutions to other common problems that may arise during (and after) installation of Lazarus and Free Pascal on macOS.

Uninstalling Lazarus and Free Pascal

Refer to Uninstalling Lazarus on macOS for uninstallation options.

Legacy Information

See Legacy Information for details of:

  • Installing Lazarus on Mac OS X 10.4 (Tiger), Mac OS X 10.5 (Leopard), OS X 10.8 (Mountain Lion)
  • Installing Lazarus 2.0.8, 2.0.10 with FPC 3.2.0 for macOS 10.10 and earlier
  • Installing Lazarus 2.0.8 with FPC 3.2.0 for macOS 10.11+
  • Installing Lazarus on PowerPC-based Macs
  • Old Xcode versions
  • Installing the gdb debugger
  • Compatibility matrix for Lazarus 1.0.0 through 1.6.4 and FPC 2.6.0 through 3.0.2.

See also

External links