andymroczblogkowski

Back in the Dark Ages of iPhone Development, when the NDA loomed over us all, getting information was hard. The deployment and code-signing piece was especially tricky to get working correctly. One was often thrilled to get it working at all.

One step of the process is choosing an application ID, which uses the common reverse domain name format. The documentation also stated that if you want to share information across multiple applications, a wildcard app ID (com.yourcompany.*) can be used. No drawbacks were given, and sharing is good, right? So I can only imagine that some people may have used a wildcard app ID for their application. And I can also only imagine that these people had no problems with their wildcard app ID, until iPhone OS 3.0 came out that is.

You see, Apple’s Push Notification service using a wildcard application ID.

Those same people may have been under the impression that it was the app ID that uniquely identified the application, and therefore changing it would yield a new application, and not update the existing one. This means that all ranking in the App Store would be lost, and users would not be notified of the update.

The good news is, this is not the case. An application’s app ID can be changed by generating a new app ID, re-generating a distribution the App Store distribution certificate, and submitting to the App Store.

So if you shipped your app with a wildcard ID, and now want to integrate push notifications, you are not screwed. Just generate a new, non-wildcard app ID.

Recently I bumped into an iPhone application configuration/deployment problem, and thought someone else might benefit from my findings.

Motivation and Goals

Here’s the basic scenario: I wanted to expose certain options in my iPhone application that were only available in Debug builds. One choice would be to add the ability to change the options in the application itself, and use the usual conditional compilation (#ifdef DEBUG…) techniques to hide or expose them based on build configuration.

However, this would require adding a whole bunch of custom UI in my application, which didn’t really seem appealing. The application was already using the standard iPhone application Setting system, which is driven by simple plists. I thought to myself, boy it would be nice if my Debug-only options could be automagically added to Settings bundle at build time.

For example, the standard settings pane would look like this:

And debug-only options would be added automatically, to produce this:

I’m a believer in the DRY principle, so I wanted to avoid duplicating and information at all possible. Also I wanted to “set it and forget it” and not require any manual build steps.

After some experimentation, trial, and error, I arrived at the following solution:

1. Store Debug settings in a separate child pane. The Settings system allows for child panes of the root pane. To keep the main settings and debug settings separate, we keep them on different panes.
2. Add an reference to the child pane from the root pane at build time. To keep the main root settings clean, we’ll inject the reference to the debug clild pane at build time.

Create the Property List

First, add a Settings Bundle to your project if you haven’t already. Choose File -> New File… -> Settings -> Settings Bundle.

Next we need to add a second plist for our Debug settings. Xcode doesn’t allow you to create a new plist inside the Settings bundle (or any bundle for that matter), so we’ll have to create our Debug.plist by some other means. If you’re familiar with the shell, the easiest way is to navigate to Settings.bundle inside your project and simply duplicate the main Root settings to create Debug settings.

cp Settings.bundle/Root.plist Settings.bundle/Debug.plist

If you prefer to use Finder, navigate to Settings.bundle and then right- or control-click and choose Show Package Contents. Then option-drag to duplicate Root.plist and rename it to Debug.plist.

Once the file has been created, collapse and expand the Settings bundle in your projects Groups & Files section to refresh it’s contents. It should look like this:

Note, you can name the child settings plist something other than “Debug” if you want. We’ll see how to do that in the next section.

The Injection Script

The purpose of the injection script is to add a child pane option to an existing settings plist file. It uses the built in PlistBuddy utility to do all the real work.

The addDebugSettingsChild.sh takes two arguments. The first is of course that path to the target plist file. The second is the name of the new child pane, or ‘Debug’ if unspecified.

Here’s the script:

#!/bin/sh

# addDebugSettingsChild.sh
#
# Simple script to inject a Debug menu in an iPhone Settings plist.
#
# created 10.15.2008 by Andy Mroczkowski, mrox.net

THIS="`basename $0`"
PLISTBUDDY="/usr/libexec/PlistBuddy -x"

set -e

if [ -z "$1" ]; then
    echo "Usage:"
    echo "   $THIS plist_file [child_pane_name]"
    echo "   - If unspecified, child_pane_name is 'Debug'"
    exit 1
fi

if [ ! -e "$1" ]; then
    echo "[$THIS] file not found: '$1'"
    exit 2
fi

if [ ! -z "$2" ]; then
    CHILD_PANE_NAME="$2"
else
    CHILD_PANE_NAME="Debug"
fi

TARGET="$1"
echo "[$THIS] adding '$CHILD_PANE_NAME' child to: $TARGET"

$PLISTBUDDY -c "Add PreferenceSpecifiers:0 dict" "$TARGET"
$PLISTBUDDY -c "Add PreferenceSpecifiers:0:Type string 'PSGroupSpecifier'" "$TARGET"

$PLISTBUDDY -c "Add PreferenceSpecifiers:1 dict" "$TARGET"
$PLISTBUDDY -c "Add PreferenceSpecifiers:1:Type string 'PSChildPaneSpecifier'" "$TARGET"
$PLISTBUDDY -c "Add PreferenceSpecifiers:1:Title string '$CHILD_PANE_NAME Settings'" "$TARGET"
$PLISTBUDDY -c "Add PreferenceSpecifiers:1:File string '$CHILD_PANE_NAME'" "$TARGET"

Download

Creating the Build Step

We’ve created a Debug settings child pane in our settings bundle, and a script to add an option to access our child pane from the root pane. Now we just have to tie the pieces together in Xcode’s build settings.

Copy addDebugSettingsChild.sh to your project’s folder. You don’t need to add it to the project itself. Next add a new “Run Script Build Phase” to the target for your application. Order it so be comes after the “Copy Bundle Resources” phase, and name it something more descriptive if you’d like. I called mine “Run Debug Settings Script”.

Next we have to make the our new Run Script phase actually do something. Basically, we need to call the addDebugSettingsChild.sh if we’re building with the “Debug” configuration, and also set up the input and out files so Xcode knows when to run the script and when not to. Let’s set up the input and output files first.

Add the path to your Root settings plist as an input file. If you used the default names and locations, this should be:

$(SRCROOT)/Settings.bundle/Root.plist

The file we will be altering will be in the built products area, not the project source root, so the output file should be:

$(BUILT_PRODUCTS_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/Settings.bundle/Root.plist

Finally create the body of the script. I only want to add my extra settings if I'm building the "Debug" configuration, so my script looks like this:

if [ "$CONFIGURATION" == "Debug" ]; then
    sh addDebugSettingsChild.sh "$SCRIPTOUTPUTFILE_0"
fi

You may notice that the script's input is specified as the output file. This is not a mistake. The addDebugSettingsChild.sh script modifies the specified plist in place, and we want to alter the one in our built-products area, not the source tree.

Again it's important to specify the input and output files. If you don't, Xcode may run the script on every build, which will result in repeated Debug child pane choices in our main settings plist.

Once you're done, it should look like this:

Conclusion

And that's it. You can now add edit the Root and Debug plists and they will be updated appropriately and everything will be happy. Well, mostly happy (see Caveats). I hope you found if useful. If not, I'm sorry. Here's some pictures of Robocop on a Unicorn to cheer you up.

Sample Project

You can download a sample project with all the above steps already completed here.

Caveats and Future Work

• Be careful when switching configurations and using Build and Run. The products in the build folder for each configuration should always be correct, but Xcode won't necessarily re-install the right Setting bundle if it doesn't detect a change. The workaround is to just build clean and re-build when switching from Debug to Release or vice versa. Any suggestions on how to improve this are welcome.
• Child pane options are always injected at the top. I'd prefer if I could add the "Debug Settings" option at the end of the main preferences, but I could not find a simple way to append an element to the end of an array with PlistBuddy. I considered using PlistBuddy to loop through the array to determine the size, and then use that to append it to the end, but I didn't want to add all that complexity to the script for a minor issue just yet.
• Debug.plist still exists, but is inaccessible, in Release builds. This method does not prevent the installation of the Debug.plist, but there will be no way to get to it, since it's not referenced as a child from the root plist. If this bothers you, you'll probably have to set up another script to remove Debug.plist.
• What if I'm not using a Settings bundle in my Release builds? This technique assumes that you're already using a Settings bundle to your application, and you want to add extra stuff to it based on build configuration. If you'd like to only have Settings bundle for Debug builds, this isn't going to work for you, though hopefully some of the information can help you get started on a similar solution.

The first few articles laid out a good foundation of basic shell usage, but little Mac-specific information. In this article, all that will change. We’re going to show a few ways to get back and forth between Terminal and Finder.

From Finder to Terminal

There a few methods to get information from Finder into the Terminal, or use Finder in Terminal-like ways.

Path Bar

One new feature in the 10.5 Finder is Path Bar. The Path Bar makes it easy to see the full path to the current folder. To enable the Path Bar (if you haven’t already), activate Finder, and choose View → Show Path Bar from the menu.

Once enabled, the Path Bar will appear at the bottom of all your Finder windows, just above the Status Bar. Below is how the Path Bar appears when I have my Home folder open in Finder.

The the above path would be interpreted as /Users/demo in the shell.

Go to Folder…

Finder also has a built in command called Go to Folder… that allows a path to be entered in a similar way as in the shell. This feature can be accessed by choosing Go → Go to Folder… from the menu, but it’s faster to use the shortcut ⌘⇧G.

The path entry field of the Go to Folder… feature also has rudimentary tab-completion support. If you type a few letters and either press the tab key (⇥) or just wait a few seconds, it will complete the current path component with the first match it finds. It’s not nearly as good as the completion in bash, but it’s there.

Drag & Drop Paths

Files or folders in Finder can also be dragged and dropped directly onto Terminal. Doing so will insert the path to the file or folder into the shell.

And voilà, the path is inserted into the shell:

OpenTerminalHere

OpenTerminalHere is a small Applescript application that launches Terminal and automatically cd’s to the current folder in Finder. It was originally written by Marc Liyanage and has since been updated to make it more Leopard-friendly. I find it extremely handy, and if you think you would too, go here for the download and setup instructions.

OpenTerminalHere is meant to be installed into Finder’s toolbar. This is done by simply dragging the OpenTerminalHere icon to Finder’s toolbar and pausing a few seconds until a small green “plus” indicator appears next to the mouse pointer. If you want to tweak the position of OpenTerminalHere or add spacing, choose View → Customize Toolbar… in Finder’s menu after installing.

Now just click on the OpenTerminalHere icon in the Finder window’s toolbar, and a Terminal will launch and cd to the current folder.

From Terminal to Finder

Even though the shell is a powerful tool, sometimes you may want to switch back to Finder to finish a task. Here are a couple tools to do just that.

open

We’ve used the open command (man page) a few times already to open files with their default application and folders in Finder. This command is actually specific to Mac OS and is not found in other Unix-like operating systems. The open command also allows you to choose the application with which to open the file, or open the file in the default text editor.

To open a file using a specific application, use the -a option:

open -a [application] [file]

For example, if I wanted to open a file called “hello.txt” in MacVim instead of the default editor, TextEdit, I would type:

open -a /Applications/MacVim.app hello.txt

Also as we mentioned just sentences ago, you can use the open command to open a file using the default text editor. This is done with the -t option.

open -t [file]

Let’s say I’m a curious individual, and I want to see exactly what iTunes stores in its XML library file. I would type:

open -t ~/Music/iTunes/iTunes\ Music\ Library.xml

(Remember those extra \’s are to escape the spaces, which was discussed in the second article.

Revealing Files in Finder

The open command can be used to open folders in Finder, but we don’t have a way to reveal a file within a folder. Many applications have a built-in “Show in Finder” feature, but unfortunately the shell does not. However, all hope is not lost.

One of the simplest ways to add new commands in the shell is through creating shell scripts. Shell scripting is a deep topic in itself, but for know, just think of a shell script as a small program that is interpreted by the shell itself. Shell scripts are written in plain text so they are quick to create and easy to modify.

A hint entitled “Select files in Finder from Terminal” on Mac OS X Hints presents a way add a “Show in Finder” feature to the shell using a custom shell script. Several others submitted improvements and alternative approaches in the comments. The solution I liked best is described in this comment by caesurae.

I liked this solution because it was relatively concise and easy to read (for the bash-literate), and it is contained within a single file. I modified the script very slightly to fix a problem with revealing directories.

Here is the full script. Immediately following is a download link, which is probably more useful. Following that, and even more useful still are installation instructions.

The Script

#!/bin/bash
#
# revealInFinder.bash
#
# 05.26.2006
#
# caesurae@gmail.com
#
# tested on Mac OS X 10.3.9 build 7W98 - Darwin 7.9.0 - AppleScript 1.9.3
#
# reveal the given file(s) and/or folder(s) in a Finder window
#
# usage: revealInFinder.bash ~/dir/file "/dir/dir/my file" file
#
########
#
# 08.07.2008
#
# Andy Mroczkowski
#
# minor update to allow for more reliable opening of directories
#
# tested on Mac OS X 10.5.4 - AppleScript 2.0.1k
#
##

# if no arguments are given, echo the usage string
if [ $# -lt 1 ]; then
  echo 'Usage: '`basename "$0"`' [files]' >&2
  exit 1
fi

# define $n, gets +1 for each argument given
# not sure if $n is needed, how to get index number of $1, $2, etc.?
n=0

# define $act, gets +1 for each argument that passes test
act=0

# step thru each argument one at a time
for thearg in "$@"; do

  n=$(( n + 1 ))

  # if $thearg exists then
  if [ -e "$thearg" ]; then

    # get the absolute path to the argument
    thearg="`cd \`dirname \"$thearg\"\`; pwd`/`basename \"$thearg\"`"

    # create a applescript statement using $thearg for osascript to execute
    osatext='tell application "Finder" to reveal POSIX file "'"$thearg"'"'
    /usr/bin/osascript -e "$osatext"

    # $act activates Finder after processing the remaining arguments
    act=$(( act + 1 ))

  # else if $thearg does not exist then
  else

    # if $thearg is not the last argument given then
    if [ $n -lt $# ]; then

      # ask to continue processing the remaining arguments
      echo -n '"'"$thearg"'" does not exist and will be ignored. continue?  (y/n)? ' >&2
      read ans
      case $ans in
        "n" ) exit 1 ;;
        "y" ) continue ;;
      esac

    # else if $thearg is the last arguement then
    else

      # print the "does not exist" string and exit
      echo '"'"$thearg"'" does not exist.' >&2

      # exit status 1 indicates an error occurred
      exit 1
    fi
  fi
done

# if $act is greater than 0 then activate the finder
if [ $act -gt 0 ]; then
  /usr/bin/osascript -e 'tell application "Finder" to activate'
fi

# exit status 0 indicates all is ok
exit 0

Download the reveal script (and unzip it if necessary).

Installation

Once you have reveal downloaded, you need to put it a place where the shell can find it. Executable files are usually kept in a directory called “bin“. To avoid any permissions problems, we’re just going to set up this script for the current user. To create a bin directory for yourself, type:

mkdir ~/bin

Now the reveal script must be moved into the bin directory. If you saved reveal in your Downlaods folder, you would type the following:

mv ~/Downloads/reveal ~/bin

Of course if you saved reveal to some place other than your Downloads folder, you’ll have use the appropriate path.

Finally we need to ensure that reveal is executable. If you downloaded it from the using the link above, the permissions should have been preserved within the zip file, but we’ll reset them just in case. Changing basic permissions from the command line is done with chmod (man page). We’ll go into detail on chmod later. For now just type

chmod +x ~/bin/reveal

Ok, now everything is in place, but there is still one more thing left to do. The shell only looks in a few pre-defined places for programs and although a ~/bin directory is common, it does not search that directory by default. We can tell the shell to look for programs in our ~/bin directory by adding it to our PATH.

The PATH variable controls where the shell looks for programs. You can manually type in the command to add ~/bin to our PATH, but the PATH variable is cleared every time we open a new shell. That’s a hassle. Instead we want it so our PATH is set up for us automatically. To do that, we will add the command to a special file called .bash_profile which is loaded every time a new shell is started.

First, create the file. The file must be in your home directory (~) or the shell won’t find it. If you already have a .bash_profile the following command won’t overwrite it.

touch ~/.bash_profile

Now open the new, empty .bash_profile file in your default text editor:

open -t ~/.bash_profile

Next add the following line exactly as it appears below. Copy and Paste are your friends. If you already have some stuff in your .bash_profile just add it to the end.

export PATH=$PATH:$HOME/bin

Save and close the file. Then close the Terminal you were working in and open a new one (your .bash_profile is only read when the shell starts up).

Congratulations, you now have installed a shell script. Have a beer.

Usage

Our new reveal script is easy to use. You just type reveal followed by one or more paths to files or directories. In fact, if you type reveal with no arguments, it prints a helpful usage statement:

Usage: /Users/demo/bin/reveal ~/dir/file "/dir/dir/my file" file

Of course since we went through all the trouble of putting reveal into our path, we can just type:

reveal ~/dir/file "/dir/dir/my file" file

Here it is in action:

Wrap-up

So there we have it – Terminal and Finder peacefully co-existing. What a wonderful world. If you have more suggestions about integrating these fine pieces of software, or a question, feel free to comment. Feedback is always welcome.