CopperSpice Overview  1.5.2
Deploying on Mac OS X

Mac applications are deployed as self contained bundles. The bundle contains the application executable as well as dependencies such as the libraries, plugins, translations, and other resources users may need. Third party libraries are normally not installed system wide.

The most common way to distribute an application bundle is to provide a compressed disk image (.dmg file) the user can mount in Finder. Refer to our sample project files for details about how to compile and link your application.

You can distribute your application from the Mac App Store. For information about this type of deployment, refer to Tools Workflow Guide

Another possibility is to use the Apple install wizard. You may need an Apple developer subscription to access this information Mac Dev Center

Additional Information


Application Bundle

Mac OS X GUI applications must be run from a bundle. A bundle is a directory structure that appears as a single entity when viewed in the Finder. A bundle for an application typically contains the executable and all the resources it needs. A Mac OS X application bundle is actually a directory, ending with .app.

For more information about bundles, refer to the following OS X Developer Library - Bundles

If you are writing a command line application, it is not advisable to use a bundle. Refer to the Deploying on Unix for information about how to deploy 'bundle-less' applications.

Accessing the Bundle Path

To find where the application bundle resides on the disk, use QCoreApplication::applicationDirPath() to determine the path of the binary within the bundle.

For more information about using the CFBundle API, refer to CF Bundle Reference


Create Application Bundle

To use the CopperSpice dynamic libraries in a Mac OS X application, the libraries must be embedded in the application bundle.

The preferred location for dynamic libraries is MyApp.app/Contents/Frameworks. Our sample Makefile will automatically create the "Contents/Frameworks" directory and copy the CopperSpice dynamic libraries into the bundle when you run 'make install'.

The hard coded path inside the dynamic libraries are initially invalid. The hard coded path was added to the CS dynamic libraries by the linker. For your application to find the bundled dynamic libraries they must have the correct 'install name'. This is done by changing the install name after your application has been linked. Our sample Makefile will automatically correct the install name.

Install Name

As an example, if your dynamic library is located in MyApp.app/Contents/Frameworks, the install name should be exactly as follows:

@executable_path/../Frameworks/libname.dylib

When the dynamic linker attempts to locate the dynamic library at runtime it will substitute the path of the current executable for @executable_path.

To change the install name, use the install_name_tool(1) on the command line.

For debugging or testing you can use the DYLD_LIBRARY_PATH environment variable to override the default path for dynamic libraries.

Refer to our sample project files for details about how to compile and link your application.

Plugins

While plugins can be anywhere in the bundle the preferred location is under Contents/Plugins.


Additional Library Dependencies

You can check which libraries your application is linking with by using the otool tool. To use otool, run the command as follows:

otool -L MyApp.app/Contents/MacOS/MyApp

Unlike the deployment processes on Deploying on Unix and Deploying on Windows, compiler specific libraries may not need to be redistributed with your application.

Mac OS X Version Dependencies

CopperSpice applications can be built and deployed on Mac OS 10.12 and higher.

For more information about cross development issues on Mac OS X, refer to: SDK Compatibility Guide

For more information about C++ runtime environment, refer to: C++ Runtime Environment Programming Guide

Plugin Dependencies

Your application may also depend on one or more plugins, such as the JPEG image format plugin or a SQL driver plugin. Be sure to distribute any plugins that you need with your application. Each type of plugin should be located within a specific subdirectory (such as imageformats or sqldrivers) within your distribution directory.

If you are deploying an application that uses WebKit, include all text codec plugins to support as many HTML encodings possible.

The following are the various alternatives to make sure that the plugins are found by your application.

  • Path Configuration This is the recommended approach since it provides the most flexibility.
  • Using QApplication::addLibraryPath() or QApplication::setLibraryPaths().
  • Using a third party installation utility or the target system's package manager to change the hard coded paths in the CsCore library.

The Creating Plugins document outlines the important issues when building and deploying plugins. For more information about deployment refer to Deploying Plugins.


Static Linking

Static builds are only partially supported and have not be fully tested. You can build the CS libraries statically, but some modules may fail to work properly. CsWebKit is known to fail if built statically.

To use this approach you must build and install a static version of the CopperSpice libraries.

Plugins can not be deployed using the static linking approach. You application will run, but some functionality will be disabled due to the missing plugins. If your application uses plugins you should use dynamic libraries.

Linking your Application Statically

Compile and link your application with the static CopperSpice libraries.

For information on the commands to build your application, refer to Compile & Link. When you run configure add the option as shown:

./configure --disable-shared

To check your application really links statically run otool. Verify the CopperSpice libraries are not mentioned in the output.

otool -L yourapp.app/Contents/MacOs/yourapp

Both static and no-framework builds require copying the src/gui/mac/qt_menu.nib directory into the application bundle. Our sample project Makefile has an example of this process. For information on the commands to build and deploy your application refer to CopperSpice Project Using Autotools.


Initialization Order

The command dyld(1) calls global static initializers in the order they are linked into your application. If a library links with CopperSpice and references globals in CS (from global initializers in your own library), be sure to link your application with CopperSpice before linking it with your library, otherwise the result will be undefined.

Compile Time Flags

The following flags are helpful when you want to define Mac OS X specific code.

  • Q_OS_DARWIN is defined when CopperSpice detects an Apple based system
  • Q_OS_IOS is definded when CopperSpice detects a Mobile Apple based system
  • QT_MAC_USE_COCOA is always defined in CopperSpice

If you want to define code for specific versions of Mac OS X use the availability macros defined in /usr/include/AvailabilityMacros.h. Refer to the QSysInfo class for information on runtime version checking.