Tuesday 29 January 2013

Inside Distribution.dist file

Inside Packagemaker Distribution.dist file

So now, you must be familiar with component and distribution packages. This post will cover everything about the ‘Distribution’ file contained inside every distribution package. This file has all the information about the behavior of the package (both visually and in terms of workflow). You can mention the background, License, Read Me files along with Installation-Check and Volume-Check. You can find the list of all the attributes which you can use inside Distribution file at DistributionDefinitionReference.

Below is an example of a valid distribution file: (Comments are provided inline)
-----------------------------------------------------------------------------------------------------------------------------------------------
<?xml version="1.0" ?>
<installer-script authoringTool="" authoringToolBuild="" authoringToolVersion="" minSpecVersion="1.000000">
<title>My Distribution Package</title>
<options allow-external-scripts="no" customize="allow"/>
<domains enable_localSystem="true"/>
<installation-check script="CustomInstallationCheck();"/>

<script>
<!-- You can write your custom Javascript functions here. -->
function CheckIfLeopardOrHigher()
{
        <!-- An example function to check if system version is 10.6 or higher -->
        retVal = true;
        SnowLeopardOrHigher = system.compareVersions(my.target.systemVersion.ProductVersion, '10.6');
        system.log("10.6 or higher:" + SnowLeopardOrHigher);
        if(SnowLeopardOrHigher < 0)
        {
               retVal = false;
        }
        return retVal;
}

function CustomInstallationCheck()
{
        <!-- An example function to show a typical installation check function -->
        if(!(system.compareVersions(system.version.ProductVersion, '10.5') >= 0))
        {
                <!-- Allow installation only on 10.5 or higher -->
                my.result.title = system.localizedString('ERROR_SYSTEM_VERSION_TITLE');
                my.result.message = system.localizedString('ERROR_SYSTEM_VERSION_MSG');
                my.result.type = 'Fatal';
                return false;
         }

         if(!(system.sysctl('hw.cputype') == '7'))
        {
                <!-- Allow installation only on Intel machines -->
                my.result.title = system.localizedString('ERROR_HW_MACHINE_TITLE');
                my.result.message = system.localizedString('ERROR_HW_MACHINE_MSG'); 
                my.result.type = 'Fatal';
                return false;
        }
        return true;
}
 </script>

<background   alignment="center"   file="background"   scaling="tofit"/>
<readme   file="ReadMe"/>

<choices-outline>
<line   choice="choice1"/>
<line   choice="choice2"/>
<line   choice="choice3"/>
</choices-outline>

<choice   id="choice1"   start_visible="false"   title="Component 1">
        <pkg-ref   id="com.vikrams.comp1" />
</choice>

<choice   id="choice2" start_visible="false" title="Component 2">
        <pkg-ref   id="com.vikrams.comp2" />
</choice>

<choice   id="choice3"  description="APPLICATION_DESCRIPTION_MSG"  start_enabled="false"   title="Component 3"   visible="!CheckIfLeopardOrHigher()">
<!-- This choice will not be visible on 10.5. Also, it will be disabled by default. See the above line. -->
        <pkg-ref    id="com.vikrams.comp3" />
</choice>

<pkg-ref   auth="Root"   id="com.vikrams.comp1"   installKBytes="102400"   version="1.0.0">#Component1.pkg</pkg-ref>

<pkg-ref   auth="Root"   id="com.vikrams.comp2"   installKBytes="234000"   version="1.0.0">#Component2.pkg</pkg-ref>

<pkg-ref   auth="Root"   id="com.vikrams.comp3"   installKBytes="540564"   version="1.0.0">#Component3.pkg</pkg-ref>

</installer-script>
-----------------------------------------------------------------------------------------------------------------------------------------------

Monday 28 January 2013

XML Attributes of Packagemaker Distribution.dist file

XML Attributes of Packagemaker Distribution.dist file

A distribution definition file defines the installation experience for the installer package that contains it. This document describes the XML schema used for distribution definition files. An installer package can contain only one distribution definition file, which must be named distribution.dist.


allowed-os-versions

Defines OS version requirements. These consist of one or more version ranges, specified as os-version elements. The version of the operating systemon the target volume must fall into one of these ranges to allow installation.

Attributes

None

Availability

None

Content

This element can contain the following element:



app

Identifies an application that must be closed before the package is installed.

Attributes

Attribute Name Type Description
id String Required. The bundle identifier of the application.

Content

None.



auxinfo

Reserved



background

Defines a background image for the Installer.

Attributes

