# Installing Lazarus on MacOS X

English (en) 한국어 (ko)

Installing Lazarus on a Mac is not particularly difficult but is a bit tedious. Its 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 -

2. Install the global command line tools for Xcode.
3. Install gdb - sort of but not really optional.
4. Install Free Pascal Compiler, FPC Source and Lazarus
5. Speak to Lazarus about gdb.

## Installation

The detailed instructions assume a recent version of OSX 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 bottom of the page.

In general, this is about using the Carbon Widget Set, it is intentionally (by Apple) limited to 32 bits and we have every reason to believe Apple may drop support for it some time in the not too distant future. The alternative is Cocoa, more information to be provided.

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

### 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 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 (its quick and easy)-

xcode-select --install

### Step 3 install gdb

While this is really optional, I suggest you do need gdb in most cases and I recommend this step. Alternatives include -

Getting gdb to run can be a bit tedious but is worthwhile in the end. I recommend this approach

1. Install brew and use brew to install gdb- http://wiki.freepascal.org/GDB_on_OS_X_Mavericks_and_Xcode_5
2. 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.
3. 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 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.

### Step 4 FPC, FPC Source and Lazarus

Get and install, in this order, the FPC, FPC Source, Lazarus. I used Lazarus 1.8rc4, its very mature and probably about to become 1.8 pretty soon. Get all three from Link https://sourceforge.net/projects/lazarus/files . 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 (i.e. one who does not pay Apple a kickback).

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 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. Now, try the Run test ! The first time in a debugging session, expect a warning and then a logon box where you need put in your password as the debugger starts up. Annoying but its all fine after that. For authorative/more detailed instructions for FPC, please go to [1] ## Compatibility Not every combination of Lazarus and Free Pascal is compatible with every installation of Mac OS X. Please refer to the following table in order to find the correct version for your development environment: Lazarus Compatibility Matrix Lazarus 1.0.0 Lazarus 1.0.2 Lazarus 1.0.4 Lazarus 1.0.6 Lazarus 1.0.8 Lazarus 1.0.10 Lazarus 1.0.12 Lazarus 1.0.14 Lazarus 1.2.0 Free Pascal (FPC) 2.6.0 FPC 2.6.2 PPC processors Mac OS X 10.4 (Tiger) Incompatible Incompatible N/A Compatible Incompatible Incompatible Compatible* Compatible* Not tested Mac OS X 10.5 (Leopard) Compatible Compatible N/A Compatible Compatible Compatible Compatible Compatible Compatible** Intel processors Mac OS X 10.4 (Tiger) Incompatible Incompatible Compatible Compatible Incompatible Incompatible With hack only Not tested Not tested Mac OS X 10.5 (Leopard) Compatible Compatible Compatible Compatible Compatible Compatible Compatible Not tested Not tested Mac OS X 10.6 (Snow Leopard) Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Mac OS X 10.7 (Lion) Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Mac OS X 10.8 (Mountain Lion) Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Mac OS X 10.9 (Mavericks) Not tested Not tested Not tested Not tested Not tested Not tested Compatible* Compatible* Compatible* Mac OS X 10.10 (Yosemite) Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Mac OS X 10.11 (El Capitan) Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested macOS X 10.12 (Sierra) Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested macOS X 10.13 (High Sierra) Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Lazarus 1.2.2 Lazarus 1.2.4 Lazarus 1.2.6 Lazarus 1.4.0 Lazarus 1.4.2 Lazarus 1.4.4 Lazarus 1.6.0 Lazarus 1.6.2 Lazarus 1.6.4 Lazarus 1.8.0 FPC 2.6.4 FPC 3.0.0 FPC 3.0.2 FPC 3.0.4 PPC processors Mac OS X 10.4 (Tiger) Compatible N/A Compatible Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible Mac OS X 10.5 (Leopard) Compatible Compatible** Compatible Compatible** Compatible** Compatible** Not tested Not tested Not tested Not tested Intel processors Mac OS X 10.4 (Tiger) Not tested Not tested Not tested Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible Incompatible Mac OS X 10.5 (Leopard) Compatible Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Mac OS X 10.6 (Snow Leopard) Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible Compatible* Mac OS X 10.7 (Lion) Compatible Compatible Compatible Not tested Not tested Not tested Compatible Compatible Compatible Not tested Mac OS X 10.8 (Mountain Lion) Compatible Compatible Compatible Compatible* Compatible* Compatible* Compatible* Compatible* Compatible* Not tested Mac OS X 10.9 (Mavericks) Compatible* Compatible* Compatible* Compatible* Compatible* Compatible* Compatible* Compatible* Compatible* Not tested Mac OS X 10.10 (Yosemite) Not tested Not tested Compatible* Compatible* Compatible* Compatible* Compatible* Compatible* Compatible* Not tested Mac OS X 10.11 (El Capitan) Not tested Not tested Not tested Not tested Not tested Compatible* Compatible* Compatible* Compatible* Not tested macOS X 10.12 (Sierra) Not tested Not tested Not tested Not tested Not tested Not tested Compatible* Compatible* Compatible* Compatible* macOS X 10.13 (High Sierra) Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested Not tested *Restrictions apply to debugging with GDB. **Not available as pre-built installer. Compiling from source required. ## Carbon and Cocoa At present (late 2017) Lazarus using Carbon is a pretty good experience, things work pretty much as expected. However, it must be remembered that Carbon is intentionally limited (by Apple) to 32 bits and there is every reason to believe it might be dropped altogether in a later release of OSX. The alternatives include Cocoa, QT and GTK2+. The latter two require 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 forum. However, Cocoa is generally recognized as the future. Its possible to build an all Cocoa version of Lazarus but at time of writing, it does not look very usable. Its also possible to make a Cocoa install and use that at the command line to compile an existing project, probably put together in a Carbon based Lazarus. Such a project will then be using the Cocoa widget set and could be 64bit. A good tutorial is available at https://macpgmr.github.io/MacXPlatform/UsingCocoaFromTrunk.html Its specifically about using a particular Cocoa only Component but provides clear instructions that can be used generally. ## Download the sources via svn • Note: IF the current SVN of FreePascal can not be compiled using the stable release of FreePascal that comes with the current stable version of Lazarus (FPC 2.6.*), you will need a newer compiler. In order to compile the latest versions of FPC, first install a precompiled 2.6.* series compiler. You can get a compiled version of FPC 2.6.* at http://www.freepascal.org/download.var. Note: only do this if the instructions below do not work. The sources are kept in a version control system called subversion or short svn: • 10.5 and higher already contains svn clients. Users of earlier versions must install SVN for Mac OS X. A good package is provided by Martin Ott. You can also use fink. SVN clients with GUI (graphical user interface) are available from Versiontracker. A quite handy client, which integrates in Finder, is SCPlugin. 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. First create a directory for fpc (e.g. /Users/username/freepascal) then open a terminal and do the following: []$ 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

