PATH Contents > Configuring a project
Configuring a project

The project settings tab lets you change the settings attached to your distribution or raw package project such as the name for the distribution or raw package file, the format of the distribution, whether some files or folders should be excluded from the payload, etc.


To access the Project settings tab for a distribution project:

1Choose Project > Project…
2Click the Settings project tab.

To access the Project settings tab for a raw package project:

Click the Project tab.

Changing the name

The build name is the name under which the package or distribution will be created on disk when you build the project.

Build Name

Naming conventions and limitations:
  • The build name can not contain the "/" (forward slash) character. It is the file separator used on macOS.

  • The length of the name is limited to 251 characters (Unicode).

  • It is not necessary to type the extension. It will be automatically set during the build phase.

  • If you're building a raw package or flat distribution that will be hosted on a web server as is, it is usually better to avoid using spaces in the name.

By default, the project name is set to the project document file name.

To change the build name:

Type the new name in the Name text field.

Changing the build location

The build location is the folder on disk where the distribution or package will be created during the build phase. If the last path components of the build location do not exist, they will be created.

Build Location

By default, the build location is a build folder at the same level as the project.

To change the build location:

1Choose Choose… from the Action pop-up menu on the right of the Path text field.
2Select or create the folder to use as the build location and click Choose.

Changing the reference folder

To know more about the reference folder, read the File Reference Style chapter.

Build Reference Folder

By default, the reference folder is set to be the project folder.

To change the reference folder:

1Choose Other… from the Reference Folder popup button.
2Select or create the folder to use as the reference folder and click Choose.

To revert the reference folder to its default value:

1Hold down the alt key.
2Choose Revert to Default from the Reference Folder popup button.

Choosing a distribution format

There are 2 distribution formats available:

Build Reference Folder

These 2 formats are not equal when it comes to compatibility and features:

Installer Plugins
Mac OS X 10.6 or later
Embedded shell scripts invoked by JavaScript
Mac OS X 10.6 or later
Can be hosted as is on a web server
    No (1)
(1) A distribution bundle needs to be embedded in a disk image or archived first.

To change the distribution format:

Choose the format from the Format popup button.

Managing the certificate of a flat distribution or raw package

If you want to ensure that a raw package of flat distribution has not been tampered between the time you built it and the time the end user installs it, you can set a certificate to the project.

When you set a certificate, the raw package or flat distribution will get signed during the build phase. You will be asked to enter your administrator password at least once when the signing step is reached. For more information on the build process, check the Building a project chapter.

When a raw package or flat distribution is signed, a certificate or lock icon will be displayed in the title bar of the Installer window: certificate icon

You can click on this icon to check the validity of the certificate.

To set a certificate:

1Choose Project > Set Certificate…
2Select the certificate you want to use.
3Click Choose.

When a certificate is set, a certificate widget is sticked to the Project pane:

Certificate of Authenticity

Caution: Gatekeeper and the Developer ID Installer Certificate

OS X 10.8 and later includes an additional "security" feature, Gatekeeper, that requires packages and flat distributions to be signed. Packages and distributions downloaded from the Internet and that have not been signed may not be allowed to be installed by users depending on Gatekeeper's current settings. Signing the packages and distributions for Gatekeeper requires to use a certificate provided by Apple to paying ADC members.

Caution: macOS Catalina (10.15.x) and Notarization

macOS Catalina and later require distributions and packages to be notarized for the end-users to be able to install them by double-clicking them.

To notarize your distributions and packages, you need to:

  • sign them with Packages 1.2.7 or productsign.
  • have a non-expired Apple Developer membership subscription ($99/year).
  • use Xcode command line tools to submit your distributions and packages to Apple's notarization server.

You can find more information about the notarization process here: Customizing the Notarization Workflow.

To inspect the certificate:

1Click the certificate widget.
2When you're finished inspecting the certificate, click OK.

To remove the certificate:

1Choose Project > Remove Certificate…
2Click Remove.

Managing exclusions

The purpose of an exclusion is to define which files or folders should be excluded from the payload of packages or the resources folders when a project is built. For instance, the payload of a package may be created with bundles that contains Source Code Management metadata used by Subversion (SVN) or CVS. When the name of a filesystem object matches an exclusion, the object (and its children if any) will not be appended to the payload.

Project Exclusions

Exclusions are built around a pattern that can be a string or a regular expression. An exclusion can apply to only files, only folders or both of them.

A few standard exclusions are available by default. By default, they are all enabled. You can not remove a standard exclusion from the list but you can disable it if needed. Standard exclusions do not list the pattern they use. Here is a list of what kind of files or folders are excluded by them:

