Cocoa VTK: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
No edit summary
 
(36 intermediate revisions by 8 users not shown)
Line 1: Line 1:
== '''Installing VTK on Apple OS 10.4.8 Mac Book Pro for the purposes of Cocoa''' ==
As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform.  This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.
----------------------------------------------
This document outlines how to install VTK 5 on a Apple Mac Book Pro running OS X 10.4.8.  Xcode 2.4 is installed.  These instructions have also been used to install VTK 5 on a Quad G5 running OS X 10.4.4 with Xcode 2.2.


Sean McBride of Rogue Research have provided an xcode project that uses VTK. It can be downloaded from [[http]]://www.rogue-research.com/vtk/SimpleCocoaVTK.html .  They state in the document that VTK must already be installed.  This document explains how to get VTK installed so that the simpleCocoaVTK xcode project will function.
== '''Supported Versions''' ==
VTK 6.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.


== '''CMAKE''' ==
VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.
-----
The first step is to install cmake. Cmake is cross platform make and can be downloaded from [[http]]://www.cmake.org/HTML/Download.html .  the version I used most recently was Darwin Universal (Tiger only installer) cmake-2.4.3-Darwin-universal.dmg.  Download the dmg file and mount it as you would for any other install.  Run the installer in the mount and when it is done Cmake will be installed. This step has been greatly simplified thanks to the installer.


'== ''VTK''' ==
On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6.  On OS X 10.7 and later, VTK 6.x is recommended.
----------
Now secure a copy of VTK.  You can download the most recent stable build from [[http]]://www.vtk.org/get-software.php#latest . As of this writing I used version 5.0.2.  The file I downloaded was vtk-5.0.2.tar.gz.  Double click the file and expand the folder on your desktop. Rename the folder just ‘VTK’.


We will need a folder to put the vtk build in, I use a folder in my home directory name Development.  Create a folder where you want vtk to reside.
== '''Windowing API''' ==


''cd ~/Development''
On OS X, there are two windowing APIs: Carbon and Cocoa.  Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa.  Carbon support is deprecated by both Apple and VTK, and should not be used for new development.  To choose, set one of the following to ON:


Now drag the VTK folder into Development.
VTK_USE_CARBON:BOOL=ON
VTK_USE_COCOA:BOOL=ON


In ~/Development create a new directory.  I named mine VTKBuild.
== '''Deployment Target and SDK''' ==


''mkdir VTKBuild''
The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers.  In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex:


Move into that folder.
CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7


''cd VTKBuild''
The 'SDK' specifies which version of OS headers and libraries you want to build against.  Usually, you want to built against the newest SDK, which is what CMake defaults to.  But you can override it:


Issue the cmake command.
CMAKE_OSX_SYSROOT:STRING=/path/to/SDK


''cmake ../VTK''
== '''Universal Binaries''' ==


