Good afternoon. Welcome to session 303. So on Monday you saw intro to Xcode. Yesterday you saw a little bit more detail about it, and today we're going to get into a lot more detail. So I hope you're ready. So I'm Anders Bertelrud, and I'd like to talk about some of the details of Xcode.

What we're going to talk about today, some of the things we'll cover are moving to Xcode. Some of you may have source code. Some of you may have old project builder projects. You may have code warrior projects. You may want to move that into Xcode. We're going to talk about optimizing build performance. As you know, the speed is a big theme of the Xcode discussion, Xcode talks in this conference, and we're going to be going into some of that.

We're going to talk about Xcode support for building for multiple OS versions from one and the same install. And also get into some issues of workflow and automation. We have several features for accessing documentation, for doing source code management, for automating your workflow in many ways. And the common theme among all of these things is time, right? This is all to save you time so that you can focus on your app and fixing your bugs and then shipping your product.

So moving into Xcode, there are several ways. And it's easy to get started. Many of you have probably already installed the developer preview for Panther and maybe played with Xcode, maybe installed it on Jaguar. There are many migration paths if you already have code. One of them is to create a new project using the new project wizard of the appropriate type, application, framework, whatever your product is, and then just add the source code that you have to the project.

Another way is to open an old Project Builder project. Xcode can seamlessly open Project Builder projects and build your targets, whatever you had in the Project Builder project. Of course, you can't make modifications that rely on Xcode-only features and then go back to Project Builder, but you can upgrade.

Also, we have a Code Warrior importer. Project Builder had this as well, but in Xcode it's been improved a lot. So we can bring in your source files, we convert your targets, and set a lot of the compiler options as well. And finally, a fourth way is if you have a make file, you can actually wrap an Xcode project around that.

You just set up a target to invoke your make file, and you can still take advantage of the editor, and you can take advantage of a lot of the features in Xcode, but you would let your make file or ant or jam or whatever you're using actually do the build.

So another important point is that if you bring in source code, let's say you bring in an old project builder project, you can actually convert each target individually. And we'll see how to do that, but you can leave the targets that work best as jam targets for now. You can take one target after another and convert them, and then gradually start taking advantage of Xcode's features.

And an important point is that some of the features we're showing, such as zero-link and fix and continue, are really only available for Xcode targets. We really rely on this new native internal build system to deal with this. So you need to upgrade your targets, convert your targets to take advantage of that. And if you create a new project or if you start with the samples, the new project templates are native targets by default.

So let's talk a little bit about some of the target types that Xcode supports. So first of all of course the native Xcode targets we talked about. We support applications, frameworks, libraries, plugins and the developer preview and we'll be extending this to all the different kinds of things you want to build, the kernel extensions, etc.

The project builder targets, you would still leave it as a project builder target if it's one of the few things we don't support yet, which are the kernel extensions, some of the Java types and of course you could leave your applications and frameworks as the old project builder targets as well, but then you wouldn't take advantage of the new features, so you'd want to upgrade.

And it's important to note we actually support external targets as well. So you could have any external build system you want. In fact, it might not even be a build system at all. Maybe it's just a shell script you want to invoke as part of your build. And it fits seamlessly into Xcode so you can have a native application target that depends on some custom shell script that you have.

Another important aspect of an Xcode project are the build settings. So the targets define what you want to build. And the settings are the little knobs and switches on that. It defines how you want it built. So they control the inner workings of a build. Do you want debug symbols or not? Do you want optimization or not? Where do you want the output file to go? That kind of thing.

They're usually set on a particular target. You've probably seen this in some of the earlier demos. We're going to get into more detail about that in a demo in this session. And you can also, though, set them on a build style, what we call a build style. So you can, for example, set up a build style for debug and another one for release.

You only need to have a single target for whatever you're building, say it's an application. But you can apply the different styles to build different variations. So the styles encode the things that are different between a debug and a release build. such as optimization level, debug symbols, those kinds of things.

And the settings in the build styles do override the ones at a lower level. We'll see a diagram here of how this fits together. But the basic point is, if you have a build style that says it turns on optimization, then that's going to override what your target says.

