NSTask Tutorial for OS X

Writing a Build Shell Script

In Xcode, choose File\New\File… and select the Other category under OS X. Choose Shell Script and hit Next:

Name the file BuildScript.command. Before you hit Create, be sure TasksProject is selected under Targets, as shown below:

Open BuildScript.command and add the following commands at the end of the file:

echo "*********************************"
echo "Build Started"
echo "*********************************"

echo "*********************************"
echo "Beginning Build Process"
echo "*********************************"

xcodebuild -project "${1}" -target "${2}" -sdk iphoneos -verbose CONFIGURATION_BUILD_DIR="${3}"

echo "*********************************"
echo "Creating IPA"
echo "*********************************"

/usr/bin/xcrun -verbose -sdk iphoneos PackageApplication -v "${3}/${4}.app" -o "${5}/app.ipa"

This is the entire build script that your NSTask calls.

The echo commands that you see throughout your script will send whatever text is passed to them to standard output, which you capture as part of the return values from your NSTask object and display in your outputText field. echo statments are handy statements to let you know what your script is doing, since many commands don’t provide much, if any, output when run from the command line.

You’ll notice that besides all of the echo commands, there are two other commands: xcodebuild, and xcrun.

xcodebuild builds your application, creates an .app file, and places it in the subdirectory /build. Recall that you created an argument that references this directory way back in startTask, since you needed a place for the intermediate build files to live during the build and packaging process.

xcrun runs the developer tools from the command line. Here you use it to call PackageApplication, which packages the .app file into an .ipa file. By setting the verbose flag, you’ll get a lot of details in the standard output, which you’ll be able to view in your outputText field.

In both the xcodebuild and xcrun commands, you’ll notice that all of the arguments are written “${1}” instead of $1. This is because the paths to your projects may contain spaces. To handle that condition, you must wrap your file paths in quotes in order to get the right location. By putting the paths in quotes and curly braces, the script will properly parse the full path, spaces and all.

What about the other parts of the script, the parts that Xcode automatically added for you? What do they mean?

The first line of the script looks like this:

#!/bin/sh

Although it looks like a comment since it’s prefixed with #, this line tells the operating system to use a specific shell when executing the remainder of the script. It’s called a shebang. The shell is the interpreter that runs your commands, either in script files or from a command line interface.

There are many different shells available, but most of them adhere to some variation of either Bourne shell syntax or C shell syntax. Your script indicates that it should use sh, which is one of the shells included with OS X.

If you wanted to specify another shell to execute your script, like bash, you would change the first line to contain the full path to the appropriate shell executable, like so:

#!/bin/bash

In scripts, any argument you pass in is accessed by a $ and a number. $0 represents the name of the program you called, with all arguments after that referenced by $1, $2 and so forth.

Note: Shell scripts have been around for about as long as computers, so you’ll find more information than you’ll ever want to know about them on the Internet. For a simple (and relevant) place to start, check out Apple’s Shell Scripting Primer.

Now you’re ready to start calling your script from NSTask, right?

Not quite. At this point, your script file doesn’t have execute permissions. That is, you can read and write the file, but you can’t execute it.

This means if you build and run right now, your app will crash when you hit the Build button. Try it if you like. It’s not a big deal while developing, and you should see the exception “launch path not accessible” in your Xcode console.

To make it executable, navigate to your project directory in Terminal. Terminal defaults to your Home directory, so if your project is in your Documents directory, you would type the command:

cd Documents/TasksProject

If your project is in another directory besides “Documents/TasksProject”, you’ll need to enter the correct path to your project folder. To do this quickly, click and drag your project folder from the Finder into Terminal. The path to your project will magically appear in the Terminal window! Now simply move your cursor to the front of that path, type cd followed by a space, and hit enter.

To make sure you’re in the right place, type the following command into Terminal:

ls

Check that BuildScript.command in the file listing produced. If you’re not in the right place, check that you’ve correctly entered your project directory in Terminal.

Once you’re assured that you’re in the correct directory, type the following command into Terminal:

chmod +x BuildScript.command

The chmod command changes the permissions of the script to allow it to be executed by your NSTask object. If you try to run your application without these permissions in place, you’d see the same “Launch path not accessible” error as before. You only need to do this once for each new script that you add to your project.

Note: Using scripts like this is simple if you are developing for yourself or shipping your app outside the Mac App Store (MAS), however when developing for the MAS the sandbox rules that apply to your app are inherited by your scripts and you’ll need to use more complex techniques to use command line programs. These techniques are beyond the scope of this tutorial. See the links at the end for more details.

Clean and run your project; the “clean” is necessary as Xcode won’t pick up on the file’s permissions change, and therefore won’t copy it into the build repository. Once the application opens up, type in the target name of your test app, ensure the “Project Location” and “Build Repository” values are set correctly, and finally hit Build.

When the spinner disappears, you should have a new .ipa file in your desired location. Success!