Legacy Document

Inside Macintosh: Mac OS Runtime Architectures /

Chapter 1 - CFM-Based Runtime Architecture / The Structure of Fragments

The Code Fragment Resource

If the Code Fragment Manager is to search for a fragment by name, the file containing the fragment must contain a code fragment resource in the resource fork. A code fragment resource is a resource of type 'cfrg' with ID 0 ('cfrg'0 resource).

The code fragment resource has the form shown in Listing 1-2.

Listing 1-2 The code fragment resource

   struct CFragResource {
      UInt32            reservedA;/* must be zero! */
      UInt32            reservedB;/* must be zero! */
      UInt16            reservedC;/* must be zero! */
      UInt16            version;
      UInt32            reservedD;/* must be zero! */
      UInt32            reservedE;/* must be zero! */
      UInt32            reservedF;/* must be zero! */
      UInt32            reservedG;/* must be zero! */
      UInt16            reservedH;/* must be zero! */
      UInt16            memberCount;
      CFragResourceMemberfirstMember;
   };

• The version field indicates the version of the code fragment resource. The current version is 1.
• The memberCount field indicates how many fragment entries ('cfrg'0 entries) are described by this resource.
• Each entry of type CFragResourceMember describes a fragment entry, listing the type of fragment, its name, location, and so on.

Since the 'cfrg'0 resource is an array, it is possible to store information for several fragments in one file. The fragments remain separate and the Code Fragment Manager can prepare them independently, but they can be shipped and marketed as a single file. In addition, the code fragment resource can point to fragments of multiple architectures, allowing you to create fat applications and shared libraries that can execute on multiple platforms. See Chapter 7, "Fat Binary Programs," for more information.

Note

Typically you can use a development tool (such as MergeFragment in MPW) to place multiple fragments in a file.

The structure of the code fragment resource is identical for all fragment types, although some of the field values may differ. Field values in the code fragment resource are determined and set at link time, but some may be changed later using a resource editor (such as ResEdit). Field values are defined in CodeFragments.h.

A code fragment resource entry has the form shown in Listing 1-3.

Listing 1-3 A code fragment resource entry

   struct CFragResourceMember {
      CFragArchitecturearchitecture;
      UInt16         reservedA;  /* zero */
      UInt8          reservedB;  /* zero */
      UInt8          updateLevel;
      CFragVersionNumbercurrentVersion;
      CFragVersionNumberoldDefVersion;
      CFragUsage1UnionuUsage1;
      CFragUsage2UnionuUsage2;
      CFragUsage     usage;
      CFragLocatorKindwhere;
      UInt32         offset;
      UInt32         length;
      UInt32         reservedC;  /* zero */
      UInt32         reservedD;  /* zero */
      UInt16         extensionCount;/* number of extensions */
      UInt16         memberSize; /* total size in bytes */
      unsigned char  name [kDefaultCFragNameLen];
   };

• The architecture field indicates the runtime environment of the fragment. Current values for this field are as follows:
  • kPowerPCCFragArch for the PowerPC runtime environment
  • kMotorola68KCFragArch for the CFM-68K runtime environment
  • kCompiledCFragArch, which is conditionally set at compile time. For example, if you are compiling for the PowerPC runtime environment, this value is set to kPowerPCCFragArch. You can specify this value in source code that is used for both PowerPC and CFM-68K builds.

• The updateLevel field indicates whether this fragment is a base fragment or one created to update another fragment. This field typically has the value kIsCompleteCFrag to indicate a base fragment.
• The next two fields, currentVersion and oldDefVersion, store the current and oldest definition version numbers that the Code Fragment Manager relies on for checking compatibility with client fragments. If a fragment does not export any symbols, it does not need to check compatibility, and these values can be ignored.
• The uUsage1 field contains a union defined as

  union CFragUsage1Union {
    UInt32  appStackSize;
   };

  If the fragment is an application, appStackSize indicates the application stack size. Typically appStackSize has the value kDefaultStackSize.

• The uUsage2 field contains a union defined as

  union CFragUsage2Union { 
    SInt16  appSubdirID;
   };

  If the fragment is an application, appSubdirID indicates the library directory. By default, the Code Fragment Manager searches the folder containing the application and the Extensions folder when looking for import libraries, but you can specify a library directory in addition to the default search directories (see "Searching for Import Libraries," beginning on page 1-16, for more information). If you do not specify a library directory, this field has the value kNoAppSubFolder. In System 7, if you want to add another library directory, you must change this field to the resource ID of an alias resource (a resource of type 'alis') in the application's resource fork. This resource should describe the application's library directory. For more information about alias resources, see the chapter "Alias Manager" in Inside Macintosh: Files.

