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.

project_settings

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:

SupportedBundleFlat
Installer Plugins
Yes
Mac OS X 10.6 or later
Embedded shell scripts invoked by JavaScript
Yes
Mac OS X 10.6 or later
Certificates
No
Yes
Can be hosted as is on a web server
    No (1)
Yes
(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:

Installer.app 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 probably 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
installer-script
minSpecVersion
1.0 if not set
The lowest version of the Install framework for which this distribution file is designed.
verifiedSpecVersion
Not set
The highest version of the Install framework for which this distribution file is designed.
maxSpecVersion
Not set
The highest version of the Install framework against which this distribution file has been qualified.
options
hostArchitectures (1)
Not set
Defines the architectures supported by the distribution.
allow-external-scripts
-
Specifies whether the system.run 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 system.run from a JavaScript requirement, you need to set this value yourself.

platforms
  client
arch (1)
Not set
Defines the architectures supported by the distribution for macOS client.
  server
arch (1)
Not set
Defines the architectures supported by the distribution for OS X server.
(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.




Revision History
10/14/19Add information about Notarization
05/16/10First version

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