PATH Contents > Customizing a package settings and scripts
Customizing a package settings and scripts

The package Settings tab lets you change settings related to authentication requirements, relative location of a package to its distribution and installation behaviors.

Package Settings

To access the Settings tab of a package of a distribution project:

1Select the package in the source list
2Click the Settings tab.

To access the Settings tab of a raw package project:

Click the Settings tab.

To access the Scripts tab of a package of a distribution project:

1Select the package in the source list
2Click the Scripts tab.

To access the Scripts tab of a raw package project:

Click the Scripts tab.


Renaming a package

The name of the package defines the name that will be used for the package on disk or in the flat distribution archive. This is also the name that will displayed in the customized mode of the Installation Type step if no localized names are defined.

Package Name

Notes and recommendations:
  • When you work on a raw package project, the name of the package is defined by the name of the project. See Configuring a project for more information.

  • You can not rename an imported package.

  • A package name can not contain spaces and can not be empty. If there is any space in the name of a package, they will be replaced by the '_' character.

  • There is no need to append the .pkg extension to the name of a package.

  • 2 packages can not share the same name within a distribution.

  • It's a good idea to use a name that means something as this is a name that will be displayed during the installation process of Installer.

To change the name of a package:

1Select the package in the source list of the project.
2Click the name of the package.
3Type the new name of the package.
4Validate with Return.


Changing the identifier and version of a package

The identifier of a package is a string that is used to uniquely identify the package.

The version of a package is a version string. It is the version of the package, not of the applications or components inside the package.

Together, the identifier and version are used by the Installer database to check if a previous version or a newer version of a package has already been installed.

Package Tag

Notes and naming convention:
  • You can not change the identifier and version of an imported package.

  • It is better to respect the Universal Type Identifier (UTI) naming convention for the identifier (e.g. com.mycompany.and.so.on).

  • An identifier can not contain a space character.

  • If the settings of a package did not change but the version of a component inside this package payload did change, there's no need to change the package version.

When you create a new package, default values are set for the identifier and version. The identifier string is built from the default package identifier prefix and the name of the package. The default version is set to 1.0.

To change the identifier:

Type the new identifier in the Identifier text field.

To change the version:

Type the new version in the Version text field.

The default package identifier prefix is created the first time you use Packages. Packages will look for your email address in Address Book and, if it does not look to be an address from a well known ISP or mail service, the identifier prefix will be built from the domain name of your email address. If Packages is unable to create the identifier prefix from your email address, a generic identifier prefix will be set.

To change the default package identifier prefix:

1Choose Packages > Preferences…
2Click the Templates button.
3Select the row for the Default Package Identifier Prefix key.
4Click in the Value column of this row.
5Type the new identifier prefix.
6Validate with Return.

During your tests, you may need to make the Installer database forget that a previous version of your package has been installed. To achieve this:

1Open the Terminal application.
2Type the following command:

$ sudo pkgutil --forget your.package.identifier

3Validate with Return and type your admin password.


Changing the post installation behavior of a package

The post installation behavior determines the behavior of the installer once the installation is completed and successful.

Post Installation Behaviors

Here is a list of available behaviors:

NameBehavior
Do NothingUpon a successful installation, you can just quit Installer. This is the default behavior.
Require RestartUpon a successful installation, Installer will invite you to restart your Mac. You can run other installations but can not quit Installer.
Require ShutdownUpon a successful installation, Installer will invite you to shut down your Mac. You can run other installations but can not quit Installer.
Require LogoutUpon a successful installation, Installer will invite you to log out. You can run other installations but can not quit Installer.

Notes:
  • You can not change the post installation behavior of an imported package.

  • If packages within a distribution have different post installation behaviors, the toughest one will be applied.

To change the post installation behavior:

Choose the behavior from the On Success popup button.


Changing the location of a distribution package

By default, when you create a package for a distribution, it will be embedded in the distribution bundle or file. You may wish to put a package outside of the distribution so that you can replace it with a newer version without having to rebuild the entire distribution. If you're distributing your application on a DVD, maybe there is not enough space on one DVD to contain your entire distribution and you need to split it on 2 DVDs.

Location Type

Packages lets you decide what the location of a raw package should be. Here is the list of the possible type of locations:

NameDescription
Embedded (1)The package will be embedded inside the distribution bundle or file.
Custom Path (1)The package will be put at the absolute or relative path you choose.
HTTP URLThe package will be hosted on a web server at the URL you choose.
Removable MediaThe package will be put on a removable media such as a CD or DVD at the path you choose.
(1) The location type of a referenced package can only be HTTP URL or Removable Media.

To change the location type of a package:

1Choose the location type from the Type popup button.
2If needed, type the URL where the package is expected to be found.

Notes:
  • If you choose the HTTP URL or Removable Media location types for packages that are not referenced packages, after the build phase, you can find these packages in a "http" or "x-disc" folder inside the build folder.

  • If you need to specify a path for a location type, this is the path of the folder that will contain the package, not the path of the package itself.

  • If you choose the Custom Path location type and you specify an absolute path or relative path other than ./ or ../, the package will be put in a "packages" folder inside the build folder.


Changing the options of a package

