Difference between revisions of "Installing Lazarus on macOS"

From Lazarus wiki
Jump to navigationJump to search
m (Typo)
m (→‎Downloading Lazarus Fixes 2.2 source: Tweak svn command (old one also works))
(45 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Installing Lazarus on macOS}}
 
{{Installing Lazarus on macOS}}
 
== Quick Installation (The Wimp Edition) ==
 
 
These instructions are intended for entrants into the exciting cross-platform development ecosystem built around the Free Pascal (FPC) compiler and the Lazarus IDE. Having had some difficulties to get my first MacOS installation running, I wanted to provide a quick and simple installation experience to get FPC and Lazarus going on a modern MacOS based computer. These instructions represent the status of the Lazarus/FPC/FPCUpDeluxe project around 07-2021 and were tested with MacOS Catalina (10.14) and MacOS Big Sur (11.4) running on Intel processor based hardware. The procedure should be the same with MacOS running on other processors like PowerPC or M1, but I don't own one of these, if you find any deviations please let me know, or feel free to contribute to this documentation.
 
 
The procedure was designed to be GUI-only (wimp-ish, like I said ...), and work without pre-installing any additional packages. Specifically the quite big official Apple Software Development Kit ("Xcode") is not required, you can install it later any time if you ever find you need it.
 
 
=== Download and install FPCUpDeluxe ===
 
 
FPCUpDeluxe is a tool developed by the Lazarus/FPC community to ease the installation of FPC and Lazarus not only on MacOS, but also on other GUI oriented operating systems like Linux or Windows, in a uniform way. It lets you pull together your individual installation package from a user-friendly GUI and does all the inner workings automatically. For those who wish to do their own build from scratch/source, see the "Pro" section of this document further down. If you want to stay on the easy path first, continue here.
 
 
First, using Safari, you download the current version of FPCUpDeluxe for the Mac from the [https://github.com/LongDirtyAnimAlf/fpcupdeluxe FPCUpDeluxe developer site]. Follow the link to the "latest" release and pick the "Cocoa" package which fits your hardware. This document was created using the file "fpcupdeluxe-x86_64-darwin-cocoa.zip" to fit my 64-bit Intel hardware based computer. After downloading and unpacking the FPCUpDeluxe app file you can find it in the "Downloads" folder as usual, but don't try to run the program from there, MacOS will block it due to security restrictions.
 
 
Instead create a folder where FPCUpDeluxe can live in peace and store some files, I suggest you use Applications/FPCUpDeluxe. Create that folder using Finder, and move the .app from "Downloads" into there. Still don't run the app yet, more MacOS security concerns need to be satisfied.
 
 
To run the app first time, open its context menu (right mouse click) and choose "open". This will bring up the three button dialog which lets you confirm that you trust this app, though it was not code-signed and notarized by Apple. Use the middle button ("open") to permit FPCUpDeluxe to run.
 
 
(Todo: Screenshot)
 
 
Now you should see the FPCUpDeluxe GUI in full bloom, with a wide selection of FPC and Lazarus versions to pick from.
 
 
(Todo: Screenshot)
 
 
=== Install FPC and Lazarus using FPCUpDeluxe ===
 
 
From the many packages on display in FPCUpDeluxe, only two are of real importance for you: "stable.git" and "trunk.git". Usually you'll make your first steps using the "stable.git" package. Pick it for both FPC and Lazarus, make sure your Internet connection is available and willing, and hit the "Install/Update FPC+Laz" button.
 
 
At the first attempt, this process will automatically trigger the installation of the "XCode Command Line Tools" (not to be mistaken with the "XCode" Apple Development Kit). This relatively small package is automatically downloaded from Apple and installed, once you build your first Lazarus/FPC installation with FPCUpDeluxe. On a reasonably fast Internet connection this will take around 5 minutes or less (numbers taken in Germany, may substancially differ in, say, Inner Mongolia). Please be patient and watch out for several dialogs popped up by MacOS where you need to grant permissions and accept Apple's license terms, so the XCode Command Line Tools get installed properly. Unfortunately FPCUpDeluxe will not wait for the tool installation to finish, but abort the installation prematurely and complain about missing files. So please wait until the XCode Command Line Tools have finished installing, and then hit "Install/Update FPC+Laz" again. This time the installation runs through, which takes around 15-30 minutes, depending on Internet speed and the speed of your hardware. Watch the console window on the right of FPCUpDeluxe to see progress and (hopefully not) error messages.
 
 
(Todo: Screenshot)
 
 
Right before the installation ends successfully, another security prompt from the MacOS Gatekeeper asks permission for FPCUpDeluxe to take control of the MacOS Finder. Be sure to follow all the nested security dialogs into the MacOS abyss of settings until you eventually you reach the one where you can grant this permission, before letting FPCUpDeluxe continue, we don't want to crash the installation right before we reached success. The permission you have just granted allows FPCUpdateLuxe to create the Lazarus IDE start icon on your MacOS desktop.
 
 
(Todo: Screenshot)
 
 
=== Enjoy your first program (Hello World)! ===
 
 
After successful installation a little demo project is displayed automatically, but unfortunately it won't work on the Mac because it is intended to run in a text console (terminal) which is not easily provided by MacOS. Start a new "Application" project, put a button on the form, double-click it to bring up it's OnClick event handler and enter the following groundbreaking code:
 
 
(Todo: sample code)
 
 
You probably may notice that the "Hello World!" text is assigned to seemingly useless string variable before displaying it, the reason is that we want at least one variable in our test code, so we can test the debugger in the next step. Also forgive the inelegant constant ($10), usually you add a predefined constant like MB_ICONINFORMATION here, but we don't want to include any libraries yet, so for the moment a constant value must do the job.
 
 
Hit the green arrow in the top menu of Lazarus to compile and run your first project, and this is what you should get:
 
 
(Todo: Screenshot)
 
 
=== A first glimpse at the debugger ===
 
 
The next step you will probably take is to configure and test the debugger. It is already installed in MacOS, but you need to enable it in Lazarus once before you can use it. See chapter 2.5 ("STep 5") of the "Expert" section below. After having installed LLDB support in Lazarus, switch our mini-project to the new debugger using "Project-Options", since it was most likely created before you configured LLDB it doesn't know about the new debugger yet. Then, set a breakpoint in our litte program by clicking left of the line number in the source code editor to insert that alarminly looking red bar, and run the code again.
 
 
(Todo: screenshot)
 
 
As soon as you hit the button, program execution stops, and the debugger kicks in and let's you exam the inner workings of your code. Amongst the many capabilities a debugger offers you, let me quickly outline the two which are, at the beginning of your Lazarus/FPC efforts, the two you will likely use most:
 
 
- hover the cursor over the "s" variable, and see the current value of s
 
 
- Use "View - Debugging Windows - Call Stack" to open the "Call Stack" window and see which method/procedure has called this code sequence.
 
 
(Todo: screenshot)
 
 
=== Final words ===
 
 
Aside from this wiki, there are two excellent user forums for further reading and to get in touch with other FPC/Lazarus cross platform developers:
 
 
[https://forum.lazarus.freepascal.org/index.php Lazarus/FPC site (English)]
 
 
[https://www.lazarusforum.de/index.php German Lazarus Forum (German/English)]
 
 
== Installation (Pro Edition) ==
 
  
 
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:
 
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:
Line 80: Line 10:
  
 
These steps are explained in more detail below.
 
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 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.
 
The detailed instructions assume a recent version of macOS on your Mac, a recent version of Xcode 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.
Line 104: Line 38:
 
=== Step 2: Xcode Command Line Tools ===
 
=== Step 2: Xcode Command Line Tools ===
  
This is shown here as a separate step because it really is a separate step in addition to Step 1. 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. FPC cannot use those Xcode internal command line tools without configuration changes (see [[Xcode]] for details), so do the following (it is quick and easy):
+
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:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
sudo xcode-select --install
 
sudo xcode-select --install
sudo xcodebuild -license accept
+
sudo xcodebuild -license accept  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
If you have problems installing the command line tolls 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.
+
For Big Sur 11.x, 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 [https://developer.apple.com/download/more/?=for%20Xcode Apple Developer Site] and downloading and installing the ''Command Line Tools for Xcode'' disk image.
  
 
=== Step 3: FPC binaries and FPC source code ===
 
=== Step 3: FPC binaries and FPC source code ===
Line 131: Line 69:
  
 
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]].
 
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]].
 
