Technical Note TN1126

Checklist for Building Applications and Extensions

CONTENTS Applications Extensions, Control Panels, Desk Accessories and Shared Libraries Documents Preference Files Summary References Change History Downloadables

This Technote tries to summarize all of the different items which you need to include to build a good, well-behaved Macintosh product.  Updated: [Oct 19 1998]

Applications

Bundle

• Include a 'BNDL', 'FREF', and icon resources so that the Finder displays your application and documents with an unique icon. See the discussion of bundles in Inside Macintosh:Macintosh Toolbox Essentials chapter 7, "The Finder Interface", for details.
• Set the bundle bit if you are including a icon for your application. This is easy to forget in the build process. Check the validity of your bundle with a utility such as "Save a Bundle" or "BNDL Banger", found on the various shareware sites.
• Register your creator with DTS. See the web page <http://developer.apple.com/dev/cftype/> for details. You must have a unique creator code for each application that includes a bundle.

Bits to Set

• You need to set the isShared bit in the Finder flags to allow your application to be launched multiple times across a network. See Inside Macintosh:Macintosh Toolbox Essentials chapter 7, "The Finder Interface", for details. If you set the isShared bit, check that your application does not try to write to its own resource or data fork. In addition, check that your application does not try to write to any locations other than its preference file in the Preferences folder in the System Folder, which can be found and created using FindFolder.
• If you are using AppleEvents, set the isHighLevelEventAware bit in the 'SIZE' resource. If you do not do this, you will get error -903 when you call AESend or when you call any routine that uses AESend.

Resources to Add

• Provide a 'hfdr' resource with resource ID number -5696 to display a help string description of your application in Balloon Help, and for the Extensions Manager. See Inside Macintosh:Macintosh Toolbox Essentials chapter 7, "The Finder Interface", for details. Here is a sample of Rez input for a help balloon resource for an application icon:
  
  

  resource 'hfdr' (-5696, purgeable) { HelpMgrVersion, hmDefaultOptions, 0, 0, {HMSTRResItem {kIconHelpString}} }; resource 'STR ' (kIconHelpString, purgeable) { "Use the SurfWriter word processor to create or edit the" "best documents you ever wrote on your Macintosh computer." };

  
  
  
• Provide a 'SIZE' resource with its bits set correctly. See Inside Macintosh:Macintosh Toolbox Essentials chapter 2, "The Event Manager", for details.
• Provide the 'vers' resources with resource ID numbers 1 and 2. The 'vers' 1 resource provides information about an individual file, while the 'vers' 2 resource provides information about a group of files which make up a particular product. The Finder displays 'vers' 1 information at the bottom of the Get Info window and the 'vers' 2 information at the top. The 'vers' 2 resource is also used in the Extensions Manager for information about an entire package of files. For details see Inside Macintosh:Macintosh Toolbox Essentials chapter 7, "The Finder Interface" and Technote OV 12, "Version Territory."

  Here is a sample of Rez input for a pair of version resources:

  
  
  

  resource 'vers' (1, purgeable) { 0x01, 0x00, release, 0x00, verUS, "1.0", "1.0 (US), © My Company, Inc. 1998" }; resource 'vers' (2, purgeable) { 0x02, 0x00, release, 0x00, verUS, "2.0", "(for SurfWriter 3.0)" };

  
  
  
• If you are writing a PowerPC-only application, include enough 68K code (in 'CODE' resources with resource ID numbers 0 and 1) to put up a dialog informing the user that this application will not run on a 68K machine. ( 0 = segment table, 1 = actual code )
• Include a resource of type 'open' to tell the Finder what kinds of documents you recognize. For details of the 'open' resource, see Inside Macintosh:More Macintosh Toolbox chapter 7, "The Translation Manager".

  Here is a sample of Rez input for a resource of type 'open'

  :
  
  

  resource 'open' (128) { 'ttxt', { 'ttro', 'PICT', 'TEXT' } };

  
  
  
• Include a resource of type 'kind' to tell Macintosh Easy Open what kinds of documents you recognize. For details of the 'kind' resource, see Inside Macintosh:More Macintosh Toolbox chapter 7, "The Translation Manager".

Other details

• Set your default stack size to a reasonable value. For PowerPC code, the stack size is set by a field in the 'cfrg' resource of the launched application. Using a value of 0 yields a stack size of 48K (though this may change in future system versions). For 68K code, the default stack size is 32K on 680x0 machines with Color QuickDraw, 24K on 68020 and higher machines without Color QuickDraw, and 8K on 68000 machines. Starting with System 7.6, Background Only Applications have a 8K default stack size; prior to that version, they have a 2K default stack size. You increase the amount of stack available to your program by using the call SetApplLimit before any other memory manager calls have been made. For example,
  
  

  SetApplLimit(GetApplLimit() - 16384);

  
  
  

  increases the stack by 16K. Call SetApplLimit before you call MaxApplZone or any other Memory Manager call. See Inside Macintosh:Memory Errata which points out that SetApplLimit has a minimum threshold below which you cannot set the stack. See also Technote 1070, "Background Only Applications" for details of heap corruption in Background Only Applications which can affect system stability.

