Researching Instruments for Xcode Tools Sensei allowed me to become familiar with most of the built-in instruments. Due to the high number of instruments, there was no way for me to cover them all in the book. I focused on the most commonly used instruments in the book. I can use this blog to explain some of the other instruments. I start with the OpenGL Driver instrument.

What the OpenGL Driver Instrument Does

The OpenGL Driver instrument records OpenGL statistics. Some statistics this instrument records include the following:

• The amount of free video memory.
• The number of textures used.
• The number of buffer swaps.
• The amount of time the CPU waited for the GPU.
• The number of surfaces the GPU allocated.

Obviously OpenGL applications are the ones to benefit from the OpenGL Driver instrument. The OpenGL ES Driver instrument records similar information for iOS applications. The OpenGL ES Driver instrument is available in both the OpenGL ES Driver and OpenGL ES Analysis templates. In most cases you should use the OpenGL ES Analysis template for OpenGL ES profiling.

One thing you’ll notice when you create a new trace document is there is no template for the OpenGL Driver instrument. Pick one of the other templates (Time Profiler and Empty would be good choices for profiling purposes) and add the OpenGL Driver instrument to the trace document by dragging the instrument from the Library to the instrument list. Click the Library button in the trace document window toolbar to open the Library.

Before You Trace

Before you start tracing you must tell Instruments the statistics to show in the track pane and detail view. Click the Info button next to the OpenGL Driver instrument to open a pop-up editor. Click the Configure button to see all the available statistics. Select the checkbox next to a statistic to tell Instruments to show it in the track pane and detail view. The extended detail view shows all the statistics so you should show only the most important statistics in the track pane and detail view.

The screenshot also shows where you set the sampling rate.

Trace Results

Use the Target menu in the trace document window toolbar to pick an application to profile. Click the Record button to start profiling. Click the Pause button to pause recording and see the statistics. The track pane graphs each statistic you told the OpenGL Driver instrument to observe.

The detail view at the bottom of the trace document window has one column for each statistic you told Instruments to show. There is one row in the detail view for each sample the OpenGL Driver instrument recorded. Selecting a sample from the list shows all the OpenGL statistics for that sample in the extended detail view. The extended detail view is on the right side of the trace document window. If you don’t see it, choose View > Extended Detail or click the right button in the View group in the toolbar.

Tags: xcode 4

I have seen several questions recently on Stack Overflow from people using the Allocations instrument in Instruments. When looking through the information the Allocations instrument provides, they have difficulty finding the areas of their code responsible for the memory allocations. Answering questions on this topic several times on Stack Overflow tells me it’s time to make a post about finding where your application allocates memory.

There are three views in Instruments that can help you find the parts of your code that are allocating large amounts of memory: the extended detail view, the call tree view, and the source view.

Extended Detail View

When you select a memory allocation from the detail view, the extended detail view shows the call stack for that memory allocation. Examining the call stack can help you find the function in your code that makes the memory allocation. To open the extended detail view, choose View > Extended Detail or click the right button in the View group in the toolbar.

Call Tree View

The Allocations instrument initially shows the table view, which tells you memory allocation statistics. Switching to the call tree view can help you find where your application allocates memory. Use the jump bar to switch to the call tree view.

To the left of the call tree view is the Call Tree collection of checkboxes. Selecting the Invert Call Tree and Hide System Libraries checkboxes can help you quickly find your code in the call tree view.

Source View

Double-clicking one of your functions from the extended detail view’s call stack or the call tree view opens the source view. The source view highlights the lines of code in the function that are allocating memory and tells you the amount of memory allocated. More information on the source view is available in the Instruments Source View post, but keep in mind that some parts of the post do not apply in Xcode 4.

This post contains the material on custom project templates I had prepared for the book. The material was not strong enough to put in the book, mainly because creating custom project templates manually in Xcode 4 is difficult (much more difficult than in previous versions of Xcode) and not documented by Apple. I had a difficult time getting a simple project template to work. But there is not a lot of information available on creating Xcode 4 project templates so I’m making what I wrote available here. I hope it helps you create your own project templates.

