Mac Installation FAQ: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(macOS only)
2	2
3	3		This page lists solutions to the most frequent problems that may arise during (and after) installation of Lazarus and Free Pascal on macOS. Please read [[Installing Lazarus on macOS]] first and pay special attention to the sections that apply to your versions of macOS, Xcode, Lazarus and Free Pascal.
4	4
5	5		## Lazarus doesn't run project
6	6
7	7		After moving to macOS or after upgrading to a new version of macOS Lazarus is unable to compile and run a project.
8	8
9	9		Solution: Most likely, this behaviour results from missing command line tools. In newer versions of Xcode they are no longer installed by default. You can install them by running
10	10
11		-	~~` xcode-select --install`~~
	11	+	```text
	12	+	xcode-select --install
	13	+	```
12	14
13	15		from the terminal. See also [[Installing Lazarus on macOS]] for more details.
14	16
15	17		## Compilation aborts with weird messages
16	18
17	19		I have correctly installed Lazarus and FPC, but compiling a simple demo program stops with the Free Pascal exit code 256 and the message "Lazarus Panic /bin/sh: clang: command not found".
18	20
19	21		Solution: This behaviour may arise from a too old Xcode version installed. Generally, you should use the newest Xcode version that is available for your operating system. Lazarus 1.6 requires, e.g., Xcode 3.2.6, or newer. With Xcode 4.3 or newer, you should also install the Xcode command line tools as described above or in the article [[Installing Lazarus on macOS]].
20	22
21	23		## ld: symbol(s) not found for architecture i386
22	24
23	25		I am trying to compile a blank project on Catalina immediately after installing FPC and Lazarus but I get this error "ld: symbol(s) not found for architecture i386".
24	26
25	27		Solution: Go to Lazarus \> Tools \> Options, if your compiler is set to ppc386 (32 bit), then change it to ppcx64 (64 bit) or fpc (a wrapper that should choose the correct compiler). There is no 32 bit support in Catalina. In later versions of Lazarus, the Lazarus \> Tools \> Options menu has been moved to the Lazarus \> Preferences menu
26	28
27	29		## Debugger not found
28	30
29	31		I have installed the latest version of Lazarus on a new Mac. My program is built fine, but when I try to run it I get a message that the debugger `/usr/bin/gdb` doesn't exist or isn't runnable.
30	32
31	33		Solution: Since version 5, Xcode does not include the GDB debugger but the LLDB debugger. For recent versions of macOS, go to the Tools \> Options \\| Debugger menu and choose "LLDB debugger (with fpDebug) (Beta)" and set the executable to `/usr/bin/lldb`. In later versions of Lazarus, the Tools \> Options menu has been moved to the Lazarus \> Preferences menu
32	34
33	35		Solution (legacy): Xcode v5 no longer includes the GDB debugger. See [[GDB on OS X Mavericks or newer and Xcode 5 or newer]] for possible solutions unless you are running a recent version of macOS (in which case, see above).
34	36
35	37		## Form not shown after moving to Mac
36	38
37	39		My application works well on Windows and Linux, but after changing to Mac my forms are invisible. I tried to re-scan the FPC source directory, and I clicked "Create Bundle", but this didn't solve the problem. Unlike my app, a very simple demo application works well.
38	40
39	41		Solution: This may result from a wrong position setting of your form(s). Your Windows machine may have a multi-monitor setup, so that the forms are outside the visible area of a single-monitor environment, i.e. if your Mac has only one monitor. You should check and correct the top and left properties of your forms in the object inspector. (Of course, this also applies in the other direction, i.e. if you have a multi-monitor Mac and a single-monitor Windows or Linux machine).
40	42
41	43		## Form not responding to mouse clicks
42	44
43	45		After starting the program the form is visible, but not responding to interaction via the user interface.
44	46
45	47		Solution: Programs for macOS-based systems are more complex than programs for Windows or Linux. They require the existence of an [[Application Bundle\|application bundle]], a special opaque directory structure, which determines the modalities of interaction with the operating system and the GUI. You may create an application bundle in the [[IDE Window: Project Options\|project settings]] or alternatively via shell commands. Make sure that the option [[IDE Window: Project Options\|Use Application Bundle for running and debugging (for Darwin)]] is checked.
46	48
47	49		## fpcsrc not present
48	50
49	51		After installing and first running Lazarus, the welcome window complains that the directory "/usr/local/share/fpcsrc" is not found.
50	52
51	53		Solution: You have to install fpcsrc. This is a Lazarus-specific installer package that comes with your distribution of Lazarus. If you have downloaded Lazarus from SourceForge you find fpcsrc in the same server directory as the Lazarus package.
52	54
53	55		## Multiple error messages after upgrading Lazarus and/or FPC
54	56
55	57		After upgrading Lazarus and/or Free Pascal to a new major version, trying to compile my code results in multiple error messages.
56	58
57	59		Solution: This behaviour may have multiple reasons. After every major upgrade you should rescan the FPC source directory. If this doesn't help it may be useful to delete the file `fpcdefines.xml` (it is within the ~/.lazarus folder). Additionally, you should check your code for incompatibilities that may result from changes in the compiler (although this is quite rare with code that is not too unusual). See [:Category:FPC User Changes by release](/wiki-category/FPC%20User%20Changes%20by%20release) for intentional changes to the compiler that may break existing code.
58	60
59	61		## Unit XY not found
60	62
61	63		I have freshly installed a new version of Lazarus on my machine. Trying to compile an application results in the error message "Error: unit not found: XY". (XY is a place holder for any unit name.)
62	64
63	65		Solution: Try to re-scan your FPC source directory via the Lazarus IDE Tools... menu.
64	66
65	67		== Fatal: Cannot find \[...\] used by \[...\], incompatible ppu=\[filename\], package \[package name\] ==
66	68
67	69		When the compiler gives the message "Cannot find A used by B", Lazarus checks what pas/pp/ppu files are in the search path, and if there is a ppu file it inserts "incompatible ppu=filename, package".
68	70
69	71		Explanation: FPC cannot use this ppu for one of these reasons:
70	72
71	73		- it was compiled with another FPC version;
72	74		- it was compiled with (depends on) some other ppu files that are not in the search path;
73	75		- you misconfigured some search path(s).
74	76
75	77		Solutions: (1) Check that you have the current [[Xcode]] (optional - see [[Installing Lazarus on macOS\|here]]) and Xcode command line tools package (mandatory) installed; (2) Lazarus \> Menu \> Tools \> Configure Build Lazarus - Find and check "Clean all" and then Build. If that doesn't work, I'd be tempted to delete both FPC + Lazarus and start again. See [[Uninstalling Lazarus on macOS\|Uninstalling Lazarus and Free Pascal]].
76	78
77	79		## Error: User defined: only cpu i386 is supported
78	80
79	81		When compiling Lazarus on macOS I receive this error: `carbonbars.pp(16,2) Error: User defined: only cpu i386 is supported`
80	82
81	83		Solution:
82	84
83	85		``` bash
84	86		make bigide LCL_PLATFORM=cocoa
85	87		```
86	88
87	89		## Error: ld: framework not found Cocoa
88	90
89	91		When compiling Lazarus on macOS I receive this error: `Error: ld: framework not found Cocoa`
90	92
91	93		Solution: You forgot to install the Xcode command line tools or they've since been deleted. See [[Installing Lazarus on macOS\|Installing Xcode Command Line Tools]] to resolve. You may also need to either:
92	94
93	95		\(1\) re-install FPC after installing the Xcode command line tools; or
94	96
95	97		\(2\) tweak the `/private/etc/fpc.cfg` file, after installing the Xcode command line tools, by adding:
96	98
97		-	~~` -Fl/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib`\~~
98		-	~~` -XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk`~~
	99	+	```text
	100	+	-Fl/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib
	101	+	-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
	102	+	```