==== Other FPC Options ====
 
 
===== fpcupdeluxe =====
 
 
You could also consider using [[fpcupdeluxe]] to install FPC and Lazarus.
 
 
===== fink =====
 
 
Alternatively, you can use [http://finkproject.org/ fink], a package manager for macOS to install FPC. Note at the time of writing (Early 2020) fink offers Lazarus 2.0.6. 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 | Free Pascal crosscompilers]] for many processors and systems.  The choice for Lazarus is between a Carbon or Cocoa look, a gtk2 look, a Qt4-based and a Qt5-based version:
 
 
<syntaxhighlight lang="bash">$ fink install lazarus-aqua
 
// or
 
$ fink install lazarus-cocoa
 
// 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 Free Pascal 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.
 
 
After installation, Lazarus can be started from the folder /Applications/Fink/. The actual details of FPC and Lazarus are in subdirectories of /sw
 
 
With any Lazarus package from fink, these widget sets are supported for your program on macOS:
 
 
carbon (Aqua), cocoa, gtk2, qt4 (Aqua), qt5 (Aqua), nogui, win32, win64 and wince.
 
 
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.
 
 
===== MacPorts =====
 
 
MacPorts also has a package description of the cocoa-64 bit version of Lazarus. Install it with:
 
 
<syntaxhighlight lang="bash">$ port install lazarus</syntaxhighlight>
 
  
 
=== Step 4: Install the Lazarus IDE ===
 
=== Step 4: Install the Lazarus IDE ===
  
{{Note| For installation on Apple Silicon/AArch64, please refer to the [[#Lazarus Fixes 2.0|Lazarus Fixes 2.0]] or [[#Lazarus Trunk|Lazarus Trunk]] instructions to build a native Lazarus IDE. Skip to the building instructions and use the Lazarus Fixes 2.0 source / Lazarus Trunk source / Lazarus 2.1.0 release version source download as you wish.}}
+
{{Note| For installation on Apple Silicon/AArch64, please refer to the [[#Lazarus Fixes 2.2|Lazarus Fixes 2.2]] or [[#Lazarus Trunk|Lazarus Trunk]] instructions to build a native Lazarus IDE. Skip to the building instructions and use the Lazarus Fixes 2.2 source / Lazarus Trunk source download as you wish.}}
  
 
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.
 
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.
Line 243: Line 145:
 
== Installing non-release versions of the Lazarus IDE ==
 
== Installing non-release versions of the Lazarus IDE ==
  
=== Lazarus Fixes 2.0 ===
+
=== Lazarus Fixes 2.2 ===
  
* [[Lazarus_2.0_fixes_branch|Fixes included in fixes_2_0]]
+
* [[Lazarus_2.2_fixes_branch|Fixes included in fixes_2_2]]
  
There are a number of reasons why you may be better off using a non-release version of Lazarus, specifically, fixes_2_0. Particularly:
+
There are a number of reasons why you may be better off using a non-release version of Lazarus, specifically, fixes_2_2. Particularly:
  
* You almost certainly need to target Cocoa, macOS 10.15 Catalina does not support 32 bit Carbon at all.
+
* You almost certainly need to target 64 bit Cocoa, macOS 10.15 Catalina and later do not support 32 bit Carbon at all.
* The Cocoa widget set has steadily improved, and the lldb debugger interface has rapidly improved, since even v2.0.0.
+
* The Cocoa widget set has steadily improved and the lldb debugger interface has rapidly improved, since even v2.0.0.
* Fixes_2_0 is a safer and more stable option than trunk, but still gets the new features much faster than the release version.
+
* If your Mac has an Apple M1 Processor, the debugger in fixes_2_2 now works for aarch64.
 +
* Fixes_2_2 is a safer and more stable option than trunk, but still gets the new features much faster than the 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. A little slow initially but very reliable and a great test of your compiler install ! You will need git which is included in all recent versions of the Xcode command line tools which you should have already installed (see [[#Step_2:_Xcode_Command_Line_Tools|Xcode Command Line Tools]] above).
+
Pre-compiled binaries based on fixes_2_2 are not available from SourceForge so we download and build from the source code. A little slow initially but very reliable and a great test of your compiler install ! You will need git which is included in all recent versions of the Xcode command line tools which you should have already installed (see [[#Step_2:_Xcode_Command_Line_Tools|Xcode Command Line Tools]] above).
  
 
About svn or git: The Xcode 11.4 command line tools on macOS 10.15 no longer install svn, only git. You can install subversion via fink, ports or brew.
 
About svn or git: The Xcode 11.4 command line tools on macOS 10.15 no longer install svn, only git. You can install subversion via fink, ports or brew.
Line 259: Line 162:
 
{{Apple Silicon Lazarus Build Notes}}
 
{{Apple Silicon Lazarus Build Notes}}
  
==== Downloading Lazarus Fixes 2.0 source ====
+
==== Downloading Lazarus Fixes 2.2 source ====
  
 
Create a directory for Lazarus and download the current fixes version:
 
Create a directory for Lazarus and download the current fixes version:
Line 270: Line 173:
  
 
Using git:
 
Using git:
  git clone -b fixes_2_0 https://github.com/User4martin/lazarus.git laz_fixes
+
  git clone -b fixes_2_2 https://gitlab.com/freepascal.org/lazarus/lazarus.git laz_fixes
  
 
Using svn:
 
Using svn:
  svn checkout https://svn.freepascal.org/svn/lazarus/branches/fixes_2_0 laz_fixes
+
  svn checkout https://github.com/fpc/Lazarus/branches/fixes_2_2 laz_fixes
  
Depending on your internet connection and server congestion this takes a few seconds or a couple of minutes.
+
Depending on your internet connection and server congestion this takes a few seconds or a few minutes.
  
==== Updating Lazarus Fixes 2.0 source ====
+
==== Updating Lazarus Fixes 2.2 source ====
  
To keep your fixes_2_0 installation up to date is as easy as:
+
To keep your fixes_2_2 installation up to date is as easy as:
  
 
Using git:
 
Using git:
Line 297: Line 200:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== Building Lazarus Fixes 2.0 source ====  
+
==== Building Lazarus Fixes 2.2 source ====  
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 308: Line 211:
 
* Note I pass a parameter to use a config directory that is based on the name of the actual install directory. It makes some scripting easy.
 
* Note I pass a parameter to use a config directory that is based on the name of the actual install directory. It makes some scripting easy.
  
* On older macOS supporting 32bit applications, replace above make line with "''make LCL_PLATFORM=carbon CPU_TARGET=i386 bigide'' " and setup your project as mentioned in the [[#Cocoa_64_bit_vs_Carbon_32_bit|Carbon and Cocoa]] section below.
+
* 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.
  
 
You might like to put a small script in your $HOME/bin directory and even set a path to it (very UNIX!)
 
You might like to put a small script in your $HOME/bin directory and even set a path to it (very UNIX!)
Line 328: Line 231:
  
 
<syntaxhighlight lang="sh">
 
<syntaxhighlight lang="sh">
cd ~
+
cd
 
mkdir -p bin/lazarus
 
mkdir -p bin/lazarus
 
cd bin/lazarus
 
cd bin/lazarus
Line 334: Line 237:
  
 
Using git:
 
Using git:
  git clone https://github.com/User4martin/lazarus.git laz_trunk
+
  git clone -b main https://gitlab.com/freepascal.org/lazarus/lazarus.git laz_trunk
  
 
Using svn:
 
Using svn:
  svn checkout https://svn.freepascal.org/svn/lazarus/trunk laz_trunk
+
  svn checkout --depth files https://github.com/fpc/Lazarus/branches all
 +
cd all
 +
svn update --set-depth infinity main
 +
 
 +
The above svn above invocation is more complex due to a bug in many versions of Subversion. This workaround was the work of Alfred (aka Don Alfredo in the [[Forum]]) who is the wizard behind [[fpcupdeluxe]].
  
 
==== Updating Lazarus trunk source ====
 
==== Updating Lazarus trunk source ====
Line 373: Line 280:
 
== Installing non-release versions of FPC ==
 
== Installing non-release versions of FPC ==
  
=== FPC Trunk ===
+
{{macOS FPC Source Installation}}
 
 
* [[FPC_New_Features_Trunk|FPC New Features in Trunk]]
 
* [[FPC New Features Trunk|FPC User Changes in Trunk]] - may break existing code.
 
 
 
Note that since fpc trunk is by definition still under development, some of the features may still change before they end up in a release version.
 
 
 
The source code is kept in a version control system called subversion or ''svn'' for short, and is mirrored in ''git'':
 
 
 
* macOS 10.5 and higher already contain a command line svn or git client if you have installed the Xcode command line utilities. You can also use fink, port or brew to get an svn client on newer macOS. 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].
 
 
 
* You also need the latest released Free Pascal Compiler version (3.2.0 as of January 2021) installed in order to be able to successfully compile the development (trunk) version.
 
 
 
Create a directory where you would like to put the source (eg fpc 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:
 
 
 
Using git:
 
git clone git://github.com/graemeg/freepascal.git fpc
 
 
 
Using svn:
 
svn checkout https://svn.freepascal.org/svn/fpc/trunk fpc
 
 
 
This will create a directory called 'fpc', which can be later used in the IDE, and download the FPC source to it.
 
 
 
To subsequently download/update the latest source changes you can simply do:
 
 
 
Using git:
 
<syntaxhighlight lang=sh>
 
[]$ cd fpc
 
[]$ git clean -f -d
 
[]$ git pull
 
</syntaxhighlight>
 
 
 
Using svn:
 
<syntaxhighlight lang=sh>
 
[]$ cd fpc
 
[]$ svn cleanup --remove-unversioned
 
[]$ svn update
 
</syntaxhighlight>
 
 
 
To build and install FPC (the highlighted text should be all on one line):
 
 
 
<syntaxhighlight lang=sh highlight=3>
 
[]$ cd
 
[]$ cd fpc
 
[]$ make distclean all FPC=/usr/local/lib/fpc/3.2.0/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 
[]$ sudo make install OS_TARGET=darwin CPU_TARGET=x86_64
 
</syntaxhighlight>
 
 
 
You will also need to update the links for the compiler in <tt>/usr/local/bin</tt> which will be pointing to the previous FPC version. For example:
 
 
 
<syntaxhighlight lang=sh>
 
[]$ 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
 
</syntaxhighlight>
 
 
 
Note that you will need to build a new <code>ppc386</code> 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 32 bit frameworks):
 
 
 
<syntaxhighlight lang=sh highlight=1>
 
[]$ make clean all FPC=/usr/local/lib/fpc/3.2.0/ppc386 OS_TARGET=darwin CPU_TARGET=i386 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 
[]$ sudo make install OS_TARGET=darwin CPU_TARGET=i386
 
</syntaxhighlight>
 
  
 
== Known issues and solutions ==
 
== Known issues and solutions ==
 
=== Resurrecting Subversion (svn) on Catalina and Big Sur ===
 
 
<div class="mw-collapsible mw-collapsed">
 
 
Xcode version 11.3.1 (Mojave) was the last version to include the Subversion (svn) utilities. You can however copy the utilities and their associated libraries from a Mojave Mac to Catalina and Big Sur on both Intel and ARM processor Macs. There are two methods to do this - one uses Subversion from Xcode and the other uses Subversion from the command line tools as follows:
 
 
<div class="mw-collapsible-content">
 
 
cd /Applications/Xcode.app/Contents/Developer/usr/bin
 
scp svn* <remote_destination>
 
cd /Applications/Xcode.app/Contents/Developer/usr/lib
 
scp libsvn_*.dylib <remote_destination>
 
scp libserf*.dylib <remote_destination>
 
 
OR
 
 
cd /Library/Developer/CommandLineTools/usr/bin
 
scp svn* <remote_destination>
 
cd /Library/Developer/CommandLineTools/usr/lib
 
scp libsvn_*.dylib <remote_destination>
 
scp libserf*.dylib <remote_destination>
 
 
</div></div>
 
 
=== Installing Lazarus 2.0.8 with FPC 3.2.0 for macOS 10.11+ ===
 
 
<div class="mw-collapsible mw-collapsed">
 
 
* There is a patch needed for Lazarus 2.0.8 so that the Cocoa widgetset can be compiled:
 
 
<div class="mw-collapsible-content">
 
 
Index: lcl/interfaces/cocoa/cocoascrollers.pas
 
===================================================================
 
--- lcl/interfaces/cocoa/cocoascrollers.pas    (revision 63408)
 
+++ lcl/interfaces/cocoa/cocoascrollers.pas    (revision 63409)
 
@@ -31,8 +31,6 @@
 
    cocoa_extra, CocoaPrivate;
 
 
  type
 
-  TSetDocumentViewType = {$if FPC_FULLVERSION = 30200}id{$else}NSView{$endif};
 
-
 
    { TCocoaScrollView }
 
 
    TCocoaScrollView = objcclass(NSScrollView)
 
@@ -51,7 +49,7 @@
 
      procedure resetCursorRects; override;
 
      function lclClientFrame: TRect; override;
 
      function lclContentView: NSView; override;
 
-    procedure setDocumentView(aView:  TSetDocumentViewType); override;
 
+    procedure setDocumentView(aView: NSView); override;
 
      procedure scrollContentViewBoundsChanged(notify: NSNotification); message 'scrollContentViewBoundsChanged:';
 
      procedure resetScrollRect; message 'resetScrollRect';
 
 
@@ -647,7 +645,7 @@
 
    Result:=documentView;
 
  end;
 
 
-procedure TCocoaScrollView.setDocumentView(aView: TSetDocumentViewType);
 
+procedure TCocoaScrollView.setDocumentView(aView: NSView);
 
  begin
 
    inherited setDocumentView(aView);
 
    resetScrollRect;
 
 
* After making this patch, recompile Lazarus 2.0.8 from within itself or with this <tt>build_laz.sh</tt> shell script (adjust path for Lazarus source as required):
 
 
<syntaxhighlight lang=sh>
 
#!/bin/sh
 
cd ~/Documents/Lazarus/
 
svn cleanup --remove-unversioned
 
make distclean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
 
</syntaxhighlight>
 
</div></div>
 
 
=== Installing Lazarus 2.0.8, 2.0.10 with FPC 3.2.0 for macOS 10.10 and earlier ===
 
 
<div class="mw-collapsible mw-collapsed">
 
 
* [Lazarus 2.0.8 only] There is a patch required for Lazarus 2.0.8 so that the Cocoa widgetset can be compiled. See [[#Installing Lazarus 2.0.8 with FPC 3.2.0 for macOS 10.11+|above]].
 
 
<div class="mw-collapsible-content">
 
 
* [Lazarus 2.0.8 + 2.0.10] There is also a patch needed for FPC 3.2.0. Edit the FPC 3.2.0 source in <tt>../packages/cocoaint/src/CocoaAll.pas</tt> and comment out or remove the CoreImage linking line:
 
 
<syntaxhighlight lang=pascal>
 
unit CocoaAll;
 
interface
 
 
{$linkframework Cocoa}
 
{$linkframework Foundation}
 
//{$linkframework CoreImage} **Comment out this line**
 
{$linkframework QuartzCore}
 
{$linkframework CoreData}
 
{$linkframework AppKit}
 
</syntaxhighlight>
 
 
* To rebuild FPC 3.2.0 with the patch, you need an FPC 3.0.4 binary installation. My <tt>build_320.sh</tt> shell script to rebuild and reinstall FPC 3.2.0 (adjust path for FPC source as required):
 
 
<syntaxhighlight lang=sh highlight=4>
 
#!/bin/sh
 
cd /usr/local/share/src/fpc-3.2.0/
 
svn cleanup --remove-unversioned
 
make clean all FPC=/usr/local/lib/fpc/3.0.4/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
 
make install FPC=/usr/local/lib/fpc/3.0.4/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64
 
</syntaxhighlight>
 
 
Note that:
 
* if more than one line above is highlighted, all the highlighted content should be on one line;
 
* you may need to change the second line depending on where your FPC Source code is installed;
 
* you will almost certainly need to run the script by using <code>sudo</code>.
 
 
Now rebuild Lazarus with this <tt>build_laz.sh</tt> shell script (adjust path for Lazarus source as required):
 
 
<syntaxhighlight lang=sh>
 
#!/bin/sh
 
cd ~/Documents/Lazarus/
 
svn cleanup --remove-unversioned
 
make distclean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
 
</syntaxhighlight>
 
 
</div></div>
 
 
==== - macOS 10.5 Leopard ====
 
 
<div class="mw-collapsible mw-collapsed">
 
 
* After installing Xcode 3.1 (includes the command line tools) for Leopard, the first issue is that Xcode 3.1 does not come with the Clang compiler.
 
 
<div class="mw-collapsible-content">
 
 
** The solution is to create/add this to the .fpc.cfg file in your home directory:
 
  #include /etc/fpc.cfg ## only add this line if the .fpc.cfg file does not already exist
 
  -WM10.5
 
  -Aas-darwin
 
 
* The second issue is that the official [https://sourceforge.net/projects/lazarus/files/Lazarus%20Mac%20OS%20X%20i386/Lazarus%202.0.10/ Lazarus Mac OS X i386 download] of FPC is FPC 3.0.4 and not 3.2.0.
 
** The solution is to download the source for FPC 3.2.0 to your home directory. Open an Applications > Utilities > Terminal and:
 
 
    svn co https://svn.freepascal.org/svn/fpc/tags/release_3_2_0
 
 
* The third issue is that the official [https://sourceforge.net/projects/lazarus/files/Lazarus%20Mac%20OS%20X%20i386/Lazarus%202.0.10/ Lazarus Mac OS X i386 download] for Lazarus 2.0.10 was compiled with FPC 3.0.4 and not FPC 3.2.0.
 
** The solution is to download the Lazarus release sources to your home directory. Open an Applications > Utilities > Terminal and:
 
 
    svn co https://svn.freepascal.org/svn/lazarus/tags/lazarus_2_0_10
 
 
* Compiling FPC 3.2.0 on Leopard is tricky (thanks to Jonas for supplying the solution). Before compiling FPC 3.2.0, make [[#Installing_Lazarus_2.0.8.2C_2.0.10_with_FPC_3.2.0_for_macOS_10.10_and_earlier|this change]] to the source so that it will not attempt to link the missing CoreImage framework. Then compile using the following <tt>build_320.sh</tt> script (enter your password at the prompt for the install to proceed):
 
 
  <syntaxhighlight lang=sh highlight=4>
 
  #!/bin/sh
 
  cd /Users/$USER/release_3_2_0/
 
  svn cleanup
 
  make clean all FPC="/usr/local/lib/fpc/3.0.4/ppc386" OS_TARGET=darwin CPU_TARGET=i386 CPU_SOURCE=i386 OPT="-WM10.5 -Aas-darwin -Xs-"
 
  sudo make install OS_TARGET=darwin CPU_TARGET=i386 CPU_SOURCE=i386
 
  </syntaxhighlight>
 
 
Note: The highlighted line above should all be on one line.
 
 
* Compiling Lazarus 2.0.10 is less tricky. Before compiling Lazarus 2.0.10, make [[#Lazarus_IDE_-_Unable_to_.22run_without_debugging.22| this change]] to the source so that the "run without debugging" option will work. I use the following <tt>build_laz.sh</tt> script:
 
 
  <syntaxhighlight lang=sh highlight=4>
 
  #!/bin/sh
 
  cd /Users/$USER/lazarus_2_0_10
 
  svn cleanup
 
  make distclean all LCL_PLATFORM=carbon CPU_SOURCE=i386 CPU_TARGET=i386 bigide OPT="-WM10.5 -Aas-darwin -Xs- -dCarbonDontUseCocoa"
 
  </syntaxhighlight>
 
 
Note: The highlighted line above should all be on one line.
 
 
* Finally, launch the newly compiled lazarus.app and adjust these Lazarus settings:
 
** Tools > Options > Environment > Files > Compiler executable: this should be set to '''<tt>/usr/local/bin/ppc386</tt>'''.
 
** Project > Project Options > Custom Options: add '''-WM10.5''' to the Custom options.
 
** Project > Project Options > Config and Target > Target CPU family: set to '''i386'''.
 
** Project > Project Options > Config and Target > Current LCL widgetset: set to '''Carbon'''.
 
** Project > Project Options: in the left pane, at the bottom, '''check''' "Set compiler options as default".
 
 
You should now be able to successfully compile and run the Lazarus default blank form project.
 
</div></div>
 
 
==== - macOS 10.8 Mountain Lion additional steps ====
 
 
<div class="mw-collapsible mw-collapsed">
 
 
* The first issue is that the official Lazarus pkg file downloads will not install on Mountain Lion, giving the error "Lazarus IDE cannot be installed on this disk" being the only disk in the system!
 
 
<div class="mw-collapsible-content">
 
 
** The solution is to download the Lazarus release sources to your home directory. Open an Applications > Utilities > Terminal and:
 
    svn co https://svn.freepascal.org/svn/lazarus/tags/lazarus_2_0_8
 
    =or=
 
    svn co https://svn.freepascal.org/svn/lazarus/tags/lazarus_2_0_10
 
 
* Unfortunately the compiler and assembler in the last version of Xcode and its command line tools available for Mountain Lion is too old to compile Lazarus.
 
** The solution is to download the macOS Clang7 binary package from https://releases.llvm.org/7.0.0/clang+llvm-7.0.0-x86_64-apple-darwin.tar.xz, uncompress it and install in your home directory.
 
** Open an Applications > Utilities > Terminal and:
 
  <syntaxhighlight lang=bash>
 
  cd /usr/bin
 
  sudo mv clang clang.OLD
 
  sudo ln -s /Users/$USER/clang/bin/clang clang
 
  sudo mv as as.OLD
 
  sudo ln -s /Users/$USER/clang/bin/as as
 
  </syntaxhighlight>
 
 
Now follow the steps [[#Installing Lazarus 2.0.8, 2.0.10 with FPC 3.2.0 for macOS 10.10 and earlier|above]].
 
</div></div>
 
  
 
=== Lazarus IDE - Unable to "run without debugging" ===
 
=== Lazarus IDE - Unable to "run without debugging" ===
Line 706: Line 345:
 
== Uninstalling Lazarus and Free Pascal ==
 
== Uninstalling Lazarus and Free Pascal ==
  
=== Installed using fink ===
+
Refer to [[Uninstalling Lazarus on macOS]] for uninstallation options.
 
 
<div class="mw-collapsible mw-collapsed">
 
 
 
If you installed Lazarus + FPC using <tt>fink</tt>, the complete uninstall of all Lazarus + FPC packages is done with:
 
 
 
<div class="mw-collapsible-content">
 
 
 
<syntaxhighlight lang="bash">
 
fink purge --recursive fpc-config
 
</syntaxhighlight>
 
 
 
If you want to preserve changes to the preference file /sw/etc/fpc.cfg, do:
 
 
 
<syntaxhighlight lang="bash">
 
fink remove --recursive fpc-config
 
</syntaxhighlight>
 
 
 
For the removal of the Lazarus preferences subdirectory in your home directory, and the files that it contains, see the end of the [[#Installed from packages or source|next section]].
 
</div></div>
 
 
 
=== Installed from packages or source ===
 
 
 
<div class="mw-collapsible mw-collapsed">
 
 
 
Normally you uninstall an application on macOS simply by dragging it from the Applications folder to the trash. As Lazarus and Free Pascal are development tools, there are files installed in several folders that you don't normally see in Finder.
 
 
 
<div class="mw-collapsible-content">
 
 
 
You can copy and save the commands below to file <tt>uninstallLaz.sh</tt> and run it if you need to unnstall 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.
 
 
 
<syntaxhighlight lang="sh">
 
#!/bin/sh
 
# Bourne Shell Script
 
#
 
bin=/usr/local/bin
 
share=/usr/local/share
 
lib=/usr/local/lib
 
receipts=/Library/Receipts
 
private=/private/etc
 
 
 
rm -fv $bin/ppcppc
 
rm -fv $bin/ppc386
 
rm -fv $bin/ppcx64
 
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 -rfv $private/lazarus
 
rm -rfv $bin/lazarus
 
rm -rfv $share/lazarus
 
rm -rfv $share/fpcsrc/fpc-*
 
rm -rfv $share/doc/fpc-*
 
 
 
rm -rfv $lib/fpc
 
 
 
rm -rfv $receipts/lazarus-*.pkg
 
rm -rfv $receipts/fpcsrc-*.pkg
 
rm -rfv $receipts/fpc-*.pkg
 
 
 
rm -fv /etc/fpc.cfg
 
rm -fv ~/.fpc.cfg
 
</syntaxhighlight>
 
 
 
To run this script, open an Applications > Utilities > Terminal, and enter:
 
 
 
<syntaxhighlight lang="bash">
 
cd <replace this text and angle brackets with the name of the directory where the script is stored> 
 
chmod +x uninstallLaz.sh
 
sudo ./uninstallLaz.sh
 
</syntaxhighlight>
 
 
 
Then enter your password when prompted.
 
 
 
'''Lazarus preference folder .lazarus in the home directory'''
 
 
 
Lazarus also creates a .lazarus preferences subdirectory 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, open an Applications > Utilities > Terminal and enter the following in the Terminal window:
 
 
 
<syntaxhighlight lang="bash">
 
cd .lazarus
 
ls -al
 
</syntaxhighlight>
 
 
 
To remove it, execute the following commands in a Terminal:
 
 
 
<syntaxhighlight lang="bash">
 
cd
 
rm -rfv .lazarus
 
</syntaxhighlight>
 
 
 
Finally, if you haven't already done so, drag Lazarus from your Applications folder to the trash.
 
 
 
</div></div>
 
  
 
== Legacy Information ==
 
== Legacy Information ==
Line 824: Line 351:
 
See [[Legacy Information: Installing Lazarus on Mac|Legacy Information]] for details of:
 
See [[Legacy Information: Installing Lazarus on Mac|Legacy Information]] for details of:
  
* installing Lazarus on Mac OS X 10.4 (Tiger);
+
* Installing Lazarus on Mac OS X 10.4 (Tiger), Mac OS X 10.5 (Leopard), OS X 10.8 (Mountain Lion)
* installing Lazarus on PowerPC-based Macs;
+
* Installing Lazarus 2.0.8, 2.0.10 with FPC 3.2.0 for macOS 10.10 and earlier
* old Xcode versions;
+
* Installing Lazarus 2.0.8 with FPC 3.2.0 for macOS 10.11+
* installing the gdb debugger;
+
* Installing Lazarus on PowerPC-based Macs
* compatibility matrix for Lazarus 1.0.0 through 1.6.4 and FPC 2.6.0 through 3.0.2.
+
* 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 ==
 
== See also ==
  
 
* [[Xcode]].
 
* [[Xcode]].
 +
* [[Other macOS installation options]].
 
* [[Multiple Lazarus|Installing multiple Lazarus versions]].
 
* [[Multiple Lazarus|Installing multiple Lazarus versions]].
 
* [[Portal:Mac|Mac Portal]] for an overview of development for macOS with Lazarus and Free Pascal.
 
* [[Portal:Mac|Mac Portal]] for an overview of development for macOS with Lazarus and Free Pascal.

Revision as of 08:37, 18 August 2021

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.
  3. Download and install the Free Pascal Compiler (FPC) binaries and the FPC source 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
  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 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 macOS 11 Big Sur 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, 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 installation on Apple Silicon/AArch64, after installing the 64 bit Intel binary and source for FPC, please refer to these instructions for building a native Apple Silicon Free Pascal Compiler.

Download and install the Free Pascal Compiler (FPC) binaries and the separate source package. A compatible FPC (and source) must be installed before you install Lazarus. You have a number of options.

Source Forge (Official Repository)

Download the official Free Pascal Compiler (FPC) binaries and FPC source packages from the Lazarus IDE file area.

When you arrive at that 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. 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.
  2. Choose the version of Lazarus you wish to install and you will be presented with the 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: Install the Lazarus IDE

Light bulb  Note: For installation on Apple Silicon/AArch64, please refer to the Lazarus Fixes 2.2 or Lazarus Trunk instructions to build a native Lazarus IDE. Skip to the building instructions and use the Lazarus Fixes 2.2 source / Lazarus Trunk source download as you wish.

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.

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.

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)".

Set Debugger2.png

If it 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 the offered -

Set Dwarf.png

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 macOS cuteness because one application appears to be interfering with another. In this case, that's fine!

In the latest versions of Lazarus (tested on 2.1.0 compiled from source) click Lazarus > Preferences... > Debugger > Debugger backend. In the Debugger type and path box select "LLDB debugger (with fpdebug)(Beta) and /usr/bin/lldb. This requires that the package lazdebuggerfplldb.lpk has been installed for it to work as described below.

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 will do nothing / at least should...)

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.

Cocoa 64 bit vs Carbon 32 bit

Lazarus using the Apple 64 bit Cocoa framework should now meet the needs of 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 macOS 10.15 Catalina which was released in October 2019.

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 Lazarus forum.

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 (unless you are running macOS 10.15 Catalina or later) and use that to generate Cocoa 64 bit binaries.

In the Carbon or Cocoa IDE, you need to set the Target to the 64 bit processor and select the Cocoa Widget set:

  • 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"
  • In the "Additions and Overrides" panel click on "Set LCLWidgetType" pulldown and set the value to "Cocoa"
  • For some reason Lazarus sets the compiler to "/usr/local/bin/ppc386" - which results in 32 bit applications. Make sure under Tools > Options 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.

Installing non-release versions of the Lazarus IDE

Lazarus Fixes 2.2

There are a number of reasons why you may be better off using a non-release version of Lazarus, specifically, fixes_2_2. Particularly:

  • You almost certainly need to target 64 bit Cocoa, macOS 10.15 Catalina and later do not support 32 bit Carbon at all.
  • The Cocoa widget set has steadily improved and the lldb debugger interface has rapidly improved, since even v2.0.0.
  • If your Mac has an Apple M1 Processor, the debugger in fixes_2_2 now works for aarch64.
  • Fixes_2_2 is a safer and more stable option than trunk, but still gets the new features much faster than the release version.

Pre-compiled binaries based on fixes_2_2 are not available from SourceForge so we download and build from the source code. A little slow initially but very reliable and a great test of your compiler install ! You will need git which is included in all recent versions of the Xcode command line tools which you should have already installed (see Xcode Command Line Tools above).

About svn or git: The Xcode 11.4 command line tools on macOS 10.15 no longer install svn, only git. You can install subversion via fink, ports or brew.


  • 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 Fixes 2.2 source

Create a directory for Lazarus and download the current fixes version:

cd
mkdir -p bin/lazarus
cd bin/lazarus

Using git:

git clone -b fixes_2_2 https://gitlab.com/freepascal.org/lazarus/lazarus.git laz_fixes

Using svn:

svn checkout https://github.com/fpc/Lazarus/branches/fixes_2_2 laz_fixes

Depending on your internet connection and server congestion this takes a few seconds or a few minutes.

Updating Lazarus Fixes 2.2 source

To keep your fixes_2_2 installation up to date is as easy as:

Using git:

cd ~/bin/lazarus/laz_fixes
git clean -f -d
git pull

Using svn:

cd ~/bin/lazarus/laz_fixes
svn clean --remove-unversioned
svn update

Building Lazarus Fixes 2.2 source

cd laz_fixes
make distclean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
//-wait some time...
open startlazarus.app --args "--pcp=~/.laz_fixes"
  • Note I pass a parameter to use a config directory that is based on the name of the actual install directory. It makes some scripting easy.
  • 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.

You might like to put a small script in your $HOME/bin directory and even set a path to it (very UNIX!)

#!/bin/bash
LAZDIR="laz_fixes"
cd ~/bin/lazarus/"$LAZDIR"
open ~/bin/lazarus/"$LAZDIR"/lazarus.app --args "--pcp=~/.$LAZDIR"

Lazarus Trunk

Precompiled binaries based on the trunk development version of the Lazarus IDE are not available from SourceForge, so here's how to download the trunk source using svn or git and build the Lazarus IDE. You will need svn (before macOS 10.15 - Catalina) or git (after macOS 10.14 - Mojave) which is included in the Xcode command line tools which you should have already installed (see Xcode Command Line Tools above).


  • 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 trunk source

cd
mkdir -p bin/lazarus
cd bin/lazarus

Using git:

git clone -b main https://gitlab.com/freepascal.org/lazarus/lazarus.git laz_trunk

Using svn:

svn checkout --depth files https://github.com/fpc/Lazarus/branches all
cd all
svn update --set-depth infinity main

The above svn above invocation is more complex due to a bug in many versions of Subversion. This workaround was the work of Alfred (aka Don Alfredo in the Forum) who is the wizard behind fpcupdeluxe.

Updating Lazarus trunk source

To update your existing trunk source.

Using git:

cd ~/bin/lazarus/laz_trunk
git clean -f -d
git pull

Using svn:

cd ~/bin/lazarus/laz_trunk
svn cleanup --remove-unversioned
svn update

Building Lazarus trunk source

make distclean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
//-wait some time...
open startlazarus.app --args "--pcp=~/.laz_trunk"

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.

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

Known issues and solutions

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