They're also passed in the environment for external shell scripts and for external tools. And this means that you can set options in your project and have those be passed down to whatever build system or tool that you're using, whether it's Make, whether it's a custom Perl script, things like that.

So how do these fit together? Well, as I mentioned, there's an ordering of them. And this is just kind of give you a flavor for some of the depth here of what you can set up. The environment variables, such as path and user and those kinds of Unix-y things are available at the lowest level, just like for Make. Above that, there are built-in settings. These are the defaults, things like where the default system locations for where frameworks go, the default optimization level for the compiler, that kind of thing.

The target settings are above that. This is what you see in the inspector, as we'll see in a demo in a little bit. And the build styles override that. So this is where you would say, turn on or off debug symbols for a particular build. The command line settings go above this.

These are not used in the IDE, but as you may know, and as we'll see later, there is an external command line tool that lets you build Xcode projects as part of a nightly build or as part of an automated process. So if you pass anything on the command line, just like with Make, it will override whatever your project said.

So build styles, what are they used for? Well, it's important to note that they dynamically override the target settings. They don't actually go and modify the target. So this is something that you pick in a pop-up menu, or you can choose it as the active build style. And it's just to avoid having to duplicate targets, because then you get into a situation where when you add a file, you're going to have to remember to add it to both your debug and release target, et cetera.

Some examples of this are the obvious ones, turn debug symbols on or off. But also, you may want to enable or disable zero link. Zero link is a feature that saves you a lot of time, but it also defers some potential link errors to the actual runtime. So if you know zero link works, it actually works by doing the linking as you load in each object file. You actually run the object files. And when that happens, if you have an undefined symbol, you may not find out until later.

So you may want to turn that off just to validate a build, and then turn it back on to get the speed benefit again. Other things you can do are to enable or disable alternate algorithms. Or if you have a demo version of your app, you may want to build a demo version with a save disabled, and then you build the full version also without having to have two separate targets.

One of the new features in Xcode compared to the older IDs that Apple has had are to user configurable build rules in a graphical way. So you can actually define how the build system maps particular file types to compilers in a very detailed way. And the way this works is that there is a list of rules, as we'll see in a little bit later. And the first one that matches is the one that gets applied. So you can define both specific and general rules and have the specific ones first, and then in that way you can control very fine grain level how your source files get processed.

In each rule can match two different things. It can either be a category of file types. Xcode has a built-in notion of various file types, Java source files, C++ files, res files, nib files, let's say. But you can also match any particular shell pattern, star.hc in this case matches anything with an extension of h or c. You can enter anything you want there. And in Xcode, you also use the rules to select the compiler version. So it's very easy to just go in and find the entries for the C files. You can pick between GCC 3.3 or GCC 3.1, let's say.

So now you've moved your project into Xcode, whether it's from project builder or by adding sources that you had separately. Let's talk a little bit about optimizing the build performance. Now, Xcode does have a fast, powerful build system, and it provides a lot of the speed benefits automatically.

So there's no dependency on external builds. We don't generate some text file that then has to get parsed by an external tool. Instead, Xcode just keeps track of the text changes that you're making to your source code or whether you add files to your project, and it automatically knows what you need to rebuild. So by the time you go to actually start a build, it's already done a lot of the work. It's tightly integrated with the user interface, so you see check marks for files that are out of date, et cetera.

However, there are still opportunities for you to tune your project. Xcode will automatically do things like predictive compilation, but you can also set up a precompiled prefix header for your project that can save a lot of time. That's something that Xcode doesn't really do for you because it depends on how your sources are laid out. You'll want to define that yourself.

You can also turn on parallel and distributed builds. Parallel builds are on by default, but distributed builds, you can access that in an easy way, but you need to enable that because we don't want to start sending your source code everywhere just without you knowing it. Zero link is something that is also enabled by default. Of course, you don't want that on for deployment, so there's fine-grained control over that, and the same for fix and continue.

So a word about precompiled headers. As you may have heard in previous talks, GCC 3.3 has a new precompiled header mechanism called PCH. And this is a lot better than the older ones because it supports C++ first and foremost, and it's also better implementation. These are easy to set up using Xcode's target inspector.