For more information on Xcode 4 project templates, look at Apple’s templates and read the following articles, which you’ve probably read if you’ve done a Google search for creating project templates in Xcode 4:

A minimal project template for Xcode 4

About XCode 4 Project Template (How To Create Custom Project Template)

Project Template Contents

At a minimum a project template consists of two items: a folder with the extension .xctemplate and a property list file named TemplateInfo.plist. You can also have additional files like icon files, source code files, and xib files in the project template. Place these files and the property list file in the template folder.

The .xctemplate extension defines the folder as a template folder. The name of the folder is the name that appears in the list of templates for the selected category in the New Project Assistant. The name of the folder is the name of the template.

Apple’s Project Templates

I recommend duplicating the TemplateInfo.plist file from one of Apple’s templates and using that copy as your TemplateInfo.plist file. You can find Apple’s iOS project templates in the following location:

Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/Project Templates

The rest of Apple’s project templates are in the following location:

Developer/Library/Xcode/Templates/Project Templates

Developer is where you installed Xcode 4.

Open the TemplateInfo.plist file in Xcode to modify it. I’m going to cover the keys in the TemplateInfo.plist file later in this post.

Moving the Template Folder

For Xcode to find your project template you must move the template folder to the user templates folder, which is in the following location:

/Users/Username/Library/Developer/Xcode/Templates/Project Templates/GroupName

You may need to manually create some of the folders in the path to the user templates folder. GroupName is the name of the category on the left side of the New Project Assistant. You can create your own group name or use one of the built-in names. Your project template will appear in the GroupName category.

TemplateInfo.plist Keys

The TemplateInfo.plist file has the following keys (this may not be an exhaustive list) for project templates:

• Ancestors
• Concrete
• Definitions
• Description
• Identifier
• InjectionTargets
• Kind
• MacOSXVersionMin
• Nodes
• Options
• Platforms
• Project
• SortOrder
• Targets

Your template does not have to use all these keys. The data type for the keys is usually one of the following: Array, Boolean, Dictionary, or String.

Ancestors Key

The Ancestors key is an array of strings. The strings are the identifiers of the project templates your template inherits from. If your template has no ancestors, you can ignore this key.

Suppose your template inherits from Apple’s Cocoa Application template. You want the same options the Apple template has to create a document-based application, to use Core Data, and to add a unit testing bundle. In this case you would need to inherit from Apple’s document-based application, Core Data application, and CoreDataSpotlight application templates. You would add the following ancestor values to your template:

com.apple.dt.unit.cocoaDocumentBasedApplication

com.apple.dt.unit.coreDataApplication

com.apple.dt.unit.coreDataSpotlightApplication

Concrete Key

The Concrete key is a Boolean value. You must set the Concrete key to YES for your template to appear in the New Project Assistant.

Definitions Key

The Definitions key is a dictionary. This key allows you to add comments, includes, and code to source code files. It also allows you to create groups from files or folders in an Xcode workspace. If you use the Definitions key to create groups, you must also have a Nodes key in your project template.

Description Key

The Description key describes the project template. The contents of the Description key appear at the bottom of the New Project Assistant when you select the project template.

Identifier Key

The Identifier key is a string value that uniquely identifies your template. It takes the following form:

com.CompanyName.TemplateName

InjectionTargets

The InjectionTargets key is an array of strings. The strings are the identifiers of project templates. The InjectionTargets key is a new key, which didn’t exist when I originally researched custom project templates. A Google search turned up no results. You’re on your own.

Kind Key

The Kind key is a string value. It should have the following value:

Xcode.Xcode3.ProjetTemplateUnitKind

If you inherit from another template, you shouldn’t have to specify the Kind key.

MacOSXVersionMin Key

The MacOSXVersionMin key is the earliest version of Mac OS X that can use the template.

Nodes Key

The Nodes key is an array key that creates a file in the project. Add a string key for each file you want to be created in the project. The value for the key is the name of the file.

Options Key

The Options key is an array that lets you add controls to the New Project Assistant. An example of a custom control is the Type pop-up menu for command-line tool projects that lets you choose the language for the project. The Type menu is an example of a custom control.

Create a dictionary key for each control you want to add. Add keys to the dictionary key. The following are common keys for controls:

• Type identifies the type of control. Pop-up menus should use a value of popup. Checkboxes should use a value of checkbox. Text fields should use a value of text. Combo boxes should use a value of combo.
• Name is the label for the control.
• Description contains tool tip text for the control.
• Identifier is a string that uniquely identifies the control.
• Default is a string that provides a default value for a control.
• Values is an array that contains the entries for a combo box or pop-up menu.
• Required is a Boolean key that says whether a condition has to be true for the control to be enabled.

You can see an example of the Required key if you create a Cocoa application. The Document Extension text field is disabled unless you select the Create Document-Based Application checkbox. If you use the Required key, you must add a RequiredOptions dictionary key that contains the conditions.

Platforms Key

The Platforms key is an array of strings that identifies the platforms the template works on. A Mac project template has the following value:

com.apple.platform.macosx

An iOS project template has the following value:

com.apple.platform.iphoneos

Project Key

The Project key is a dictionary key that contains build settings. For those of you creating project templates for personal use, I recommend using a configuration settings file instead of placing build setting values in the project template. A reason to add build settings is if you want to add libraries to the project template. Add a build setting for linker flags and add the flags for the libraries, such as -lLibraryName.

If you use the Project key to place build settings in the project template, you will most likely need to create additional dictionary keys inside the Project key. Create a Configuration dictionary key for configuration-specific build settings. Inside the Configurations dictionary, create Debug and Release dictionaries. Place your configuration-specific build settings inside the Debug and Release dictionaries. Create a SharedSettings dictionary for any build settings that apply to all build configurations. Place any build settings that apply to all build configurations inside the SharedSettings dictionary.

SortOrder Key

I’m not exactly sure what the SortOrder key does. I haven’t seen a sort order value other than 1 in Apple’s templates.

Target Key

The Targets key is an array key you use to add frameworks, libraries, build phases, and build settings to the template. The build settings you add to the Targets key apply to the target while the build settings you add to the Project key apply to the project.

To add frameworks to the template, add a Frameworks key to the Targets key. The Frameworks key should be an array. Add string keys to the Frameworks key. The value of a string key is the name of the framework. None of Apple’s project templates use a library so I don’t know what you have to do to add a library to the Target key.

To add build phases, create a dictionary key named BuildPhases. Add a dictionary key for each build phase you want in the project template. At a minimum you need to add a Class string key to the dictionary key that contains the name of the build phase. Use the following values:

• Sources is the name for the Compile Sources build phase.
• Frameworks is the name for the Link Binary with Libraries build phase.
• Resources is the name for the Copy Bundle Resources build phase.
• CopyFiles is the name for the Copy Files build phase.
• ShellScript is the name for the Run Script build phase.
• Headers is the name for the Copy Headers build phase.
• Rez is the name for the Build Carbon Resources build phase.

Tags: xcode 4

In Xcode 4.2 when you add a new Objective-C test case class to your project and click the Next button, you will see a Test Type menu. This menu has two choices: Application and Logic. The menu determines the unit test Xcode adds in the class’s implementation file. If you choose Application, Xcode adds a test for the application delegate. If you choose Logic, Xcode adds a dummy test that asserts 1 + 1 = 2.

It doesn’t matter what you choose from the Test Type menu. You’ll probably delete the unit test Xcode creates and add your tests. You can add your tests to both test types.

Tags: unit testing, xcode 4

Xcode 4 adds support for tabbed editing. When using tabbed editing you most likely want Xcode to open a new tab when you open a file from the project navigator. To get this behavior you must tell Xcode to open a new tab when you double-click a file in the project navigator.

Open Xcode’s preferences. Click the General button. Choose Uses Separate Tab from the Double Click Navigation menu.

Now when you double-click a file in the project navigator, Xcode opens the file in a new tab.

Tags: xcode 4

I am happy to announce that the print version of Xcode Tools Sensei is available. Go to the book’s site to buy it. The print version of the book will also be available on Amazon soon. I submitted the book to Amazon last night and was told it would take 5-7 business days for it to appear on Amazon. This means the book should be on Amazon late next week or the week after that. I will add a link to the book’s Amazon page when the book is available on Amazon.