• The usage field indicates the type of fragment. Possible values are as follows:
  • kApplicationCFrag for an application
  • kImportLibraryCFrag for an import library
  • kDropInAdditionCFrag for a plug-in

• The where field indicates where the fragment is located. Possible values are as follows:
  • kDataForkCFragLocator if the fragment is in the data fork
  • kMemoryCFragLocator if the fragment is stored in ROM
  • kResourceCFragLocator if the fragment is stored in a resource

• The next two fields, offset and length, indicate the starting and ending offsets of the fragment container. For example, the values kZeroOffset and kCFragGoesToEOF indicate that the container for the fragment starts at the beginning of the data fork and ends at the end of the data fork.

  If the fragment is stored in a resource, the offset field describes the type of resource, and the length field contains the resource ID number.

• The field extensionCount indicates the number of extensions. See "Extensions to Code Fragment Resource Entries" (page 1-29) for more information.
• The field memberSize contains the total size, in bytes, of the code fragment resource entry. This size includes any extensions.
• The name field contains the name of the fragment.

Extensions to Code Fragment Resource Entries

The basic code fragment resource entry structure shown in Listing 1-3 is used for most applications and shared libraries. However, a code fragment resource entry can also contain one or more extensions, which appear directly after the fragment name. Such an extended code fragment resource entry stores additional information about the fragment that may be used by third-party software. For example, while the regular entry might simply indicate that a fragment mooLib is an import library, an extension could also indicate that it is a SOM class library that inherits from the class cow.

Note

A code fragment resource can contain any combination of extended and regular entries.

Padding is added after the name field to begin the extensions on a 4-byte boundary (the length byte of the name string does not include this padding). All extensions must be aligned on 4-byte boundaries, with padding added after each if necessary. The memberSize field includes any padding added after the last extension.

An extension to the code fragment resource has the form shown in Listing 1-4.

Listing 1-4 Structure of a sample code fragment resource extension

   struct CFragResourceSearchExtension {
      CFragResourceExtensionHeaderextensionHeader;
      ExtensionData           data [1];
   };

The extensionHeader field contains a data structure defined as shown in Listing 1-5.

Listing 1-5 The code fragment resource extension header

   struct CFragResourceExtensionHeader {
      UInt16extensionKind;
      UInt16extensionSize;
   };

• The extensionKind field defines the type of extension. Each type defines the format of the information contained in the extension. Currently only one is defined (extensionKind = 30EE).
• The extensionSize field specifies the total size, in bytes, of this extension, including any padding necessary to round the extension to a 4-byte boundary. This size added to the offset of the extension gives the offset of the next extension (if any).

The information that follows the extensionHeader field depends on the value of extensionKind. As an example, Listing 1-6 shows the format of the code fragment resource extension of type 30EE.

Listing 1-6 A code fragment resource extension of type 30EE

   struct CFragResourceSearchExtension {
      CFragResourceExtensionHeaderextensionHeader;
      OSType                  libKind;
      unsigned char           qualifiers [1];
   };

• The libKind field indicates the type of fragment. Currently defined values are as follows:
  • kFragDocumentPartHandler for a part handler
  • kFragSOMClassLibrary for a SOM class library
  • kFragInterfaceDefinition for an interface definition library
  • kFragComponentMgrComponent for a component used by the Component Manager

• After the libKind field, you can define up to four Pascal-style strings in the qualifiers field. The values of these strings depend on the libKind field. The currently defined values are as follows:
  • For type kFragDocumentPartHandler, the first qualifier indicates the handler type. The second qualifier indicates the handler subtype (if any).
  • For type kFragSOMClassLibrary, the first qualifier indicates the base class.
  • For type kFragInterfaceDefinition, the first qualifier indicates the interface definition name.
  • For type kFragComponentMgrComponent, the first qualifier indicates the component type. The second qualifier indicates the component subtype.

    For any extension, the fourth qualifier can hold the name of the fragment. Unlike the string in the name field, this string is visible to the client fragment.

Sample Code Fragment Resource Entry Definitions

This section contains examples of the most common types of code fragment resource entries.

A PowerPC Application 'cfrg' 0 Resource Definition

Listing 1-7 shows an example of a 'cfrg'0 resource definition for a PowerPC application.

Listing 1-7 A sample 'cfrg'0 resource for a PowerPC runtime application