A lot of code will scroll by. When it is done you will find a file named CMakeCache.txt in your VTKBuild folder.  Edit that file in your favorite text editor. You need to edit it to make VTK build for cocoa instead of carbon.  Find the following lines in the text file and change them to look like the following.  (You're turning offs to ons and vice versa)
VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex:


'''VTK_USE_CARBON:BOOL=OFF'''
CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64


'''VTK_USE_COCOA:BOOL=ON'''
Possible values are: ppc, ppc64, i386, and x86_64.


Finally, change the flag CMAKE_INSTALL_PREFIX from
== '''Cocoa Memory Management Models''' ==


'''CMAKE_INSTALL_PREFIX=/usr/local'''
Cocoa has three memory management models, chronologically by date of introduction:


to
* manual reference counting (MRC)
* garbage collection (GC)
* automatic reference counting (ARC)


'''CMAKE_INSTALL_PREFIX=~/Development/VTKBuild'''
VTK supports MRC and GC. MRC is the default. GC was deprecated by Apple in OS X 10.8, but to use it set:


Save the file.
VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc


Make sure you are in ~/Development/VTKBuild and issue the command
ARC support will eventually be available, but if your host application is ARC you can build VTK as MRC and still link to it.


''cmake ../VTK''  
== '''VTK_USE_SYSTEM options''' ==


again.  When it is complete, do another one for good measure since Drew McCormick seems to think it's good practise (and it only takes a second).
VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries.  The advantage of doing so is that it reduces your compile time and binary size.  Only a few are built-in to OS X, which you can make VTK use by setting:


In ~/Development/VTKBuild issue the make command.
VTK_USE_SYSTEM_ZLIB:BOOL=ON
VTK_USE_SYSTEM_EXPAT=ON
VTK_USE_SYSTEM_LIBXML2=ON


''make''
== '''Use Application Bundles''' ==


VTK is now being built and a lot of material will scroll by the screen.  Hopefully there will be no errors. On my virgin mac book pro with xcode 2.4 installed it all worked the first time.
On OS X, there are (at least) two kinds of executables:
now issue the following command
* Application Bundles
* plain UNIX executables
To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly.
Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is [http://vtk.org/Bug/view.php?id=2025 bug 2025].
When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file:


''make install''
IF(APPLE)
  SET(EXECUTABLE_FLAG MACOSX_BUNDLE)
ENDIF(APPLE)


The make install command will copy all the .h header files for vtk into a single directory, the ~/Development/VKBuild/include/vtk-5.1 directory, the one defined by CMAKE_INSTALL_PREFIX. We do this because the simpleCocoaVTK xcode project needs to have all the headers in one folder and installing VTK spreads the headers in a number of different directories.  This make install gathers them all up and puts them into one folder.  (Just copies though, the originals are still in the right place).
If for some reason you cannot build as an application bundle, see [http://vtk.org/Bug/view.php?id=2025 bug 2025] for possible workarounds.


== '''SIMPLE COCOA VTK''' ==
== '''SimpleCocoaVTK''' ==
----------------
To make Xcode aware of VTK we need to add two source trees, as outlined in the Rogue Research page.
Open the simpleCocoaVTK project in xcode.  Then go to xcode -> preferences and look for the source tree icon along the top bar.  In my xcode it is the third icon from the right and looks like a traffic sign.  Click the icon and a table display will come up.  Click the + icon twice and add two rows to the table.


For the first row, set the setting name and display name to ‘vtk-lib’ (without the single quotes) and set the path to ‘/Users/rglover/Development/VTKBuild/bin’ (without the single quotes).  Notice I have my username in there (rglover), replace it with your own.
SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK.  It illustrates how to use the VTK libraries within an Xcode-based OS X application.  SimpleCocoaVTK is an example, it is not required to use VTK.


For the second row, set the setting name and display name to ‘vtk-include’ (without the single quotes) and set the path to ‘/Users/rglover/Development/VTKBuild/include/VTK-5.1’ (without the single quotes).
Originally standalone, SimpleCocoaVTK is now part of VTK itself in the [http://vtk.org/gitweb?p=VTK.git;a=tree;f=Examples/GUI/Cocoa Examples/GUI/Cocoa] folder. See the documentation there for how to use it.


Case is important here so make sure it is correct.
{{VTK/Template/Footer}}
 
With the simpleCocoaVTK xcode project open do a ‘clean all’ by clicking on the hammer build icon and selecting the double broom clean all icon.
 
A final point, make sure zero link is off.  To check this click the targets icon (looks like a bulls eye) in the left hand menu.  Drop down the bulls eye until you see the SimpleCocoaVTK target (the standard A icon made of pencil/pen/ruler).  Click SimpleCocoaVTK to select it and hit the info button (blue i icon in the top menu).  Click the Build tab and make sure that the configuration drop down says ‘All Configurations’ and the collection drop down says ‘All Settings’.
In the search box type ‘zerolink’.  The list will shorten to a manageable size and you will see zero link there.  Click the checkbox button until it is empty (not a checkmark or a negative sign, just empty). 
 
Close information and ‘clean all’ again. 
 
Now build. 
 
Fingers crossed, you should see the app build with no errors and begin to run.

Latest revision as of 19:04, 27 July 2015

As VTK is cross-platform, building on Mac OS X is much the same as on any other supported platform. This page only discusses some OS X-specific topics related to VTK 5.10 and later. For information on antique versions of VTK, refer to the version of this page in the history from 2013-07-21 or earlier.

Supported Versions

VTK 6.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.5 or later.

VTK 5.x supports Intel and PowerPC, 32 and 64 bit, and requires OS X 10.4 or later.

On OS X 10.5, you should use at least VTK 5.4.2. On OS X 10.6, at least VTK 5.6. On OS X 10.7 and later, VTK 6.x is recommended.

Windowing API

On OS X, there are two windowing APIs: Carbon and Cocoa. Older versions of VTK defaulted to Carbon, but newer versions default to Cocoa. Carbon support is deprecated by both Apple and VTK, and should not be used for new development. To choose, set one of the following to ON: 

VTK_USE_CARBON:BOOL=ON
VTK_USE_COCOA:BOOL=ON

Deployment Target and SDK

The 'deployment target' and 'SDK' are concepts that should be familiar to OS X developers. In brief, the 'deployment target' specifies the oldest version of OS X that you which to support at runtime; it should always be set. Ex: 

CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.7

The 'SDK' specifies which version of OS headers and libraries you want to build against. Usually, you want to built against the newest SDK, which is what CMake defaults to. But you can override it: 

CMAKE_OSX_SYSROOT:STRING=/path/to/SDK

Universal Binaries

VTK can be built as a universal binary, that is, as libraries that have executable code for several CPU types. Even if you want to build for only one CPU type, you should always specify them explicitly, ex: 

CMAKE_OSX_ARCHITECTURES:STRING=i386;x86_64

Possible values are: ppc, ppc64, i386, and x86_64.

Cocoa Memory Management Models

Cocoa has three memory management models, chronologically by date of introduction:

  • manual reference counting (MRC)
  • garbage collection (GC)
  • automatic reference counting (ARC)

VTK supports MRC and GC. MRC is the default. GC was deprecated by Apple in OS X 10.8, but to use it set: 

VTK_REQUIRED_OBJCXX_FLAGS:STRING=-fobjc-gc

ARC support will eventually be available, but if your host application is ARC you can build VTK as MRC and still link to it.

VTK_USE_SYSTEM options

VTK has several VTK_USE_SYSTEM_* options, allowing you to link against the OS's built-in versions of popular third party libraries. The advantage of doing so is that it reduces your compile time and binary size. Only a few are built-in to OS X, which you can make VTK use by setting: 

VTK_USE_SYSTEM_ZLIB:BOOL=ON
VTK_USE_SYSTEM_EXPAT=ON
VTK_USE_SYSTEM_LIBXML2=ON

Use Application Bundles

On OS X, there are (at least) two kinds of executables:

  • Application Bundles
  • plain UNIX executables

To be able to display a graphical interface (that is, display windows that allow mouse and keyboard interaction), OS X requires you to use an application bundle. If a plain UNIX executable tries, it will mostly work, but there will be various bugs, such as keyboard and mouse events not working properly. Many, but not all, of the VTK examples are built as plain UNIX executables, and thus have these problems. This is bug 2025. When you build your own VTK application, it is best to make it in the form of an application bundle. Simply add the following to your CMakeLists.txt file: 

IF(APPLE)
  SET(EXECUTABLE_FLAG MACOSX_BUNDLE)
ENDIF(APPLE)

If for some reason you cannot build as an application bundle, see bug 2025 for possible workarounds.

SimpleCocoaVTK

SimpleCocoaVTK is a sample Cocoa application written by Sean McBride and Mike Jackson that uses VTK. It illustrates how to use the VTK libraries within an Xcode-based OS X application. SimpleCocoaVTK is an example, it is not required to use VTK.

Originally standalone, SimpleCocoaVTK is now part of VTK itself in the Examples/GUI/Cocoa folder. See the documentation there for how to use it.


VTK: [Welcome | Site Map]
Retrieved from "https://public.kitware.com/Wiki/index.php?title=Cocoa_VTK&oldid=58088"