What you do is you define a prefix header for the common API. A lot of Carbon applications, for example, would start by including the Carbon.h header. Similarly, Cocoa apps may start by including Cocoa.h. So if you put this in a prefix header, precompile the prefix header, you can get really fast turnaround.

Keep in mind the prefix header gets included for all files in the target. So if you have C++ and C files, it needs to be compatible with both. This is easy to do with the #ifdef. We'll see that in the demo. And also keep in mind to only put headers that change relatively infrequently into the PCH because, of course, if they change, then the precompiled header will need to be recompiled. Now, Xcode knows about all the dependencies and the inclusions, so it will automatically recompile the prefix header for you, but that still takes extra time. So you wouldn't want to put anything in there that changes a lot.

Distributed builds is another new feature that we're really excited about. Xcode can take advantage of multiple processors in your machine, of course, but your neighbor in the cubicle next to you has that G5 sitting there, and he's surfing the web, and yeah, you really want to compile on that machine, actually.

So what you can do is you can take advantage of, in effect, instead of a two-processor system, you can have an end-processor system, right, where end is the sum of all the CPUs and all the different machines that you choose for distributed builds. So it can be distributed to other machines, and there's two modes. There's what we call sort of the free love mode, which is where it uses rendezvous to just see, oh, is there anybody out there who has said that they want to be a distributed build server? And if so, okay, well, we'll send it.

We'll send them our files, right? But for a more controlled environment, you may want to just specify a list of servers, for example, the ones that are known to be in your team's department in a lab somewhere or something. And a note about this is it does require GCC 3.3 and Xcode targets. So here's another reason to upgrade to upgrade an imported project builder target to be an Xcode target.

Zero Link is another feature designed to save you time. We found that link time is a significant part of the turnaround time. And not so much for a full build, but when you do the edit debug build cycle, you spend a lot of time watching it say linking this and that. So Zero Link takes advantage of the fact that typically when you make edits, you edit, let's say you have 100 files, you edit a couple of them, and then you want to link again.

Well, then it has to read all those files back in, generate the binary, et cetera. So what we've rather do is just leave those other 98 files alone, just load them off of the disk when the application starts running. So again, it eliminates the link step by running directly. And this is on by default in the development build style. So while you're doing day-to-day development, you get Zero Link by default for a native target. The deployment build, of course, you get a real binary because you don't want to actually ship your object files.

With Fix and Continue, this is another feature that's mostly automatic. It lets you fix things while you're debugging. And as we've seen in some of the previous demos, you don't even have to stop at a breakpoint. And for simple logic errors, this can be a real time saver. It's enabled by default. You can turn this one off too if you want. There's no real reason to turn it off, but we want to give you lots of control over these things. And with that nifty search field now in the inspector, there's no real reason not to.

This is great for localized changes. You don't want to change things that have global effect, like the size of a struct, but logic errors, off by one errors, that kind of thing works great. So I'm going to ask Scott Tooker to come up on stage and demo some of these things.

What I'm going to go through today is, we've already gone through this in previous sessions, but we want to take another pass through the target settings and give you kind of a deeper feel for how to set up your target, both just the settings you want to set and also some tips and tricks for the precompiled headers, how to set that up properly. We'll also look a little bit at the build styles and at build feedback, a little bit more in depth on that. So let me bring up my project.

So the first thing I want to do is just point out that the way it works is that we just bring up the inspector on the target, and there are four parts to this inspector. There's this general tab where you have your name of the target and the product, and notice that the name of the target can be different than the product, and also the target dependencies. This target doesn't have any at this point. There's the build tab, which I'll get back to later in just a bit, and this is kind of the meat. This is where all the settings go. There's also the rules that was talked about earlier.

This is where you can set for a given type of file, you know, what do you want to use. And as pointed out, you can also create your own, and you can reorder them how you like. And then finally there's the properties. So for those applications that are, for those targets that produce bundles like applications and frameworks, here's where you can set stuff that would normally go in your info key list, like your bundle identifier, an icon, or document types in the case of an application. And just note that we also do support, for example, opening up the Info.plist as a file so you can directly edit it.