99	103
100	104		so that the compiler can find the macOS frameworks.
101	105
102	106		## Error ppc1 not found
103	107
104	108		''When compiling the Free Pascal Compiler on macOS I receive this error:
105	109
106	110		```text
107	111		/usr/local/bin/ppcx64 -Ur -Xs -O2 -n -Fux86_64 -Fusystems -Fu../rtl/units/x86_64-darwin -Fix86_64 -FEx86_64/bin/x86_64-darwin -FUx86_64/units/x86_64-darwin -dRELEASE -dx86_64 -dGDB -dBROWSERLOG -Fux86 -Fix86 pp.pas
108	112		/bin/mv -f x86_64/bin/x86_64-darwin/pp ppcx64
109	113		/Applications/Xcode.app/Contents/Developer/usr/bin/make echotime
110	114		Start now 08:06:02
111	115		/bin/rm -f ppc1
112	116		/bin/mv -f ppcx64 ppc1
113	117		/Applications/Xcode.app/Contents/Developer/usr/bin/make 'FPC=/Users/Developer/fpc trunk/compiler/ppc1' 'OLDFPC=' next CYCLELEVEL=2
114	118		Makefile:135: *** Compiler /Users/Developer/fpc trunk/compiler/ppc1 not found. Stop.
115	119		make[3]: *** [ppc2] Error 2
116	120		make[2]: *** [cycle] Error 2
117	121		make[1]: *** [compiler_cycle] Error 2
118	122		make: *** [build-stamp.x86_64-darwin] Error 2
119	123		```
120	124
121	125		Solution: GNU Make does not handle directory names with spaces in them. Rename "fpc trunk" to "fpc_trunk" or similar and it should work without this error.
122	126
123	127		## Error: library (X11 or Truetype) not found
124	128
125	129		If you are compiling X11 applications (typically using fpGui) FPC needs to know where to find the libX11.dylib and libfreetype.dylib libraries. If FPC cannot find these libraries, you will receive a library not found error during linking.
126	130
127	131		Solution: Depending on your version of macOS or XQuartz these may be found in `/usr/X11/lib` or `/opt/X11/lib` with a symlink from `/usr`. The best solution to this is probably to edit `/etc/fpc.cfg` and add the line `-Fu/usr/X11/lib`
128	132
129	133		## Application does not accept keyboard input
130	134
131	135		After compiling my application, I cannot enter anything in the edit boxes and the application will not accept any keyboard input.
132	136
133	137		Solution: You forgot to create an [[Application Bundle\|application bundle]]. Lazarus \> Project \> Project Options \> Application - Create Application Bundle.
134	138
135	139		## Warning arm64 function not 4-byte aligned
136	140
137	141		When compiling on an Apple Silicon M1 processor, I get a "warning arm64 function not 4-byte aligned" for every function.
138	142
139	143		Solution: That's probably a consequence of using -Os. That setting unconditionally sets procalign (jump align) to 1. That's definitely wrong for AArch64 and a bunch of other architectures. There is no "minimum required alignment" for these settings defined yet anywhere in the compiler, so that will need to be added. In the meantime, do not use -Os to optimize size.
140	144
141	145		## Resource compiler "fpcres" not found
142	146
143	147		When compiling an application after installing or compiling a new Lazarus version, it fails with the error "Error (9021) Resource compiler "fpcres" not found, switching to external mode"
144	148
145	149		Solution: Create a file called `.fpc.cfg` (note the leading dot in the filename) in your home directory and add the lines:
146	150
147		-	~~`#include /etc/fpc.cfg`\~~
148		-	~~`-FD/usr/local/bin`~~
	151	+	```text
	152	+	#include /etc/fpc.cfg
	153	+	-FD/usr/local/bin
	154	+	```