Tags: xcode book

This post contains the material on custom file templates I had prepared for the book. I decided not to put this material in the book because it wasn’t strong enough for me to support. But information on creating custom file templates in Xcode 4 isn’t easily available so I’m making it available here. I hope it helps you create your own file templates.

File Template Contents

At a minimum a file template has the following items:

• A folder with extension .xctemplate
• A property list file TemplateInfo.plist
• The file itself, which usually has the name ___FILEBASENAME___ (triple underscores)

File templates can also include additional files, such as xib files and icon files.

The .xctemplate extension defines the folder as a template folder. The name of the folder is the name that appears in the list of templates for the selected category in the New File Assistant. The name of the folder is the name of the template.

The extension for the ___FILEBASENAME___ file depends on the language. If you create a C, C++, or Objective-C template, there may be a second file for the header file.

Apple’s File Templates

The easiest way to create a custom file template is to copy one of Apple’s templates and modify it to suit your needs. Apple’s file templates also provide good examples that you can study to help you build your own templates. Apple’s iOS file templates are in the following location:

Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File Templates

The rest of Apple’s file templates are in the following location:

Developer/Library/Xcode/Templates/File Templates

Developer is where you installed Xcode.

Making Changes to Existing Templates

After creating a copy of one of Apple’s templates, you must modify the files to customize them. Open the ___FILEBASENAME___ file and the TemplateInfo.plist file in Xcode to make your changes. I’m going to cover the keys in the TemplateInfo.plist file later in this post.

Moving the Template Folder

For Xcode to find your file template you must move the template folder to the user templates folder, which is in the following location:

/Users/Username/Library/Developer/Xcode/Templates/File Templates/GroupName

You may need to manually create some of the folders in the path to the user templates folder. GroupName is the name of the category on the left side of the New File Assistant. You can create your own group name or use one of the built-in names. Your file template will appear in the GroupName category.

TemplateInfo.plist Keys

The TemplateInfo.plist file has the following keys (this may not be an exhaustive list) for file templates:

• AllowedTypes
• CounterpartTemplateFile
• DefaultCompletionName
• Description
• Kind
• MainTemplateFile
• MacOSXVersionMin
• Options
• Platforms
• SortOrder
• Summary

Your template does not have to use all these keys. The data type for the keys is usually one of the following: Array, Boolean, Dictionary, or String.

AllowedTypes Key

The AllowedTypes key is an array that contains allowed file types. Source code file templates use this key. The following are examples of common allowed types:

• public.objective-c-source (Objective-C)
• public.objective-c-plus-plus-source (Objective C++)
• public.c-source (C)
• public.c-plus-plus.source (C++)
• public.c-header (header file for C, C++, Objective C)
• public.ruby-script (Ruby)
• public.python-script (Python)
• com.sun.java-class (Java .class file)
• com.sun.java-source (Java .java file)
• public.xml (XML)
• public.source-code (generic source code)

Use the public.source-code type for languages other than the ones I listed.

CounterpartTemplateFile Key

Only languages that have header files use the CounterpartTemplateFile key. Supply the name of the header file.

DefaultCompletionName Key

The DefaultCompletionName key contains the initial name for the file. When you save the file for the first time, this name appears as the file name in the Save panel.

Description Key

The Description key describes the file template. The contents of the Description key appear at the bottom of the New File Assistant when you select the file template.

Kind Key

Text files have the following Kind key value:

Xcode.IDEKit.TextSubstitutionFileTemplateKind

MainTemplateFile Key

The value of MainTemplateFile should be the name of the file in the .xctemplate folder. It generally has the following value:

___FILEBASENAME___.Extension (triple underscores)

Where Extension depends on the type of file you’re creating. For C, C++, and Objective-C files, the main template file is the implementation file, not the header file. The extension for an Objective-C file is .m.

MacOSXVersionMin Key

The MacOSXVersionMin key is the earliest version of Mac OS X that can use the template.

Options Key

The Options key is an array that lets you add controls to the New File Assistant. You can see an example of a custom control if you add an Objective-C class to a project. When you add an Objective-C class, there is a combo box that lets you choose the subclass. The combo box is an example of a custom control.

