Blog Forty

In this tutorial, we demonstrate the use of Xcode 5's "Run Script Build Phase" to automatically generate resized images, such as thumbnails, as part of your project's build.

Motivation

If you have large source images that rarely get used in your application, generating thumbnails and other resized versions of those images in advance can save processor time for users.

Since this gets inconvenient to do by hand if your images change, we automate this process for whatever image sizes we need in our applications. The rest of this post describes one way of doing that.

Prerequisites

You should have a directory of images that you want to resize. The example script searches the path:

${SRC_ROOT}/Images/Originals/*.jpg

See the example project to see where the Images folder is located to see what ${SRC_ROOT} means on that project. Here is a Google search to get you started on further information.

It is not necessary for the original image files to be added to your Xcode project for the resized images to end up in the bundle. Also, this project uses JPG image files, but that is not required.

Adding the Build Phase

Open your project, then click on your project root in the project navigator.

Next, go into the Build Phases tab. You should see a list of build phases, including ones like "Compile Sources," "Link Binary With Libraries", and "Copy Bundle Resources."

Now, we want to add a new script build phase. One way to add a script build phase is to go to the top menu bar and navigate the following path:

Editor → Add Build Phase → Add Run Script Build Phase

After clicking "Add Run Script Build Phase,", you should see a new line appear in the list of build phases with the descriptor "Run Script." Drag that line beneath the build phase with the descriptor "Copy Bundle Resources ([n] items)."

If you click the build phase's arrow to expand the control, you’ll see that there are a few fields to fill out. Here's an image of the script in our project. We'll include text for copy/pasting below.

Shell:

/bin/bash

The script:

cd "${SRCROOT}/Images/Originals"

for f in *.jpg
do
    cp $f "${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/Tiny-$f"
    cp $f "${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/Small-$f"
    cp $f "${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/Medium-$f"
    cp $f "${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/Large-$f"
done

cd "${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}"
sips -Z 50 Tiny-*.jpg
sips -Z 100 Small-*.jpg
sips -Z 200 Medium-*.jpg
sips -Z 300 Large-*.jpg

Once you have this build phase in place, save your project and run a clean build. Now, you should be able to access the files you have created in the bundle. One way to access them is with [NSImage imageNamed:], like so:

[NSImage imageNamed:@“Small-[image_file_name]”]
// (e.g.):
[NSImage imageNamed:@“Small-knit_hat.jpg”]

Bundled

To see the build phase in action, check out the example. It is an Xcode project with a simple application that uses this process.

This particular application of script build phases is just about as simple as it gets. We hope this simple (but useful) example has inspired you to find even more useful ways to use build phases.

Thanks for reading.

Resources

For details on the parameters of the program used to resize images (it comes standard on Macs, as far as we can tell), go to your terminal and check out:

man sips

The previously linked search that should get you to more information on environment variables available to Script Build Phases.

The images in the example project are from the online collection of the Walters Art Museum in Baltimore. They license and publish a huge amount of art under Creative Commons, and it's worth checking out their collection.

Have something to add? Join the conversation on Hacker News.