Installer
The Plugin Installer is a shell application that you can use to create an installer tailored specifically at Mail plugins, but that allows you to customize the process to your needs.
- Provides a pre-built package to correctly install Mail plugins and other requirements that may be needed.
- Provides preference migration into the OS X sandbox if needed.
- Ensures that Mail has been launched at least once to ensure that all the directories and such are there.
- Provides for de-quarantining of installed items, so user doesn't get warnings about downloaded files.
- Simple configuration with a plist and a script to build the complete installer.
The Installer supports Lion, Mountain Lion & Mavericks.
A file package format has been defined (with an extension of mpinstall) that can be used to create a Mail Plugin specific installer that Mail Plugin Manager handles for you, very similar to Installer, but it is aware of the specific constraints of Mail Bundles and will install the Mail Plugin Manager as well, if desired.
A single plist manifest file (see below) defines what will be installed, you can have other components besides just the plugin, and where they should go. You can define Release Notes sections (using either an rtf file or html) and a license agreement as well. The user is presented with a view of what will be installed, so that we are not hiding anything from them. When necessary, it will prompt for required authorization.
Here are images of a dummy installation:
Similarly a file package format has been defined (with an extension of mpremove) for an uninstall, so the user can double-click something to start an uninstall. It has an almost identical feature set to the uninstall and uses the same format for the manifest file (see below). This allows you to provide a package which the user can double-click to uninstall the plugin as well.
There is the ability to trigger an uninstall directly from your plugin as well if you want to have a button in your prefs to uninstall.
The manifest file, which should be named mpm-manifest.plist is a plist file that contains a description of the items to install or uninstall. It also is used to describe to the user what is being installed.
There are several keys at the top level of the plist that are used to configure the installer window and define information about what we are doing.
manifest-type [install/uninstall] (String)
display-name Plugin Name (String)
background-image-path path/to/image_to_show_in_installer (String)
completion-message Text to show at completion. (String)
action-items (see below) (Array)
confirmation-steps (see below) (Array)
launch-items (see below) (Array)
Install specific (ignored during uninstall). These define the min and max versions of OS and min version of Mail supported. Pretty self-explanatory. The configure-mail-min-bundle-version key indicates the minimum bundle version value for configuring Mail. This key is required to have the installer configure Mail properly.
min-os-major-version 10.X.Y (String)
max-os-major-version 10.X.Y (String)
min-mail-version X.Y (Number)
configure-mail-min-bundle-version Min Mail Bundle Version (Number)
Uninstall specific (ignored during install). These are used to determine how the Mail Plugin Manager application can be deleted in different situations. These are only valid if the Manager is included in an uninstall manifest.
can-delete-bundle-manager-if-no-other-plugins-use (Boolean)
can-delete-bundle-manager-if-no-plugins-left (Boolean)
This is an array of dictionary objects that describe what is to be installed or uninstalled. The objects will not be installed in any particular order. Here are the keys and example values with a description of them afterward.
path Delivery/MyPlugin.mailbundle (String)
destination-path <LibraryDomain>/Mail/Bundles/ (String)
name My Bundle (String)
description A Bundle for Testing (String)
is-bundle-manager (Boolean)
should-delete-path-if-exists (Boolean)
should-hide-item (Boolean)
should-only-release-quarantine (Boolean)
user-can-choose-domain (Boolean)
The key path is the path where to find the original object to act upon.
- In the case of an install, this value should be a path relative to the package file or an absolute URL. For instance, in the example above there would be a folder called
Deliveryinside the.mpinstallpackage that would contain the mail bundle. If it is a full URL it will try to install directly from the web, but please remember that no access will mean a failure. Currently not yet implemented. - For an uninstall, this value should be a path to where the item to be deleted should be. This should be a full path or a path using a tilda (~).
The key destination-path is the path to where the item should be copied during an install. It is ignored during an uninstall. This is a full path, a path using a tilda (~), or a path beginning with the special marker <LibraryDomain>. The value <LibraryDomain> will be expanded to the Library folder in the domain the users selects to install to. Tildas will also be expanded.
The key name is the value used in display during the install/uninstall.
This key is optional, but strongly recommended
The key description is the value used in display during the install/uninstall during the Review step.
This key is optional
The key is-bundle-manager indicates that the item described is the Mail Plugin Manager application. This is a boolean flag that is used to facilitate the proper installation/removal of this item. Special handling is done to ensure the most recent version is available/installed and that it is not removed if another plugin is using it.
This key is optional
The key should-delete-path-if-exists indicates that the item described is an item that should be deleted from the user's system. This does not have any special display type and in general should be used with the should-hide-item below so it is not visible.
This key is optional
The key should-hide-itme indicates that the item described is should not be displayed to the user during an install.
This key is optional
The key should-only-release-quarantine indicates that the item should have the system quarantine flag removed so the user is not presented with a dialog asking them about the app, when it is run in the background. This will not display the item described.
This key is optional
The key user-can-choose-domain let's the user select the domain they want to install to. The default values is NO and the User Domain will be used. This is ignored during uninstall.
This key is optional.
Currently not implemented.
This is an array of dictionary objects with values describing each of the steps to display to the user, in the desired order, during the confirmation of the install/uninstall process.
Here are the keys and example values with a description of them afterward.
type [license|information|confirm] (String)
title (Name shown at top of page) (String)
bullet-title (Name of step in list at left) (String)
path /path/to/resource (String)
license-agreement-required (Boolean)
The key type defines one of three types of display steps, license and information are essentially the same and just display some content to the user, however the license type step will test to see if the user must agree to a license and, if so, present a proper alert to ensure that they agree. The confirm step shows the list of what will happen and show the Install/Remove button before doing the actions.
The key title is used at the top of the information display and is used as the default bullet title, if one of those is not present.
This key is required.
The key bullet-title is used in the step list on the left side of the window. If no value is provided the title value is used.
This key is optional, but recommended.
The key path is the path where to find the resource to display for either an information or license type. The path should be relative to the manifest file and should be either an RTF/RTFD file or an HTML file (with resources relative to that file. It is required for the license and information types.
The key license-agreement-required works in conjunction with the license type and is ignored in other cases. If set to YES, then the license will require the user to agree before continuing. The default is NO.
This key is optional.
These packages can be localized in the same way that applications or bundles can. If you put an .lproj folder for a language in the package, any text values that are pulled out of your manifest file will attempt to be localized from those localization folders.
Unfortunately this doesn't include the base of the project itself and thus all the parts around this that are not localized will come through in English. Hopefully we can get some localization done for the rest of the app.
Only used during an uninstall.
This is simply an array of strings that contain the key of LaunchAgents that should be removed. The item will be unloaded using launchctl, if it is running and the file for it will be deleted, if it can be found.