BundleUtilitiesExample

Overview

CMake 2.6.2 includes a new module called 'BundleUtilities'. This module is intended to make the task of creating a fully standalone OS X application bundle much easier than before. It still requires some setup on your part though. In this example we will walk through the necessary files and CMake code that are needed to use the 'BundleUtilities.cmake' effectively. Get the project here.

Basic Flow

The CMake code that we will generate will do a couple of things. It will configure a couple of template files to be run during the 'install' phase of the build. During the install phase of the build a cmake script is run, which in turn runs a base shell script to ensure all the necessary folders are created and any pre-existing application bundle is removed. At the completion of the shell script, cmake continues by calling the 'BundleUtilities' module which will complete the actual copying of libraries into the Application bundle. After copying the libraries, the cmake code will then adjust the 'install_name' property of the libraries and executable to finally make the application bundle stand-alone.

Additional Files

There are 2 additional files that are added to the project (They are already in the sample project linked above).

1. QtTest/Resources/OSX_Tools/CompleteBundle.cmake.in
2. QtTest/Resources/OSX_Tools/CreateBundle.sh.in

Additions to your CMakeLists.txt File

The first additional bit of code that we need will be placed in the CMakeLists.txt file just after the target_link_libraries(...) command.

# If we are build a "Debug" version then put that on the built Application
 SET (EXE_DEBUG_EXTENSION "_debug")
#-- Set the Debug and Release names for the libraries
 SET_TARGET_PROPERTIES(QtTest 
   PROPERTIES
   DEBUG_OUTPUT_NAME QtTest${EXE_DEBUG_EXTENSION}
   RELEASE_OUTPUT_NAME QtTest
)
 # --- If we are on OS X copy all the embedded libraries to the app bundle
IF (APPLE)
 # -------- Function to build OS X Stand Alone Bundles -----------------
 function(MakeOSXBundleApp target binary_dir)
   #-- Set some useful variables
   SET (OSX_MAKE_STANDALONE_BUNDLE_CMAKE_SCRIPT "${binary_dir}/${target}_OSX_MakeStandAloneBundle.cmake")
   SET (OSX_MAKE_STANDALONE_BUNDLE_BASH_SCRIPT "${binary_dir}/${target}_OSX_MakeStandAloneBundle.sh")
   #-- Configure the cmake file and the shell script
   CONFIGURE_FILE("${PROJECT_RESOURCES_DIR}/OSX_Tools/CompleteBundle.cmake.in"
     "${OSX_MAKE_STANDALONE_BUNDLE_CMAKE_SCRIPT}" @ONLY IMMEDIATE)
   CONFIGURE_FILE("${PROJECT_RESOURCES_DIR}/OSX_Tools/CreateBundle.sh.in"
     "${OSX_MAKE_STANDALONE_BUNDLE_BASH_SCRIPT}" @ONLY IMMEDIATE)
   #-- Create the installation code
   install(SCRIPT "${OSX_MAKE_STANDALONE_BUNDLE_CMAKE_SCRIPT}")               
 endfunction(MakeOSXBundleApp)
 IF(CMAKE_BUILD_TYPE MATCHES "Debug")
     MakeOSXBundleApp( "QtTest${EXE_DEBUG_EXTENSION}" ${PROJECT_BINARY_DIR})
 ELSE (CMAKE_BUILD_TYPE MATCHES "Debug")
     MakeOSXBundleApp(QtTest ${PROJECT_BINARY_DIR})
 ENDIF(CMAKE_BUILD_TYPE MATCHES "Debug")
ENDIF (APPLE)

1. This cmake code adds a '_debug' extension to the normal application name if we are building in debug mode.
2. It will then configure the cmake.in file and the sh.in file and place those new files in the project binary directory.
3. The code finally executes an 'install' command so that during a 'make install' phase the bundle creation code is actually executed

After all this is added to your project, rerun cmake on your project, build your project and finally try 'make install' or run the 'Installation' target from Xcode. You will see lots of text output during the installation phase indicating what is currently being performed. After all the libraries are copied and the install_name of each is corrected a verification phase will be performed to make sure the application bundle is properly created. Assuming the verification has passed you should now have a QtTest.app that you can place on another computer and successfully run.

Notes

This example does not cover the copying of any Qt Plugins or any other plugins. There is an additional argument to the 'BundleUtilities' module that can take care of the plugins.