Requirements: You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.
Attribute Name Type Description
alignment String Optional. The alignment used to render the background image. Values: center (default), left, right, top, bottom, topleft, topright, bottomleft, and bottomright. Only used by the Installer.
file String Required. The filename of an image in the distribution package—for example, background.png or ./background.png.
mime-type String The standard MIME type of the image.
scaling String Optional. The scaling used to render the background image. Values: tofit (default), none, and proportional.
uti String The UTI type of the image. This attribute is provided because some file types don’t have a MIME type.

Content

None.



bundle

Defines a single bundle. The meaning of this element differs considerably depending on its parent element; see the parent element’s documentation for details.

Attributes

Attribute Name Type Description
CFBundleShortVersion-String String Optional. The short version string of the bundle, as defined in its Info.plist file.
CFBundleVersion String Optional. The bundle’s version, as defined in its Info.plist file.
id String Required. The identifier of the bundle—that is, the value of CFBundleIdentifier in the bundle’s Info.plist file.
path String Required. The path atwhich the bundle is installed, relative to where the package is installed. For example, Applications/Sample.app.
search Boolean Optional. Indicates whether to search for the bundle by its identifier if it is not found at the given path. Values: false (default), true.
BuildVersion - Reserved
SourceVersion - Reserved

Content

None



bundle-version

Defines the version of the bundles delivered by the parent element. You do not typically specify this element; productbuild inserts it from the actual package data when the product archive is created.

Attributes

None.

Availability

Available in Mac OS X v10.6.6 and later.

Content

This element can contain the following elements:
  • "bundle": The package-relative path and version strings of the bundles installed.



choice

Defines an installation choice of a distribution package.

Attributes

Attribute Name Type Description
customLocation Absolute file path Optional. Specifies the default installation location, within the installation volume, for this choice. Implies that the user can choose a different installation location. If unspecified, the user cannot choose the installation location for this choice.
customLocationAllow-AlternateVolumes Boolean Optional if customLocation is specified; otherwise, not allowed. Specifies whether the user can choose the installation volume. Values: false (default) indicates that the user can choose a different location than what is given by customLocation but cannot change the volume; true indicates that the user can choose the installation volume and the location on that volume. A value of true is only valid for packages that use the Installer.
description String,localization key Required for packages that use the Installer; otherwise, optional. Specifies the description of the installation choice. Localizable.
description-mime-type String Optional. The MIME type of the text data in the description attribute. Values: text/plain (default), text/rtf, or text/html.
enabled Boolean JavaScript expression Optional. Specifies whether the user can select or deselect this option in the Installer customization pane. If false, or a JavaScript expression that evaluates to false, the choice is dimmed so the user cannot select or deselect it. Re-evaluated as the user interacts with the choice tree, so a choice can be enabled or disabled based on the state of other choices. Default value is true.
id String Required. Unique identifier of the installation choice, used to bind this element to the line element that determines its position in the installation-choice hierarchy. Mustmatch the choice attribute of exactly one line element.
selected Boolean JavaScript expression Optional. Specifies whether this option is selected or deselected for installation. If false, or a JavaScript expression that evaluates to false, the choice will not be installed. In general, you should not declare this attribute on a choice that is visible and enabled, because it can interfere with the user’s selections. Default value is true.
start_enabled Boolean Optional. Specifies whether this option is initially enabled in the Installer customization pane. Values: true (default), or false.
start_selected Boolean Optional. Specifies whether this option is initially selected or deselected for installation. Values: true (default), or false.
start_visible Boolean Optional. Specifies whether this option is initially visible in the Installer customization pane. Values: true (default), or false.
title String,localization key Required. Specifies the title of the installation choice. Localizable.
visible Boolean JavaScript expression Optional. Specifies whether this option is visible in the Installer customization pane. If false, or a JavaScript expression that evaluates to false, the choice is hidden from the user. Default value is true. Avoid making choices appear and disappear while the user is interacting with the installation process. This provides a poor user experience.
bundle - Reserved
customLocationIs-SelfContained - Reserved
tooltip - Reserved
versStr - Reserved

Content

This element can contain the following element:
  • "pkg-ref": The choice’s packages. You should only associate packages with a choice that has no subchoices (as defined by the hierarchy of line elements)



choices-outline

Defines the installation-choice hierarchy of a distribution package.

Attributes

Attribute Name Type Description
ui - Reserved.

Content

This element can contain the following element:
  • "line"
: The top-level installation choices.


conclusion

Specifies text that is displayed by Installer at the end of the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.
Attribute Name Type Description
file String Required. The filename of the conclusion file in the distribution package—for example, conclusion.rtf.
mime-type String The MIME-type specifier for the data contained in the file.
uti String The UTI-type specifier for the data contained in the file.
language - Reserved

