CopperSpice Overview
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.

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 which are required for your application. Each type of plugin should be located within a specific subdirectory (such as imageformats or sqldrivers) within your distribution directory.

For more information about creating and deploying a plugin refer to the CopperSpice API. From the API main page look under the category of "Concepts" for the topic named "Plugins". Alternatively, use the following link.

Plugin Documentation

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 CopperSpice (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.