Xcode Tools Tips
Xcode Tools Sensei helps you use the Xcode Tools, but there's no way one book can solve every problem someone may have with the tools. I've created this page to help fill the void.
If you have any tips you would like to share, and I will add them to this page.
Attention Xcode 4 and Xcode 5 Users
I wrote the tips on this page for older versions of Xcode. Xcode 4 is a major change, which means many of these tips won't apply to Xcode 4. I have some Xcode 4 tips on my blog. The link to the blog is on the site map at the top of the page. The Xcode 4 tips are in the Xcode category with the tag xcode 4. The following list contains the most widely read Xcode 4 tips from my blog:
- Accessing Build Settings
- Adding Command-Line Arguments
- Adding Frameworks to Projects
- Creating Custom Xcode 4 File Templates
- Creating Custom Xcode 4 Project Templates
- Downloading Xcode Without Using the Mac App Store
- Finding the Application You Built
- Setting the Active Build Configuration
- Using Makefiles
Many of the Xcode 4 tips also apply to Xcode 5. I also have tips specific to Xcode 5 on my blog. They are tagged xcode 5.
Creating Universal Binaries with Xcode 3
For those of you using Xcode 3, Apple has made it easy to create universal binaries that run on both Intel and PowerPC Macs. When you create a project, the Release build configuration is set up to create a 32-bit universal binary, and the Debug build configuration is set to create a 32-bit version of your program for your Mac's architecture. All you have to do to create a universal binary is change the active build configuration to Release by choosing Project > Set Active Build Configuration.
If you need to create a 64-bit universal binary, you must change the value of the Architectures build setting. Apple provides an option to build a 4-way universal binary that contains 32 and 64-bit versions of your program.
Xcode 3.2 Update
In Xcode 3.2 the Release build configuration builds a three-way universal binary: Intel 32-bit, Intel 64-bit, and PowerPC 32-bit. Xcode 3.2 does not support building 64-bit PowerPC programs.
Changing the Application Name for an Xcode Project
When you create an Xcode project, Xcode uses the project name as the title of whatever it builds. If you create an Xcode application project named MyProject, Xcode will create an application named MyProject when you build the project.
Suppose you're working on your application for a few weeks when you discover the perfect name for your application. You change the name of your project from MyProject to PerfectName, clean your project, and rebuild it. You expect to find an application named PerfectName in your build folder, but the application is still called MyProject. How do you get Xcode to build the project so the application name is PerfectName?
The answer is to modify the Product Name build setting, which you can find in the Packaging build settings collection. Product Name is the name of what Xcode builds, such as an application, a framework, or a library. Xcode initially uses the project name as the product name so when you look at the Product Name build setting, it will most likely be blank. Change the value of the Product Name to what you want, which would be PerfectName in this ongoing example.
When you change the Product Name build setting, you'll want to change it for the target, not the project. A target's build settings override the project's build settings. If you change the Product Name for the project, the change won't take effect because the target has the old name.
Supplying Launch Arguments for Command-Line Programs
If you look at the main() function in a C, C++, or Objective C program, you will see that main() takes two arguments: argc and argv. Java programs have one argument in main(): args. These arguments let you supply arguments to your program when it launches. If you wrote a program to play an audio file, you could supply the name of the file to play as a launch argument.
When you launch a command-line program from the Terminal application, you type the launch arguments as you launch the program. Xcode lets you run and debug command-line programs inside Xcode so you don't have to run the Terminal application. How do you supply the launch arguments from Xcode?
- Select the executable from the Groups and Files list.
- Click the Info button in the project window toolbar to open the executable's information panel.
- Click the Arguments tab in the information panel.
- At the top of the information panel, you will see a section titled Arguments to be passed on launch. This section is where you add the launch arguments. Click the + button to add the arguments.
Changing the Executable Name
When you create an Xcode application project, Xcode uses the project name as the name of the executable file. How do you change the name of the executable file? Change the target's Product Name build setting, which is part of the Packaging collection.
- Select the target from the Groups and Files list.
- Click the Info button in the project window toolbar to open the target's information panel.
- Click the Build tab in the information panel.
- Choose Packaging from the Collection pop-up menu.
- Enter the desired executable file name as the value for the Product Name build setting.
If you want to change the executable file name for all build configurations, make sure you choose All Configurations from the Configuration pop-up menu when you're changing the executable name. If you want to change the executable name for a single build configuration (Example: adding the word Debug to the executable name for the debug configuration), select that configuration from the Configuration pop-up menu.
Using External Text Editors with Xcode
There are lots of text editors available on Mac OS X. If you shelled out good money for a text editor, you want to use it to edit your source code instead of Xcode's editor. How do you tell Xcode to use your desired text editor to edit your source code files?
Choose Xcode > Preferences to open Xcode's preferences window. There is a toolbar at the top of the window with many buttons. Click the File Types button. From here you can assign the editor to use for lots of file types.
Initially there will be two items: file and folder. Click the disclosure triangle next to file. Click the disclosure triangle next to text because you're interested in text editing. The two most interesting subcategories are sourcecode and scripts.
When you come across a file type you want to edit with your text editor, select the Preferred Editor column for that file type. A menu will pop up. Choose External Editor. If your text editor does not appear in the submenu, choose Other. Navigate to the location of your text editor, and click the OK button. Repeat these steps for every file type you want to edit with your text editor.
Now when you double-click a source code file in Xcode's project window, it will open in your text editor.
Referencing Another Project in Your Xcode Project
In most cases you can get away with having multiple targets in a single project, but there are cases where your Xcode project may need to reference another Xcode project. Suppose you wrote a framework that you want multiple applications to access. Having one project that contains a target for the framework and every application would be hard to manage. What would work better would be to have each application in its own project and have each application project reference the framework project. How do you accompish this?
The solution is to create a cross-project reference. A cross-project reference lets your Xcode project access the reference project's targets and products. To create a cross-project reference, add the reference project's project file to your Xcode project by choosing Project > Add To Project. In the example from the previous paragraph, each application project would add the framework project's project file.
Adding Java Files to an Ant Project
When you create an Ant application project in Xcode 2.4, the Groups and Files list has a src folder, which is where the source code files are supposed to go. The project is set up so Ant compiles all the files in the src folder. Normally when you add files to an Xcode project, you can drag them where you want in the Groups and Files list. But if you add source code files to the project, you can't drag them to the src folder in the Groups and Files list. How do you get the source code files in the src folder so Ant will compile the files?
Go to the Finder and move the source code files to the src folder inside your project's folder. Choose Project > Add to Project in Xcode and select the files you want to add. After selecting the files you want to add, a sheet opens. Select the Copy Items into destination group's folder if needed checkbox.
Xcode will copy the files to your project folder. If you look at the Groups and Files list, the files will be in two places: the project folder and the src folder. You can delete the files in the project folder at this point. The source code files reside in the src folder and have been added to the project. You will now be able to compile the source code files you added.
Adding Descriptions to Your Project Templates
When you create a new Xcode project and select a project from the project list, a description of the project appears below the project list. If you create your own project templates, it would be nice to have descriptions of your templates appear when selecting them in the project list. Where do you put the description?
You put the description in the project template's TemplateInfo.plist property list file. This file resides in the Xcode project file's (the Xcode project you're using as a template) bundle. Control-click the project file in the Finder to open a contextual menu. Choose Show Package Contents from the menu to open a Finder window that shows the bundle's contents.
Double-clicking the TemplateInfo.plist file opens it in the Property List Editor application. Click the disclosure triangle next to Root. You should see a property named Description. The Description property's contents is what you will see when you select the project from the project list when you create a new project. Double-click the Value column for the Description property and type the project's description.
Save the TemplateInfo.plist file, and your description should now appear when you create a new Xcode project. If the description does not appear, you may have to relaunch Xcode.
Entering Input When Debugging Command Line Programs
When debugging a command line program with Xcode, one problem you may have is figuring out where to input data and read the program's output. If you open the debugging console window by clicking the Console button, you will be able to see your program's output, but you will get an error message any time you try to enter input in the console window. Where do you enter the input your program needs?
The answer is Xcode's standard I/O log. The standard I/O log works similarly to Xcode's run log when you run your program in Xcode without the debugger. Choose Debug > Standard I/O Log to open the log window. Now when you debug your program, you will see its output in the standard I/O log, and you will be able to input any data your program needs to run.
Uninstalling the Xcode Tools
Normally when you install a new version of the Xcode Tools over an existing version, the installation just works. But sometimes problems occur, and a symptom of installation problems is constant crashing. If Xcode is constantly crashing, a good thing to do is uninstall the Xcode Tools and reinstall them. You must take the following steps to uninstall the Xcode Tools:
- Launch the Terminal application.
- Go to the directory where the uninstall script resides. Type cd /Developer/Library (replace Library with Tools on Xcode 1 and 2) .
- Run the uninstall script. Type sudo perl uninstall-devtools.pl. You will need to know your account password to do the uninstall.
Now you can do a clean install of the Xcode Tools.
Creating a Matrix of Controls in Interface Builder
Interface Builder has a feature for Cocoa programs that I wish I had included in Xcode Tools Sensei. The feature lets you easily create matrices of controls, including buttons, checkboxes, text boxes, and radio buttons. To create a matrix of controls,
- Add the control to the window.
- Select the control.
- Option-drag to create the matrix.
To change the spacing between cells in the matrix, select the matrix and command-drag.
If a control cannot be part of a matrix, option-dragging creates a copy of the control instead of a matrix of that control.
Changing the Compiler Xcode Uses to Build Your Project
When you create a project in Xcode 2 that uses C, C++, or Objective C, the project is set to use gcc 4.0 as the compiler. If you want to build your project so it will run on Intel Macs, you must use gcc 4.0. But gcc 4.0 can cause you problems, especially for C++ programs. The C++ library changed from a static library to a dynamic library in gcc 4.0. Mac OS X 10.3.9 is the first version of Mac OS X that shipped with the dynamic C++ library. C++ programs compiled with gcc 4.0 will not run on versions of Mac OS X earlier than 10.3.9.
If you want your C++ programs to run on Mac OS X 10.3, you must tell Xcode to build your project with an earlier version of gcc.
- Select the name of your project from the Groups and Files list.
- Click the Info button in the project window toolbar to open the project's information panel.
- Click the Build tab in the information panel.
- Choose Customized Settings from the Collection pop-up menu.
- Click the + button to add a build setting.
- Give your new build setting the name GCC_VERSION_ppc and the value of the gcc version you want to use. To use gcc 3.3, give the build setting the value 3.3.
What you have just done is tell Xcode to compile the PowerPC version of your program with gcc 3.3. There currently is no need to change the Intel gcc version because Intel Mac apps must be compiled with gcc 4. But if you need to change the Intel gcc version in the future, the build setting GCC_VERSION_i386 specfies the gcc version to use for Intel Mac apps.
Getting Your Executable File to Run on Another Computer
One of the most common questions about Xcode I read on mailing lists and message boards involves people having problems running the programs they build with Xcode on another computer. Their program runs on their Mac, but when they move the program to another Mac, the program doesn't launch.
The culprit is ZeroLink. The first stage of building programs in compiled languages is compiling your source code files into object files. After compiling your source code files, the linker links the object files with the frameworks and libraries you added to your project. The linker links the object files, frameworks, and libraries into an executable file.
Xcode initially turns on ZeroLink for your project. When you turn on ZeroLink, Xcode skips the linking stage. The executable file doesn't have all the code it needs to run. When your program runs, the operating system loads code when it's needed. The code resides in your project's build folder.
The problem occurs when you move the executable file to another Mac. The code needed to run your program isn't in the executable file; it's in the build folder on your Mac. Because the code needed to run the program is on your Mac, the program won't launch on the other computer.
The fix is to turn off ZeroLink. The easiest way to turn off ZeroLink for versions of Xcode prior to 2.2 is to switch from the debug to the release build configuration. In Xcode 2.1 choose Project > Set Active Build Configuration > Release to change to the release build configuration. If you have an older version of Xcode, choose Project > Set Active Build Style > Deployment to turn off ZeroLink.
When you switch build configurations, you won't be able to debug your program. If you need to debug your program on other computers, don't change the build configuration. Turn off ZeroLink manually. The ZeroLink setting is in the Linking build settings collection.
Xcode 2.2 lets you easily turn ZeroLink on and off. Choose Build > Allow ZeroLink.
Using Resource Files with Xcode
I covered this topic indirectly in the book, but using resource files with Xcode and Project Builder has caused problems since Apple released Mac OS X so I decided to place the material here. Resource files were the way to store user interfaces before Mac OS X. They also can store pictures, sounds, and custom data. While nib files have replaced resource files for user interfaces, some programs (mostly Carbon programs) still need to use resource files. Xcode supports resource files, but it makes using them tricky. If you need to use resource files in your program, you must take the following steps:
- Give your resource files the extension .r or .rsrc.
- Add a Build Resource Manager Resources build phase to your target.
- Add your resource files to the Build Resource Manager Resources build phase.
When you give resource files the extension .r or .rsrc, Xcode compiles the resource files in your project, merges them into one resource file, and automatically opens the file when your program launches. If you use a different file extension, you must write code to open the resource file so you can load the file's resources.
The Build Resource Manager Resources build phase compiles the resource files in your project. Unfortunately, none of Xcode's project templates includes this build phase so you must add the Build Resource Manager Resources build phase to your targets. Choose Project > New Build Phase > New Build Resource Manager Resources Build Phase.
When you add a resource file to your project, Xcode adds the file to the Copy Bundle Resources build phase. The Copy Bundle Resources build phases just copies the files to the Resources directory in the application bundle. You must move your resource files to the Build Resource Manager Resources build phase.
Click the disclosure triangle next to a target in the Groups and Files list to see the target's build phases. Click the disclosure triangle next to a build phase to see the files in the build phase. Select a file and drag it to move the file to a different build phase.
Viewing Global Variables in the Debugger
Xcode does not automatically show global variables in the variable viewer of the debugger window. You must tell Xcode the global variables you want to look at.
- Open the global variables browser by choosing Debug > Tools > Global Variables.
- Select a library from the library list to see the library's global variables.
- Select the checkbox next to a global variable to tell Xcode to show the variable in the variable viewer.
Now your global variables should appear in the variable viewer during debugging.
acid Missing from CHUD Tools 4.2.2 Package
If you install the CHUD Tools 4.2.2 package, you'll notice that the trace tool acid is missing. To get acid back you must install the CHUD Tools 4.1.1 package, rename acid, and install 4.2.2.
- Go to Apple's Tools Download page and click the CHUD Tools link.
- A window with the various CHUD Tools packages will open in the Finder. Double-click the 4.1.1 package to install it.
- Launch the Terminal application, go to the directory /usr/bin, and rename acid.
- Install the CHUD Tools 4.2.2 package.
- Go back to the Terminal and change acid's name back to acid.