Application Installation

A trouble-free installation goes a long way to reassure the user about your product before the application is even running. We'll deal with installation on Windows, Linux, and Mac OS X in turn. Information about where to get the third-party tools mentioned in this section is provided in Appendix E.

Installation on Windows

On Windows, an installer is pretty much necessary, both because users expect it and because of the way file associations and shortcuts need to be set up.

Because it's such a specialized area, wxWidgets doesn't attempt to provide an installation utility for your applications. Several installer creators are available, such as NSIS and InstallShield; a favorite with many developers is Inno Setup, a very capable, free installer that can be driven via a simple script or tailored using Pascal. Several third-party applications are listed on the Inno Setup web site for graphically creating a script that can be used to create an installer.

If you release your application frequently, you will probably want to automate the installer creation via a release script. In examples/chap20/install, we have provided example scripts for you to adapt for your own needs. Because they are Unix shell scripts, you will need MinGW's MSYS package, which is also supplied on the CD-ROM. Given a directory of files, makeinno.sh creates a portion of the Inno Setup script listing the subdirectories and files. It requires you to supply the hand-tailored top and bottom parts of the script specifying other details. You can invoke makeinno.sh with a command like this:

 sh makeinno.sh c:/temp/imagedir innotop.txt innobott.txt myapps.iss 

This will create the Inno Setup script myapp.iss from the files in c:/temp/imagedir.

You can adapt the release script makesetup.sh for building your own application's Windows installer. makesetup.sh copies required files into an "image" directory, which is used to build the installer script before invoking Inno Setup, creating the setup.exe file. This script uses variables specified in the file setup.var. You can add your own release functions, from building the application to copying files to your FTP site using the Curl utility.

When you distribute an application, don't forget to include a Windows XP "manifest" file with your application. The manifest is an XML file that tells Windows XP to apply theming to your application. You can include the manifest simply by including the wxWidgets standard resource file in your own .rc file:

 aardvarkpro ICON aardvarkpro.ico #include "wx/msw/wx.rc" 

This includes a standard manifest file. If you want to include your own instead, define the wxUSE_NO_MANIFEST symbol before including wx.rc, and specify your own, as follows:

 aardvarkpro ICON aardvarkpro.ico #define wxUSE_NO_MANIFEST 1 #include "wx/msw/wx.rc" 1 24 "aardvark.manifest" 

You may also simply include the manifest file alongside the application. For more information on the manifest syntax, see the file docs/msw/winxp.txt in your wxWidgets distribution.

Installation on Linux

On Linux, you can use a graphical installer, a custom shell script, or a distribution-specific package such as RPM for Red Hat-based distributions, or Debian packages for Debian distributions. You can also simply supply the distribution as a tarred, compressed archive (.tar.gz or .tar.bz2) with instructions on unarchiving into a suitable directory.

Tools for creating GUI installations for Linux include Loki Setup (free), Zero G's InstallAnywhere, and InstallShield.

A wxWidgets for GTK+ application is desktop-agnostic: there are no dependencies on either GNOME or KDE, so it can run under either desktop environment. Most KDE distributions also contain GTK+ libraries. However, because they use a different theming engine, GTK+ applications can look a little out of place on a KDE desktop, so consider recommending to your users that they install a Qt theming engine for GNOME such as GTK-Qt (but test it first with your application).

You may want to provide a desktop icon so the user can launch the application easily. To add an icon to the KDE desktop, you need to copy a suitable APP.desktop file to PREFIX/share/applications, where APP is the name of your application and PREFIX is typically /usr, /usr/local, or the value of the KDEDIR environment variable. Here's a sample desktop file for an application called Acme, assuming Acme was installed into /opt/Acme:

 [Desktop Entry] BinaryPattern=Acme; MimeType= Name=Acme Exec=/opt/Acme/acme Icon=/opt/Acme/acme32x32.png Type=Application Terminal=0 

To add an icon to the GNOME desktop, the file follows a similar syntax but should be copied to ~/.gnome-desktop (for a single user). For more information on desktop configuration specification for KDE and GNOME, see http://www.freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec.

Information about RPM, including a free online book, can be found at http://www.rpm.org, and instructions for creating Debian packages are at http://www.debian.org. Packaging your applications using these methods allows the system to resolve dependencies and makes it easier for the user to view and manage installed applications. For a tool that can help create RPM, .deb, and other package formats, you could try EPM.

A sample shell script installer for Linux, called installacme, is included in examples/chap20/install. It takes the user through installing the application and also creates a shell script called acme, which sets a location variable before running the actual executable. The advantage of this approach is that the application can be run without either adding a directory to the user's PATH variable or installing the actual application into an existing bin directory. In this scheme, all data files and the executable are kept in the same location, which makes it easy to uninstall the application. You may want to adapt the script to copy data files to standard Linux locations instead.

Also in examples/chap20/install is maketarball.sh, a release script that creates a distribution tarball, itself containing the installacme script and a further tarball of data files. You can alter maketarball.sh to suit your own needs.

Shared Library Issues on Linux

Because there is no standard GUI on Linux, added to the fact that there are many Linux distributions and versions of those distributions, you may find that on some systems, your application complains about missing libraries. There's a strong temptation to statically link everything with your application, but this can lead to problems, too. Although you shouldn't link GTK+ statically to your application, you can statically link wxWidgets by specifying --disable-shared when you configure wxWidgets. You can also consider bundling wxWidgets and/or GTK+ shared libraries with your application.

