Clozure CL Documentation

5.6. The Application Builder

One important feature of the IDE currently has no Cocoa user interface: the application builder. The application builder constructs a Cocoa application bundle that runs a Lisp image when double-clicked. You can use the application builder to create Cocoa applications in Lisp. These applications are exactly like Cocoa applications created with XCode and Objective-C, except that they are written in Lisp.

To make the application builder available, evaluate the expression (require :build-application). Clozure CL loads the required subsystems, if necessary.

BUILD-APPLICATION &key (name "MyApplication") (type-string "APPL") (creator-string "OMCL") (directory (current-directory)) (copy-ide-resources t) (info-plist NIL) (nibfiles NIL) (main-nib-name NIL) (application-class 'GUI::COCOA-APPLICATION) (toplevel-function NIL) [Function]

The build-application function constructs an application bundle, populates it with the files needed to satisfy Mac OS X that the bundle is a launchable application, and saves an executable Lisp image to the proper subdirectory of the bundle. Assuming that the saved Lisp image contains correct code, a user can subsequently launch the resulting Cocoa application by double-clicking its icon in the Finder, and the saved Lisp environment runs.

The keyword arguments control various aspects of application bundle as BUILD-APPLICATION builds it.

name: Specifies the application name of the bundle. BUILD-APPLICATION creates an application bundle whose name is given by this parameter, with the extension ".app" appended. For example, using the default value for this parameter results in a bundle named "MyApplication.app".
type-string: Specifies type of bundle to create. You should normally never need to change the default value, which Mac OS X uses to identify application bundles.
creator-string: Specifies the creator code, which uniquely identifies the application under Mac OS X. The default creator code is that of Clozure CL. For more information about reserving and assigning creator codes, see Apple's developer page on the topic.
directory: The directory in which BUILD-APPLICATION creates the application bundle. By default, it creates the bundle in the current working directory. Unless you use CURRENT-DIRECTORY to set the working directory, the bundle may be created in some unexpected place, so it's safest to specify a full pathname for this argument. A typical value might be "/Users/foo/Desktop/" (assuming, of course, that your username is "foo").
copy-ide-resources: Whether to copy the resource files from the IDE's application bundle. By default, BUILD-APPLICATION copies nibfiles and other resources from the IDE to the newly-created application bundle. This option is often useful when you are developing a new application, because it enables your built application to have a fully-functional user interface even before you have finished designing one. By default, the application uses the application menu and other UI elements of the IDE until you specify otherwise. Once your application's UI is fully implemented, you may choose to pass NIL for the value of this parameter, in which case the IDE resources are not copied into your application bundle.
info-plist: A user-supplied NSDictionary object that defines the contents of the Info.plist file to be written to the application bundle. The default value is NIL, which specifies that the Info.plist from the IDE is to be used if copy-ide-resources is true, and a new dictionary created with default values is to be used otherwise. You can create a suitable NSDictionary object using the function make-info-dict. For details on the parameters to this function, see its definition in "ccl/cocoa-ide/builder-utilities.lisp".
nibfiles: A list of pathnames, where each pathname identifies a nibfile created with Apple's InterfaceBuilder application. BUILD-APPLICATION copies each nibfile into the appropriate place in the application bundle, enabling the application to load user-interface elements from them as-needed. It is safest to provide full pathnames to the nibfiles in the list. Each nibfile must be in ".nib" format, not ".xib" format, in order that the application can load it.
main-nib-name: The name of the nibfile to load initially when launching. The user-interface defined in this nibfile becomes the application's main interface. You must supply the name of a suitable nibfile for this parameter, or the resulting application uses the Clozure CL user interface.
application-class: The name of the application's CLOS class. The default value is the class provided by Clozure CL for graphical applications. Supply the name of your application class if you implement one. If not, Clozure CL uses the default class.
toplevel-function: The toplevel function that runs when the application launches. Normally the default value, which is Clozure CL's toplevel, works well, but in some cases you may wish to customize the behavior of the application's toplevel. The best source of information about writing your own toplevel is the Clozure CL source code, especially the implementations of TOPLEVEL-FUNCTION in "ccl/level-1/l1-application.lisp"

BUILD-APPLICATION creates a folder named "name.app" in the directory directory. Inside that folder, it creates the "Contents" folder that Mac OS X application bundles are expected to contain, and populates it with the "MacOS" and "Resources" folders, and the "Info.plist" and "PkgInfo" files that must be present in a working application bundle. It takes the contents of the "Info.plist" and "PkgInfo" files from the parameters to BUILD-APPLICATION. If copy-ide-resources is true then it copies the contents of the "Resources" folder from the "Resources" folder of the running IDE.

The work needed to produce a running Cocoa application is very minimal. In fact, if you supply BUILD-APPLICATION with a valid nibfile and pathnames, it builds a running Cocoa application that displays your UI. It doesn't need you to write any code at all to do this. Of course, the resulting application doesn't do anything apart from displaying the UI defined in the nibfile. If you want your UI to accomplish anything, you need to write the code to handle its events. But the path to a running application with your UI in it is very short indeed.

Please note that BUILD-APPLICATION is a work in progress. It can easily build a working Cocoa application, but it still has limitations that may in some cases prove inconvenient. For example, in the current version it provides no easy way to specify an application delegate different from the default. If you find the current limitations of BUILD-APPLICATION too restrictive, and want to try extending it for your use, you can find the source code for it in "ccl/cocoa-ide/build-application.lisp". You can see the default values used to populate the "Info.plist" file in "ccl/cocoa-ide/builder-utilities.lisp".

For more information on how to use BUILD-APPLICATION, see the Currency Converter example in "ccl/examples/cocoa/currency-converter/".

5.6.1. Running the Application Builder From the Command Line

It's possible to automate use of the application builder by running a call to CCL:BUILD-APPLICATION from the terminal command line. For example, the following command, entered at a shell prompt in Mac OS X's Terminal window, builds a working copy of the Clozure CL environment called "Foo.app":

ccl -b -e "(require :cocoa)" -e "(require :build-application)" -e "(ccl::build-application :name \"Foo\")"

You can use the same method to automate building your Lisp/Cocoa applications. Clozure CL handles each Lisp expressions passed with a -e argument in order, so you can simply evaluate a sequence of Lisp expressions as in the above example to build your application, ending with a call to CCL:BUILD-APPLICATION. The call to CCL:BUILD-APPLICATION can process all the same arguments as if you evaluated it in a Listener window in the Clozure CL IDE.

Building a substantial Cocoa application (rather than just reproducing the Lisp environment using defaults, as is done in the above example) is likely to involve a relatively complicated sequence of loading source files and perhaps evaluating Lisp forms. You might be best served to place your command line in a shell script that you can more easily edit and test.

One potentially complicated issue concerns loading all your Lisp source files in the right order. You might consider using ASDF to define and load a system that includes all the parts of your application before calling CCL:BUILD-APPLICATION. ASDF is a "another system-definition facility", a sort of make for Lisp, and is included in the Clozure CL distribution. You can read more about ASDF at the ASDF home page.

Alternatively, you could use the standard features of Common Lisp to load your application's files in the proper order.