Legacy Document

Inside Macintosh: Mac OS Runtime Architectures /

Chapter 1 - CFM-Based Runtime Architecture / Preparing a Closure

Searching for Import Libraries

When the Code Fragment Manager is called to prepare a fragment, if the fragment requires other import libraries to complete the closure, the Code Fragment Manager goes through an ordered search process to find physical copies of those libraries. For example, the Code Fragment Manager can search folders containing the application or the root fragment as well as a common folder specially designated to hold shared libraries.

Currently the Code Fragment Manager looks for files that contain a resource of type 'cfrg'. The 'cfrg'0 resource identifies the fragment name of the import library. There can be more than one fragment name listed in a single 'cfrg'0 resource. This might happen if there are multiple import libraries contained in a single file or if a single import library or application is to be identified by more than one name. Fragments are typically stored in the data fork, although it is possible to store a fragment in a resource. In either case, the 'cfrg'0 resource points to the location of the fragment within the file. For more information about the 'cfrg'0 resource, see "The Code Fragment Resource," beginning on page 1-25.

Once the Code Fragment Manager finds a library that is compatible with the fragment it's preparing, it stops searching and resolves imports in the fragment to code or data in that library. If it reaches the end of its search without finding a compatible library, the fragment preparation fails.

Note

Because the Code Fragment Manager is searching for the import library by name, the file containing the library must have a 'cfrg'0 resource. However, you can prepare fragments that do not contain a 'cfrg'0 resource by calling Code Fragment Manager routines from your program. See "Calling the Code Fragment Manager," beginning on page 3-3, for more information.

In System 7 through 7.5, the search process for import libraries is as follows:

1. Check connections in the same process to see if a connection for the import library already exists.

   If the connection is already in use in another closure, then the Code Fragment Manager can simply increment its reference count and use it.

   If the existing connection is associated with an incompatible version of the import library, the preparation fails. In all the steps that follow, however, finding an incompatible import library version merely causes the Code Fragment Manager to move to the next step in the search procedure. See "Checking for Compatible Import Libraries" (page 1-19) for more information about how the Code Fragment Manager checks for compatible libraries.

2. Check the folder containing the root fragment.

   If the root fragment folder is not the same as the application folder, the Code Fragment Manager searches here first. The Code Fragment Manager looks only in the top level of the folder, not in any subfolders contained within it.

3. Check the file containing the application.

   Since a file can contain multiple fragments, the file containing the application fragment may also contain import library fragments.

4. Check the application subfolder.

   When you build your application, you can designate a library folder for the Code Fragment Manager to search for import libraries. For more information, see "The Code Fragment Resource," beginning on page 1-25.

5. Check the folder containing the application.

   The Code Fragment Manager looks only in the top level of the application folder, not in any subfolders contained within it.

6. Check the Extensions folder.

   The Extensions folder usually contains import libraries used by multiple applications (libraries for QuickTime, for example). The Code Fragment Manager searches the Extensions folder and one level of folders inside the Extensions folder.

7. Check the ROM registry.

   The ROM registry keeps track of all import libraries that are stored in the ROM of a Mac OS-based computer. The Mac OS registers all ROM-based import libraries in this registry at system startup time.

8. Check the file registry.

   The final stage of the search path is a file and directory registry that the Code Fragment Manager maintains internally. This registry, which is currently reserved for system use, is a list of files and directories that, for various reasons, cannot be put into the normal search path followed by the Code Fragment Manager or would not be recognized as import libraries even if they were in that path.

In System 7.6, the Code Fragment Manager combines steps 6, 7, and 8, searching all three locations and choosing the import library that best fits the compatibility requirements.

The Code Fragment Manager searches a folder by looking for files of type 'shlb' that contain a resource of type 'cfrg'. Within a folder, the Code Fragment Manager also looks for alias files of type 'shlb' and resolves them to their targets.

At any stage, the Code Fragment Manager selects the one import library of all those available to it that best satisfies its compatibility version checking. If an import library meets the relevant criteria, the library search stops. Otherwise, the search continues to the next stage. If the final stage (the file and directory registry) is reached and no suitable library can be found, the Code Fragment Manager gives up and does not prepare the original fragment.