But let me jump back here to build. And as I said, this is the meat of the target inspector. This is where all your settings are. So you'll notice here we're looking at the common settings. These are settings we expect you to change often. There are things like, okay, I want to enable C++ exceptions, or I want, maybe I have a style of library or my header search paths. But there's much more than this. Let me just open this up.

We actually have several groups here. Many are static, but there's actually one dynamic group that I'll get to in a second. So you'll notice here we have kind of our standard build settings. These are settings that aren't bound to a given compiler like GCC or a tool like Res.

They may apply to multiple tools, or they may just be something that's specific to Xcode itself. We also have GCC settings, and we have some resource manager settings. And then for these groups, we also provide some subdivisions. And as you can see, we also show the subdivisions in some cases by different icons next to the warnings, next to the settings. Let's talk a little bit more about the actual UI itself. So let me go back to the common settings. And you'll notice here what we provide. If I select one of these guys, we actually provide descriptions.

Because one thing we noticed when we looked at environments is that, especially when dealing with things like GCC, but also other environments, sometimes the settings can be very cryptic. And you as a developer may not know or really need to know what all these things mean. And so we wanted to provide descriptions to make it easy for you to get a little bit of background on, OK, if I check this on, what is it going to do to my code? Also, as you can see, especially if I go to, for example, the GCC settings, there are quite a number of them. And so we wanted to provide a quick way that you could get to just the settings you want, even if you didn't know exactly what it was called. So, for example, if I want to find out about, let's say, prefix files, I can say prefix.

Now, it's interesting. You'll notice here, okay, this has prefix, this has prefix, but effective C++ violations, what's going on there? Well, if I click on it, and if you go through here, what you'll find out is it's actually referencing the prefix in the description. So, this isn't the best example, but another example is, for example, if I wanted to do something with type ID, which has to do with RTTI.

It actually picks it up right here. So this way you don't have to know exactly what it's called, you just have to kind of know what you're looking for. So we hope that this will make it a lot--we believe this will make it a lot easier for people when they need to set those types of target settings.

The one last thing I want to talk about was this current settings. You'll notice that it has the same kind of icon as some of our smart groups over here have, because it's actually a smart group. What the current settings contains-- let me get rid of that. What you see is all those settings that you've set on your target that are different from the defaults. So it's kind of like a very convenient filter because if you went to go back and look at common settings or the GCC settings, you'd see a bunch of things.

But some of these may be things you've never touched and never want to touch. These are the actual settings that you have changed from the defaults. So it gives you a quick look to see, okay, what's different about my target from what a default stock target would give me.

So at this point, I'm going to close this. And I want to talk a little bit about build styles, which was talked about earlier. One of the problems we're trying to solve with build styles is that you want to be able to just override one thing in your target.

And we've seen some environments where you'll have to have three different targets that all build the same exact thing, except maybe they have a different optimization style. So what we've implemented are these build styles. And we have two by default in every project. One is the development style, and one is the deployment style.

And so you can see here it's the same UI as the target editor. And I'm not going to go into that, but one small thing I wanted to mention was sometimes you want to add your own custom flag build settings for whatever reason. You may need to reference them in a script, for example. And this is very easily done by just clicking this little plus button. I can just type, you know, my build setting. And then you can put in the value.

And just as easily, if you want to get rid of something, you just go down here and hit the minus button. It goes away. And then one final thing is in this project inspector where we have the build styles, we also allow you to indicate for a given project you may want to build it into a separate location like we're doing here. This provides some cleanliness, but also it can leverage our build system. If you build a lot of projects into a common location, we can actually do some stuff to use those things together. So let me close that.

So now let's talk just a second about the prefix file. So it was mentioned earlier you can create these precompiled prefix header files. Well, the way this works is if I go to the build-- let me search for prefix. We have two settings. One is the prefix header. And you'll notice here it's qt._prefix.h. And we just check on the precompile prefix header. And to show you what a common prefix header looks like, let's go over here.