Standard ExclusionExcluded files or folders
Remove .DS_Store filesRemoves .DS_Store files created by the Finder.
Remove .pbdevelopment filesRemove .pb_development files created by ProjectBuilder or old versions of Xcode.
Remove SCM metadataRemove helper files and folders used by the CVS and SVN Source Code Management systems.
Optimize nib filesRemove classes.nib, info.nib and designable.nib files within .nib bundles.
Remove Resources Disabled foldersRemove Resources Disabled folders.
This information is also available through the tooltip attached to these exclusions.

To add a custom exclusion:

1Click the + button.
2Type the pattern the name of a file or folder should match to be excluded in the Pattern column of the new row.
3Click the popup in the Kind column for this row to select if this pattern should be looked only for files, only for folders or for both.
4If the pattern should be interpreted as a regular expression, click the checkbox in the RegEx column for this row.

To enable or disable an exclusion:

Click the checkbox in the • column to switch the state of the pattern.

To remove a custom exclusion:

1Select the row(s) of the custom exclusion(s) you want to remove.
2Click the - button.
2Click Remove.

Using advanced options

Advanced options let you set values for settings that are either advanced or not documented.

Project Advanced Options

Note: Do not change any of these values if you don't know exactly what you're doing.

The following advanced project options are supported:

NameDefault ValueDescription
1.0 if not set
The lowest version of the Install framework for which this distribution file is designed.
Not set
The highest version of the Install framework for which this distribution file is designed.
Not set
The highest version of the Install framework against which this distribution file has been qualified.
hostArchitectures (1)
Not set
Defines the architectures supported by the distribution.

If your solution works natively on both Intel and Apple Silicon architectures and you want to remove the Rosetta alert during the installation, set this value to 'i386 arm64'. If you are using Packages 1.2.10 or later, in most cases, you don't have to set this value. It will be computed automatically during the build process.

Specifies whether the JavaScript function can be executed.

If you are using a Result of Exterrnal Script requirement, this value will be set to yes automatically. If you are calling from a JavaScript requirement, you need to set this value yourself.

arch (1)
Not set
Defines the architectures supported by the distribution for macOS client.
arch (1)
Not set
Defines the architectures supported by the distribution for OS X server.
Not set
The bundle identifier of the main application or component in the distribution.
Not set
The version of the main application or component in the distribution.
any volume
Defines if the distribution can be installed at the root of a volume.
system volume
Defines if the distribution can be installed in the home folder of the current user.
current user's home folder
Defines if the distribution can be installed at the root of the startup volume.
(1) To set an architecture, you can also double-click the label.

Preferences Advanced Options

By default, the Advanced Options section is not visible.

To show or hide the Advanced Options section:

1Choose Packages > Preferences…
2Click Advanced.
3Click the Show Advanced User Options checkbox.

To change the value of an advanced option:

Click or double-click the appropriate cell to change the value of the text field or checkbox.

Adding notes and comments

You can add notes or comments to a project. For instance, you can list the versions of applications installed by the project.

Project Comments

To add or change comments:

1Click the Comments project tab.
2Type your notes in the text field.

Note: The comments text field supports styled text.

User defined settings

User defined settings let you define keywords that will be replaced by values when the project is built. User define settings are available for both distribution and raw package projects.

User defined settings are available in Packages 1.2.10 and later.


The keyword will be replaced by the custom value defined in the project. Or it will be replaced by the value you provide as an argument when building using the packagesbuild command line tool.

The following project properties support user defined settings:

Distribution name
Host architectures
Product id
Product version
Localized title
Localized choice title
Localized choice description
License template keyword
Localized requirement explanation
Localized requirement warning
Files requirement path
External script requirement argument
Package name
Package identifier
Package version
Package component location path
Must-close application bundle identifier
Payload custom folder name
Payload file destination name
Payload elastic folder name
Standard locator bundle identifier

To show or hide the list of user defined settings for a project:

1Choose View > Show User Defined Settings (or Hide User Defined Settings).

To add a user defined setting:

1Click the + button.
2Type the name of the keyword to use for the setting.
3Type the value for the keyword.

To remove a user defined setting:

1Select the row of the setting you want to remove.
2Click the - button.

To use a user defined setting:

1Use the macro ${keyword} in the text field where you want to use a user defined setting.

Note: You can mix both keyword(s) and text. e.g. "com.${COMPANY_NAME}.${APP_NAME}"

The user defined setting are automatically replaced by their default value when a text field is not being edited:

Not in edition mode

Revision History
01/02/22Add documentation for user defined settings.
11/21/21Add documentation about the product and domains advanced options.
10/14/19Add information about Notarization.
05/16/10First version

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