Adding a new build rule to parse all rtf files

Question

Xcode includes a flexible build rules system. The documentation is all but non-existant however.

A project I am working on for iOS 5 and iOS 6 includes an rtf help file. For iOS 6, I can convert the rtf file into an archived NSAttributedString object, then load that at runtimeand display it directly to a UITextView. For iOS 5, I can't (without a lot of work in Core Text...) so I want just the text without the style info.

I wrote a command line tool, RTFToData that takes an RTF file as input and generates a .txt file and a .data file (where the .data file contains a version of the styled text that my project knows how to use.)

Here is the syntax of my command line tool:

RTFToData [-o] source_path [destination_path] -o (optional) overwite existing files source_path (required) path to source RTF file (must have extension "rtf" or "RTF" destination_directory (optional.) writes output files to source file directory if no destination specified destination_directory must exist if specified.

I want to set up my project so that I can add .rtf files as sources (with the "add to target" checkbox NOT checked.) I want Xcode to run my RTFToData command on each file specifying that the output files should be copied into a directory and then added to the target.

Ideally, I'd like the build process to know about the dependencies between my source .rtf files and the processed .data and .txt files. If I touch a .rtf file, I'd like the build process to re-run the rtftodata command.

I am a makefile and unix scripting neophyte. I THINK I can use a run script build rule that will do this, but I am unclear on how. I guess I need to write a script that finds all files of type ".rtf", pipes that list of files into an invocation of my RTFToData.

Can somebody outline the steps I need to take in the Xcode IDE to make my project handle this smoothly?

As a side-note, is there some directory where you can put command line tools so they are available to the current version of Xcode? So far I've been installing the RTFToData command in /Library/usr/bin, but I'd really like the build tool to be included in the project, or at the very least, not have to use sudo to set up every development machine that is used to build this project.

Answer 1

Create a custom build phase

1. Add the .rtf files to your project and make sure they are added to your target.

2. Go to your target settings and select the "Build Rules" tab:

   

3. Click the "Add Build Rule" button at the bottom.

   

4. You want to configure your rule based on something like this:

   

   Enter a standard wildcard glob for the files you want to match (*.rtf).

   Inside the script section you can make use of a number of environment variables. Assuming your glob has matched the input file Test.rtf you have access to these vars:

   • INPUT_FILE_PATH = /path/to/your/project/source/Test.rtf
   • INPUT_FILE_NAME = Test.rtf
   • INPUT_FILE_BASE = Test
   • INPUT_FILE_SUFFIX = .rtf
   • INPUT_FILE_DIR = /path/to/your/project/source/

   You want to process your file and send it to the ${DERIVED_FILES_DIR} directory with whatever new filename or extension you need. In this case we take the base filename from the input and give it a new extension.

   Fill out the "Output Files" section with the same output file you used in the script. This will ensure the dependency system works and that the file will be copied to your .app. The script will only be run if the input has changed or the output file is missing from the .app.

   Note that the "Output Files" should not have double quotes. The paths will be quoted for you by Xcode.

   If your script generates multiple output files, add extra entries for those as well.

Once this is all set up, .rtf files added to your target will be converted to whatever output files your script generates. The original .rtf files will not exist in the final .app.

Where to put scripts/programs

As a side-note, is there some directory where you can put command line tools so they are available to the current version of Xcode?

Put your tools somewhere below the directory that contains your .xcproject. Then from your build phase/rules use the ${SRCROOT} environment variable, which is the directory containing your project:

Assuming this file system layout:

/path/to/project/project.xcodeproj
/path/to/project/Tools/CommandLineTool

Use this in your build phase/rules:

"${SRCROOT}/Tools/CommandLineTool" "${INPUT_FILE_PATH}" ...

Remember to use double-quotes everywhere you can!