Content

None.



domains

Indicates what domains the package may be installed into. If this element is not present, enable_anywhere is true, enable_currentUserHome is false, and enable_localSystem is true.

Attributes

Attribute Name Type Description
enable_anywhere Boolean JavaScript expression Required. If true, or a JavaScript expression that evaluates to true, the product can be installed at the root of any volume, including nonsystem volumes. Otherwise, it cannot be installed at the root of a volume.
enable_currentUserHome Boolean JavaScript expression Required. If true, or a JavaScript expression that evaluates to true, the product can be installed into the current user’s home directory. Otherwise, it cannot be installed in the current user’s home directory. A home directory installation is done as the current user (not as root), and it cannot write outside of the home directory. You should enable this only if the product can be installed in the user’s home directory and be completely functional from that location.
enable_localSystem Boolean JavaScript expression Required. If true, or a JavaScript expression that evaluates to true, the product can be installed into the root directory. This attribute should usually be true unless the product can be installed only to the user’s home directory.

Content

None.



installation-check

Specifies whether the installation host meets the distribution’s system requirements. The installation check passes if the script returns true, any RAM requirements are met, and any graphics requirements are met.

Attributes

Attribute Name Type Description
script Boolean JavaScript expression Optional. Specifies whether the requirements are met. If true (default), or a Boolean JavaScript expression that evaluates to true, the installation proceeds, subject to the other checks. If the script evaluates to false, it must also set my.result.type and my.result.message to indicate the severity of the problem and provide a message to display. If my.result.type is Warning, the installation may be allowed to proceed after informing the user.

Content

This element can contain the following elements:



installer-gui-script

The root element of the distribution definition. All other elements in the distribution definition file are children of this element.

Attributes

Attribute Name Type Description
minSpecVersion Integer Required. The schema version of a distribution file. Use 1 for the version used prior to Mac OS X v10.6.6, or 2 after that.
maxSpecVersion - Reserved.
verifiedSpecVersion - Reserved.

Content

This element can contain the following elements:



license

Specifies text that is displayed by Installer during the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.
Attribute Name Type Description
file String Required. The filename of the welcome file in the distribution package—for example, welcome.rtf.
mime-type String The MIME-type specifier for the data contained in the file.
uti String The UTI-type specifier for the data contained in the file.
auto - Reserved
auto - Reserved
sla - Reserved

Content

None.



line

Defines where a choice fits into the installation-choice hierarchy of a distribution package.

Attributes

Attribute Name Type Description
choice String Required. Identifies the installation choice associated with this node of the installation-choice hierarchy of a distribution package. The valuemust match the ID of a choice element. See “choice”. Do not reference the same ID from more than one line element, not even from different installation-choice hierarchies; if you do so, the behavior is undefined.

Content

This element can contain the following element:
  • "line": The subchoices of this choice.



localization

Reserved.



locator

Defines a search rule for finding software that is already installed on the system.

Attributes

None.

Content

This element can contain the following element:



must-close

Identifies applications that must be closed before the package is installed. Applications are considered only if the package that contains this element has been selected for installation.

Attributes

None.

Content

This element can contain the following element:
  • "app": The applications.



options

Specifies the installation properties of a package within the distribution.

Attributes

Attribute Name Type Description
allow-external-scripts Boolean Optional. Specifies whether the run and runOnce JavaScript functions can be executed. Values: false (default) or true. For information about these functions, see “System” in Installer JavaScript Reference .
customize String Optional. Specifies whether the user can customize the installation by selecting or deselecting installation choices. Values: allow (default) gives the user an opportunity to customize the installation, always presents the customization view automatically. never does not provide access to the customization view.
hostArchitectures String Optional. A comma-separated list of supported architecture codes. Valid codes are i386, x86_64, and ppc. Note that i386 matches both 32-bit and 64-bit systems, but x86_64 matches only 64-bit systems.
mpkg String Optional. Identifies a package (pkg-ref element) whose installation operations must be performed as part of the installation of this distribution. Deprecated.
require-scripts Boolean Optional. Indicates whether the distribution uses JavaScript code. Values: true (default) or false. If this value is false, all attributes whose value may be a JavaScript expression must be set to either true or false. Available in Mac OS X v10.6.6 and later.
rootVolumeOnly Boolean Optional. Specifies whether the user can choose an installation volume other than the boot volume. Values: true or false. Deprecated. Use domains instead.
type - Reserved
visibleOnlyForPredicate - Reserved

Content

None.



os-version

