Carbon Interface: 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		## Introduction
4	4
5	5		> Warning: With the release of macOS 10.15 Catalina in October 2019, Apple has removed all support for the 32 bit Carbon framework from the operating system in favour of the [[Cocoa Interface\|64 bit Cocoa framework]]. The last versions of macOS and Xcode which had the necessary Apple files to compile 32 bit applications was Mojave 10.14.x and Xcode 11.3.1.\
6	6		> \
7	7		> Carbon development has been discontinued. The [[Cocoa Interface]] is now the default interface for macOS. Patches however are still accepted to fix compilation when Carbon breaks. There are no core Lazarus developers that still use the Carbon interface. The information below may be outdated.
8	8
9	9		Carbon is a macOS native API which descends from the old Mac OS APIs and is available since Puma 10.0. One thing to note, however, is that Apple has restricted Carbon to 32 bit applications only. To write 64 bit applications one should use the Lazarus [[Cocoa Interface]]
10	10
11	11		## See also
12	12
13	13		- [[macOS Programming Tips]]
14	14		- [[Carbon interface FAQ]] - A list of frequently asked questions about Carbon interface
15	15		- [[Carbon interface internals]] - If you want to help improving the Carbon interface
16	16
17	17		## What you need
18	18
19	19		The Carbon widgetset is now the default [[Widgetset\|widgetset]] under macOS. For installation instructions see [[Installing Lazarus on macOS]].
20	20
21	21		## Getting a "carbonproof" Lazarus
22	22
23	23		![](/wiki-images/6/62/Carbon_ide_0_9_25.png)
24	24
25	25		> Note: If you installed even a vaguely recent Lazarus version, you can skip this and the next section since Lazarus installers since 0.9.25 include both the Carbon widgetset source and compiled units for the Carbon widgetset.
26	26
27	27		- macOS includes a command line svn client if you have installed the [[Xcode]] command line tools. If you want a GUI SVN for macOS: Install the SVN client using [fink](http://www.finkproject.org/). SVN clients with a GUI (graphical user interface) are available from [Versiontracker](http://www.versiontracker.com/macosx/).
28	28
29	29		- Then follow [[Installing Lazarus on macOS]].
30	30
31	31		- Start Lazarus. The IDE will start with a new project and an empty form. Save this project under a name of your choice. In the following examples we assume this to be /Users/\<yourUsername\>/pascal/test/project1.lpi
32	32
33	33		### Compiling Carbon interface via Makefile
34	34
35	35		Since 0.9.25 carbon is the default widgetset for macOS, so the below is not needed anymore.
36	36
37	37		If your are still using a Lazarus below 0.9.25, you have to type this in Terminal.app:
38	38
39		-	~~`make lcl LCL_PLATFORM=carbon`~~
	39	+	```
	40	+	make lcl LCL_PLATFORM=carbon
	41	+	```
40	42
41	43		### Compiling the Lazarus IDE with the Carbon interface via Makefile
42	44
43	45		This requires Lazarus 0.9.25 or later.
44	46
45	47		Type in Terminal.app:
46	48
47		-	~~`make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL"`~~
	49	+	```
	50	+	make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL"
	51	+	```
48	52
49	53		On Leopard (Leopard 10.5.x) you should type:
50	54
51		-	~~`make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL -k'-dylib_file' \`\~~
52		-	~~` -k'/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'"`~~
	55	+	```
	56	+	make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL -k'-dylib_file' \
	57	+	-k'/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'"
	58	+	```
53	59
54	60		As stated on Apple's developer pages: <http://developer.apple.com/qa/qa2007/qa1567.html>
55	61
56	62		Important notes about the Carbon IDE
57	63
58	64		- You must run Lazarus via lazarus.app.
59	65
60	66		- Make sure your editor is using a mono-font. You can check that on the Editor Options dialog. The "Monaco" font is a good suggestion.
61	67
62	68		### Error ATSUFindFontFromName
63	69
64	70		if you're getting an error
65	71
66		-	~~`carbonproc.pp(563,13) Error: Identifier not found "ATSUFindFontFromName"`~~
	72	+	```
	73	+	carbonproc.pp(563,13) Error: Identifier not found "ATSUFindFontFromName"
	74	+	```
67	75
68	76		when compiling a project for macOS using FPC 3.0.4 you need:
69	77
70	78		- either set CPU target explicitly to i386. (FPC 3.0.4 compiles to x86_64 for Darwin target by default. This is done due Apple stopping support for 32-bit target)
71	79
72	80		:*You either set the target in Project options (by switching it from default to i386)
73	81
74	82		:*or if you compiling from command-line (i.e building an IDE) set up the following parameter to make command
75	83
76		-	~~`CPU_TARGET=i386`~~
	84	+	```
	85	+	CPU_TARGET=i386
	86	+	```
77	87
78	88		- either set LCL target (widgetset) to "[[Cocoa Interface\|Cocoa]]"
79	89
80	90		## Compiling the Carbon interface via Lazarus
81	91
82	92		We now assume your Lazarus directory is located at /Users/\<yourUsername\>/pascal/lazarus/
83	93
84	94		- Start Lazarus.
85	95		- Set Tools -\> Options -\> Environment -\> Files -\> Lazarus Directory to /Users/\<yourUsername\>/pascal/lazarus/
86	96		- Set Tools -\> Configure "Build Lazarus"\> to
87	97
88	98		![](/wiki-images/7/7c/BuildLazarusOptionsCarbonIntf.png)
89	99
90	100		For 0.9.24 add this to your 'Options':
91	101
92	102		-k-framework -kCarbon -k-framework -kOpenGL
93	103
94	104		This will prevent unresolved symbols (Carbon-symbols like _ActivateWindow) while linking lazarus.
95	105
96	106		- Tools\>Build Lazarus -- This will compile the Carbon Interface and put the .ppu files into /Users/\<yourUsername\>/pascal/lazarus/lcl/units/powerpc-darwin and /Users/\<yourUsername\>/pascal/lazarus/lcl/units/powerpc-darwin/carbon
97	107
98	108		## Your first native Carbon app
99	109
100	110		### Compiler Options
101	111
102	112		Set Project \> Compiler Options \> Paths \> LCL Widget Type to carbon
103	113
104	114		You should now be able to compile the project without errors. It will create an executable project1, but you cannot focus it. The reason is that macOS expects some hidden resource files.
105	115
106	116		Note for Leopard 10.5: As discussed in [this](http://www.lazarus.freepascal.org/index.php?name=PNphpBB2&file=viewtopic&t=5174&start=0&postdays=0&postorder=asc&highlight=) forum topic, on Leopard you have to add the following linker parameters to your project:
107	117
108		-	~~`-dylib_file '/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'`~~
	118	+	```
	119	+	-dylib_file '/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'
	120	+	```
109	121
110	122		(This parameter is located at Project \> Compiler Options \> Linker \> Pass additional options to the linker)
111	123
112	124		## Creating the Apple resource files
113	125
114	126		> Note: Since 0.9.25 Lazarus can create application bundles without compiling this tool on your own. The corresponding button is at Project \> Project Options... \> Create Application Bundle
115	127
116	128		The command line tool:
117	129
118	130		Open /Users/\<yourUserName\>/pascal/lazarus/components/macfiles/examples/createmacapplication.lpi in the IDE. Compile.
119	131
120	132		Open a Terminal of your choice. Type:
121	133
122	134		cd /Users/<yourUserName>/pascal/project1/
123	135		/Users/<yourUserName>/pascal/lazarus/components/macfiles/examples/createmacapplication project1
124	136		ln -s ../../../project1 project1.app/Contents/MacOS/project1
125	137
126	138		Now you can start the program from IDE (checked option [[IDE Window: Project Options\|Use Application Bundle for running and debugging (darwin only)]]) or via its Finder icon or in the native macOS Terminal via "open project1.app"
127	139
128	140		Tip: There is also a script that creates an app bundle for a GTK executable at [[macOS Programming Tips]]. You can modify it to use with a Carbon executable (take out the 4 instructions that start the executable with X11). A slightly improved version of this script for Carbon apps is also available for downloading from [here](http://web.fastermac.net/~MacPgmr/Lazarus/).
129	141
130	142		### Application Bundle
131	143
132	144		See [[Application Bundle]].
133	145
134	146		#### Hiding a macOS app from the Dock
135	147
136	148		For information on how to hide a macOS application from the Dock, refer to the article [[Hiding a macOS app from the Dock]].
137	149
138	150		## Cross-compiling Intel to PowerPC
139	151
140	152		With 0.9.26 Lazarus comes with precompiled units for both architectures Intel and PowerPC. Since there are still a lot of Mac PowerPC users, you might want to build an application for both archs, or even create a universal binary.
141	153
142	154		### IDE Environment configuration
143	155
144	156		Before you're able to cross-compile, you must make sure, that the IDE Environment compiler settings are correct. Open Environment-\>Files, check out "Complier path" setting.
145	157
146	158		If you need to cross-compile an application or LCL (using Lazarus), you should define "fpc" binary as a compiler. fpc binary will select the proper compiler (ppc386 or ppcppc), depending on your current target selected.
147	159
148	160		![](/wiki-images/8/8a/Crossppcidesettings.png)
149	161
150	162		Of course, you specify the necessary compiler manually (ppc386 - for Intel, ppcppc - for PowerPC), but using "fpc" is more correct and easier
151	163
152	164		### Project configuration
153	165
154	166		If you are using an Intel Mac and want to compile an application for PowerPC, you need to do the following
155	167
156	168		- Go to projects Compiler options-\>Code
157	169		- Select powerpc for Target CPU family.
158	170
159	171		Rebuild the application (if you have compiled an intel application it will be overwritten with powerpc app).
160	172
161	173		### Define binary architecture
162	174
163	175		If you are not sure about the target CPU of the binary, you can use the command-line tool "lipo" to check it. Example:
164	176
165		-	~~`$ lipo -info project1. `\~~
166		-	~~`Non-fat file: project1 is architecture: ppc`~~
	177	+	```
	178	+	$ lipo -info project1.
	179	+	Non-fat file: project1 is architecture: ppc
	180	+	```
167	181
168	182		### Getting PowerPC units
169	183
170	184		If you have Lazarus and FPC installed from .dmg file provided at Lazarus sourceforge, then you already should have all necessary units for PowerPC compilation.
171	185
172	186		If you don't use the provided .dmg files (i.e. using svn version), you might need to rebuild LCL units for powerpc target as well.
173	187
174	188		Open Tools -\> Configure "Build Lazarus" -\> Advanced Build Options.
175	189
176	190		- Type powerpc into Target CPU field.
177	191		- Select all components, except for IDE and Samples (since there's no need to rebuild them) for building.
178	192		- It's recommended that you check 'Clean all' as well.
179	193
180	194		![](/wiki-images/e/e4/Powerpcbuild.png)
181	195
182	196		Press Build and wait for building process to complete. After that you need to recompile your project, making sure that the project's compiler project is configured for powerpc.
183	197
184	198		LCL building might fail if you don't have RTL/FCL units compiled for the powerpc arch. You'll need RTL/FCL sources to compile them.
185	199
186	200		- Go to the rtl/fcl sources directory (the one where 'rtl' and 'packages' directories are contained')
187	201		- Run the following line from the terminal
188	202
189	203		(making and installing rtl/fcl files tries to write into /usr/local dir, that might need root access. using sudo might be required)
190	204
191		-	~~`make clean all install CPU_TARGET=powerpc `~~
	205	+	```
	206	+	make clean all install CPU_TARGET=powerpc
	207	+	```
192	208
193	209		- Wait for the make process to complete, then rebuild the LCL and your project again.
194	210
195	211		## Creating Universal binaries
196	212
197	213		Lazarus will create an application tuned for a single CPU, for macOS this is either a PowerPC or Intel CPU. You may want to distribute your application as a 'Universal Binary', allowing users that may have either a PowerPC or Intel computer to use the program. To do this, you need to compile two versions of your application: one with PowerPC as the target CPU and one as Intel. Next, you need to stitch these two executables together using the macOS program "lipo" (installed with the other macOS developer tools required by Lazarus). For example, consider two versions of the application 'myprogram'. One in the 'ppc' folder compiled for PowerPC and one in the 'intel' folder compiled for Intel CPUs. You can then combine these two to a univeral application by running this command:
198	214
199		-	~~` lipo -create ./ppc/myproj ./intel/myproj -output ./myproj`~~
	215	+	```
	216	+	lipo -create ./ppc/myproj ./intel/myproj -output ./myproj
	217	+	```
200	218
201	219		Now, copy the newly created application myproj inside your .app folder.
202	220
203	221		## Cocoa controls in Carbon applications
204	222
205	223		Carbon is considered a legacy API by Apple. This means that newer features and controls in macOS might not be available using Carbon API. Though it doesn't mean, that they cannot be used in Carbon application. It just requires additional work to access them. In C it means using Obj-C, but since Obj-C is not available in Pascal. In Lazarus you have to use the [[PasCocoa]] library.
206	224
207	225		The following capabilities require Cocoa:
208	226
209	227		- [[TTrayIcon]]
210	228
211	229		To configure Cocoa support in Lazarus, complete the following steps depending on your Lazarus version:
212	230
213	231		### Lazarus 0.9.29 or later
214	232
215	233		In these versions PasCocoa is already installed and configured and LCL-Carbon is compiled with Cocoa support by default, you just need to complete this steps:
216	234
217	235		1\) If you have previously configured PasCocoa in your /etc/fpc.cfg file, remove this configuration now
218	236
219	237		2\) Build LCL-Carbon if not already built
220	238
221	239		### Lazarus 0.9.28 or earlier
222	240
223	241		1\) Download and configure FPC for the PasCocoa library.
224	242
225	243		You'll find the instruction [here](http://wiki.lazarus.freepascal.org/Cocoa_Interface#Compiling_the_Cocoa_Interfaces). You only have to to download PasCocoa and configure your fpc.cfg file, as described. (You don't need to compile the PasCocoa samples or the Cocoa widgetset).
226	244
227	245		2\) Now you need to recompile Carbon LCL with Cocoa support enabled.
228	246
229	247		Open Tools -\> Configure "Build Lazarus"...-\>Advanced Build Options
230	248
231	249		Select LCL for Build+Clean Add "-dCarbonUseCocoa" to Options.
232	250
233	251		![](/wiki-images/6/6d/CarbonUseCocoa.png)
234	252
235	253		After that click build
236	254
237	255		This should rebuild the LCL only. If you finished step 1 (downloading PasCocoa) successfully, then the LCL should compile with no problems.
238	256
239	257		After the LCL is rebuilt, you need to rebuild your project.
240	258
241	259		Don't forget, if you need Cocoa controls for CPU other than your Mac, you'll need to rebuild the LCL, specifying the proper CPU target.
242	260
243	261		---
244	262		From the Free Pascal wiki, page "Carbon Interface", as it stood on 2023-11-13 after a change by Bart, 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).

Back to history