PATH Contents > Building a project
Building a project

Building a project is the operation that creates the distribution and/or raw packages on disk. Once you have properly configured your project, this is probably the operation you will perform most often later on.


Building a project from the application

When you build a project from the Packages application, you can follow the progression of the build operation through the build window.

Project Build Window

The build window will let you know if a build is successful or failed. If the build fails, it will try to explain the origin of the failure.

Notes:
  • If a project uses a certificate, you may be requested to enter your password during the build process.

  • If you want to change when or if the build window should automatically appear or disappear, read the Changing build preferences chapter.

  • Building a project is usually quite fast but it may take time depending on the size of the payload.

To build a project:

Choose Build > Build.

To build a project and open it with Installer:

Choose Build > Build and Run.

To display or hide the build window:

Choose Build > Build Results.


Building a package with Quick Build

Sometimes you just need to quickly build a raw package to distribute a component through Apple Remote Desktop. The Quick Build feature of Packages is made for that.

This feature supports the following types of components:

Aperture Plug-Ins
Applications
Cocoa Services
Color Pickers
Dashboard Widgets
Dictionaries
Frameworks
Preference Panes
QuickTime Components
Screen Savers
Spotlight Plug-Ins
WebKit Plug-Ins

During the build phase of a Quick Build, the build window will not be displayed. A bezel window will inform you instead of the status of the build process.

Project Quick Build

Notes:
  • The identifier of the package is created from the identifier of the component.

  • If the type of the component is not supported or a default location for the installation can't be computed, the package will not be built.

  • If you have chosen to be asked whether to sign the package, a dialog will be displayed to let you decide what to do.

To build a raw package for a supported component with the Quick Build feature:

1Select the component in the Finder.
2Drag and drop the component on the application icon in the Finder or in the Dock.


Building a project in debug mode

The debug mode lets you build a distribution or raw package and disable bundle locators.

You may want to do that if your distribution or raw package contains bundles that have locators attached to them and you want to simulate a clean install.

Notes:
  • You should not distribute a project built in debug mode.

  • Distributions or raw packages built in debug mode are put in a build_debug folder.

To build a project in debug mode and open it in Installer:

Choose Build > Build and Debug.


Building a project from the command line

If you need to integrate the creation of a distribution or package into an automated workflow, you can use the packagesbuild tool.

It is located in /usr/local/bin and the only mandatory argument is the path of the Packages project to build. With the optional arguments, you can build a project in debug mode, change the reference folder or temporary build location.

Project packagesbuild tool

packagesbuild returns 0 if the project is built successfully, otherwise a non-zero value.

Notes:
  • You can of course call the packagesbuild tool from a script.

  • Be aware that if a project uses a certificate, user interaction might be required to access the keychain.

To build a project with the command line tool:

1Open the Terminal application.
2Type the following command and validate with Return:

$ /usr/local/bin/packagesbuild --project /path/to/the/project.pkgproj

To build a project in verbose mode:

1Open the Terminal application.
2Type the following command and validate with Return:

$ /usr/local/bin/packagesbuild --verbose --project /path/to/the/project.pkgproj

To build a project in debug mode:

1Open the Terminal application.
2Type the following command and validate with Return:

$ /usr/local/bin/packagesbuild --debug --project /path/to/the/project.pkgproj

To build a project with a specific reference folder:

1Open the Terminal application.
2Type the following command and validate with Return:

$ /usr/local/bin/packagesbuild --reference-folder /path/to/the/reference/folder --project /path/to/the/project.pkgproj

By default, Packages uses the /private/folder to build the various components of a project before assembling them in the build folder.

To build a project in a specific temporary build location:

1Open the Terminal application.
2Type the following command and validate with Return:

$ /usr/local/bin/packagesbuild --temporary-build-location /path/to/the/build/location --project /path/to/the/project.pkgproj

To build a project and set the custom value for a user defined setting:

1Open the Terminal application.
2Assuming you have defined the VERSION user defined setting in your project, type the following command and validate with Return:

$ /usr/local/bin/packagesbuild --project /path/to/the/project.pkgproj VERSION="1.1"


Changing build preferences

By default, when you try to build a project which has been modified but not saved yet, Packages will ask you whether you want to save the project before building.

Project Unsaved Behavior

To change the behavior upon building unsaved projects:

1Choose Packages > Preferences…
2Click Building.
3Choose the behavior from the Unsaved project pop-up menu.

By default, when you build a project, Packages always display the build window and it stays displayed after the build finished.

Project Build Window Behavior

To change the build window behavior:

1Choose Packages > Preferences…
2Click Building.
3Choose the behaviors from the Show during builds and Hide after builds pop-up menus.

By default, when you build a project, the only feedback you get regarding the success of the operation is a visual one. Packages can also play a sound on success or failure of the build operation.

Project Build Sound Feedback

To change the sound played:

1Choose Packages > Preferences…
2Click Building.
3Choose either On success or On Failure case.
4Check the Play sound checkbox or uncheck it if you don't want a sound to be played.
5Choose the sound to play from the Play sound pop-up menu.

To make Packages speak an announcement:

1Choose Packages > Preferences…
2Click Building.
3Choose either On success or On Failure case.
4Check the Speak announcement using checkbox.
5Choose the voice to use in the pop-up menu.

Notes:
  • The announcements are either "Build Succeeded" or "Build Failed" depending on the outcome of the build process.

  • They are localized.


To hide build notifications:

1Choose Packages > Preferences…
2Click Building.
3Uncheck the Notify using system notifications checkbox.

Notes:
  • These notifications are only displayed if Packages is not the active application when the build completes.


To stop the Packages icon from bouncing in Dock:

1Choose Packages > Preferences…
2Click Building.
3Uncheck the Bounce Packages Icon in Dock if application inactive checkbox.


By default, packages made through Quick Build are not signed.

Quick Build Signing Behavior

To set the certificate to use for signing Quick Build packages:

1Choose Packages > Preferences…
2Click Building.
3Choose Other… from the Sign with certificate pop-up menu.
4Select the certificate that should be used.
5Click Choose.

To change the signing behavior for Quick Build packages:

1Choose Packages > Preferences…
2Click Building.
3Choose one of these menu items:

  • Developer ID Installer …: packages will be signed using the certificate you defined.
  • Don't sign: packages will not be signed.
  • Ask for each build: for each Quick Build, you will be asked whether to sign the package and whether to use the defined certificate or another one.


By default, packages made through Quick Build have their version set to 1.0.

Quick Build Package Version

To set Quick Build packages to use the version of the bundle component in the payload:

1Choose Packages > Preferences…
2Click Building.
3Click the Use bundle version checkbox.

Packages made through Quick Build are saved in the same folder as the original bundle of their payload. If this folder is not writable by the current user, by default the package is created in the current user's home directory.

Quick Build Package Failover Folder

To change Quick Build failover folder:

1Choose Packages > Preferences…
2Click Building.
3Choose Choose… from the Failover folder pop-up menu.
4Select the folder that should be used as a failover folder.
5Click Choose.

By default, projects are built in the /private/tmp/ folder.

Project Build Temporary Path

To change the temporary build path:

1Choose Packages > Preferences…
2Click Building.
3Click Choose…
4Select the folder that should be used for temporary build.
5Click Choose.




Revision History
01/01/22 Update the command line examples for version 1.2.10.
01/06/18 Add documentation for the new signing options for Quick Builds.
Update screenshots for Build Preferences pane.
01/06/18 Add documentation for the new build behaviors.
09/01/10 Use the proper name for some widgets name.
Added new chapters related to Quick Build preferences.
05/16/10 First version

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