A few options are available to change the default behavior of the installation process for the package.

Package Options

Here is what these options do:

NameDescription
Require admin password for installationOnly a user with administrative privileges can install the package. An administrator password will be requested during the installation process. If you install anything in /Applications or /Library, this option should be enabled.
Relocatable (1)For a raw package, this option means that the user can change the default destination for the payload.
Overwrite directory permissions (1)If a directory from the package payload already exists on disk, when this option is enabled, the permissions of the directory on disk will be changed to match those of the directory in the payload.
Follow symbolic links (1)If a symbolic link is encountered during the installation of the package payload, the link will be resolved instead of being replaced by a real file or folder.
(1) These options are not supported by referenced packages.

Notes:
  • You can not change the options of an imported package.

  • If the value of the Require admin password for installation option is not the same for all the packages of a distribution, the most restrictive one will be used.


To enable or disable an option:

Click the checkbox of the option you want to enable or disable.


Defining a package pre- and post-installation scripts

When a package is to be installed, it is possible to run a script before the installation is performed and a script after the installation is completed. The "script" can either be a shell (or python or perl) script or a binary. You can call secondary scripts or binaries from these scripts.

Package Pre- and Post-Installation Scripts

To set a pre- or post-installation script:

1Click the appropriate Set… button.
2Select the script you want to use.
3Click Set.

To remove a pre- or post-installation script:

1Click the appropriate Remove… button.
2Click Remove.

Notes:
  • If you use a binary, make sure that it's a Universal binary (PowerPC and Intel).

  • I would not recommend using an AppleScript script for a pre- or post-installation script. This can work but the result can be unexpected in some cases.

  • If the installation process requests an admin password, the pre- and post-installation scripts will be run as root.

  • If a pre- or post-installation script return a non-zero value, the installation will fail.

Here are some environment variables that are available to the pre- and post-installation scripts and that may be of some interest:

NameDescription
INSTALL_PKG_SESSION_IDThe identifier of the package being installed.
USERThe account name of the current login user.
HOMEThe home folder of the current login user.
COMMAND_LINE_INSTALLWhen this variable is set, the installation is being performed by the installer tool.
DSTVOLUMEThe absolute path to the volume chosen as the target of the installation. (Mac OS X 10.6 only)
DSTROOTThe absolute path to the folder where the package payload will be installed. (Mac OS X 10.6 only)

If you need to use additional resources such as secondary scripts or binaries, you can add them to the Additional Resources hierarchy.

Package Additional Resources

The Additional Resources hierarchy looks like the "View as List" mode of the Finder and it works the same way. You can add items, arrange them, rename some of them, etc.

The hierarchy can contain the following 2 types of items:

TypeDescription
File system itemA reference to a real file or folder on disk.

A file system item can be moved and removed. It can not be renamed.

Custom folderA folder that does not exist on disk.

A custom folder can be moved, removed and renamed.


To add a file system item to the hierarchy:

1Select the folder in which you want to insert a new item.
2Click the + button of the file hierarchy or choose Hierarchy > Add Files…
3Select the file or folder you want to add.
4Click Add…
5If requested, choose the reference style from the Reference Style popup button and click Add.

To add a custom folder to the hierarchy:

1Select the folder in which you want to insert a new item.
2Choose Hierarchy > New Folder.
3Type the name of the folder and validate with Return.

To remove items from a file hierarchy:

1Select the items in the hierarchy.
2Click the - button of the hierarchy or choose Edit > Delete.
3Click Remove.

Note: The item will only be removed from the hierarchy, it will not be removed from disk.

By default, when you add a reference to a real folder in the file hierarchy, its contents is not disclosed in the hierarchy.

To reveal the contents of a referenced folder:

1Select the referenced folder in the file hierarchy.
2Choose Hierarchy > Expand > Fully.

Notes:
  • You can also reveal only the contents of the first level of a referenced folder.

  • Not revealing the contents of a folder can be useful to be able to change the contents of the real folder on disk without having to update the hierarchy in Packages.

To reorder the items in the hierarchy:

1Select the items in the hierarchy.
2Drag and drop them to the new location in the hierarchy.


On the right of the hierarchy view, the inspector pane displays information related to the current selection in the hierarchy.

File Inspector

The inspector can display the following information for a single or multiple selection:

ValueDescription
IconThe icon for the file or folder as displayed in the Finder.
NameThe name of the file or folder.
Modification DateThe date of the last modification for the file or folder.
ArchitecturesArchitectures supported by the executable if an executable is selected.
TypeThe type of the item: a file, folder or custom folder.
ReferenceThe reference style for the item.
SourceThe relative or absolute path of the item on disk.

To rename a custom folder:

1Select the custom folder in the hierarchy.
2Type the new name of the folder in the Name text field of the inspector.
3Validate with Return.

To change the reference style of an item:

1Select the item in the file hierarchy.
2Choose the new style from the Reference popup button.




Revision History
05/22/13 Documents the INSTALL_PKG_SESSION_ID environment variable.
03/07/11 Indicates which env variables are only available with Mac OS X v10.6.
05/16/10 First version

Copyright 2010-2014 Stéphane Sudre. All rights reserved.