Create a dictionary key for each control you want to add. Add keys to the dictionary key. The following are common keys for controls:

• Type identifies the type of control. Pop-up menus should use a value of popup. Checkboxes should use a value of checkbox. Text fields should use a value of text. Combo boxes should use a value of combo.
• Name is the label for the control.
• Description contains tool tip text for the control.
• Identifier is a string that uniquely identifies the control.
• Default is a string that provides a default value for a control.
• Values is an array that contains the entries for a combo box or pop-up menu.
• Required is a Boolean key that says whether a condition has to be true for the control to be enabled.

Platforms Key

The Platforms key is an array of strings that identifies the platforms the template works on. A Mac file template has the following value:

com.apple.platform.macosx

An iOS file template has the following value:

com.apple.platform.iphoneos

SortOrder Key

I’m not exactly sure what the SortOrder key does. I haven’t seen a sort order value other than 1 in Apple’s templates.

Summary Key

The Summary key summarizes what the file template does. The summary is a shorter form of the file template’s description.

Tags: xcode 4

If you build a SDL OpenGL application for Mac OS X using SDL 1.2.14 (using the binary installer at the SDL site) and the Mac OS X 10.7 SDK, you can get the following error:

typedef redefinition with different types ('unsigned int' vs 'void *')

The SDL header file SDL_opengl.h and the OpenGL header file glext.h both define a data type GLhandleARB. SDL_opengl.h defines it as an unsigned integer. The Mac OS X 10.7 version of glext.h defines it as a void pointer. Defining GLhandleARB as different data types in different header files causes problems.

The SDL team fixed the problem in their Mercurial repository. The fix is not too difficult to apply. In your SDL_opengl.h file, change the following line of code:

typedef unsigned int GLhandleARB;

To the following:

#if defined(__APPLE__)    

	typedef void *GLhandleARB;

#else    

	typedef unsigned int GLhandleARB;

#endif

The fix defines GLhandleARB as a void pointer on Mac OS X and an unsigned integer on other operating systems.

One of Xcode 4.2′s new features is compiler support for ARC (Automatic Reference Counting), which automates memory management of Objective-C objects. Xcode 4.2 includes a refactoring tool to convert an existing project to ARC. Choose Edit > Refactor > Convert to Objective-C ARC. When you convert a project to ARC, a sheet opens that walks you through the conversion. But there are a couple of problems that can occur.

Problem 1: Clicking the Save Button Does Nothing

In the last step of the conversion, Xcode shows the changes it will make to each file when it does the conversion. Clicking the Save button is supposed to complete the conversion, but you may find nothing happens when you click the Save button. The only way to close the sheet is to click the Cancel button.

You can get this problem if your project is in a git repository. Xcode is set to take a snapshot of your project when you convert it to ARC. But snapshots do not work well with git repositories. Xcode tries to take a snapshot, the snapshot fails, and Xcode stops the conversion.

The workaround is to move the .git folder out of your project folder temporarily, convert the project, and move the .git folder back. Files that start with a period are hidden by default in the Finder so you will either have to use the Terminal to move the .git folder or use a utility that shows hidden folders in the Finder.

Problem 2: Release Builds of Mac Projects Generate Build Errors

After converting your project to ARC, you may get the following error when you build your project:

-fobjc-arc is not supported with fragile abi

Xcode generates this error when you try to build a 32-bit version of a Mac application that uses ARC. ARC can build only 64-bit Mac applications. The Release build configuration is set to build both 32-bit and 64-bit Intel binaries. The error occurs when building with the Release build configuration because Xcode is trying to build a 32-bit version of your project, which ARC does not support. The solution is to set the Architectures build setting to 64-bit Intel.

Tags: xcode 4

The electronic version of Xcode Tools Sensei has been updated for Xcode 4.2. Go to the book’s site to buy it. You can also read the table of contents, introduction, and a sample chapter at the book’s site.

You may be wondering when the print version will be available. The release of the print book is weeks away. I have to layout the print book, create the index, and have a test copy shipped to me to make sure there are no glaring errors before I can release the print version.

Tags: xcode book