Difference between revisions of "Carbon Interface"

From Free Pascal wiki
Jump to navigationJump to search
m (typos and language tweaks.)
Line 21: Line 21:
  
 
[[Image:carbon_ide_0_9_25.png|thumb|Carbon IDE version 0.9.25 running on Mac OS X 10.4]]
 
[[Image:carbon_ide_0_9_25.png|thumb|Carbon IDE version 0.9.25 running on Mac OS X 10.4]]
Note: If you installed a Lazarus snapshot, you can skip this section and the next since the snapshot includes both the Carbon widgetset source and compiled units for the Carbon widgetset.
+
Note: If you installed a Lazarus snapshot, you can skip this and the next section since the snapshot includes both the Carbon widgetset source and compiled units for the Carbon widgetset.
  
 
*Install SVN for Mac OS X: A good package is provided by [http://www.codingmonkeys.de/mbo/ Martin Ott]. Another option is to install the SVN client using [http://www.finkproject.org/ fink]. SVN clients with a GUI (graphical user interface) are available from [http://www.versiontracker.com/macosx/ Versiontracker].
 
*Install SVN for Mac OS X: A good package is provided by [http://www.codingmonkeys.de/mbo/ Martin Ott]. Another option is to install the SVN client using [http://www.finkproject.org/ fink]. SVN clients with a GUI (graphical user interface) are available from [http://www.versiontracker.com/macosx/ Versiontracker].
 
*Then follow [[Installing_Lazarus#Downloading_Lazarus_SVN]]
 
*Then follow [[Installing_Lazarus#Downloading_Lazarus_SVN]]
  
*Start Lazarus. The IDE will start with a new project with 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
+
*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
  
 
=== Compiling Carbon interface via Makefile ===
 
=== Compiling Carbon interface via Makefile ===
Line 32: Line 32:
 
Since 0.9.25 carbon is the default widgetset for Mac OS X, so the below is not needed anymore.
 
Since 0.9.25 carbon is the default widgetset for Mac OS X, so the below is not needed anymore.
  
Type in terminal:
+
If your are still using a Lazarus below 0.9.25, you have to type this in Terminal.app:
  
 
  make lcl LCL_PLATFORM=carbon
 
  make lcl LCL_PLATFORM=carbon
Line 40: Line 40:
 
This requires Lazarus 0.9.25 or superior.
 
This requires Lazarus 0.9.25 or superior.
  
Type in terminal:
+
Type in Terminal.app:
  
 
  make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL"
 
  make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL"
Line 80: Line 80:
 
Set Project > Compiler Options > Paths > LCL Widget Type to ''carbon''
 
Set Project > Compiler Options > Paths > LCL Widget Type to ''carbon''
  
You should now be able to compile the project without errors. It will create an executable ''project1'', but you cannot focus it. That's because Mac OS X expects some hidden resource files.
+
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 Mac OS X expects some hidden resource files.
  
 
'''Note for OS X 10.5:''' As discussed in [http://www.lazarus.freepascal.org/index.php?name=PNphpBB2&file=viewtopic&t=5174&start=0&postdays=0&postorder=asc&highlight= this] forum topic, on Leopard you have to add the following linker parameters to your project:
 
'''Note for OS X 10.5:''' As discussed in [http://www.lazarus.freepascal.org/index.php?name=PNphpBB2&file=viewtopic&t=5174&start=0&postdays=0&postorder=asc&highlight= this] forum topic, on Leopard you have to add the following linker parameters to your project:
Line 109: Line 109:
  
 
With 0.9.26 Lazarus comes with precompiled units for both architectures Intel and PowerPC.
 
With 0.9.26 Lazarus comes with precompiled units for both architectures Intel and PowerPC.
Since there're still a lot of Mac PowerPC users, you might want to build an application for both arhcs, or even create
+
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.
 
a universal binary.
  
 
=== IDE Environment configuration ===
 
=== IDE Environment configuration ===
  
Before you're able to cross-compile, you must make sure, that IDE Environment compiler settings are correct.
+
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.
 
Open Environment->Files, check out "Complier path" setting.
  
Line 121: Line 121:
  
 
[[Image:crossppcidesettings.png]]
 
[[Image:crossppcidesettings.png]]
 
  
 
Of course, you specify the necessary compiler manually (ppc386 - for Intel, ppcppc - for PowerPC), but using "fpc" is more correct and easier
 
Of course, you specify the necessary compiler manually (ppc386 - for Intel, ppcppc - for PowerPC), but using "fpc" is more correct and easier
Line 127: Line 126:
 
=== Project configuration ===
 
=== Project configuration ===
  
If you're using Intel Mac and want to compile an application for PowerPC, you need to do the following
+
If you are using an Intel Mac and want to compile an application for PowerPC, you need to do the following
 
* Go to projects ''Compiler options''->''Code''
 
* Go to projects ''Compiler options''->''Code''
 
* Select ''powerpc'' for Target CPU family.
 
* Select ''powerpc'' for Target CPU family.
  
Rebuild the application (if you have compiled intel application it will be overwritten with powerpc app).
+
Rebuild the application (if you have compiled an intel application it will be overwritten with powerpc app).
  
 
=== Define binary architecture ===
 
=== Define binary architecture ===
  
If you're unsure about target CPU of the binary, you can use command-line tool to check it,
+
If you are not sure about the target CPU of the binary, you can use the command-line tool "lipo" to check it.
for example
+
Example:
  
 
  $ lipo -info project1.  
 
  $ lipo -info project1.  
Line 146: Line 145:
 
have all necessary units for PowerPC compilation.
 
have all necessary units for PowerPC compilation.
  
If you don't use provided .dmg files (i.e. using svn version), you might need to rebuild LCL units for powerpc target as well.
+
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.
  
 
Open Tools -> Configure "Build Lazarus" -> Advanced Build Options.
 
Open Tools -> Configure "Build Lazarus" -> Advanced Build Options.
Line 155: Line 154:
 
[[Image:powerpcbuild.png]]
 
[[Image:powerpcbuild.png]]
  
Press Build, and wait for building process to complete. After that you need to recompile your project, make sure that project's compiler project is configure for powerpc.
+
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.
 
 
 
 
  
LCL building might fail if you don't have RTL/FCL units compiled for powerpc arch.
+
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.  
 
You'll need RTL/FCL sources to compile them.  
* Go to rtl/fcl sources directory (the one, there 'rtl' and 'packages' directories are contained')
+
* Go to the rtl/fcl sources directory (the one where 'rtl' and 'packages' directories are contained')
 
* Run the following line from the terminal  
 
* Run the following line from the terminal  
  
Line 168: Line 165:
 
  make clean all install CPU_TARGET=powerpc   
 
  make clean all install CPU_TARGET=powerpc   
  
 
+
* Wait for the make process to complete, then rebuild the LCL and your project again.
* Wait for make process to complete, and then rebuild LCL and your project again.
 
  
 
== Creating Universal binaries ==
 
== Creating Universal binaries ==
  
Lazarus will create an application tuned for a single CPU, for OSX 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 OSX program lipo (installed with the other OSX developer tools required by Lazarus).  For example, consider two versions of the application 'myprogram', with the one in the 'ppc' folder compiled for PowerPC, while the one in the 'intel' folder is compiled for Intel CPUs. You can then combin these by running the command
+
Lazarus will create an application tuned for a single CPU, for OS X 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 OS X program "lipo" (installed with the other OS X 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:
 
   lipo -create ./ppc/myproj ./intel/myproj -output ./myproj
 
   lipo -create ./ppc/myproj ./intel/myproj -output ./myproj
 
Now, copy the newly created application myproj inside your .app folder.
 
Now, copy the newly created application myproj inside your .app folder.
Line 179: Line 175:
 
== Cocoa controls in Carbon applications ==
 
== Cocoa controls in Carbon applications ==
  
Carbon is considered legacy API by Apple, it means that newer features and controls in Mac OSX might not be available using Carbon API. Though it doesn't mean, that they cannot be used in Carbon application.  
+
Carbon is considered a legacy API by Apple. This means that newer features and controls in Mac OS X might not be available using Carbon API. Though it doesn't mean, that they cannot be used in Carbon application.  
It just required additional work to access them. In C language, that would mean using Obj-C language, but since Obj-C is not available in Pascal, Lazarus users should use [[PasCocoa]] library.
+
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.
 
 
 
 
As an example, MacOSX TTrayIcon is available only if PasCocoa is used.
 
 
 
 
 
If you need TTrayIcon (or any other Cocoa based control) you must do need to complete 2 following steps:
 
  
 +
As an example, Mac OS X TTrayIcon is available only through PasCocoa.
  
1st) Download and configure your FPC for PasCocoa library.
+
So, if you need TTrayIcon (or any other Cocoa based control) you have to complete the following two steps:
  
You'll find the instruction [http://wiki.lazarus.freepascal.org/Cocoa_Interface#Compiling_the_Cocoa_Interfaces here]. You need to make only point to download PasCocoa and configure your fpc.cfg file, as described. (You don't need to compile PasCocoa samples or Cocoa widgetset).
+
1) Download and configure FPC for the PasCocoa library.  
  
 +
You'll find the instruction [http://wiki.lazarus.freepascal.org/Cocoa_Interface#Compiling_the_Cocoa_Interfaces here]. 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).
  
2nd) Now you need to recompile Carbon LCL with Cocoa support enabled.
+
2) Now you need to recompile Carbon LCL with Cocoa support enabled.
  
 
Open Tools -> Configure "Build Lazarus"...->Advanced Build Options
 
Open Tools -> Configure "Build Lazarus"...->Advanced Build Options
Line 205: Line 197:
 
After that click build
 
After that click build
  
This should rebuild LCL only. If you done the 1st step (downloading PasCocoa) successfully, then LCL should compile with no problems.
+
This should rebuild the LCL only. If you finished step 1 (downloading PasCocoa) successfully, then the LCL should compile with no problems.
 
    
 
    
After LCL is rebuilt, you need to rebuild your project.
+
After the LCL is rebuilt, you need to rebuild your project.

Revision as of 20:56, 27 August 2009

Deutsch (de) English (en) 日本語 (ja)

macOSlogo.png

This article applies to macOS only.

See also: Multiplatform Programming Guide


Introduction

Carbon is a Mac OS native API.

Other Interfaces

Platform specific Tips

Interface Development Articles

See also

What you need

The Carbon widgetset is now the default widgetset under Mac OS X. For installation instructions see Installing Lazarus on Mac OS X.

Getting a "carbonproof" Lazarus

Carbon IDE version 0.9.25 running on Mac OS X 10.4

Note: If you installed a Lazarus snapshot, you can skip this and the next section since the snapshot includes both the Carbon widgetset source and compiled units for the Carbon widgetset.

  • 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

Compiling Carbon interface via Makefile

Since 0.9.25 carbon is the default widgetset for Mac OS X, so the below is not needed anymore.

If your are still using a Lazarus below 0.9.25, you have to type this in Terminal.app:

make lcl LCL_PLATFORM=carbon

Compiling the Lazarus IDE with the Carbon interface via Makefile

This requires Lazarus 0.9.25 or superior.

Type in Terminal.app:

make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL"


On Leopard (OS X 10.5.x) you should type:

make all LCL_PLATFORM=carbon OPT="-k-framework -kCarbon -k-framework -kOpenGL -k'-dylib_file' \
    -k'/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'"

As stated on Apple's developer pages: http://developer.apple.com/qa/qa2007/qa1567.html

Important notes about the Carbon IDE

  • You must run Lazarus via lazarus.app.
  • 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.

Compiling the Carbon interface via Lazarus

We now assume your Lazarus directory is located at /Users/<yourUsername>/pascal/lazarus/

  • Start Lazarus.
  • Set Environment>Environment Options>Files>Lazarus Directory to /Users/<yourUsername>/pascal/lazarus/
  • Set Tools>Configure "Build Lazarus"> to

BuildLazarusOptionsCarbonIntf.png

For 0.9.24 add this to your 'Options':

-k-framework -kCarbon -k-framework -kOpenGL

This will prevent unresolved symbols (Carbon-symbols like _ActivateWindow) while linking lazarus.

  • 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

Your first native Carbon app

Compiler Options

Set Project > Compiler Options > Paths > LCL Widget Type to carbon

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 Mac OS X expects some hidden resource files.

Note for OS X 10.5: As discussed in this forum topic, on Leopard you have to add the following linker parameters to your project:

-dylib_file '/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib'

(This parameter is located at Project > Compiler Options > Linker > Pass additional options to the linker)

Creating the Apple resource files

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

The command line tool:

Open /Users/<yourUserName>/pascal/lazarus/components/macfiles/examples/createmacapplication.lpi in the IDE. Compile.

Open a Terminal of your choice. Type:

cd /Users/<yourUserName>/pascal/project1/
/Users/<yourUserName>/pascal/lazarus/components/macfiles/examples/createmacapplication project1
ln -s ../../../project1 project1.app/Contents/MacOS/project1

Now you can start the program from IDE (checked option Use Application Bundle for running and debugging (darwin only)) or via its Finder icon or in the native Mac OS X Terminal via "open project1.app"

Tip: There is also a script that creates an app bundle for a GTK executable at OS X 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.

Cross-compiling Intel to PowerPC

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.

IDE Environment configuration

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.

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.

crossppcidesettings.png

Of course, you specify the necessary compiler manually (ppc386 - for Intel, ppcppc - for PowerPC), but using "fpc" is more correct and easier

Project configuration

If you are using an Intel Mac and want to compile an application for PowerPC, you need to do the following

  • Go to projects Compiler options->Code
  • Select powerpc for Target CPU family.

Rebuild the application (if you have compiled an intel application it will be overwritten with powerpc app).

Define binary architecture

If you are not sure about the target CPU of the binary, you can use the command-line tool "lipo" to check it. Example:

$ lipo -info project1. 
Non-fat file: project1 is architecture: ppc

Getting PowerPC units

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.

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.

Open Tools -> Configure "Build Lazarus" -> Advanced Build Options.

  • Type powerpc into Target CPU field.
  • Select all components, except for IDE and Samples (since there's no need to rebuild them) for building.
  • It's recommended that you check 'Clean all' as well.

powerpcbuild.png

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.

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.

  • Go to the rtl/fcl sources directory (the one where 'rtl' and 'packages' directories are contained')
  • Run the following line from the terminal

(making and installing rtl/fcl files tries to write into /usr/local dir, that might need root access. using sudo might be required)

make clean all install CPU_TARGET=powerpc   
  • Wait for the make process to complete, then rebuild the LCL and your project again.

Creating Universal binaries

Lazarus will create an application tuned for a single CPU, for OS X 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 OS X program "lipo" (installed with the other OS X 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:

 lipo -create ./ppc/myproj ./intel/myproj -output ./myproj

Now, copy the newly created application myproj inside your .app folder.

Cocoa controls in Carbon applications

Carbon is considered a legacy API by Apple. This means that newer features and controls in Mac OS X 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.

As an example, Mac OS X TTrayIcon is available only through PasCocoa.

So, if you need TTrayIcon (or any other Cocoa based control) you have to complete the following two steps:

1) Download and configure FPC for the PasCocoa library.

You'll find the instruction here. 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).

2) Now you need to recompile Carbon LCL with Cocoa support enabled.

Open Tools -> Configure "Build Lazarus"...->Advanced Build Options

Select LCL for Build+Clean Add "-dCarbonUseCocoa" to Options.

CarbonUseCocoa.png

After that click build

This should rebuild the LCL only. If you finished step 1 (downloading PasCocoa) successfully, then the LCL should compile with no problems.

After the LCL is rebuilt, you need to rebuild your project.