Script Debugger allows parts of a script to be kept in a separate, secondary compiled script file. The secondary file is called a library. With a library, your scripts can easily make use of common code. If the code in the library changes, scripts that use the library inherit the changed code automatically when they are compiled.

If you’re going to make extensive use of libraries, it might be a good idea to add the Libraries icon to your script window toolbar. To do so, choose View > Customize Toolbar and drag the Libraries icon into the toolbar. The icon indicates whether the script has libraries. In addition, it contains a popup menu which you can use to add a library from your Script Libraries folder instantly to your script.

The illustration below shows: (1) the toolbar icon for a script without libraries; (2) the use of the toolbar popup menu to add a library to a script; (3) the toolbar icon for a script with libraries.

The popup menu automatically looks for library files in Application Support/Script Debugger 4.5/Script Libraries, both in your user ~/Library/ and in the top-level /Library/ directory. Therefore you are encouraged to keep library files in one of these locations, so that the popup menu can find them and you can take advantage of this feature. (The popup menu also looks for a Script Libraries folder in the same folder as Script Debugger itself, but use of this feature is not encouraged.)

To add a library file to your script:

• If the library file is in a Script Libraries folder (in one of the specified locations), use the toolbar icon popup menu as shown above.
• Or, choose File > Libraries (or click the Libraries toolbar button) to summon the Libraries dialog, and then:
  • If the library file is in your Script Libraries folder, click the first button () to access the popup menu and choose a library file. (Option-choose to reveal the library file in the Finder.) This popup menu is the same as the toolbar icon popup menu.
  • Or, click the second button (+) to choose any compiled script file.
  • Or, drag a compiled script file from the Finder into the dialog.

The Relative To popup determines how you want Script Debugger to locate this library file in future:

• Absolute means that the library file is sought in its current location.
• Document means that the library file is sought in the same location relative to the current script. The current script must have been saved or this option won’t be enabled. For example, you might start with the library file in the same folder as the current script. Both files can then be moved, and as long as they are moved together (so that they remain in the same folder), the library file will be found.
• Application Support means that the library is sought in the same location relative to your Script Libraries folder. This is naturally the default when you use the shortcuts described above for adding a library from your Script Libraries folder.

The way a file is listed to show its path in the Libraries dialog changes depending on your choice in the Relative To popup. (If there isn’t enough room to see a full path, you can widen the dialog.)

To examine or edit a library file:

• Choose File > Libraries and:
  • Double-click the library file listing to open the file for editing.
  • Option-double-click the library file listing to reveal the file in the Finder.

A script that uses Script Debugger’s library feature will run in other contexts — the library resources are invisibly merged into the script when the script is saved, in a way that AppleScript understands — but it cannot be edited except by Script Debugger. In order to distribute to others a script which uses libraries, in a form that can be edited with any script editor application, you will want to flatten the script. This means that the contents of all library files on which the script depends are visibly incorporated into the contents of the script itself.

To flatten a script:

• Choose File > Export > Flattened Script.

The Script Debugger Libraries mechanism may remind you of the AppleScript load script command, but it has several advantages over load script:

• There is no need for your code to load anything, as Script Debugger does the loading for you.
• With load script, the loaded material becomes a script object within your script, whereas with Script Debugger’s library feature, the loaded material is blended with your script.
• With load script, you have to specify or calculate a pathname in code, whereas Script Debugger helps keep track of libraries for you.

Here is a further technical discussion about how the Libraries feature works.