#include "CodeFragmentTypes.r"
resource 'cfrg' (0) {
   {
      kPowerPCCFragArch,/* runtime environment */
      kIsCompleteCFrag, /* base-level library */
      kNoVersionNum,    /* current version number*/
      kNoVersionNum,    /* oldest definition version number */
      kDefaultStackSize,/* use default stack size */
      kNoAppSubFolder,  /* no library directory */
      kApplicationCFrag,/* fragment is an application */
      kDataForkCFragLocator,/* fragment is in the data fork */
      kZeroOffset,      /* beginning offset of fragment */
      kCFragGoesToEOF,  /* ending offset of fragment */
      "mooApp"          /* name of the fragment*/
   }

• The value kPowerPCCFragArch indicates that this fragment was created for use with the PowerPC runtime environment.
• The value kIsCompleteCFrag indicates that the fragment is complete by itself.
• The constant kNoVersionNum in the next two fields has the value 0, a valid version number.
• The constant kDefaultStackSize in the next field indicates that the stack should be given the default size for the current software and hardware configuration. In System 7, you can use stack-adjusting techniques that call GetApplLimit and SetApplLimit if you determine at runtime that your application needs a larger or smaller stack.
• The constant kNoAppSubFolder indicates that there is no library search folder.
• The value kApplicationCFrag indicates that this is an application.
• The value kDataForkCFragLocator indicates that the fragment is stored in the data fork of the file.
• The values kZeroOffset and kCFragGoesToEOF in the next two fields indicate that the container for the fragment starts at the beginning of the data fork and ends at the end of the data fork.
• The default fragment name is usually the name of the output file from the linker, but you can assign a specific name if you wish.

A CFM-68K Application 'cfrg' 0 Resource Definition

Listing 1-8 shows a sample 'cfrg'0 resource definition for a CFM-68K runtime application. The fields that have values different from those in a PowerPC application 'cfrg'0 resource entry are underlined.

Listing 1-8 A sample 'cfrg'0 resource for a CFM-68K runtime application

#include "CodeFragmentTypes.r"
resource 'cfrg' (0) {
   {
      kMotorola68KCFragArch,   /* runtime environment */
      kIsCompleteCFrag,        /* base-level library */
      kNoVersionNum,           /* no current version number*/
      kNoVersionNum,           /* no oldest definition version number */
      kDefaultStackSize,       /* use default stack size */
      kNoAppSubFolder,         /* no library directory */
      kApplicationCFrag,       /* fragment is an application */
      kResourceCFragLocator,   /* fragment is in a resource */
      kRSEG,                   /* resource type = 'rseg' */
      kSegIDZero,              /* resource ID = 0 */
      "mooApp"       /* name of the application fragment*/
   }

• The constant kMotorola68KCFragArch in the first field indicates that this fragment was created for use with the CFM-68K runtime environment.
• The next underlined value, kResourceCFragLocator, indicates that this is a segmented application stored in resources.
• The next two underlined fields, kRSEG and kSegIDZero, tell the Code Fragment Manager that the initial container to load is contained in a resource of type 'rseg' with a resource ID 0.

For more information about the structure of CFM-68K applications, see "CFM-68K Application Structure," beginning on page 9-3.

A Shared Library 'cfrg' 0 Resource Definition

Shared libraries have essentially the same 'cfrg'0 resource entry for both PowerPC and CFM-68K implementations (only the field indicating the runtime environment differs).

Listing 1-9 shows the 'cfrg'0 resource for an import library (plug-ins are identical except the fragment type is set to kDropInAdditionCFrag). Values that differ from an application's 'cfrg'0 resource are underlined.

Listing 1-9 A sample 'cfrg'0 resource for an import library

#include "CodeFragmentTypes.r"
resource 'cfrg' (0) {
   {
      kPowerPCCFragArch,          /* runtime environment */
      kIsCompleteCFrag,           /* base-level library */
      6,                          /* current version number*/
      4,                          /* oldest definition version number */
      kDefaultStackSize,          /* use default stack size */
      kNoAppSubFolder,            /* no library directory */
      kImportLibraryCFrag,        /* fragment is a library */
      kDataForkCFragLocator,      /* fragment is in the data fork */
      kZeroOffset,                /* fragment starts at offset 0 */
      kCFragGoesToEOF,            /* fragment occupies entire fork */
      "mooLib"                    /* name of the library fragment */
   }

• The first two underlined fields store the current and definition version numbers that the Code Fragment Manager relies on for checking compatibility with client fragments. If you do not specify version numbers when you link, the version numbers are set to 0. See "Checking for Compatible Import Libraries," beginning on page 1-19, for more details.
• The application stack size field is ignored for shared libraries.
• The library directory field is ignored for shared libraries.
• The value kImportLibraryCFrag specifies that this is an import library. A plug-in would have the value kDropInAdditionCFrag.
• As you do with an application, you may supply a specific library name. However, for an import library you must do so before linking to a client because the fragment name is bound to the client at link time.