Compile on a Linux distribution that's not too old (very old versions of libraries won't be distributed with newer distributions) and not too new (the required libraries will be too new to appear on older distributions). Also consider prepending -lsupc++ to your linker flags so that the application statically links with some basic C++ library support without requiring the full shared library to be available, removing another potential complication. (However, be aware there are licensing issues to consider when statically linking GPL'ed code with your application.)

Ultimately, you may need to distribute different versions of your applications for different distributions. If you don't want to reboot every time you switch Linux versions, consider using a tool such as the excellent VMware that can run multiple virtual machines simultaneously.

Installation on Mac OS X

On Mac OS X, all you really need to do is make sure your bundle directory structure is correct and then make it into a suitable disk image, which we'll cover shortly. A Mac OS X application can be installed simply by dragging the folder to an appropriate location on the disk, with no "setup" application required.

We'll describe bundles briefly in the following, and you can find more information about them on the Apple web site at http://developer.apple.com/documentation/MacOSX/Conceptual/SystemOverview/Bundles/chapter_4_section_3.html.

A bundle consists of a standard hierarchy and an Info.plist file that describes key files and properties.

A minimal bundle hierarchy looks something like this:

 DialogBlocks.app/                     ; top-level directory     Contents/         Info.plist                    ; the property list file         MacOS/             DialogBlocks              ; the executable         Resources/             dialogblocks-app.icns     ; the app icon             dialogblocks-doc.icns     ; the document icon(s) 

Here's an example Info.plist file, for DialogBlocks:

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd"> <plist version="0.9"> <dict>       <key>CFBundleInfoDictionaryVersion</key>       <string>6.0</string>       <key>CFBundleIdentifier</key>       <string>uk.co.anthemion.dialogblocks</string>       <key>CFBundleDevelopmentRegion</key>       <string>English</string>       <key>CFBundleDocumentTypes</key>       <array>             <dict>                   <key>CFBundleTypeExtensions</key>                   <array>                         <string>pjd</string>                   </array>                   <key>CFBundleTypeIconFile</key>                   <string>dialogblocks-doc.icns</string>                   <key>CFBundleTypeName</key>                   <string>pjdfile</string>                   <key>CFBundleTypeRole</key>                   <string>Editor</string>             </dict>       </array>       <key>CFBundleExecutable</key>       <string>DialogBlocks</string>       <key>CFBundleIconFile</key>       <string>dialogblocks-app.icns</string>       <key>CFBundleName</key>       <string>DialogBlocks</string>       <key>CFBundlePackageType</key>       <string>APPL</string>       <key>CFBundleSignature</key>       <string>PJDA</string>       <key>CFBundleVersion</key>       <string>1.50</string>       <key>CFBundleShortVersionString</key>       <string>1.50</string>       <key>CFBundleGetInfoString</key>       <string>DialogBlocks version 1.50, (c) 2004 Anthemion Software Ltd.</string>       <key>CFBundleLongVersionString</key>       <string>DialogBlocks version 1.50, (c) 2004 Anthemion Software Ltd.</string>       <key>NSHumanReadableCopyright</key>       <string>Copyright 2004 Anthemion Software Ltd.</string>       <key>LSRequiresCarbon</key>         <true/>       <key>CSResourcesFileMapped</key>       <true/> </dict> </plist> 

The icons for the application and its document types are specified with the CFBundleIconFile and CFBundleTypeIconFile properties. As mentioned in Chapter 10, "Programming with Images," if you are working mainly on Windows or Linux, you might like to create a number of different icons in 16x6, 32x32, 48x48, and 128x128 resolutions. Save them as transparent PNGs, copy them to the Mac, and then open each file with the Finder and copy and paste them into the appropriate locations in Apple's icon editor before saving as an icns file.

The maketarball.sh release script mentioned in the previous section for Linux can also create a Mac OS X disk image, such as AcmeApp-1.50.dmg. It copies a pre-existing AcmeApp.app bundle hierarchy to the release directory, copies the Mac OS X binary and data files into the bundle, and then creates an Internet-enabled disk image with the following code:

[View full width]
 echo Making a disk image... hdiutil create AcmeApp-$VERSION.dmg -volname AcmeApp-$VERSION -type UDIF -megabytes 50 -fs  HFS+ echo Mounting the disk image... MYDEV=`hdiutil attach AcmeApp-$VERSION.dmg | tail -n 1 | awk '{print $1'}` echo Device is $MYDEV echo Copying AcmeApp to the disk image... ditto --rsrc AcmeApp-$VERSION /Volumes/AcmeApp-$VERSION/AcmeApp-$VERSION echo Unmounting the disk image... hdiutil detach $MYDEV echo Compressing the disk image... hdiutil convert AcmeApp-$VERSION.dmg -format UDZO -o AcmeApp-$VERSION-compressed.dmg echo Internet enabling the disk image... hdiutil internet-enable AcmeApp-$VERSION-compressed.dmg echo Renaming compressed image... rm -f AcmeApp-$VERSION.dmg mv AcmeApp-$VERSION-compressed.dmg AcmeApp-$VERSION.dmg 

The disk image file can then be copied to your FTP site or CD-ROM. When the Mac OS X user clicks on the file from within a web browser, the file will be downloaded, uninstalled, and mounted as a virtual disk without further user intervention. It then remains for the user to drag the application folder to an appropriate disk location to complete the installation.