This file contains release notes for the latest release of Project Builder. You can always get back to this file by choosing Show Release Notes from the Help menu. Older release notes can be accessed with the Show Older Release Notes menu item. Also, please see the bottom of this file for information on additional sources of developer documentation.
Other interesting release notes can be found in the Release Notes Table of Contents (/Developer/Documentation/ReleaseNotes/index.html). Advanced Project Builder users may want to check out the PB Build Settings release note (/Developer/Documentation/ReleaseNotes/PBBuildSettings.html).
Project Builder now supports parallel builds. This makes full use of multiprocessor machines by running multiple build commands at once, for example to compile two or more source code files simultaneously. By default, the maximum number of build commands Project Builder will run simultaneously is the same as the number of processors in the machine. The level of parallelism can be set from the Building Preferences pane, and the PBX_NUMBER_OF_PARALLEL_BUILD_SUBTASKS environment variable can also be used to control this setting. In this release builds on single processor machines are recommended to use a value of 1 and builds on dual processor machines are recommended to use a value of 2. Values of up to 3 are supported, though in most cases building with a value higher than 2 will result in slightly slower builds.
Project Builder uses its internal dependency graph to determine when it is possible to run more than one build command at once, so all projects should still build correctly with parallel builds enabled. It is rare but conceivable that a complex project that built fine without parallel build support might fail due to inaccuracies in Project BuilderÕs dependency graphÑfor this reason, there is a new build setting named DISABLE_PARALLEL_BUILDING that can be set to YES on a per-target basis in the Expert View in the target editor. In this manner, a parallel builds can be disabled for a particular problematic target without losing the speed benefits of parallel builds for other targets.
The build log pane has been significantly improved. Not only does it correctly serialize the output from multiple build commands running in parallel, it also makes it much easier to focus on the relevant information in the build log. Unlike in previous versions of Project Builder, where the desired level of build log detail had to be chosen before the build began, full build log information is now always collected while the build is running. However, only the information selected by dynamic switches at the top of the build log panel is shown at any given time. All build steps can be shown, or only those with messages. Warnings and errors can be shown, or only errors. These filtering settings can be changed at any time, either during a build or after it has finished. In addition, the textual output from the build commands (along with the exact command lines used to invoke the build commands) can optionally be viewed in a transcript text view.
Header dependencies have been completely re-implemented. These used to be done by jam. It would search through source looking for include statements and trying to match them with real files. The problems with this was that it did not do a very good job matching them, partly because jam had no knowledge of concepts like header maps or frameworks). In Jaguar, we introduced an alternative, mostly to get some testing, of a new scheme that computed dependencies from Project Builder's indexing data. This was also found to have some fatal flaws. Now we have a new implementation. The IDE now does the source scanning, similar to what jam did, but the IDE can do it properly, consulting header maps, understanding frameworks, and, in general, following the same logic that the compiler does to locate a header for a given include. There are several build settings that can be used to control this behavior.
ENABLE_HEADER_DEPENDENCIES defaults to YES. This is actually the old ENABLE_HEADER_SCANNING with a name change. Existing old settings will be upgraded to the new name. This setting controls whether any header dependency data is used during the build. If you turn this off, editing a header file will never cause any recompilation of source files.
PATH_PREFIXES_EXCLUDED_FROM_HEADER_DEPENDENCIES can be used to provide a list of path prefixes. Any header anywhere inside one of the folders specified here will NOT be scanned for dependencies. This setting has a reasonable default value that leaves out read-only locations for system headers to avoid the overhead of scanning them.
DO_HEADER_SCANNING_IN_JAM defaults to NO. If you set this to YES, the build system will go back to the original implementation and let jam do everything. This can be used in the rare event that the new header dependence introduces build failures because required headers are generated just in time for use and so may not be seen by the build system.
The summary is that, by default, the new mechanism is used and should always be much more correct than either of the previous attempts.
Finally, when you're using the new mechanism, Project Builder will now correctly track dependencies for headers included from your target's prefix header. Note that this functionality does not work when using jam to do the scanning.
There's a new build setting for expert users who wish to control whether dependencies are set up between source files and prefix headers. Usually, all source files in a target are made to depend on the prefix header (or in the case of PFE use, the PFE generated from the prefix header). This means that any time the prefix header changes or gets precompiled again for any reason, all the source files in the target will be rebuilt. This is technically correct. Sometimes, though, if you really know what you're doing, you may know that your source files do not need to be recompiled. If you set ENABLE_PREFIX_HEADER_DEPENDENCIES to NO then Project Builder's build system will not set up these dependencies and the source files will not necessarily rebuild when the prefix header changes or is re-precompiled. This can result in incorrect builds! Also note that as soon as you remove that setting or set it to YES, the dependencies will be reinstated and all your source files will be recompiled the next time you build if the prefix header was changed or re-precompiled after the mod date of any of your .o files. This setting is analogous to the existing ENABLE_HEADER_DEPENDENCIES setting that can be used to disable header dependencies for headers that are directly imported or included by your source files.
Fortran files (.f, .for, .f77, .f90, .F, .fpp extensions) are processed with the gcc compiler and pick up flags from the OTHER_FFLAGS build setting. Although Fortran file extensions such as .f90 are recognized and such files are passed as Fortran to the compiler this should be considered a convenience and not evidence that gcc supports Fortran 90 or other modern Fortran usage.
The processes used to link compiled code to produce binaries have changed in three ways:
Single module binaries
Because the time required to load a dynamically loadable binary is related to the number of modules in the binary it is important to generate a single module binary when possible. In the past the default was to produce binaries with a single module by first generating a single "master" object file that was a superset of all other object files. This master object file would then be used for the final link. It is now the default to generate a single module binary directly by using new link options. When SINGLE_MODULE is YES which is the default value, linking will use the -single_module option whenever possible. If GENERATE_MASTER_OBJECT_FILE is YES which used to be the default then an extra prelink step will be used to generate a single object file from all other object files to use for the final link. If changes to linker usage cause build problems then returning to the master object file generation process should restore previous behavior.
Exported symbol editing
Editing exported symbols may be desirable to prevent external access to internal functionality and also to improve performance by reducing the count of exported symbols. When exported symbol editing was originally introduced only symbols in object files could be edited. Because of this, editing symbols indirectly implied generation of a master object file that was be edited prior to linking. Now any binary can be edited, and the default is to edit the final binary instead of a master object file which should no longer be needed and by default should no longer be generated. Important related issues are that final binaries may have symbols added during linking that may need to be taken into account, and editing symbols with the linker will assume that such symbols are to be ignored while editing symbols separately with the nmedit tool will edit all symbols the same way regardless of where they originated from. The EXPORTED_SYMBOLS_FILE is still the setting to use to indicate a file listing symbols to export.
Stripping
In the past deployment binaries were stripped using the strip tool. The default behavior has been changed to strip binaries using flags given to the linker at link time. It is possible to return to the old behavior of invoking the strip tool separately by setting SEPARATE_STRIP to YES.
Build settings changes
Support for public and private headers for static library targets. It is now possible to specify whether a header file is public and / or private. If the build environment variables PUBLIC_HEADER_DIR and PRIVATE_HEADER_DIR are set, the marked files will be copied to the proper place during an install build.
Most build command flags and parameters are now quoted only if they include text that needs to be quoted in order to be passed correctly through the shell. Because flags with the prefix OTHER are more likely to contain special characters these settings are always used with double quotes.
New flags are now used to differentiate build variant compiles and links. The new flags are or the form OTHER_toolFLAGS_variant where tool may be C, CPLUSPLUS, AS, or LD and variant may be normal, debug, or profile. Because abstract tool references replace specific tool names this should reduce confusion regarding what flags are used depending on the choice of compiler. The values in old flags that were previously used are not moved forward to the new flags, but in most cases the new flags have correct default values and so do not need to be customized.
The version of the gcc compiler that is used is now determined by the GCC_VERSION setting, which should get a correct default value and also react correctly to the previously used USE_GCC2 and USE_GCC3 settings.
There is a new setting GCC_TREAT_WARNINGS_AS_ERRORS that will cause gcc to treat warnings as errors.
The default mode flag used to set the mode of files in deployment products has been changed to "ugo-w,o+rX".
In previous releases, product files generated during a build that were located outside the product, such as headers associated with libraries and resource files associated with tools, were lost from deployment builds because only products and content inside products were copied to installed locations. In this release deployment product files go directly to installed locations so that files outside the product are not always lost.
Build settings can now be referenced in the Info.plist Settings dictionary of a target. The syntax is the same as elsewhere, i.e. $VAR, $(VAR), and ${VAR} are all recognized. For example, if you have a build setting named CURRENT_VERSION, you can use its value in any of the values in the Info.plist dictionary (e.g. CFBundleGetInfoString = "MyApp v$(CURRENT_VERSION)"). Any build setting reference that either uses invalid syntax or references an undefined build setting are left untouchedÑif, for example, the value of the NSHumanReadableCopyright key is "Shareware $10", the Ò$10Ó part will be left untouched. Also, only references in dictionary values are expandedÑdictionary keys cannot contain references to build settings.
You can now set per-file, per-target compiler flags. To do so, select one or more build files in the Sources build phase of the target editor. Show the inspector (command-I). You can enter any number of compiler options into the inspector. These compiler options will be always appended to the end of the compiler flags during compilation, allowing to override other flags defined by the target or a build style. Build files which have compiler flags set in this way will display an icon to the right of their name in the Sources build phase. Note that these settings apply only for the specific target on which they were set; they do not apply to other targets in the project, even if the file belongs to multiple targets.
Prefix Header settings have been moved to the main GCC options page for easier navigation.
In the Executable editor, you can now check (use) more than one line in the arguments listing. Arguments from all checked lines are concatenated together in the order they appear in the list. Each line is still split and can contain more than one argument. This allows you to have one line that says "-NSOpen ~/TestFiles/test1" and another that says "-NSScriptingDebugLogLevel 1" (if, for example, you are trying to debug your Cocoa app's AppleScript support). Then you can enable one or both of these lines depending on your particular debugging needs. In addition, lines in the arguments list can now be reordered by drag and drop.
Frameworks that need to have a different "install_name" from their actual install locations can now accomplish this with a new build setting DYLIB_INSTALL_NAME_BASE. This setting defaults to $(INSTALL_PATH). But if it is set explicitly, the explicit setting will be used instead.
Stripping of Binaries
Changes to the process for stripping of symbols may result in binaries built with these tools being significantly different in size from binaries built using previous developer tools releases. The traditional process for stripping deployment products during builds can be used by setting SEPARATE_STRIP=YES which should eliminate differences in size introduced by differences in the new stripping process.
The flags used for stripping bundles now default to -x instead of -S. This change should make most bundles that are stripped for deployment 10-15% smaller by not including symbol information that was not expected or useful in most cases and not change how bundles are used. The flags used for stripping of any product can be changed by customizing the STRIPFLAGS setting.
There have been several improvements to the CodeWarrior importer focusing on providing correct/usable group, file, and target references in the imported project:
The importer no longer requires path relative information in the CodeWarrior XML export file, but not having the relative path information results in a longer import time.
The importer is much better at finding files that use a project-relative access path in CodeWarrior.
The importer is better at finding files that have no path information in CodeWarrior.
The importer can now find files that use a compiler-relative access path in CodeWarrior (for example, PowerPlant sources).
File references that use a project-relative access path in CodeWarrior now result in a project relative path in Project Builder (even if the source file is outside the project folder).
A simple heuristic has been added to add header files to the Project Builder project that exist in the same folder as included source files. This doesn't cover the case of headers that exist in a folder hierarchy separate from source files.
Most CodeWarrior target types are now imported. The few that are not imported have no clear analog in Project Builder (for example, the Object target).
Target dependencies and target ordering are now imported properly. The active target now defaults to the first target in the list instead of the first target created.
The importer does a better job of stripping out unneeded file references (for example, MSL libraries).
Framework & link order information for a target is now imported properly.
Prefix file information is now brought over and used. Project Builder uses the path to the file if it can be found, otherwise just the file name is used.
PFE is turned on for those targets that have prefix file information. If a target does not have prefix file information, both PFE and ppc-precomp are turned off.
High ASCII/MacRoman characters are properly decoded from the XML file.
Known Bugs or Missing Features in the CodeWarrior importer
Most target settings are not brought over to targets in the imported project.
In general, importing will not find all the headers your project uses (see above about heuristic to find headers).
The new Project Builder project is created in the same directory as the CodeWarrior project being imported.
While we do a better job at removing unneeded file references, we don't always provide the Mac OS X analogs when a replacement is needed.
This version of Project Builder has a number of new features related to file encodings and a number of changes and new policies about file encodings.
Starting in this version of Project Builder, we are requiring that all textual files referred to by your project have specified file encodings. If you work in a basically linguistically homogeneous environment (which is my obfuscated way of saying "if all the folks you work with speak the same primary language"), you may never have run into problems with file encodings. Similarly, if you stick to strict ASCII in all your source files, you have probably never had any file encoding issues either.
However, it is more common than one might think to have the code you write wind up in the hands of someone who speaks a different language from you and who may, therefore, have a different default file encoding than you. This can be a particular issue for example projects and project templates which are, by their nature, meant to be used by many different people.
When you open a project with this version of Project Builder, it will check to see if there are any references to text files which do not have specified file encodings. If there are, you will see a sheet asking you to choose an encoding to assign to these files. If the files always open fine for you and display correctly with no garbage characters or other oddities, you should just use the default selected encoding in the sheet. The default selected encoding is your account's default which depends on your language preferences. It will be Mac OS Roman if your preferred language is set to English.
Whatever you choose in this sheet, it will not affect the content of your files at all. It will only affect the settings in your project file and how Project Builder interprets files when you load them into its text editor. If, after you've chosen a default encoding, you find that some (or all) of your files start to not look right, you can change the encoding used for any file using the Text Settings tab of the Info dialog.
In addition to this new sheet, there are several other new features related to encodings.
When you choose to change a file's encoding using either the Text Settings tab of the Info dialog or the File Encoding submenu of the Format menu, Project Builder will now ask whether you want to convert the existing file's contents to the new encoding or reinterpret the file's contents using the new encoding. If you are changing the encoding because the file does not load and display properly, then you should choose to reinterpret because its current setting is incorrect and you are changing it to make it correct. If the current setting is correct, but you want to change how the file is encoded (for example, if you want to change your Mac OS Roman source to UTF-8), you should choose to convert. Previously, Project Builder would always convert if the file was open and reinterpret if the file was not open.
When you add files to a project, the Add Files Options sheet now includes a file encoding popup which you can use to choose the encoding for the files. Whatever encoding is selected in this popup will be assigned as the encoding for all the text files that are being added.
File Templates are now interpreted as UTF-8 by default. All the built in file templates have been converted to UTF-8. File Templates can also specify a different encoding, if necessary, by including a "TextFileEncoding" key in their TemplateInfo.plist. The value of the key should be the numeric NSStringEncoding constant (see Foundation/NSString.h for the values) For example, a ".strings" file template can be in UTF-16 (which is the recommended encoding for string tables).
Finally, let's discuss briefly what the "best" encoding is to use. The answer to this question really depends on a number of things including:
If your code has to be able to be transported to other platforms and/or used with other development environments or text editors, often the limiting factor will be the other development environments or text editors. Project Builder is extremely flexible with regard to encodings and supports many more file encodings than would probably ever be interesting for your source code to use. The absolute most portable encoding is strict ASCII.
The problem with strict ASCII is that it is extremely limited in what human languages it covers. If you do not need to be compatible with other editors, or if the other editors you care about all support UTF-8 then UTF-8 is often an ideal choice. UTF-8 has two very nice properties:
Different compilers will also have different restrictions that may affect your choice of file encoding.
For C-based languages, Project Builder uses gcc. C is an ASCII-based language and you cannot use non-ASCII characters except in two specific cases. Comments can contain anything since the compiler never tries to interpret what is in a comment. C string constants can contain any byte sequence and that byte sequence will wind up unchanged in your app. As long as you treat your C string constants as being encoded in the encoding used for your source files, non-ASCII characters in string constants will be OK. There's one big caveat with C, though. Some character encodings are based on escapes and in these encodings, a byte that looks like ASCII may not really be the ASCII character it looks like. If, for example, some Japanese characters in JIS encoding happen to come out looking like the ASCII for "*/" and they appear in the middle of a comment, you're going to have trouble. This is why UTF-8 is a good choice.
For Java, compilers can typically handle lots of different encodings as long as they are told what encoding to use. Project Builder supports the JAVAC_SOURCE_FILE_ENCODING build setting to tell the compiler what encoding your Java files are in. The limitation here is that all the Java source files that are used in a single target need to have the same encoding. The reason for this is that Java compilers expect to be able to pull in and compile more than one source file, often implicitly as they locate cross-dependencies between classes. This makes it hard to compile a Java target in chunks where different encodings could be specified. While many encodings are supported by Java compilers, UTF-8 is, again, a very good choice for Java files.
When creating new files or projects, PB now warns the user of existing files that would be overwritten and gives some choices as to how to proceed. (In the last couple releases, PB would always save copies of the files being overwritten, but would give no warning to the user and did not allow other choices.)
Project templates now can show a description in the New Project Assistant that describe what they are for.
When a new Bundle target is created in an existing Application project, the user is asked whether to add the bundle to the application. This saves the user the often confusing operation of doing this by hand.
Entries in the Groups & Files as well as Targets list can be alphabetically sorted using the context menu. If a single group is selected, items within that group are sorted. If multiple entries are selected, they are sorted among each other. This sorting affects the project file.
Entries in the individual Build Phases editors (such as Headers, Resources) can be alphabetically sorted using the context menu. This sorting affects the build order (or link order in some cases).
The contents of the Bookmark / History popup menu in an editor can be cleared with the Clear File History menu item in the View menu. This is especially useful when the user has chosen to save project settings as this makes the popup grow over time beyond reason. Modified files listed in the history are not closed and remain in the history.
Two new Tasks have been defined for Bookmarks and Breakpoints. This allows users to prefer to have Bookmarks in a separate window from the Groups & files, etc... The Many Windows default configuration now has these tasks assigned to separate windows. Some Windows and One Window default configurations have these tasks assigned to the shared project window.
Folder references now filter out certain files from being shown. Filtering is done via a list of regular expressions. Files whose names match any of the expressions are not listed. The default list defaults to not showing CVS folders, .DS_Store files, and files starting with with .nfs. The PBXFolderDisplayFilters default can be used to override the default list.
There is now a preference in the Text Editor settings to show the current column number as well as the line number in the navigation bar. With this turned on the display will look like "Filename:line#:column#".
The class browser now shows argument types for Java methods.
In the Text Editing Preference pane, there's a new preference to show line numbers in the breakpoint gutter.
A full rewrite of the CVS integration support has been put in place by default. It provides performance improvements and many new features:
Performance when executing many CVS commands (like a project-wide status), is much improved and should not cause machine freezes anymore with larger projects. Responsiveness of the UI while the commands are being executed is also improved.
A 'CVS' task has been added that shows a flat table of all files in the project with "interesting" status. All the CVS menu items can act on this table (which is also sortable by status, filename, or path). This task can be shown via the new 'Show CVS' menu item (Shift-cmd-V) in the CVS menu.
Basic CVS authentication has been added, when means we now support pserver (without a .cvspass file), ssh (passphrase only), and rsh when connecting to a CVS repository (we continue to support direct access). By default Project Builder supports rsh external authenication. To enable ssh external authenication set the PBXUseExternalAuthenticationAsSSH default to YES.
The Update, Revert, and Compare menu items have been replaced with two new submenus: 'Update To' and 'Compare With'.
Update To
Specific Revision... - Brings up a dialog where you can type in the revision number. If you have a revision number selected in the active file editor, that revision is used.
Compare With
Specific Revision... - Brings up a dialog where you can type in the revision number to compare with. If you have a revision number selected in the active file editor, that revision is used.
The user can choose to use BBEdit for comparisons. They can also set which side the local file is displayed on and if ancestors should be used when merging.
CVS menu items can now act directly on the active file editor.
Files under CVS control needing to be merged (i.e. there is a potential for conflict) are now colored blue in the Files & Groups pane and the CVS pane. Files under CVS control that have actual conflicts are colored green.
The single-file find panel now has an option for whether the search should wrap around.
There's a new Launch Configuration UI in the Executable editor. This is still being fleshed out, but will add the ability to do a variety of things including controlling what debugger is used, running/debugging on remote systems, what to do with input and output, etc...
External editors are now supported by Project Builder. BBEdit or emacs work best, but other editors work to some extent. External editors are configured in the File Types preferences pane just like built in editors. Only vi and emacs are listed as choices initially, but you can select "Other..." and choose any application. Once you've chosen an application, it will always be available in the menu of external editors.
External editors are chosen per-file-type. So you might decide to use BBEdit for all source code, TextEdit for RTF, Preview for all images except TIFF, and Photoshop for TIFF. Minimal support for opening a file relies only on the application handling the standard 'odoc' AppleEvent (the same event Finder sends when you double-click a file). More sophisticated integration requires more support from the external application.
For BBEdit, the following functionality is in place: Double-clicking in any PB list will open the file in BBEdit, and if there's a selection range or line number, BBEdit will show it. (e.g. for build results, find results, bookmarks, stack frames, etc...) If you start a build with unsaved files, Project Builder will include unsaved BBEdit files in the Save All dialog, and allow you to save them. Some other text editors support showing selection ranges or lines. Most other text editors do not support the saving functionality.
Note that if you have a built-in editor in a window, single clicks will still load the file in Project Builder. But if PB loads a file internally that is set to use an external editor, it will load the file read-only and will not allow editing inside PB. What this means is that if your Batch Find window has an editor in it, you can still browse find results inside PB by single clicking them. But if you want to edit, you would double-click to edit them in BBEdit. If Project Builder notices that a file it has opened read-only has been saved by an external editor since it was last loaded, it will simply reload it.
In order to use emacs, you will have to add the following lines to your ~/.emacs configuration file (create a new file with these lines if you do not already have a ~/.emacs file):
(autoload 'gnuserv-start "gnuserv-compat" "Allow this Emacs process
to be a server for client processes." t)
(gnuserv-start)
Current Limitations:
If you move or update an external editor, you need to re-choose the editor to avoid a performance hit.
Setting and removing breakpoints using the breakpoint gutter has been changed. Clicking now toggles breakpoints on and off for a line. Command-clicking a breakpoint enables/disables the breakpoint without removing it. There's a context menu when you control-click on a breakpoint or in an empty area of the gutter. Breakpoints in the gutter are no longer "selectable".
There are now toggling menu commands in the Debug menu for adding/removing a breakpoint at the current line in the active editor and for enabling/disabling a breakpoint as well.
You can copy/drag backtrace information from the thread view in the debugger. The format is similar to gdb's 'bt' command.
Support for dynamic C++ types in the debugger integration. GDB now reports the dynamic type for C++ objects. This type is displayed in the Debugger type column (not shown by default; use the Context menu to enable it). The contents of a pointer to a C++ object are the fields from the full dynamic type hierarchy; these will change when the dynamic type changes. Due to a limitation in the symbolic debugging information, if the class is in a namespace, only the static type is displayed.
If you use GDB from the command line, you can request that GDB use the dynamic type by issuing the GDB command "set print object on". It is not recommended to use this with Project Builder from the GDB console; so do not put it in your .gdbinit file.
There's a new preference in the Text Settings tab to show line numbers in the breakpoint gutter.
There are now options for hiding/showing the gutter. There are now two options: show the gutter all the time, or show it only when debugging. The gutter in a particular editor can still be manually toggled on and off as well via the View menu.
If the UI seems confused about the state of the program being debugged you can use the gdb console with the command 'info prog' to find out if the program is stopped or running. If this reports that your program is stopped (ex."Program stopped at 0x3e38.") and the only active UI debugger button is 'pause' then you will need to type 'continue' in the gdb console to re-sync with gdb.
There is a new preferences pane for Customizing Command-Key Equivalents
Project Builder now lets you change the command-key equivalents for all its menu items and lets you change the keyboard shortcuts for common editing tasks, such as paging through a document and moving the cursor. You can choose a pre-defined set of key bindings or create your own. Simply choose Project Builder > Preferences and click Key Bindings.
You can choose from different predefined sets of key bindings, including sets that mimic the key bindings in popular text editors and Macintosh IDEs. To choose a predefined set of key bindings:
Choose Project Builder > Preferences, click Key Bindings, and use the Key Binding Sets menu.
Select the desired key binding set and click Apply
You can also create, copy, and delete sets of key bindings. To manage sets of key bindings:
Choose Project Builder > Preferences, click Key Bindings, and use New, Copy, and Delete buttons beside the Key Bindings Set menu
To create a new set of key bindings, click New. To copy an existing set of key bindings, choose the set from the Key Bindings Set menu and click Copy. To delete a set of key bindings, choose the set from the Key Bindings Set menu and click Delete.
To change the command-key equivalent for a menu item or to change key binding for a particular editing task:
Choose Project Builder > Preferences, click Key Bindings, and click the Menu Key Bindings or Text Key Bindings tab. The Menu Key Bindings section lists all the menu items in Project Builder, organized by menu. The Text Key Bindings section contains common editing tasks, organized by the type of task.
Double-click in the Key column beside the task or menu item, and press the new key combination.
For example, to change the command-key equivalent for Find Previous to be ⇧⌘G (command-shift-G), youÕd go to the Key Bindings preference pane, click the Menu Key Bindings tab, open the File menu by clicking the triangle besides Find, double-click in the Key column besides Find Previous, and hold down the Command, Shift, and G keys simultaneously. The command-key equivalent changes to ⇧⌘G.
In the Text Key Bindings tab, you can enter more than one key combination for a task by clicking the "+" button that appears when you begin editing. You can delete key equivalents on either tab by pressing the "-" button.
Text Key Bindings also support emacs-style multi-key bindings. To enter a multi-key equivalent, simply type the key prefix and then type additional keys. For example, to bind ⌃X⌃S (control-X control-S) to Save Document, simply type a ⌃X followed by a ⌃S in the Key field next to the Save Document command on the Text Key Bindings tab. Currently, Project Builder only supports ⌃X (control-X) as a multi-key prefix.
Remember that new key equivalents do not take effect until you click the Apply button.
Project Builder currently lists all key equivalents using the traditional menu glyphs. Below is a listing of the glyphs mapped to their English descriptions:
Command: ⌘ Shift: ⇧ Option: ⌥ Control: ⌃ Left Arrow: ← Home: ↖ Right Arrow: → End: ↘ Up Arrow: ↑ Page Up: ⇞ Down Arrow: ↓ Page Down: ⇟ Backspace: ⌫ Tab right: ⇥ Delete: ⌦ Return: ↩ Escape: ⎋ Enter: ⌤
Note: Due to current limitations in the underlying system, you cannot assign a menu key equivalent without the Command key.
Project Builder plug-ins can now have a 'ProjectBuilder Extras' folder in their resources which will be searched just like other 'ProjectBuilder Extras' locations for things like project and file templates, etc...
Improved User Scripts menu support. In the previous release, Project Builder's default StartupScript created a User Scripts menu and populated it with the Menu Script Definition files that it found in ~/Library/Application Support/Project Builder/Scripts. The start-up script visited the Menu Script Definition files in alphabetic order, adding their commands to the User Scripts menus. Beyond renaming the Menu Script Definition file, there was no easy way to specify the order of commands in the User Scripts menu. (See Project Builder Help for information about how to enable the User Scripts menu.)
In this release, StartupScript has been enhanced in a number of ways:
It first looks for an optional numeric prefix on the names of the Menu Script Definition files, and adds the commands in ascending order. Numeric prefixes should be integers less than 9000. Definition files that are not prefixed in this way are added alphabetically, after the definition files that have prefixes.
It supports a two-level menu hierarchy. The name of each immediate subfolder of ~/Library/Application Support/Project Builder/Scripts becomes the name of the corresponding submenu. Menu Script Definition files within the subfolders are added as commands of the corresponding submenu. You can determine where submenu names appear in the User Scripts menu by adding numeric prefixes to the subfolder names.
It interprets files with names like "n---" (where 'n' is a numeric prefix) as requests to put menu separators at the corresponding location in the list of menu commands. In other words, files whose names consist of an integer followed by three dashes will not be examined for script contents; they simply cause the start-up script to add a menu separator at the corresponding location in the menu it is building.
For example, if ~/Library/Application Support/Project Builder/Scripts contains these entries and subentries:
10-sort.sh
20-addCopyright.sh
30---
40-Search/
10- searchAppleDeveloper.pl
20-searchGoogle.pl
50---
BuildProject.sh
For example, if ~/Library/Application Support/Project Builder/Scripts contains these entries and subentries:
Sort
Insert copyright
Search > Search Apple Developer site for string
Search Google for
string
Build Project
Note the menu separator lines before and after the Search submenu name.
HeaderDoc convenience scripts have been added to the default User Scripts menu. Most of the scripts simply inject a specific type of HeaderDoc template (for function, typedef, and struct declarations, for example) at the insertion point of the active document. However, the "Insert @method template" command is somewhat smarter. If you select a method declaration and choose "Insert @method template", the declaration is parsed and the resulting comment lists the method name, each parameter name, and a field for comments about the return value, if appropriate. (The other comment-insertion scripts will be refined to this level in a later release.)
Integration of javadoc-generated documentation. Project Builder's documentation indexer (/Developer/Tools/pbhelpindexer) can now index HTML documentation generated by javadoc. After the documentation is indexed, it becomes accessible in PB in the standard ways Ñ entries in the Class browser (as well as in the results of a Batch Find) display book icons if documentation is available, and clicking the book takes you to the documentation. Option-double clicking a symbol in source code takes you to the related documentation, if it exists.
To be indexed, the documentation must be in plain files, not 'jar' archive files. (This restriction will be removed in a future release).
Mac OS X includes developer tools such as Project Builder, and it also includes developer documentation.
Additional Release Notes for Mac OS X are located in: /Developer/Documentation/ReleaseNotes
In this folder, there are Release Notes on specific tools, such as the compiler (Compiler.html), the GDB debugger (GDB.html), and the linker (CompilerTools.html), as well as on APIs (e.g. CoreFoundation.html, AppKit.html, Foundation.html, CarbonCore.html, etc...). The file PBOverview.html discusses the Project Builder IDE and its role in development on Mac OS X. Be sure to review the "Late Breaking News" section in PBOverview.html for any last-minute information about Project Builder. Also, for advanced build system information, check PBBuildSettings.html.
Apple Help on Mac OS X supports not only a user Help Center, but also a separate Developer Center. The Developer Center's table of contents is built dynamically just like the user Help Center. You can access the Developer Center and three of the main books in it directly from Project Builder's Help menu with the Developer Center, Developer Tools Help, Cocoa Help, and Carbon Help menu items. And, of course, you can access the help for Project Builder directly with the Project Builder Help menu item.
Apple's reference documentation is indexed using a special markup specification. Project Builder indexes these markups and can perform searches on them. If you do Definition searches in Project Builder, each result for which there is documentation will have a little book icon next to it. If you click the book icon, Help Viewer will be messaged to show the documentation for the API. Similarly, every class or method in the class browser that has documentation will also have a little book next to it.
http://developer.apple.com: Apple's Developer Central site is the best source of official up to date technical documentation on Mac OS X as well as being the primary place to find out about developing for the Macintosh platform.
http://developer.apple.com/tools/projectbuilder: The Project Builder home page on Apple's developer site.
http://www.stepwise.com: Stepwise is a great site for finding Mac OS X information including exclusive articles (often developer-centric) as well as links to Mac OS X related articles all over the web. It also has links to a number of other resources for Mac OS X and Cocoa developers. Plus there's SofTrak, a Mac OS X specific database tracking third party software releases and versions.
There are a number of mailing lists that are great for Mac OS X & Project Builder developers. First are the Apple-hosted lists. For more information please go to http://lists.apple.com. There are lists on the following topics and many more:
- projectbuilder-users: This list is great for asking (and answering) questions about the IDE.
- java-dev: A place for Mac Java developers to hang out.
- cocoa-dev: Keep in touch with the Cocoa community.
- carbon-dev: Keep in touch with the Carbon community.
- fortran-dev: For fortran development issues.
- unix-porting: for folks porting standard Unix software packages.
There are also some mailing lists you cannot subscribe to but that can be used to send feedback about various things to Apple:
- macosx-tools-feedback@group.apple.com: Send suggestions on how to improve Project Builder and other Developer Environment tools and apps to this list. (Bug reports should be reported through the normal ADC site: http://developer.apple.com/bugreporter.)
- cocoa-feedback@group.apple.com: Ever wish that NSView had that one essential method you're missing? Suggest it here.
Finally, there are some external mailing lists that might be of interest to Mac OS X developers:
- macosx-dev@omnigroup.com: This is a lively forum for asking and answering questions about Mac OS X development issues. It is also a good place to discuss ideas and learn new things. Lots of Cocoa discussion goes on here, and some Carbon stuff as well. Plenty of new Cocoa developers have found this list and it has recently become a great place to learn about Cocoa.
- macosx-talk@omnigroup.com: This is a very high traffic list. Discussions of issues not directly developer related or issues that are too "religious" to be fruitfully discussed on the macosx-dev list get shunted here. Lots of advocacy and griping too!