149	155
150	156		If the file already exists it should contain the first of the lines above, so just add the second line.
151	157
152	158		## ld: file not found: /usr/lib/crt1.10.5.o
153	159
154	160		When compiling FPC from source, linking fails with "ld: file not found: /usr/lib/crt1.10.5.o"
155	161
156	162		Solution: Add `"OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk"` to your `make` command line - the reason is that when compiling the FPC source, the `fpc.cfg` file, which contains this option, is not used.
157	163
158	164		## ld: library not found for -lc
159	165
160	166		''When compiling FPC from source, I get this "ld: library not found for -lc, An error occurred while linking "
161	167
162	168		Explanation: The compiler cannot find the operating system SDK frameworks.
163	169
164	170		Solutions:
165	171
166	172		- If you have not installed the command line tools, you need to do so. Note that when you upgrade the operating system, the command line tools are deleted during the upgrade process.
167	173
168	174		- If you have installed the command line tools, then you need to tell the compiler where to find the SDK frameworks by adding:
169	175
170	176
171	177		`OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"`
172	178
173	179		to your `make` command line. Note that older versions of the command line tools (eg those for Mountain Lion 10.8.5) did not also install the SDK frameworks in which case you will need to install the latest version of the full Xcode package for your operating system and, for example, adding:
174	180
175	181		`OPT="-XR/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk/"`
176	182
177	183		to your `make` command line.
178	184
179	185		## codesign error when compiling FPC from source
180	186
181	187		When compiling FPC on older versions of macOS, I receive this error:
182	188
183		-	~~` /usr/bin/codesign --remove-signature ppc3.tmp `\~~
184		-	~~` ppc3.tmp: unsupported type or version of signature`\~~
185		-	~~` make[2]: *** [cycle] Error 1`\~~
186		-	~~` make[1]: *** [compiler_cycle] Error 2`\~~
187		-	~~` make: *** [build-stamp.x86_64-darwin] Error 2`~~
	189	+	``` pascal
	190	+	/usr/bin/codesign --remove-signature ppc3.tmp
	191	+	ppc3.tmp: unsupported type or version of signature
	192	+	make[2]: *** [cycle] Error 1
	193	+	make[1]: *** [compiler_cycle] Error 2
	194	+	make: *** [build-stamp.x86_64-darwin] Error 2
	195	+	```
