---

Porting Tips

Although many applications have been created from scratch for Mac OS X, many more have been ported from existing Windows, UNIX, or Mac OS 9 applications. With the introduction of the G5 processor, some application developers are even taking the step of porting their 32-bit applications to the 64-bit memory space offered by the new architecture.

The Reference Library > Porting section of the Apple Developer Connection Reference Library contains documents to help you in your porting efforts. The following sections also provide general design guidelines to consider when porting software to Mac OS X.

In this section:

64-Bit Considerations
Windows Considerations
Carbon Considerations

64-Bit Considerations

With Macintosh computers using 64-bit PowerPC and Intel processors, developers can begin writing software to take advantage of the 64-bit architecture provided by these chips. For many developers, however, compiling their code into 64-bit programs may not offer any inherent advantages. Unless your program needs more than 4 GB of addressable memory, supporting 64-bit pointers may only reduce the performance of your application.

When you compile a program for a 64-bit architecture, the compiler doubles the size of all pointer variables. This increased pointer size makes it possible to address more than 4 GB of memory, but it also increases the memory footprint of your application. If your application does not take advantage of the expanded memory limits, it may be better left as a 32-bit program.

Regardless of whether your program is currently 32-bit or 64-bit, there are some guidelines you should follow to make your code more interoperable with other programs. Even if you don’t plan to implement 64-bit support soon, you may need to communicate with 64-bit applications. Unless you are explicit about the data you exchange, you may run into problems. The following guidelines are good to observe regardless of your 64-bit plans.

• Avoid casting pointers to anything but a pointer. Casting a pointer to a scalar value has different results for 32-bit and 64-bit programs. These differences could be enough to break your code later or cause problems when your program exchanges data with other programs.

• Be careful not to make assumptions about the size of pointers or other scalar data types. If you want to know the size of a type, always use the sizeof (or equivalent) operator.

• If you write integer values to a file, make sure your file format specifies the exact size of the value. For example, rather than assume the generic type int is 32 bits, use the more explicit types SInt32 or int32_t, which are guaranteed to be the correct size.

• If you exchange integer data with other applications across a network, make sure you specify the exact size of the integer.

There are several documents to help you create 64-bit applications. For general information about making the transition, see 64-Bit Transition Guide. For Cocoa-specific information, see 64-Bit Transition Guide for Cocoa. For Carbon-specific information, see 64-Bit Guide for Carbon Developers.

.

Windows Considerations

If you are a Windows developer porting your application to Mac OS X, be prepared to make some changes to your application as part of your port. Applications in Mac OS X have an appearance and behavior that are different from Windows applications in many respects. Unless you keep these differences in mind during the development cycle, your application may look out of place in Mac OS X.

The following list provides some guidelines related to the more noticeable differences between Mac OS X and Windows applications. This list is not exhaustive but is a good starting point for developers new to Mac OS X. For detailed information on how your application should look and behave in Mac OS X, see Apple Human Interface Guidelines. For general porting information, see Porting to Mac OS X from Windows Win32 API.

• Avoid custom controls. Avoid creating custom controls if Mac OS X already provides equivalent controls for your needs. Custom controls are appropriate only in situations where the control is unique to your needs and not provided by the system. Replacing standard controls can make your interface look out of place and might confuse users.

• Use a single menu bar. The Mac OS X menu bar is always at the top of the screen and always contains the commands for the currently active application. You should also pay attention to the layout and placement of menu bar commands, especially commonly used commands such as New, Open, Quit, Copy, Minimize, and Help.

• Pay attention to keyboard shortcuts. Mac OS X users are accustomed to specific keyboard shortcuts and use them frequently. Do not simply migrate the shortcuts from your Windows application to your Mac OS X application. Also remember that Mac OS X uses the Command key not the Control key as the main keyboard modifier.

• Do not use MDI. The Multiple Document Interface (MDI) convention used in Microsoft Windows directly contradicts Mac OS X design guidelines. Windows in Mac OS X are document-centric and not application-centric. Furthermore, the size of a document window is constrained only by the user’s desktop size.

• Use Aqua. Aqua gives Mac OS X applications the distinctive appearance and behavior that users expect from the platform. Using nonstandard layouts, conventions, or user interface elements can make your application seem unpolished and unprofessional.

• Design high-quality icons and images. Mac OS X icons are often displayed in sizes varying from 16x16 to 512x512 pixels. These icons are usually created professionally, with millions of colors and photo-realistic qualities. Your application icons should be vibrant and inviting and should immediately convey your application’s purpose.

• Design clear and consistent dialogs. Use the standard Open, Save, printing, Colors, and Font dialogs in your applications. Make sure alert dialogs follow a consistent format, indicating what happened, why it happened, and what to do about it.

• Consider toolbars carefully. Having a large number of buttons, especially in an unmovable toolbar, contributes to visual clutter and should be avoided. When designing toolbars, include icons only for menu commands that are not easily discoverable or that may require multiple clicks to be reached.

• Use an appropriate layout for your windows. The Windows user interface relies on a left-biased, more crowded layout, whereas Aqua relies on a center-biased, spacious layout. Follow the Aqua guidelines to create an appealing and uncluttered interface that focuses on the task at hand.

• Avoid application setup steps. Whenever possible, Mac OS X applications should be delivered as drag-and-drop packages. If you need to install files in multiple locations, use an installation package to provide a consistent installation experience for the user. If your application requires complex setup procedures in order to run, use a standard Mac OS X assistant. For more information, see “Bundles and Packages.”

• Use filename extensions. Mac OS X fully supports and uses filename extensions. For more information about filename extensions, see File System Overview.

Carbon Considerations

If you develop your software using Carbon, there are several things you can do to make your programs work better in Mac OS X. The following sections list migration tips and recommendations for technologies you should be using.

Migrating From Mac OS 9

If you were a Mac OS 9 developer, the Carbon interfaces should seem very familiar. However, improvements in Carbon have rendered many older technologies obsolete. The sections that follow list both the required and the recommended replacement technologies you should use instead.

Required Replacement Technologies

The technologies listed in Table 8-1 cannot be used in Carbon. You must use the technology in the “Now use” column instead.

Recommended Replacement Technologies

The technologies listed in Table 8-2 can still be used in Carbon, but the indicated replacements provide more robust support and are preferred.

Use the Carbon Event Manager

Use of the Carbon Event Manager is strongly recommended for new and existing Carbon applications. The Carbon Event Manager provides a more robust way to handle events than the older Event Manager interfaces. For example, the Carbon Event Manager uses callback routines to notify your application when an event arrives. This mechanism improves performance and offers better mobility support by eliminating the need to poll for events.

For an overview of how to use the Carbon Event Manager, see Carbon Event Manager Programming Guide.

Use the HIToolbox

The Human Interface Toolbox is the technology of choice for implementing user interfaces with Carbon. The HIToolbox extends the Macintosh Toolbox and offers an object-oriented approach to organizing the content of your application windows. This new approach to user interface programming is the future direction for Carbon and is where new development and improvements are being made. If you are currently using the Control Manager and Window Manager, you should consider adopting the HIToolbox.

For an overview of HIView and other HIToolbox objects, see the documents in Reference Library > Carbon > Human Interface Toolbox.

Use Nib Files

Nib files, which you create with Interface Builder, are the best way to design your application interface. The design and layout features of Interface Builder will help you create Aqua-compliant windows and menus. Even if you do not plan to load the nib file itself, you can still use the metrics from this file in your application code.

For information about using Interface Builder, see Interface Builder User Guide.

---