OS X: Creating Packages from the Command Line - Tutorial and a Makefile - Part II

In the previous part of this tutorial we examined how pkgbuild and productbuild are used to build component packages and product archives. We also saw how hdiutil can be used to create a DMG image file to nicely package and distribute your product archive.

Although simple, the procedure is somewhat tedious: lot of typing, three different commands (four or more if we include building), lots of different paths and a many options. All of which, in a precise order, in order to satisfy the dependencies of each commands and to make sure the archives are updated whenever some component file changes.

Exactly what a Makefile is for!

A Makefile to build a Product Archive

All the steps described in the previous part of this tutorial can be automated with a proper Makefile. The Makefile we are going to create is basic, but can be used as a starting point to provide your project a set of ready to go and easy to use make targets to package it into a product archive and distribute it into a DMG file. This Makefile assumes that it is located into your XCode project root directory so that project binaries can be built and installed using

$ xcodebuild install

If this is not the case, just update the relevant action to run the build from the correct directory.

Let's start writing the Makefile in a top-down fashion. Let's add a default all target depending on anything else:

• $(DISTDIR) is the source folder for the DMG file, where the product archive will be stored.
• $(DEPSDIR) is an ancillary folder used to store directory. You can add more than one if component packages are stored in multiple folders, or remove it altogether if your product archive will be made up of a single component package.
• $(PRODUCT) is the product archive.
• $(DMGFILE) is the DMG image file creating from the source folder $(DISTDIR).

The resulting target is:

.PHONY : all
all : $(DISTDIR) $(DEPSDIR) $(PRODUCT) $(DMGFILE)

$(DISTDIR) and $(DEPSDIR) are created by the Makefile since we assume it is the Makefile that populates them:

$(DISTDIR) :
  mkdir $(DISTDIR)

$(DEPSDIR) :
  mkdir $(DEPSDIR)

$(PRODUCT), the product archive, depends on:

• $(BINARIES), the main component binaries.
• $(DEPENDENCY), a placeholder for the dependencies, a set of component packages to add to the product archive. If you have multiple dependencies, you will create multiple entries of this kind. You could omit this entry altogether, since productbuild would fail if a required component package is missing, but I think it is preferable to have make fail because of a missing target dependency.
• $(COMPONENT_PFILE), the component package property list file.
• $(COMPONENT), the component package.
• $(DISTRIBUTION_FILE), the distribution file.
• $(REQUIREMENTS), the requirements file.

$(PRODUCT) : $(BINARIES) $(REQUIREMENTS) \
             $(DEPENDENCY) $(COMPONENT_PFILE) \
             $(COMPONENT) $(DISTRIBUTION_FILE)
  productbuild --distribution $(DISTRIBUTION_FILE) \
    --resources . \
    --package-path $(DEPSDIR) \
    --package-path $(DEPENDENCYDIR) \
    $(PRODUCT)

The $(BINARIES) are usually compiled and installed with xcodebuild:

$(BINARIES) :
  xcodebuild install

The component package property list file, $(COMPONENT_PFILE), must be created beforehand as seen in the previous post. Let's emit a meaningful error if it is missing referring to a target we will examine later on.

$(COMPONENT_PFILE) :
  @echo "Error: Missing component pfile."
  @echo "Create a component pfile with make compfiles."
  @exit 1

The main component package $(COMPONENT) depends on the binaries $(BINARIES) and the component property list file $(COMPONENT_PFILE) and it must be created with pkgbuild, as seen in the previous part of this tutorial:

$(COMPONENT) : $(BINARIES) $(COMPONENT_PFILE)
  pkgbuild --root $(BINARIES) \
  --component-plist $(COMPONENT_PFILE) \
  $(COMPONENT)

The distribution file $(DISTRIBUTION_FILE), as in the case of $(COMPONENT_PFILE), must be created beforehand. We will emit a meaningful error if it missing referring to a target we will examine later on:

$(DISTRIBUTION_FILE) :
  @echo "Error: Missing distribution file."
  @echo "Create a distribution file with make distfiles."
  @exit 1

Now the Makefile is functional except for one detail: who is going to create the two required property list files $(COMPONENT_PFILE) and $(DISTRIBUTION_FILE)? We have seen in the previous part of this tutorial that both pkgbuild and productbuild can be run in an analysis mode which analyses their input and creates an initial descriptor. We will add two targets to the Makefile that will provide the user a quick way to get initial versions of the required descriptors:

.PHONY : distfiles
distfiles : $(COMPONENT)
  productbuild --synthesize \
  --product $(REQUIREMENTS) \
  --package $(DEPENDENCY) \
  --package $(COMPONENT) \
  $(DISTRIBUTION_FILE).new
  @echo "Edit the $(DISTRIBUTION_FILE).new template to create a suitable $(DISTRIBUTION_FILE) file."

.PHONY : compfiles
compfiles : $(BINARIES)
  pkgbuild --analyze \
  --root $(BINARIES) \
  $(COMPONENT_PFILE).new
  @echo "Edit the $(COMPONENT_PFILE).new template to create a suitable $(COMPONENT_PFILE) file."

Note that in the distfiles target the $(DEPENDENCY) variable is used as argument of the --package option. As explained earlier, you have to either add as many "dependency variables" as required by your product archive, or remove it altogether if the product archive only contains one component package, $(COMPONENT).

The files created by both the distfiles and the compfiles targets must be manually edited by the user and moved to their expected name by removing the .new extension.

Finally, let's add some targets to perform some housekeeping:

• clean, to remove the DMG file and all the packages.
• distclean, to remove the distribution files.
• compclean, to remove the component file.

.PHONY : clean
clean :
  -rm -f $(DMGFILE) $(PRODUCT) $(COMPONENT)
  -rm -rf $(BINARIES)

.PHONY : distclean
distclean :
  -rm -f $(DISTRIBUTION_FILE) $(DISTRIBUTION_FILE).new

.PHONY : compclean
compclean :
  -rm -f $(COMPONENT_PFILE) $(COMPONENT_PFILE).new

Populate the Variables

So far, we have used Makefile variables in our targets and actions in order to decouple the basic Makefile structure from the details of a specific project. Now, variables must be populated for the Makefile to work in every specific project.

This is the typical variable definition block I use at the top of this kind of Makefiles:

PROGRAM = Name
DISTDIR = ./dist
DEPSDIR = ./deps
BINARIES = /tmp/Name.dst
DMGFILE = $(PROGRAM).dmg
PRODUCT = $(DISTDIR)/$(PROGRAM).pkg
COMPONENT = $(DEPSDIR)/$(PROGRAM)Component.pkg
COMPONENT_PFILE = $(PROGRAM).plist
DISTRIBUTION_FILE = distribution.dist
REQUIREMENTS = requirements.plist

PROGRAM is a shared fragment which is typically set to the XCode project name. The DMG file name DMGFILE, the product archive name PRODUCT and the binary installation directory BINARIES are all initialised using this prefix. If want to customise any of these names or adjust any path to your needs, just modify accordingly the corresponding variable.

Use It

The default Makefile target, all, can be executed by simply invoking

$ make

If everything works correctly, you will find a DMG file image in your execution directory containing your product archive.

Conclusion

In this tutorial we have covered the basic tasks every OS X developer should master in order to build product packages for his own projects. Furthermore, the skeleton of a Makefile performing all the required operations has been provided. This is only the beginning of the work of creating an installer, since most of an installer properties and requirements must be manually set by the developer. However, the tedious part of building component packages and creating product packages can be automated in a relatively simple Makefile that I hope it will be useful to many of you.