• All applications and Background Only Applications should have a memory partition set to at least 64K. This ensures there is always enough room for the system and extensions to work in the application's heap.
• Set the following resources as purgeable: 'DLOG', 'DITL', 'dctb', 'ictb', 'actb', 'dftb', 'dlgx', 'CNTL', 'WIND'
• Set the following resource as non-purgeable: 'WDEF'
• You will usually find that if you turn off MacsBug symbols (68K) and traceback tables (PowerPC), you will generate smaller binaries. See your development environment's documentation for details about how to disable MacsBug symbols and traceback tables.
• Check that you have removed all calls to DebugStr and Debugger from your final build. Search 68K binaries for the hexadecimal values A9FF or ABFF, which are the trap words for Debugger and DebugStr. For PowerPC, use DumpPEF and verify that your application does not import the DebugStr or Debugger symbols.
• If your application requires any extensions, or weak-links to any shared libraries, test your application to make sure it works correctly even if those libraries are removed from the system. See Technote 1083, "Weak-Linking to a Code Fragment Manager-based Shared Library" for details.

Back to top

System Extensions, Control Panels, Desk Accessories and Shared Libraries

Preferred File Types

• If possible, write your control panel as an application with the file type of 'APPC'. See Technote 1090, "System 7.6" for details.
• Desk Accessories of the classic 'DRVR' style are especially discouraged. If possible, write your desk accessory as an application with the file type of 'APPD'. See Technote 1090, "System 7.6" for details.
• System extensions implemented as INIT resources are a bad idea in the general case: they can reduce system stability and are difficult to debug. If possible, write what would have been an INIT resource as a Background Only Application. See Technote 1070, "Background Only Applications" for details. Include support for the 'quit' AppleEvent, since this is the only way for the system to tell your Background Only Application to terminate.

Bundle

• Include a 'BNDL', 'FREF', and icon resources so that the Finder displays your program with an unique icon. See the discussion of bundles in Inside Macintosh:Macintosh Toolbox Essentials chapter 7, "The Finder Interface", for details.
• Set the bundle bit in the Finder flags if you are including a bundle for your application. This is easy to forget in the build process. Check the validity of your bundle with a utility such as "Save a Bundle" or "BNDL Banger", found on the various shareware sites.
• Register your creator code with DTS. See the web page <http://developer.apple.com/dev/cftype/> for details. You must have a unique creator code for each program that includes a bundle.

Resources

• You need a 'CCI' resource with resource ID number 128 for Extensions Manager 4.0 compatibility. Here is a sample of Rez input for a 'CCI' resource:
  
  

  type 'CCI' as 'TEXT'; resource 'CCI' (128, purgeable) { "This extension is part of the SurfWriter package." "It serves as a demonstration for a technote." };

  
  
  
• You need a 'hfdr' resource with resource ID number -5696 to display a help string description of your file when Balloon Help is turned on, and for all versions of the Extensions Manager. See Inside Macintosh:Macintosh Toolbox Essentials chapter 7, "The Finder Interface", for details. Here is a sample of Rez input for a help balloon resource for an extension:
  
  

  resource 'hfdr' (-5696, purgeable) { HelpMgrVersion, hmDefaultOptions, 0, 0, {HMSTRResItem {kIconHelpString}} }; resource 'STR ' (kIconHelpString, purgeable) { "This extension is a demonstration for a technote." };

  
  
  
• If you need to allocate more than 16K of memory in an INIT resource of your system extension or control panel, use a 'sysz' resource with resource ID number of 0. The description of the use of the 'sysz' resource in Inside Macintosh: Operating System Utilities, chapter 9, "The Start Manager" is in error when it claims that the 'sysz' resource is not needed under System 7 or later. See Inside Macintosh:Memory Errata for an updated description.

Other Details

• To display an icon at system startup, use the sample code "ShowInitIcon" (also found on the Tool Chest Developer CD).
  
  
• Shared libraries are linked based off their 'cfrg' resource, and not the file name of the shared library. Ensure that the file names are written so that users can determine what kind of library it is, and what it may be used for.

Back to top

Documents

Resources

• You should add 'STR ' resources with resource ID numbers of -16396 and -16397 for the missing-application name string and the "this document cannot be opened" message string. This allows the Finder to display a meaningful error message when your documents cannot be opened because your application is not available. See Inside Macintosh:Macintosh Toolbox Essentials chapter 7, "The Finder Interface", for details. Here is a sample of Rez input for a missing-application name string resource:
  
  

  resource 'STR ' (-16396, purgeable) { "SurfWriter" };

  
  
  

  Here is a sample of Rez input for a "this document can not be opened" message string resource:

  
  
  

  resource 'STR ' (-16397, purgeable) { "Sorry, I can only be opened by the application SurfWriter." };

  
  
  

Back to top

Preference Files

Material concerning Preferences files has been removed from this Technote. The topic turned out to be too complicated to treat in a few sentences and is covered in Technote 1134, "The Preferences Problem".

Back to top

Summary

By going over this straightforward and quick checklist you can be sure that you have fixed the simple, yet significant, issues that would distract from your application's feel of quality fit-and-finish. You have also possibly eliminated some subtle bugs. By following these rules you are one step closer to having created the ideal Macintosh software product.

Back to top

References

Technote OV 12, "Version Territory"

Technote 1070, "Background Only Applications"

Technote 1090, "Mac OS 7.6"

Technote 1091, "Extensions Manager 4.0"

Technote 1134, "The Preferences Problem"

Inside Macintosh:Macintosh Toolbox Essentials chapter 2, "The Event Manager"

Inside Macintosh:Macintosh p Essentials chapter 7, "The Finder Interface"

Inside Macintosh:More Macintosh Toolbox chapter 7, "The Translation Manager"

Inside Macintosh:Operating System Utilities chapter 9, "The Start Manager"

Back to top

Change History

Back to top

Downloadables

Back to top