This is my Qt prefix.h. You'll notice that this is fairly simple. Remember that because your prefix is implicitly included before every file, you do need to be careful because, for example, these are all C++ files that are being -- these are all headers with C++ that are being implicitly included.

But if I was to include this, say, from a C file, I don't want these headers to be implicitly included because it could cause problems. So remember to use these guards here, this ifdef, C++, ifdefc. But it does provide a lot of flexibility because you can then have different sets of headers that get included for different types of files.

Now finally, let's go ahead. I'm going to build and run this to just talk a little bit about our build feedback. Well, yeah. Well, one, our single file builds are really fast. Two, you saw there for just a second it said the build failed. Well, one thing I can do is we have this detailed build window where I can go and I can say, "Oh, look.

I had errors while compiling this file here. I have two warnings and I have a series of errors." And that's one place I can go. But there's actually places that are even more common you can look at. We actually have this errors and warnings smart group that if I click it pops up with a window that at the top has a list of all the errors and warnings.

And then even just with the keyboard I can go through this list and it'll jump me around to the various errors and warnings. And if I want this in a separate window, all I need to do is double click the errors and warnings. And there you go. There's a separate window. I can just track it over there. And then finally, in a given file, let me go to, for example, this warning right here.

You'll notice right here we have the warnings and the errors in line. And if you actually click on them, we'll show you in the status bar, okay, this is what the warning said. So in this case, they're relatively easy to fix. Turns out I forgot a semicolon and mislabeled something. And then you can just go on your way. Back to you, Anders. ANDRES BORUCH: OK. Thanks, Scott.

All right, so that was just showing you where to actually set some of these flags that we talked about in the slides earlier. So I'm going to switch gears a little bit, talk about building for multiple OS releases. So you now have the nice Panther Preview CD in your bag.

Well, you also have the shipping Jaguar OS, and you may want to deploy for 10.1 also. So Xcode lets you build for multiple OS releases, but still be booted off of one release. This also saves you time, of course, because you don't have to set up multiple partitions and install on multiple partitions, and then rerun. So a typical example is you might want to run the Jaguar version of Xcode, but then you actually use the Panther APIs, Panther Preview APIs.

Each target can individually specify the minimum and the maximum OS. And the minimum version of the OS is the minimum that you require your customers to have to run it. So features on that version will be assumed to be available. Now, the maximum version specifies the version for which you want to take advantage of features. So let's say your minimum is Jaguar, your maximum is Panther.

You want to be able to take advantage of Panther features, but you want to do so in a fail-safe way. So if the feature is not available, you just don't call it. So, and the Xcode Developer Preview supports 10.1.5. It has SDKs for 10.1.5, 10.2.6, and for the Panther Preview. And this is the developer CD for both Jaguar and Panther.

The APIs for each OS release are packaged in an SDK. So what does one of these SDKs contain? Well, it's a folder that just has the headers and stub libraries for that version of the OS. So you actually get the same headers as you would on an install with developer packages.

SDKs can be added independently and removed independently. They can be rather large since they contain all the headers and the stub libraries for a particular version. So you can add them after the fact or you can remove them if you decide that you don't need, for example, 10.1.

And one of the things that happens when you set the minimum and maximum OS version you want to target is that special macros are set. These are documented in more detail in the help pages, but you can then use the macros in your code to check which functions are available, which functionality. You can use them at runtime to check whether a particular function pointer is nil and then just not call that. So this way you can take advantage of new features and still support older releases.

Another thing Xcode has is what's called source tree support. You may have external sources such as Power Plant or the QT frameworks or other large source bases that are not part of your project, but they're installed someplace on your machine that someplace may be different for each developer.

So what each developer can do is to set up just a single source tree to point to a place on disk and say, okay, here's where my QT sources live, here's where my Power Plant sources live, and then the project can just reference that and access them that way. The source tree can refer to the source base using either relative or absolute paths. So you can nest projects inside of folders that group the source trees and the projects. Or you could put the source base. an absolute place on disk.

This feature is used by the Code Warrior importer when it imports a project that uses, for example, Power Plant. It will actually find Power Plant on your disk and set up a source tree to that. So, you don't have to copy the sources in or carry those along or anything.

