Distributing Mac Qt applications

From qtnode

There are usually two ways of distributing applications for MacOS X: Disk Images (dmg) or Package Installers ([m]pkg).

Which one you use usually depends what kind of program you'd like to distribute. Usually a self-contained *.app bundle should not need to install further files in system directories and therefor using a disk image is the most "mac-alike" way for application distribution, as the user just mounts it, drops your bundle into his Applications folder and umounts and deletes the disk image.

If you like to create such a self-contained application bundle for your Qt app, you usually suffer from the fact that your app is linked against absolute system paths as long as you haven't built your Qt statically and therefor isn't really self-contained. Now Trolltech has a page which explains these issues in detail (http://doc.trolltech.com/4.2/deployment-mac.html) and even provides a tool called deployqt to automate the task of putting the Qt binary libraries properly into your app bundle.

Note: Sometimes a Qt module is a runtime rather than compile-time dependency which may not be recognized by deployqt unless you explicitely name it in your project file. A good example is if you load an svg image into a QLabel through designer. You get no compiler errors or warnings if you forget to name the needed svg and xml modules in your project file, you just won't see the image. Now to ensure that deployqt copies it into your bundle and to ensure it is later actually shown on your user's Macs, add "QT += xml svg" and everything should be fine.

Creating a disk image

On Mac OS X the command line program `hdiutil` is used to generate disk images:

 hdiutil create -srcfolder SOURCE_FOLDER -format UDBZ -volname "YOUR_APPLICATION_NAME" "TARGET_PATH/NAME.dmg"

This will create the disk image NAME.dmg in TARGET_PATH based off the contents in SOURCE_FOLDER. The format string "UDBZ" means that bzip2 is used as compression algorithm, which is available from 10.4 and beyond. If you have to target Panther (10.3) as well, use "UDZ0" which stands for zlib and creates a slightly greater disk image.

If you've created the image, you can optionally "internet-enable" it. This means that as soon as a user double-clicks on the image, its contents get automatically extracted in the directory the image resides and afterwards the image is put into Trash. To enable this functionality, execute the following on the just created disk image:

 hdiutil internet-enable -yes "TARGET_PATH/NAME.dmg"

Further things to consider

The above commands only create a basic dmg with no fancinesses, however it is possible to copy additional files to the SOURCE_FOLDER before it gets packed into the final dmg. You could add for example a background image for the folder (.background/background.png), a the volume icon (.VolumeIcon.icns) or the directory layout itself (.DS_Store). This is useful to make it even easier for your users to install your application e.g. by giving them hints what to do ("drag an drop the application into your application folder"). I haven't researched how .DS_Store files could be created automatically, for now the usual way is to create such a file in a normal folder by moving icons into specific positions, adding a background image and copy the resulting .DS_Store into your final dmg.