Defines a range of supported OS versions. This element is designed for you to use a specific OS version number for the min attribute, and a major OS version number for the before attribute. The expectation is that you will know an exact minimum version but not an exact major version. This keeps you from having to guess the last minor revision before the next major revision, as you would have to do if the before attribute were inclusive.

Attributes

Attribute Name Type Description
before String Optional. The maximum allowed version (exclusive). If the OS version is greater than or equal to this version, installation will be disallowed (unless the OS falls in the range of another os-version element). If no value is given, there is no upper bound on the range—any version newer than the minimum is allowed.
min String Required. The minimum allowed version (inclusive). If the OS is less than this version, installation will be disallowed (unless the OS falls in the range of another os-version element).

Content

None.



pkg-ref

References a component package that can be installed.

Attributes

Attribute Name Type Description
active Boolean Javascript expression Optional. Indicates whether the package is installed. Values: true (default), false. If false, or a JavaScript expression that evaluates to false, the package is not installed, even if its associated choice was selected. This provides an additional way to activate and deactivate packages. It overrides the setting on the parent element.
auth String Defines the authorization level needed to install this package. Values: none or root. Deprecated. The installation domain determines the necessary authorization level.
id String Required. Uniquely identifies a component packagewithin a distribution package—for example, com.apple.Text- Edit.pkg. The value of this attribute is usually the same as the component package’s identifier, but it is not required to be the same. If there are multiple pkg-ref elements with the same ID, their attributes will be collapsed together as if they were specified with a single element. In particular, a pkg-ref element with only an ID can be used inside of a choice element to bind that choice to a pkg-ref that is more fully defined elsewhere in the distribution file.
installKBytes Integer Optional. Specifies the size of the package’s payload in kilobytes. You typically omit this attribute because productbuild sets it from the actual package when the product archive is created.
onConclusion String Optional. Specifies the action to take after the installation has finished. Values, fromlowest to highest: None (default), RequireLogout, RequireRestart, or RequireShutdown. The Installer takes the highest value from all enabled packages and requires the associated action
onConclusionScript String Optional. A JavaScript expression that evaluates to one of the string values expected for onConclusion. If this attribute is present, any onConclusion attribute is ignored. Available in Mac OS X v10.7 and later.
version String Required. Specifies the version of the package’s payload. You typically omit this attribute because productbuild will set it from the actual package when the product archive is created.
archiveKBytes - Reserved
packageIdentifier - Reserved

Content

Required. A URL specifying the location of the installation package to which this element refers. Typically, you specify a simple filename and productbuild adjusts the URL as needed when the product archive is created. If you define multiple pkg-ref elements with the same ID, exactly one of them should have text content. This element can contain the following elements:
  • "must-close": (zero or one) :The application(s) to be closed before installing this package.
  • "bundle-version":(zero or one): The bundle version.
  • "relocate": (zero or more): The information to support relocatable bundles.
To provide a must-close element, add a separate pkg-ref element with the same ID to contain the must-close element. For example:
&ltpkg-ref id="abc"&gtx.pkg&lt/pkg-ref&gt
&ltpkg-ref id="abc"&gt
&ltmust-close&gt
&ltapp id="com.example.MyApp"/&gt
&lt/must-close&gt
&lt/pkg-ref&gt



ram

Specifies the minimum amount of RAM that the system must have.

Attributes

Attribute Name Type Description
min-gb String Required. The minimum required RAM in gigabytes. (Consistent with how sizes are displayed in Mac OS X v10.6 and later, a gigabyte is defined as 109 bytes, not 230 bytes.)

Availability

Available in Mac OS X v10.6.6 and later.

Content

None.



readme

Specifies text that is displayed by Installer during the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.
Attribute Name Type Description
file String Required. The filename of the readme file in the distribution package. For example, readme.rtf.
mime-type String The MIME-type specifier for the data contained in the file.
uti String The UTI-type specifier for the data contained in the file.
language - Reserved.

Content

None.



relocate

Describes a relocatable bundle. Relocatable bundles allow the user to install an upgrade in the same path as the current version. The path is located by the search element whose ID is specified by the search-id attribute. The bundle is specified by the child bundle element. For example, application bundles are typically relocatable.

Attributes

Attribute Name Type Description
search-id String Required. Specifies the ID of the search element whose results are applied to the bundle that is this element’s child element. If the search returns false, the relocate does nothing. If the search returns an array of results, the first result is used.

Content

This element can contain the following element:
  • "bundle"(exactly one): The bundle (within the package) that will be installed at the path. The only required attribute for this bundle element is its ID.



required-bundles