So we talked a little bit about build and about how to configure your project to take advantage of some of the speed improvements there, such as setting up a prefix header, precompiled prefix header. We talked a little bit about the OS support. We also have some workflow and automation features that you might not be aware of and that you probably haven't seen in any demos so far. So some of the stuff we've shown so far has been talked about in previous sessions, but the second half here are some kind of pearls that haven't been talked about yet.

Source code management, we've been mentioned a little bit in previous sessions. Xcode is tightly integrated with the SCM support. So we have built-in support for CVS and Perforce. And it's not just a menu that you pull down and you can access all the features there. We actually show the information about the SCM state in line along with the files. It's a lot more integrated.

And we support the day-to-day operations such as adding, removing files, changing files, updating files, that kind of stuff. You can also compare. You can look at the history. You can open the inspector on a particular file and you can see the source code management history. You can see who checked in, what changes, and when. And you can actually select two revisions and compare them graphically in a tool called File Merge.

Some of the other things we leave to external repository management systems are creating new repository and things like that. We also have very good documentation access. That's also part of productivity and speed, is getting quick access to your documentation. And you look at this function with five arguments and you need the details of that really quickly.

We have API look up, which searches as you type. You may have seen in previous demos and probably see soon again maybe how we can quickly narrow down a large list of symbols of documentation pages for the APIs. Mac OS X, as you know, has a very rich set of APIs.

In fact, there are multiple sets of APIs, Cocoa, Carbon, et cetera. So you can focus on any one of those or more than one, or you can search through them all and quickly look for what you want to find. The full text search is better for things like the conceptual documentation where you may have a phrase or a concept, in mind, and you may just try out a couple of phrases until you get the hits that you want.

So what's available in this area? First of all, there's help for Xcode itself. That's available from the Help menu, as we'll show in a minute. We also have access to the full documentation for Carbon, Cocoa, I/O Kit, et cetera, all the reference documentation. If you need information about a specific method or function or class, it's just a couple of mouse clicks away. Sun's Java documentation is also available. The Mac OS X man pages are available. We're based on BSD, and all those man pages are available right there in Xcode.

Another aspect is scripting and automation. So you access the documentation and you can certainly do that through, let's say, man on the command line. You could do that through the built-in documentation support. You could also use scripts to set up custom queries or that kind of thing. There are several levels of automation here. Xcode itself is scriptable. Project Builder was not. That was the previous IDE. Xcode is actually scriptable from the ground up.

There is a command line build tool also so that you can use that in your nightly builds. Let's say if you have a batch build that occurs every night that pulls 15 projects together and builds them with special options, you could do that. The command line build tool is actually linked against the same framework that the Xcode is. It's called Xcode IDE users so it has exactly the same code paths for building and all that. It has access to the entire build system.

There is a user scripts menu which is, this was an MPW feature that was requested and it's been added. You can add custom menu items tied to your own scripts. And we also have MPW inspired worksheet functionality. So we'll talk a little bit more about these. The scriptability, as I mentioned before, you can actually have access to Xcode's object model through Apple script. You can change target settings and multiple targets, add files to targets, add to projects, those kinds of things. You can also start and stop builds using Apple script if you want.

There are still, I should say, there are still a couple of things that are not supported. Some of the details, for example, not every property of every object, but we're working on adding that because we want Apple's scriptability to be a very full-featured way of accessing Xcode's functionality.

Another way to automate things is to build from the command line. So you may have a build that starts at 2:00 AM at night. There's a tool called pbbuild. This is kind of for historical reasons to provide compatibility with some scripts. It provides access to the IDE, and as I mentioned, it uses the exact same build system as the IDE does. So you have access to all the same features.

This ties in a little bit to the worksheet functionality we have. This is another NPW-inspired feature. As Ted mentioned in the overview for Developer Tools, there's a great legacy of Developer Tools here. We wanted to make sure we brought forward some of the pearls that people have really liked in previous IDEs.

So Xcode has NPW style worksheet functionality. And what this means is you have a text file. You can select one or more commands and just execute them as if you typed them in a terminal or a shell. And one of the nice ways to use this is that you can save frequently used snippets of shell code or even Perl code or Apple script just in a text file and then run it whenever you need to.

