Debugging and Testing a Generator
Quick Look gives developers some facilities for debugging and testing their generator code. The following sections describe those facilities and offers some strategies and advice for debugging and testing generators.
Because a generator is a plug-in and is not a self-contained executable, debugging it could be problematic if you were left on your own. Fortunately, Quick Look gives you a way to debug generator code easily: the
qlmanage diagnostic tool (installed in
qlmanage executes your project’s generator in almost the same kind of environment as the Quick Look daemon (
quicklookd) does. You can run this tool as your project’s executable and, by specifying certain arguments, you can step through your generator code and see how it handles previews and thumbnails.
To set up your Quick Look project for debugging, complete the following steps:
Choose New Custom Executable from the Project menu.
In the Assistant window, enter “qlmanage” as the executable name. In the Executable Path field specify the full path to the tool:
Click Finish to dismiss the Assistant.
The Executable Info window appears for
qlmanage, as shown in Figure 10-1. Click the Arguments tab.
In the Arguments pane of the Executable Info window (Figure 10-2) enter one or more debugging options in the Arguments table.
qlmanagetool takes the following arguments:
Absolute path to document
Requests preview of specified document
Absolute path to document
Requests thumbnail of specified document.
quicklookdand the Quick Look client’s generator cache
Prints information on
quicklookdactions, including a list of detected generators
Prints a brief description of options
You can also run the
qlmanage tool from the command line. The following example requests a thumbnail of a specified document:
qlmanage -t /tmp/MySketchDoc.sketch2
This example displays a preview for a particular document:
qlmanage -p /tmp/MySketchDoc.sketch2
-m option for
qlmanage is useful, as it prints (to standard output) a report from the Quick Look daemon on current generator status.
Listing 10-1 Sample output of
2007-04-05 17:00:46.998 qlmanage[1190:d03] Server statistics:
server: living for 21s (9 requests handled)
memory used: 10 MB (10551296 bytes)
last burst: during 0s - 1 requests - 0s idle
com.apple.ichat.ichat -> /System/Library/QuickLook/iChat.qlgenerator
com.apple.safari.bookmark -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Bookmark.qlgenerator
com.apple.sketch1 -> /Library/QuickLook/QuickLookSketch.qlgenerator
public.rtf -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Text.qlgenerator
public.audio -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Audio.qlgenerator
com.apple.dashboard-widget -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/StandardBundles.qlgenerator
com.apple.rtfd -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Text.qlgenerator
com.microsoft.word.doc -> /System/Library/QuickLook/Office.qlgenerator
com.apple.addressbook.person -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Contact.qlgenerator
public.plain-text -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Text.qlgenerator
com.apple.quartz-composer-composition -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Movie.qlgenerator
public.xml -> /Library/QuickLook/QuickLookSweet.qlgenerator
com.apple.eventmanager.events -> /Library/QuickLook/WebViewQLPlugin.qlgenerator
com.apple.sketch2 -> /Library/QuickLook/QuickLookSketch.qlgenerator
com.apple.package -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Package.qlgenerator
com.apple.ical.bookmark -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/iCal.qlgenerator
com.adobe.pdf -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/PDF.qlgenerator
public.font -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Font.qlgenerator
com.apple.mail.emlx -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Mail.qlgenerator
com.microsoft.excel.xls -> /System/Library/QuickLook/Office.qlgenerator
com.apple.eventmanager.eventsbin -> /Library/QuickLook/WebViewQLPlugin.qlgenerator
com.apple.mail.email -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Mail.qlgenerator
com.apple.ical.ics -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/iCal.qlgenerator
com.apple.systempreference.prefpane -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/StandardBundles.qlgenerator
com.apple.safari.history -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Bookmark.qlgenerator
public.html -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Web.qlgenerator
com.apple.eventmanager.eventsq -> /Library/QuickLook/WebViewQLPlugin.qlgenerator
com.apple.addressbook.group -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Contact.qlgenerator
public.movie -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Movie.qlgenerator
com.apple.application -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/StandardBundles.qlgenerator
com.apple.ichat.transcript -> /System/Library/QuickLook/iChat.qlgenerator
com.apple.ical.bookmark.todo -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/iCal.qlgenerator
public.vcard -> /System/Library/Frameworks/QuickLook.framework/Resources/Generators/Contact.qlgenerator
generators change detected: NO
Once you have set up your Quick Look generator project for debugging, specify breakpoints in your code, change the build configuration to Debug, and choose Build and Debug from the Debug menu.
Testing Tools and Strategies
After your generator seems to be bug-free, you can test it further to determine if anything else needs to be improved. Copy the generator to an application bundle or to one of the standard file-system locations for Quick Look generators. Try out your generator with different client applications (Finder, Spotlight, Time Machine, and so forth). Using
qlmanage as an executable (see Debugging Facilities) you can test your generator to see how it handles thumbnails and previews. Force preview- or thumbnail-generation by closing a Finder or Spotlight window and see how well your generator responds.
In addition, check your generator to see how well it performs; if it takes longer than two seconds to generate a preview, then you should closely examine your code to find out where you could improve performance.
As an aid to testing, or even debugging, you can set the
QLEnableLogging user default at the command line:
defaults write -g QLEnableLogging YES
After doing this, Quick Look prints log messages showing its activity, such as which generators it loads and which documents it requests previews and thumbnails for. Here is a sample log message:
2006-12-15 11:18:16.839 quicklookd[26260:3b03] [QL] Thumbnailing /Users/jalon/Documents/PreviewableDocuments/Test5.sketch2. Content type UTI: com.apple.sketch2. Generator used: <QLGenerator /Library/QuickLook/quicklooksketch.qlgenerator>