Specifies bundles that must be already installed on the system. If the child bundle element has a version specified, this is interpreted as the minimum supported version for that bundle. It may also have its search attribute set to true, indicating that the bundle should be located by its identifier if it doesn’t exist at the specified path.

Attributes

Attribute Name Type Description
all Boolean Optional. Values: true (default) to require all of the specified bundles, or false to require at least one of them.
description String, localization key Optional. A description of the required bundles, displayed to the user if the requirement is not met.

Content

This element can contain the following element:



required-cl-device

Specifies requirements that must be met by at least one OpenCL device.

Attributes

None.

Availability

Available in Mac OS X v10.7 and later.

Content

The predicate, as a string. For details about the predicate format, see the productbuild(1) man page. To prevent characters in the predicate from being interpreted by the XML parser, mark it as CDATA content.



required-gl-renderer

Specifies requirements that must be met by at least one OpenGL hardware renderer.

Attributes

None.

Availability

Available in Mac OS X v10.6.8 and later.

Content

The predicate, as a string. For details about the predicate format, see Specifying required OpenGL capabilities for the Mac App Store and the productbuild man page. To prevent characters in the predicate from being interpreted by the XML parser, mark it as CDATA content.



required-graphics

Specifies GPU requirements.

Attributes

Attribute Name Type Description
description String,localization key Optional. A description of the graphics requirement. Localizable. If no description is specified, a generic message is used. It is generally best to use the generic message unless the requirements are very straightforward.
single-device Boolean Optional. Values: false (default) to allow the OpenCL and OpenGL requirements to bemet by different devices, or true to require a single device to simultaneously meet both requirements.

Content

This element can contain the following elements:



script

Defines a set of JavaScript functions.

Attributes

Attribute Name Type Description
language - Reserved.

Content

JavaScript code, typically the definition of functions called from attributes of other elements. To prevent characters in the script from being interpreted by the XML parser, mark it as CDATA content:
&ltscript&gt
&lt![CDATA[
// ... JavaScript ...
]]&gt
&lt/script&gt

If you choose not to mark your script as CDATA content, you must take great care to properly escape all characters that have special meaning in XML markup.



Defines a search rule for finding installed software. The result should be used by another search rule or bound to a bundle via a relocate element.

Attributes

Attribute Name Type Description
id String Required. Uniquely identifies the search; used in the search-id attribute of other elements to reference this search.
script String Required if type is script; otherwise, not allowed. A JavaScript expression that evaluates to false, a path as a string, or an array of paths. If it returns an array of paths, the first one is the preferred path. This expression can be a function call, but the called function must be defined in the child script element.
search-id String Optional if type is component; otherwise, not allowed. The ID of another search. The other search is performed, and its results further filtered by removing those results that don’t match the version strings given by the child bundle element. This allows the other search to be qualified for certain values of CFBundleShortVersionStrings or CFBundleVersions.
search-path String Optional if type is component; otherwise, not allowed. A path to a bundle. If there is a bundle at this path that matches the version string of this element’s child bundle element, then the path is used as the search result.
type String Required. Indicates the type of the search. Valid values are: component Search for a bundle on disk that matches the identifier and version strings given by the child bundle element. By default, the Installer uses Launches Services to perform the search, and it searches only the volume that the user selected as the installation target. The search-id and search-path attributes modify this behavior. script Search by evaluating the JavaScript code contained in the script attribute.

Content

This element must contain exactly one of the following elements:
  • "bundle": The bundle for a component search.
  • "script": The script for a script search.



strings

Reserved.



tag

Reserved.



tags

Reserved.



title

Defines the title of the product.

Attributes

None.

Content

The title or a localization key used to look up the title.



volume-check

Specifies whether a particular volume meets the distribution’s volume requirements. All of the tests in the script attribute and the child elements must pass.

Attributes

Attribute Name Type Description
script Boolean Javascript espression Required. Specifies whether the requirements for installing on a particular volume are met. If the script evaluates to false, itmust also set my.result.type and my.result.message to indicate the severity of the problem and provide a message to display. The property my.target.mountpoint contains themount point of the volume being checked.

Content

This element can contain the following elements:



welcome

Specifies text that is displayed by Installer at the beginning of the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.
Attribute Name Type Description
file String Required. The filename of the welcome file in the distribution package—for example, welcome.rtf.
mime-type String The MIME-type specifier for the data contained in the file.
uti String The UTI-type specifier for the data contained in the file.
language - Reserved

Content

None.


-------------------------------------------------------------------------------------------------------------
Disclaimer: This reference is a copy of Distribution Definition Reference published by Apple.