It also is nice because unlike terminal, it preserves the history independently. So you can come back to a command and its output that you ran maybe half a year ago, right? And you can see what the output was and you can compare things that way. We'll see some of this in the demo. And again, the results here are pasted back into the text buffer. So it's an iterative worksheet experience. So to help demo some of these features, I'm going to ask Matt Morse to come up on stage.

Well, as Anders has pointed out, there's a wealth of documentation on the system. There are over 500 books of various scope from small topics all the way up to the human interface guidelines. And besides that, there's over 75,000 bits of reference documentation for the APIs that are available in the libraries on your system. So this is a great wealth of documentation. The challenge is to get to the piece of documentation that you need quickly.

So I'd like to show you some of the ways you can do that in Xcode. Xcode has a documentation window. Well, first there's help available through Xcode help. And the documentation window is available also from the help menu. So you bring up the documentation window. It has a look very much like the project window with your groups over here.

In this case, the groups are sections of the documentation, the entire installed library and subsections that focus on particular technologies. As you see, as I'm selecting the different subsections, the technology home page appears in the content area. And from there you can burrow in and find the documentation you want if you want to browse in that way. A navigation note that I think you should know is you can command click any link to bring up the documentation in a separate window, and you can option click to bring it up in your browser.

OK, so that's one way to navigate through the documentation if you're browsing. Up here, you've seen this area updating as I was clicking as well. This is the results of a search for the API symbols that So, to focus on a particular symbol, just start typing its name and you quickly go from the entire universe of 75,000 available symbols down to the few that match what you're looking for. And in this case, let's say you were looking for the groups method.

and clicking that brings it up in the content area. Another navigation note is take a look at the symbol pop-up. It's just like in the code editor. You can easily get around the documentation for a class using this. OK. I think I should mention this was shown in the overview session as well, but you can turn off any of these columns, titles that you don't find useful.

and customized it for the way you like to get around it. OK, so that's the API search mechanism. You can also do a full text search, as you could in Project Builder, on any of the sections here that you have selected in your library. So that's the documentation window, but often the quickest way to the answer you want is directly from your code editor. So let's take a look at a project.

Bringing up some source code here. Getting down to something interesting. You can, if you want to look up the documentation for a specific symbol or class method, just option click it. And if there are multiple destinations, as you see, you get a menu to select from. If you wanted to see the documentation for NSString, just pick that. Likewise, you can control click to bring up the full text search feature to search for anything that you want.

OK, so the code editors nicely link to the documentation access. Another way you can get to documentation is through the class browser. If you're doing object-oriented programming, you'll probably find the class browser very useful. You can get to the header documentation, or the header declarations, but also the blue books give you access to the documentation for the selected class or method of that class. So make use of that. Another way you can get around is, or another type of documentation you can access is the man pages, the Unix manual pages, either by name or searching.

So for example, For example, there it is. And the man pages are all linked, hyperlinked, so you can go to related man pages. This one I didn't see. The link for. Okay, so that's a good way to access, those are a number of good ways to access the local documentation, the documentation that's installed on your system. If you want to extend your search a little further, the user scripts menu that Anders mentioned can help you there. For example, select, make a selection in your code editor and You can then search the developer website at Apple for that selection.

send it out to the internet and do a Google search. OK, so those are some of the fast ways to get around the documentation and find answers to the questions you have. Let me take a little closer look at the user scripts menu. User scripts are scripts that extend the command set of Xcode with commands that you decide, you create. Xcode comes with a number of pre-built commands and here they are.

Let me show you how some of these work. A very useful one I find is this uncomment comment selection and you see as it was pointed out earlier that there's a key equivalent for it. So if you need to take some piece of your code out of service, you can do it as easily as that.

OK, another comment type that I find very useful is this-- comment with a prefix with exclamation points. If you need to come back to something later, you can-- Mark it in that way, and with a consistent prefix you can easily get back to that sort of comment. OK, if you're doing object-oriented programming, you might find that you're doing a lot of typing, creating accessor methods for your instance variables. Here, too, user scripts can help you out. For example, let's make an accessor method for that instance variable.

