Sign in Join
Wiki copytemporary

Carbon Interface: what changed

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

OldNewLine
11*(macOS only)*
22
33## Introduction
44
55> **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.\
66> \
77> 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.
88
99Carbon 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]]
1010
1111## See also
1212
1313- [[macOS Programming Tips]]
1414- [[Carbon interface FAQ]] - A list of frequently asked questions about Carbon interface
1515- [[Carbon interface internals]] - If you want to help improving the Carbon interface
1616
1717## What you need
1818
1919The Carbon widgetset is now the default [[Widgetset|widgetset]] under macOS. For installation instructions see [[Installing Lazarus on macOS]].
2020
2121## Getting a "carbonproof" Lazarus
2222
2323![](/wiki-images/6/62/Carbon_ide_0_9_25.png)
2424
2525> **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.
2626
2727- 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/).
2828
2929- Then follow [[Installing Lazarus on macOS]].
3030
3131- 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
3232
3333### Compiling Carbon interface via Makefile
3434
3535Since 0.9.25 carbon is the default widgetset for macOS, so the below is not needed anymore.
3636
3737If your are still using a Lazarus below 0.9.25, you have to type this in Terminal.app:
3838
39-```
39+```text
4040make lcl LCL_PLATFORM=carbon
4141```
4242
4343### Compiling the Lazarus IDE with the Carbon interface via Makefile
4444
4545This requires Lazarus 0.9.25 or later.
4646
4747Type in Terminal.app:
4848
49-```
49+```text
5050make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL"
5151```
5252
5353On Leopard (Leopard 10.5.x) you should type:
5454
55-```
55+```text
5656make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL -k'-dylib_file' \
5757 -k'/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'"
5858```
5959
6060As stated on Apple's developer pages: <http://developer.apple.com/qa/qa2007/qa1567.html>
6161
6262**Important notes about the Carbon IDE**
6363
6464- You must run Lazarus via lazarus.app.
6565
6666- 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.
6767
6868### Error ATSUFindFontFromName
6969
7070if you're getting an error
7171
72-```
72+```text
7373carbonproc.pp(563,13) Error: Identifier not found "ATSUFindFontFromName"
7474```
7575
7676when compiling a project for macOS using FPC 3.0.4 you need:
7777
7878- 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)
7979
8080:*You either set the target in Project options (by switching it from default to i386)
8181
8282:*or if you compiling from command-line (i.e building an IDE) set up the following parameter to make command
8383
84-```
84+```text
8585CPU_TARGET=i386
8686```
8787
8888- either set LCL target (widgetset) to "[[Cocoa Interface|Cocoa]]"
8989
9090## Compiling the Carbon interface via Lazarus
9191
9292We now assume your Lazarus directory is located at /Users/\<yourUsername\>/pascal/lazarus/
9393
9494- Start Lazarus.
9595- Set Tools -\> Options -\> Environment -\> Files -\> Lazarus Directory to /Users/\<yourUsername\>/pascal/lazarus/
9696- Set Tools -\> Configure "Build Lazarus"\> to
9797
9898![](/wiki-images/7/7c/BuildLazarusOptionsCarbonIntf.png)
9999
100100For 0.9.24 add this to your 'Options':
101101
102102 -k-framework -kCarbon -k-framework -kOpenGL
103103
104104This will prevent unresolved symbols (Carbon-symbols like _ActivateWindow) while linking lazarus.
105105
106106- 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
107107
108108## Your first native Carbon app
109109
110110### Compiler Options
111111
112112Set Project \> Compiler Options \> Paths \> LCL Widget Type to *carbon*
113113
114114You 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.
115115
116116**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:
117117
118-```
118+```text
119119-dylib_file '/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'
120120```
121121
122122(This parameter is located at Project \> Compiler Options \> Linker \> Pass additional options to the linker)
123123
124124## Creating the Apple resource files
125125
126126> **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
127127
128128The command line tool:
129129
130130Open /Users/\<yourUserName\>/pascal/lazarus/components/macfiles/examples/createmacapplication.lpi in the IDE. Compile.
131131
132132Open a Terminal of your choice. Type:
133133
134134 cd /Users/<yourUserName>/pascal/project1/
135135 /Users/<yourUserName>/pascal/lazarus/components/macfiles/examples/createmacapplication project1
136136 ln -s ../../../project1 project1.app/Contents/MacOS/project1
137137
138138Now 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"
139139
140140Tip: 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/).
141141
142142### Application Bundle
143143
144144See [[Application Bundle]].
145145
146146#### Hiding a macOS app from the Dock
147147
148148For information on how to hide a macOS application from the Dock, refer to the article [[Hiding a macOS app from the Dock]].
149149
150150## Cross-compiling Intel to PowerPC
151151
152152With 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.
153153
154154### IDE Environment configuration
155155
156156Before 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.
157157
158158If 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.
159159
160160![](/wiki-images/8/8a/Crossppcidesettings.png)
161161
162162Of course, you specify the necessary compiler manually (ppc386 - for Intel, ppcppc - for PowerPC), but using "fpc" is more correct and easier
163163
164164### Project configuration
165165
166166If you are using an Intel Mac and want to compile an application for PowerPC, you need to do the following
167167
168168- Go to projects *Compiler options*-\>*Code*
169169- Select *powerpc* for Target CPU family.
170170
171171Rebuild the application (if you have compiled an intel application it will be overwritten with powerpc app).
172172
173173### Define binary architecture
174174
175175If you are not sure about the target CPU of the binary, you can use the command-line tool "lipo" to check it. Example:
176176
177-```
177+```text
178178$ lipo -info project1.
179179Non-fat file: project1 is architecture: ppc
180180```
181181
182182### Getting PowerPC units
183183
184184If you have Lazarus and FPC installed from .dmg file provided at Lazarus sourceforge, then you already should have all necessary units for PowerPC compilation.
185185
186186If 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.
187187
188188Open Tools -\> Configure "Build Lazarus" -\> Advanced Build Options.
189189
190190- Type *powerpc* into Target CPU field.
191191- Select all components, except for IDE and Samples (since there's no need to rebuild them) for building.
192192- It's recommended that you check 'Clean all' as well.
193193
194194![](/wiki-images/e/e4/Powerpcbuild.png)
195195
196196Press 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.
197197
198198LCL 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.
199199
200200- Go to the rtl/fcl sources directory (the one where 'rtl' and 'packages' directories are contained')
201201- Run the following line from the terminal
202202
203203(making and installing rtl/fcl files tries to write into /usr/local dir, that might need root access. using sudo might be required)
204204
205-```
205+```text
206206make clean all install CPU_TARGET=powerpc
207207```
208208
209209- Wait for the make process to complete, then rebuild the LCL and your project again.
210210
211211## Creating Universal binaries
212212
213213Lazarus 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:
214214
215-```
215+```text
216216 lipo -create ./ppc/myproj ./intel/myproj -output ./myproj
217217```
218218
219219Now, copy the newly created application myproj inside your .app folder.
220220
221221## Cocoa controls in Carbon applications
222222
223223Carbon 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.
224224
225225The following capabilities require Cocoa:
226226
227227- [[TTrayIcon]]
228228
229229To configure Cocoa support in Lazarus, complete the following steps depending on your Lazarus version:
230230
231231### Lazarus 0.9.29 or later
232232
233233In 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:
234234
2352351\) If you have previously configured PasCocoa in your /etc/fpc.cfg file, remove this configuration now
236236
2372372\) Build LCL-Carbon if not already built
238238
239239### Lazarus 0.9.28 or earlier
240240
2412411\) Download and configure FPC for the PasCocoa library.
242242
243243You'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).
244244
2452452\) Now you need to recompile Carbon LCL with Cocoa support enabled.
246246
247247Open Tools -\> Configure "Build Lazarus"...-\>Advanced Build Options
248248
249249Select LCL for Build+Clean Add "-dCarbonUseCocoa" to Options.
250250
251251![](/wiki-images/6/6d/CarbonUseCocoa.png)
252252
253253After that click build
254254
255255This should rebuild the LCL only. If you finished step 1 (downloading PasCocoa) successfully, then the LCL should compile with no problems.
256256
257257After the LCL is rebuilt, you need to rebuild your project.
258258
259259Don'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.
260260
261261---
262262*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