---
title: WWDC2000 Session 192
framework: wwdc
role: article
path: wwdc/wwdc2000-192
---

# WWDC2000 Session 192

## Transcript

Kind: captions Language: en so today I'm going to talk about basically some of the nuts and ball builder and we're going to have a few of the engineers up here what we're going to cover in detail is basically what should be your first day of using project builder we want to talk you through getting the code that you have into the new project builder I'll cover the first bullet up there importing a project to project builder then honors vertical route is going to come up one of the designers of the build system and talk about how we customize the build process to support some other features that you may have in your project and then finally Mike Faris who is a lead designer of the CF bundle objects on Mac OS 10 will talk about how you actually create those bundles for Mac OS 10 so just to recap what we covered in the last session project builder sits at the middle of a lot of other tools it's sort of the central clearinghouse for the developer experience we talked the interface builder we talked to the performance tools we'll be integrating with all the web objects tools and we invoke a command-line compiler and debuggers to do the real work of producing your project and debugging it so this is what project builder looks like today in order to actually get your code into it we've had built in some support for three different streamlined transitions one taking a basic source code project taking a project builder whoa project the old PD dot project files and also we've built in fairly recently support for importing code warrior projects so importing source directories importing source directories is fairly straightforward this is a mainline feature of the application so we allow you to do it not only when you're creating a new project but whenever you want to add some more source code to your projects basically in creating a new project you you can make the project either an empty project or any of the existing project templates that we support make sure you have some targets in there it makes it a little more convenient when you actually import the source code and then just grab some folders out of the finder drop them into our group view of project builder and you're good to go you'll get all the factory default build settings that you usually would have with the project template so you may have to do some work there if you're importing a bear source code directory for importing pbi project files the old project builder a project builder wall or whatever we decide to call it today we have a very sophisticated automatic import feature this is the feature that we use ourselves to bring the PDX code base into our own IDE so we initially started developing on the old project builder when we got enough stuff there we did switch the entire team over to developing on our own app and we've had a lot of testing on this because there are a lot of people who are using the old project builder at Apple and need to get their code into the new system so we've had a lot of testing we have a lot of features on this so if you're if you currently have a PVD project file this should be a very simple process for you the one caveat is that if you've written sophisticated make file post amble and preamble and old project builder users will know what that is and make file a preamble will have some settings of build variables you may have to go into the target editor and set up some of those settings yourself and if you have sophisticated build actions that you put into the post amble we do have support for that in the new environment but our model is very different so we aren't able to give you an automated transfer of those build actions but we do give you a very straightforward way to implement them and hopefully it shouldn't take much time unless your project is extremely sophisticated we also support code warrior projects the code warrior project that we support or the XML code warrior projects so you'll need to output an XML based file from code warrior and then again just invoke our automatic import feature we'll bring in all of your groups and files we'll bring in the compatible targets as far as we can go some of the rad features and things are not of course in our project model so they don't translate over and will translate your compiler settings again as best we can given that we're running on a tool that's very different from what Metro refuses and again as you can imagine once you import the code warrior project you'll have to tune it a little bit you have to tweak some of the settings prop to get some of the features that you're going to want and as we see some of the tuning that needs to be done again this is a newer feature we'll be adding more and more automation and hopefully get better and better and eventually on par with the current level of old project builder import that we have so now I'd like to bring up honors Bertrille rude he's one of the designers of our build system and he's also the guy that's responsible for that with the slide views that you see in the UI so what we're going to do is just cover the three ways that I just talked about it getting your source code into project builder the first way is going to be a source simple import of a source directory we'll use the simple text sources to show this so the first thing that honors is going to do is bring up the new project because we want to start out with a carbon application because we know that simple text is going to be eventually a carbon carbon application so he'll select that and choose a spot word on the file system and then we're ready to go so we get here is basically created out of our project template and it does give you a lot of nice factory default it gives you a default target it gives you some some standard groups but since we're going to be importing these things we really don't want the sources that we put in here or the resources so on we'll just select those and delete them from project and so now what we can do is we can go out to finder and we can grab the simple text source base and we'll just drag that folder right into project builder and what this what happens now is a sheet comes down that I don't know if you all can you can all see that from where you are it gives you a few options the first thing is it will give you a list of the targets to choose from right now we only have one if that target is checked all those files will go into the target into the right spot I'll show you that in a minute the two other checkboxes are kind of interesting the first one we're actually going to check which tells project builder to actually take the source base and copy it into the directory we created for the new project you can also leave that unchecked and simply reference those project files wherever they happen to reside on the disk though I do want to point out that that referencing facility is not a substitute for the Mac os10 layering that we provide with the frameworks and shared libraries so I encourage you if you find yourself leaving that box unchecked and sharing a bunch of directories between projects to really explore the back OS 10 framework model because that's probably going to serve you a lot better in the long run the next thing that is up there is a check box it says recursively create groups from added folders so what that tells project builder to do is to basically descend the source tree that you've just dragged in and create a project model for it so every folder gets a group and every file will get what we call file reference that points to that and the paths will all be set up nicely for you so you can easily move things around if you leave that unchecked what it's going to do is import those things in what we call a folder reference on basically project builder though it allows you to navigate down into that folder reference it basically treats it as a filesystem blob so you you get the same experience you would navigating down that folder in in finder it will keep it synced with the filesystem and in the build system we'll look at that folder as a single entity and this is to support people who maybe have multiple image directories or resource directories that they just want to treat as a blob and they're not very interested in having fine control over it you usually always leave that box check for importing sources so why don't we go ahead and do that hit ok and we're let the disk spin for a little bit while it copies all the sources over and what you see is that we've basically grabbed all the simple text files and put them into their own group and of course you're free at this point to move them around to reorder them to regroup them to do whatever you want if it imported some files made it part of the project that files that you're not interested in having you can obviously take those out of the project the other thing that it did if we go over to the target panel is it put them all into the target for you and the target is actually set up nicely because we separate our target out into what we call build phases and these build phases know what files they'd like to have in them we put your headers in the header space we've put any resources that we might have into the into the resources and we've also gotten any frameworks and libraries that you might want we also have some build settings and some other things that Andres is going to cover after the demo discussing how you might want to set up your project but we do have of course all the factory default build settings on this so the other thing that I wanted to show is just the way that we have imported these files if Honor's wants to just bring up the inspector briefly if we raise the inspector what we try to do is make all of these files as relative as possible that allows you to the most flexibility in terms of structuring your project so we'll bring everything in as a group relative reference if you've told us to recursively create those groups for you and of course you're welcome to change that to whatever kind of reference you want but most of these imports are going to import these relative to the paths we've assigned to the particular group and so why don't we close that project and now what we're going to do is import the same project but we've created an old PDF project file in here and we're going to import it as a pbi project file so it says PVL project and what Andres has done here is brought up our file importer and you can select that off of the file menu he's selecting the Peavey project file and all you have to do once you've selected that file is just hit finish and because we own the PV I project model we go through intake every setting that we know about and translate it over into the new project model so again we have the groups and files and what you'll see here if you're an old project builder user you'll be you'll be very used to the hierarchy that we've set up very much like the old suitcases that were in PV whoa and of course the difference is that now you can go through and move these files around however you want it affects nothing in the build system it affects nothing in the file system unless you tell it you want you want it to affect it and again we'll have a very similar target so honors can show that target setting basically this is going to look very similar with the with the added benefit that because we know this format because we have a lot more information here we're able to bring over a lot more of your compiler settings and and build settings that you used to having inside of the old project builder so finally we're going to show the newest feature which is importing the code warrior project and again we've made simple text into a code warrior project we saved it out as XML onder's will raise the code warrior importer at this point select the XML file and hit finish and what we have is again project builder project we've got our sources we've got all of our files that we expect again this is going to be paralleling whatever structure you have a code warrior the other thing that we have is again a target and since we actually have two targets inside of the code Warrior Project we brought both of them over and translated all the settings that we knew about and again this is going to look very similar to the project builder project that you've seen before so that's how you get your code into project builder and now I'm going to go back to the slides and let onder's come out and talk about how you customize the build process once you've got everything in there thanks done so now we've seen a couple of different ways which you can bring your source code into project builder and now that we have a project I'm going to talk a little bit about how you can customize it so again here's how project builder fits in and we've seen the importing and we're focusing on this part so there are a couple of ways of customizing the build I'm going to talk about three of them in roughly the order of increasing flexibility first one is just editing build settings compiler Flags linker flags big browsers they're defined that type of thing if you need more flexibility you can actually modify how it targets built and add your own build phases to for example copy files or run scripts at any point in the build if you have a new make a new based project for example with it they'll make file or highly customized build system you can also add a mention in the previous session you can also invoke a custom build tool to build the project that way so editing the builds the build settings again a project builder target consists of one or more build settings that do things like compile source files incorporate the resources into the product and that finally link your compiled sources against the frameworks and produce the output and there are target settings that apply to these builds one or more of these build phases for example compiler Flags you want optimization what kind of alignment you want those sorts of things we also have other targets based settings such as the install location if you intend to install this framework somewhere on the file system what do you intend it to go we can build for deployment we can also add custom settings in the first session Dave showed the target settings panel and we have a table view where right now with the expert mode and so you can add really any build setting that you want and those will be available in the build agents that I'm going to describe later so this is the simplest way of editing your project settings just checking switches entering values and tables and for many of the projects this is all you ever need to do if you need a little bit more flexibility you can actually add a build phase to copy arbitrary sets of files or folders to arbitrary places in the file system you can either copy it into special folders inside of the bundle that you're building for example if you're building an application well that's packaged just an application wrapper and in Mac OS 10 and it has various sub locations so for example if you're practicing frameworks together with your application they will go into a framework sub direct subfolder and you can actually use copy files build phase to encounters then we have support for some of the standard ones or you can just enter any path that you that you want the other thing is use the copy files build phase for is to copy a file or folder to an arbitrary place in the file system say you want to install some release notes into local developer release notes forever when you deploy or your application so you can have a copy file build phase for that if you need some more flexibility than that you can actually add a script build phase and execute arbitrarily complex script commands at any point during the build so this is very powerful you could actually generate files based on the contents of other files you could even go have a command that goes out across the net and fetches some files brings in some records from database whatever and the scripts have full access to the build settings I mentioned before that you could add your own build settings to the target Settings panel and any script can access any of those they also have access to the standard settings such as what's the install location what's the optimization level that's in effect you want debugging that sort of thing and you can use it for anything but primarily they're currently used for make file preamble and post sample conversion so John mentioned that if you have a project builder role project with a lot of customized make files we may not import all of those things and you used to have to put commands by editing the make file type code sample directly well now you put those commands into a part of the UI and just enter it in between the I'll show you that in the demo later on the other thing you can use it for as opposed to install action suppose you want to change some permissions of a particular file or suppose you want to invoke a tool like a new tar to just package up your project or whatever you can do anything you like with that and finally the feature that they've mentioned that we've talked about before for a project would own customized build systems such as for example of new projects a project that you got from somewhere and you want to commit sources or commit your changes back to that without changing the build system you can use a legacy target and what you can do in this case is to take the project bring it into project builders you can use the editor debugger all those nice features and for the build you say go use that tool over there and that could be you make for example or it could be any other type of a tool and in fact you can invoke any command you want there but typically we use for make file and so the one caveat with this is it's great you get a lot of flexibility you can override their build system completely but of course that means that if you add project files project builder is not going to know about that so in that case we'll still have to edit to make file so we expect most people will want to bring their projects in through one of the importers and use it as a full project or project but we have this legacy target feature in case you're working with open open software things like that so I'm going to ask microphones to come up and help me do a demo of this some show off some of these features first of all let's go ahead and make the simple text micro-target active it's already active and let's go ahead and add an icon in this case sorry I'm on the completely wrong script here so we imported a simple text project and if we go to the simple text add C file I take a look at this project before so I happen to know that it has a special preprocessor defined to use the new framework syntax for importing Carbon headers that define was not set in the code or XML project so let's go ahead and add that now let's scroll down to yeah down to the simple text see there and just go ahead and copy the string so we can paste it into the build settings and if we switch over to the targets and we go into the build settings we see some build settings here the general settings at the top install location we have some directory user interface at this point for the compiler settings as Mike shows you you can collapse those if you don't want to see all of it and let's go down to the build flags at the bottom there and add a dash d and then paste that preprocessor macro into the other C flags so we're planning on adding directed user interface for this as well a nice whole list of all the preprocessor macros you wanted to find those kinds of things in the meantime the expert mode gets you gives you the ability to add anything you want so that should be all we need so let's go ahead and head build and watch synth effects build here so as they mentioned the first session the top card of the pane there shows the warnings and errors you have the bottom card shows the expert settings that part CAG it shows the expert bill log that part can actually be collapsed if you want by just dragging the split view there we have a couple of warnings that I think a harmless in this case but we do have some link errors and those look like the speech synthesis framework is missing so Mike's going to go up to the project menu and we'll add the framework it's a standard system framework the open panel takes them to the standard system location for frameworks and just choose speech synthesis and if we build again let's go ahead and add that to the simple text my code target and as you see it appears down and the list of frameworks that does target links again so if we've built again it should work fine this time so it's linking to simple text and build succeeded so let's go ahead with that and so we built simple text after importing it from the code warrior project that have been exported as an XML and we're able to get it up and running and building here in fairly short order so that's great so let's go ahead and and take a look at some of the other ways in which you can configure the build here let's add a copy files build say suppose we have a release note file that we want to install into a particular file system location after we build for install so I can add a new copy files build phase and as you can see in the pop-up there we list a set of standard system locations currently says resources you can pick anything there that's inside of the application wrapper these are standard sub sub locations or you can pick an absolute path and that's what mics can do in this case and enter an appropriate path into the system for Apple provided release notes you won't be in sewing here and I'm going to check the box that says copy only when installing and sophistic oh okay I'll take a look at that after the demo all right so we have a path so what we need to do now is to add the actual release note file to the project and so we under the project menu we have add files I'm going to go ahead and add you just have a sample RTF file there could be anything and I'm going to add that and we're not going to edit to a target in this case because we're going to drag it into our special build phase later on we just want to add to the project for now and it's going to appear it there under instances and we can just drag it and drop it into the files area of the target that we could drag as many files as we want any folders as well and they'll all get put into that location we could also add other copy files gold faces we had other location okay so now we're going to show how we could actually add custom build commands as part of the build so mics can add a shell script build phase and by default the shell there is been SH but it could be anything you could in fact invoke Perl and invoke some pro commands as part of your build in this case it may be hard for those of you sitting the back to read but Mike's entering little scripts that just echoes the one line timestamp to a log file whenever we build the project so just just amidst a log whenever the project builds successfully so that's all done and we're not checking the run only when installing box because in this case we actually want it to execute every time we build the product so if we get set build then we saw some output in the build log up there but if we open the build log file we can actually see that a line was emitted to that file so right there so just to show it's not fake well build again and then just revert to show you that it's executing all those commands and it's updating so this is a powerful way in which you can add any any kind of customization you want as part of the build and it really is quite flexible and finally let's go ahead and show a legacy target and in this case I'm actually not going to invoke you make - to invoke make I'm actually going to invoke some other tool just an arbitrary command so Mike is creating a new legacy make file target just call it count lions we're going to have a little command that counts all the lines of your source code and the default tool has been mates and the fault default parameter is the action so if you don't change anything it's going to try to invoke make which is going to look for make file and this is probably the primary reason you would use a legacy target we're just going to enter a fun little command here to just find your source files and pass them through a little tool that's going to count the lines so just give us an idea of what this how flexible this can be the correct looks right so it's going to find our headers files or C files and the resource file and so it's going to make this target active if you notice Mike check in the little checkbox there and we just have build to run this target and in this case all it does is just count the lines of source code so you can actually use this for a wide range of different uses if you want and normally you're not going to need to do this to build your project to build your product but you may want to do this kind of thing - for example package of resources or or whatever and my dependencies we can also make the count lines being invoked anytime the main simple text dot o is built so just add a dependency make simple text Auto be the default target and and we can build it and and the output will get emitted to the log and then we'll proceed with the build so this summarizes some of the features of project builder we're working on adding convenient UI so that you should never have to type any of these commands if you don't want to but the power is there underneath so you can do pretty much anything you like - and at this point I'm going to hand it over to Mike and he's going to talk a little bit about the application features application packaging features of project builder so I can't emphasize enough how important the application packaging and the bundling structure is to Mac os10 it's pervasive alright almost everything on the system is packaged as a bundle and so it was very important for us to make sure that we had full support for building bundles in project builders alright we've seen this slide a couple times before and we're going to be talking about how project builder building stuff so I want to just briefly talk a little bit and then we'll get right on to the demo because that exciting part so we'll talk a little bit about building bundles we'll talk a little bit about managing your info.plist which is one of the the main pieces of your bundle so it provides all the metadata that's needed to tell other subsystems what your bundle does we'll talk a little bit about resource handling we'll talk about bundle resources which are just files that you own your bundle as well as resource management resources for carbon apps and specifically I want to touch on localization features and how we support that in project builder and then finally we'll talk a little bit about how you get just random other stuff embedded in your bundle if you need it to be so first of all project builder has full support for building bundles applications frameworks and bundle targets all produce bundles in the end bundle targets is what you would use to build say a plug-in we're going to automatically construct the bundle as part of the build process all right so you don't have to configure that at all if you have an application framework or bundle target we're going to produce the full bundle for you and the build system knows where all the pieces go and for any pieces that you have that are custom you can tell us where to put them now the info.plist is an XML file that each bundle has which declares various things that are needed by different pieces of the system so CF bundle which is the core foundation facility for dealing with bundles uses a lot of keys in the bundle for instance the executable name of the actual binary that is inside your bundle that is the app that's supposed to be run that's declared in the info.plist the finder also declares various things that it wants to find in your info.plist to do things like associate documents with your application to figure out what icon to show for your application and so forth and project builder allows you to manage your info.plist completely and we provide some custom UI for all the common stuff that you want to do we'll show that a little bit and we also provide an arbitrary plist editor if you have custom content that you need to put in your P list that you'll use if we've forgotten something and in the custom UI you can do it in expert UI so okay resources there's kind of two there's two kinds of resources the term is a little bit overloaded bundle resources are just files that go inside your bundle and resource manager resources are the resources that you typically find you know in the resource fork of a mac OS application both of these types of resources in Mac OS 10 can be global or localizable when they're localizable you have multiple versions for different languages that you're going to support they can also be platform specific so if you need to have a slightly different version of a resource for your mac os9 carbon you know application and your Mac OS 10 the carbon application you can still package those all in the same bundle and the correct version will be used depending on which platform the app is running on now project builder also helps you to make sure that the bundles that you're building satisfy the requirements and the main requirements are that for a localizable resource you must have a version for your development region your project is going to have a development region so by default that's English but if you choose to develop your primary interface in French or in Japanese or whatever you can do that the bundle knows what its development region is project builder knows what the development region is and it's going to make sure that at the very least you have a version of each resource of the development region and then you can have versions for every you know all the other regions as well and then finally if you're going to have platform specific resources you also must have a platform generic resource and that's just in case you find yourself running on a platform that you did not anticipate there'll be a version to use okay and then finally we'll cover like I said other bundle content you can use copy files build phases as been mentioned before to copy stuff into your bundle tools can be put into the executables directory of your bundle if your app needs to make use of some command line tool in some cases you can put frameworks inside the bundle you can put other support files whatever you want to put in there all right now I'm going to invite onder's back up to do some of this demoing so the first thing we're going to do because of course aqua you know you have to have an icon for aqua so let's add an icon to simple text now the code warrior project did not have the icns file as part of the project so it didn't import when we imported that code warrior project but I happen to know that there is a nice ENS file here so onder's is going to actually go and add that icns file to the project and we'll go ahead and let it get added to the simple text target and okay you see it appear there and if we actually go to the target editor for simple text you'll see that it also appeared in the bundle resources days in Mac OS 10 icons are just files that go inside the bundle they're stored in the icns format but they're just separate files that sit inside the resources directory of your bundle so project builder knew to put that file into the bundle resources phase so that it'll be copy and when you build now the other thing though is that we have to tell the info.plist about our icon so the finder will know that it's supposed to display it for us now we do that in the application settings tab of the target and you can see that there's a bunch of text fields here onder's will enter the icon name in the icon field and then while we're here maybe we can set a few other things we should probably have a creator code other than for question marks so let's do that and it's a good idea for bundles to have an identifier string as well bundle identifier czar useful for integrating with the CF preferences facility there also useful for locating the corefoundation bundle instance at runtime for your your application or for your framework or for your loadable bundle okay and by the way we we recommend Java package naming conventions for the identifiers just to ensure that uniqueness now we have settings for a bunch of stuff in the custom UI here but there's more stuff than where we'll be adding more custom UI in the future but we also have this expert mode and this just shows you the raw property list you can edit stuff there arbitrarily if you have custom content that you want to put in your P list because maybe your program wants to access it at runtime you can do that there you'll notice that the things that we changed in the custom UI have already showed up here now we won't bother with any other P list settings now though so let's move on to resources and in particular localization now onder's is going to go ahead and go find all the rest of the dot r files because actually in the code warrior project the only one that was part of the project is main dot R because it just imports all the other ones but because we want to do some localization we'll go ahead and add all the other files to the project just so we have them to work with so onder's is finding all those and we'll add them now we won't add them to any target because the main dot r is already part of our research manager build phase and it just imports all the other ones so we're not going to bother with adding them to the target but now they're part of our project there's one in particular localized R that happens to contain all of the strings that need to be localized in tech a simple text interface so that's the one that we want to make a localized version of and to do that we'll use the project inspector and you can see there's a pulldown called localization and platform and all we need to do is say make this a localized resource you'll notice that a disclosure triangle appeared next to it and if we disclose that you can see that there's basically a list of the very versions that we have of this resource when we first make it localized you're only going to have a version for your development region but the whole point of this is we want to localize the thing so let's make another variant for say Japanese now notice that it added another line there so we have English and Japanese now the English version are sorry the Japanese version starts out as just a copy of the English version but it's a separate copy so now you can go in and edit the Japanese version to translate it into Japanese and the project builder build system takes care of all of this so it knows where the global resources are supposed to go and the localized resources are supposed to go it compiles them all separately it puts them in the right places and everything you know will be automatic so that's just a taste of the localization support and finally let's just show one more thing which is let's say that simple text had a command line tool that it wanted to run in some circumstances of course it wouldn't show it to the user at all but it would maybe use it in the background to do some stuff and you would like to have that command line tool be part of simple text so let's go ahead and create a new target and it will be a tool target they will just call my helper tool so now we have this new target and if you open it up we can see that it doesn't actually have any files in it and we're not actually going to build a tool now but this would you know if we filled in some source files to be compiled this would build us a command line tool now we want to set up a dependency because for us to build simple text and have it be complete we also have to build this command line tool so onder's will just set up the target dependency to make sure that the helper tool builds whenever we build simple text and if we switch back to the files tab when we added the tool target in the products group which is sort of an automatically managed group of the project you'll see that a line was added for the helper tool this line refers to the actual tool that will be produced it shows up in red because we haven't built it yet so it doesn't actually exist on the disk but the reference is there and we can make use of it so we'll go back to the simple text target and we're going to create another one of these copy files build phases now we can't use the one we did before because this one is going to copy stuff to a different place so we'll just do a separate one and we did an absolute path one before this time what we want is for the tool to be installed into the executables area of the bundle so we just choose executables if you wanted it to be nested underneath the executable somewhere and you could use that sub path field but we don't want to do that we also don't want to do the only one installing because this tool should be part of the thing whenever we build it and finally we have to tell what it's going to copy so we just drag in the reference for the helper tool there and now whenever we build simple text it'll first build that tool and then make sure that tool gets installed into the executables of the simple text app package so that simple text can find it at runtime now this is just sort of a taste of the the degree to which we've tried to integrate the bundle packaging scheme into project builders basic model and we can see some more detail on some of this in the Mac os10 localization session especially as it applies to localized and carbon and cocoa applications for now I want to invite John back up here one last time and he's going to sign some of this up for us and then we'll do some Q&A so what we talked about today is just the first step in using project builder there's a lot of other stuff that we we could have covered today but we'll leave that for now for you to explore again you can take any one of these three variants of a project pull it into project builder use the app then to customize it however you want and then finally produce one of the Mac os10 bundles and a framework and or a curtal kernel loadable module so there's some support resources public emailing list if you have some feedback for us and it's the feedback Elias is Mac OS tool feedback and group tackle comm and we also have the fee-based support with DTS