So I've put the declaration on the clipboard, and now I can just paste it in. And likewise, there's a similar command for pasting in the definition. Okay, there's sort commands, and one last thing I'd like to show you with the user scripts menu is the suite of HeaderDoc commands. These commands let you put structured comments in your headers that later can be generated into HTML documentation. It's much like Java doc, but it's for C, C++, and Objective C. So let's see how that works. For example, let's say we want to document this class.

We can insert a class template comment. Take the class name up there. And here's where you'd write your abstract and description. And here's a method that we'll document. I don't know exactly what it does, but we can at least put in a skeletal comment. And you see that in this case the user script is smart enough to parse the declaration and pull out the parameters here. Okay, if we save that and view HeaderDoc for this header, Xcode will invoke the HeaderDoc tool, generate the HTML, and create some documentation for our class.

So I encourage you to give that a try. OK, so that's user scripts. The related feature of worksheets I'd like to show right now. Worksheets are kind of a less formal way of adding commands to Xcode. And as was pointed out, it's a good way to keep a history of commands that you find useful, that are difficult to retype, or easily forgotten. So here's just a simple command. Hit Control-R. Select it, hit Control-R, and it's executed in that text buffer. And that's the output. So we just did a listing, Unix listing of the root directory.

This command is used to invoke an application in a way to see if it's doing any redundant drawing. Those command line switches are good to remember. One way to do it is to leave it in your worksheet. Let's see what that looks like. I'm invoking TextEdit. with those special flags that show where the drawing is happening. And this makes it easy to see if any excess drawing is going on.

Thank you. All right. This is a command that lets you know what symbols you're importing from a particular library. In this case, we're going to look at TextEdit and see what it's pulling in from the Cocoa library. So Command-R, Control-R, and there you have it. And I'd like to show you just one more.

As we look through this list of commands, you see some are in Perl, some are invoking Apple scripts, some were Unix commands. Here's one that, as a genetic engineer, you might want to use if you've misplaced a patch of DNA and you need a little bit more. So there you go. Those are the features of worksheets, user scripts, and documentation access. Thank you. MATT MORELL: Thanks, Matt.

All right, so as you see, you can really go to town and customize this and just pretty much set up any kind of workflow you want and bind it to a key command. So I just want to wrap up some of the things we talked about. We want to leave a fairly long Q&A session here today, because this is a fairly detailed session.

Some of the things we touched on are Xcode has a lot of productivity features, right? Some of them, we tried to make many of them work automatically, and a lot of them work pretty well automatically. We're still a developer preview, so by GM we want to get them to work a lot better automatically. There's still room for improvement in terms of your fine tuning.

Things like fix and continue, we can work on making that even better. Other things you really need to customize, like the scriptability here. We provide you with a lot of sample scripts. All those scripts under the user menu come as sample scripts, but of course you can add or modify any of them. This HeaderDoc knowledge, for example, is not built into Xcode in any way. That's just in the script.

So you could really add whatever you want. Precomputing. We've got a lot of different compiled headers. We talked a little bit about how to set those up. There's a lot more information in the help pages. Xcode gives you the power and the flexibility here to really customize your workflow the way you want to.

So how to learn more about this? Well, we're not going to ask you to go out on the web and read about this, right? We have built-in help pages. So as we just saw, you can use the documentation search features not just for the API documentation, but also for help about Xcode functionality itself.

There are, of course, the Inside Mac OS X books, especially the System Overview book that talks more about some of the concepts that underlie this. The IDE, of course, supports the platform initiatives, things like frameworks, things like that kind of concept. And those IDE-independent things are documented in the System Overview. Xcode knows how to build them, but the best documentation is in the System Overview.

Of course, the developer connection tools pages, and the CVS documentation, and the Perforce documentation are available on the web. Who to contact for more information? Guy Fugigiorgi, Technology Manager for Development Tools. I'm actually going to invite him up on the stage now for Q&A. And here are also some other URLs. There are a couple more sessions you may want to check out.