[]$make clean all []$ sudo make install


[]$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 []$ make clean all


Then start lazarus either via command line or by double click in the finder:

 open lazarus.app


Source code of stable versions is available in the 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

[]$make clean bigide  and <return> again. Subsequently, Free Pascal 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. 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. # Legacy Information ### XCode Compatability 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: 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: xcode-select --install 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 developer.apple.com (please take care to install the command line tools that are correct exactly for your Xcode version). #### Xcode 4.3+ compatibility (Mac OS X 10.7/10.8) 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. 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 Apple Developer. #### Xcode 3.2.x compatibility (Mac OS X 10.6) 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) Most versions of Lazarus and FPC are compatible with Xcode 3.1 (see the 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. #### 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 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 ### Installation from disk images Download the three disk images (.dmg files) for fpc, fpcsrc and lazarus from either of the following links: Open up each disk image and install in this order: 1. fpc 2. fpcsrc 3. Lazarus After installation the Lazarus application can be found in /Developer/lazarus/, the FPC source files in /usr/local/share/fpcsrc. 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): Environment Options  Lazarus directory: /Developer/lazarus Compiler path: /usr/local/bin/ppc386 (PowerPC Macs: /usr/local/bin/ppcppc) FPC Source: /usr/local/share/fpcsrc  Project | Options  All paths blank LCL Widget Type: default (Carbon beta)  Project | Inspector  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. This is the easiest way to install Lazarus on Mac OS X. ### Installation using fink To obtain the up-to-date release versions of lazarus (1.4) AND freepascal (2.6.4) use fink, a package manager for Mac OS X. The extra bonus of fink is easy installation as well as clean removal of a huge number of other open source software packages, including FreePascal crosscompilers for other processors and systems. The choice for lazarus is between an Aqua look of lazarus (preferred by most), a gtk2 look and a Qt4-based version: $ fink install lazarus-aqua


or

$fink install lazarus-gtk2  or $ fink install lazarus-qt4


This also installs a number of other packages, such as the FreePascal compiler, the lazarus sources, gtk2 libraries and more. At the prompt, whether you want to install these additional packages, simply hit RETURN and go for a coffee. It really takes 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 all looks, these widget sets for your program are supported on Intel-Macs:

carbon (Aqua), gtk2, qt4 (Aqua), nogui

These additional cross platform widget sets are supported:

win32, win64 and wince.

Projects with the gtk1 widget set are also supported on 10.4 and 10.5 through the lazarus-common-gtk1 package. On 10.6 and up, gtk1 libraries are deprecated in general and you have to port your project to the gtk2 or carbon widget set. The support of PowerMacs has also been stopped with the release of lazarus 1.4.0.

## Install from Source / Development version

You need the latest stable released FPC installed in order to compile the development version.

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

# Uninstalling Lazarus and Free Pascal

## Installed using fink

The complete uninstall of all fpc and lazarus packages is done with:

fink purge --recursive fpc-config

If you want to preserve changes to the preference file /sw/etc/fpc.cfg, do:

fink remove --recursive fpc-config

For the removal of the Lazarus preference folder and files in your home directory, see below ( Lazarus preference folder).

## Installed from disk images or sources

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.

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.

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/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 rm -r$receipts/lazarus-*.pkg
rm -r $receipts/fpcsrc-*.pkg rm -r$receipts/fpc-*.pkg

rm -fv /etc/fpc.cfg

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.

To run this script, change to the directory where it's stored and enter:

chmod +x uninstallLaz.sh
sudo ./uninstallLaz.sh

### Lazarus preference folder .lazarus in the home directory

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. OS X 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:

cd ~/
ls -al
cd .lazarus
ls

To remove it, execute the following commands:

cd ~/
rm -rv .lazarus

# Known issues

• FPC 2.4.4 has a bug. You can not compile the IDE with the range check flag -Cr.
• 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