188	196
189	197		Explanation: Older versions of the macOS `codesign` command line utility do not have a `--remove-signature` option.
190	198
191	199		Solution: You can provide a custom codesign command via the CODESIGN=xxx make parameter to your make command line. You could use CODESIGN=/usr/bin/true to work around it.
192	200
193	201		## Error: Internal error 200609171
194	202
195	203		When compiling my Objective-Pascal delegate function(s)/procdeure(s) the compiler stops with this error: "Error: Internal error 200609171".
196	204
197	205		Explanation: The internal error comes from using the DWARFv3 (-gw3) information format for debugging. There is a bug in the Free Pascal Compiler up to and including 3.2.2 related to generating debug information for Objective-Pascal with that format.
198	206
199	207		Solution: Switch to using the DWARFv2 (-gw) debugging information format OR use FPC main (development version 3.3.1).
200	208
201	209		## Lazarus reports success, but there are errors!
202	210
203	211		I compiled my application and although Lazarus says my application compiled successfully, there are a bunch of errors shown. For example -
204	212
205		-	~~` ``Compile Project, Target: project1: Success, Errors: 8`` `\~~
206		-	~~` Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107840:10: warning: section "__datacoal_nt" is deprecated`\~~
207		-	~~` Error: .section __DATA, __datacoal_nt, coalesced`\~~
208		-	~~` Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107840:10: note: change section name to "__data"`\~~
209		-	~~` Error: .section __DATA, __datacoal_nt, coalesced`\~~
210		-	~~` Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107883:10: warning: section "__datacoal_nt" is deprecated`\~~
211		-	~~` Error: .section __DATA, __datacoal_nt, coalesced`\~~
212		-	~~` Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107883:10: note: change section name to "__data"`\~~
213		-	~~` Error: .section __DATA, __datacoal_nt, coalesced`~~
	213	+	```text
	214	+	<font color=green>Compile Project, Target: project1: Success, Errors: 8</font>
	215	+	Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107840:10: warning: section "__datacoal_nt" is deprecated
	216	+	Error: .section __DATA, __datacoal_nt, coalesced
	217	+	Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107840:10: note: change section name to "__data"
	218	+	Error: .section __DATA, __datacoal_nt, coalesced
	219	+	Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107883:10: warning: section "__datacoal_nt" is deprecated
	220	+	Error: .section __DATA, __datacoal_nt, coalesced
	221	+	Error: /Users/trev/prg/LAZARUS/laz_avaudioplayer/lib/x86_64-darwin/unit1.s:107883:10: note: change section name to "__data"
	222	+	Error: .section __DATA, __datacoal_nt, coalesced
	223	+	```
214	224
215	225		Explanation: These are actually harmless warnings from the assembler, but for some reason Lazarus shows them as errors. Just ignore them.
216	226
217	227		## GUI application menu inaccessible
218	228
219	229		My GUI application menu is not accessible
220	230
221	231		Solution: All macOS GUI applications must be wrapped in an [[Application Bundle]].
222	232
223	233		## Other questions
224	234
225	235		I didn't find my issue here.
226	236
227	237		Solution: You might find a possible solution at [the Lazarus and Free Pascal Forum](http://forum.lazarus.freepascal.org/index.php/board,15.0.html). Otherwise, you might ask your question there.
228	238
229	239		## See also
230	240
231	241		- [[Lazarus Faq\|Lazarus FAQ]]
232	242
233	243		---
234	244		From the Free Pascal wiki, page "Mac Installation FAQ", as it stood on 2022-03-13 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
235	245		Category: FAQs
236	246		Category: FPC
237	247		Category: Install
238	248		Category: Lazarus
239	249		Category: macOS

Back to history