# The &CCL; IDE

## Introduction

&CCL; ships with the complete source code for an integrated development environment written using Cocoa on Mac OS X. This chapter describes how to build and use that environment, referred to hereafter simply as "the IDE".

The IDE provides a programmable text editor, listener windows, an inspector for Lisp data structures, and a means of easily building a Cocoa application in Lisp. In addition, its source code provides an example of a fairly complex Cocoa application written in Lisp.

The current version of the IDE has seen the addition of numerous features and many bugfixes. Although it's by no means a finished product, we hope it will prove more useful than previous versions, and we plan additional work on the IDE for future releases.

## Building the IDE

Building the &CCL; IDE is now a very simple process.

1. In a shell session, cd to the ccl directory.

2. Run ccl from the shell. The easiest way to do this is generally to execute the ccl or ccl64 command.

3. Evaluate the form `(require :cocoa-application)`

For example, assuming that the &CCL; distribution is installed in "/usr/local/ccl", the following sequence of shell interactions builds the IDE:

    oshirion:ccl mikel$ ccl64
    Welcome to Clozure Common Lisp Version 1.2-r9198M-trunk  (DarwinX8664)!
    ? (require :cocoa-application)
    ;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
    ;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...

    [...many lines of "Compiling" and "Loading" omitted...]

    Saving application to /usr/local/ccl/Clozure CL.app/

    oshirion:ccl mikel$

&CCL; compiles and loads the various subsystems that make up the IDE, then constructs a Cocoa application bundle named "Clozure CL.app" and saves the Lisp image into it. Normally &CCL; creates the application bundle in the root directory of the &CCL; distribution.

## Running the IDE

After it has been built, you can run the "Clozure CL.app" application normally, by double-clicking its icon. When launched, the IDE initially displays a single listener window that you can use to interact with Lisp. You can type Lisp expressions for evaluation at the prompt in the listener window. You can also use Hemlock editing commands to edit the text of expressions in the listener window.

## IDE Features

### Editor Windows

You can open an editor window either by choosing Open from the File menu and then selecting a text file, or by choosing New from the File menu. You can also evaluate the expression `(ed)` in the listener window; in that case &CCL; creates a new window as if you had chosen New from the File menu.

Editor windows implement Hemlock editing commands. You can use all the editing and customization features of Hemlock within any editor window (including listener windows).

### The Lisp Menu

The Lisp menu provides several commands for interacting with the running Lisp session, in addition to the ways you can interact with it by evaluating expressions. You can evaluate a selected range of text in any editing buffer. You can compile and load the contents of editor windows (please note that in the current version, &CCL; compiles and loads the contents of the file associated with an editor window; that means that if you try to load or compile a window that has not been saved to a file, the result is an error).

You can interrupt computations, trigger breaks, and select restarts from the Lisp menu. You can also display a backtrace or open the Inspector window.

#### Checking for Updates

At the bottom of the Lisp menu is an item entitled "Check for Updates". If your copy of &CCL; came from the Clozure Subversion server (which is the preferred source), and if your internet connection is working, then you can select this menu item to check for updates to your copy of &CCL;.

When you select "Check for Updates", &CCL; uses the svn program to query the Clozure Subversion repository and determine whether new updates to &CCL; are available. (This means that on Mac OS X versions earlier than 10.5, you must ensure that the Subversion client software is installed before using the "Check for Updates" feature. See the wikiHow page on installing Subversion for more information.) If updates are available, &CCL; automatically downloads and installs them. After a successful download, &CCL; rebuilds itself, and then rebuilds the IDE on the newly-rebuilt Lisp. Once this process is finished, you should quit the running IDE and start the newly built one (which will be in the same place that the old one was).

Normally, &CCL; can install updates and rebuild itself without any problems. Occasionally, an unforeseen problem (such as a network outage, or a hardware failure) might interrupt the self-rebuilding process, and leave your copy of &CCL; unusable. If you are expecting to update your copy of &CCL; frequently, it might be prudent to keep a backup copy of your working environment ready in case of such situtations. You can also always obtain a full, fresh copy of &CCL; from Clozure's repository..

### The Tools Menu

The tools menu provides access to the Apropos and Processes windows. The Apropos window searches the running Lisp image for symbols that match any text you enter. You can use the Apropos window to quickly find function names and other useful symbols. The Processes window lists all threads running in the current Lisp session. If you double-click a process entry, &CCL; opens an Inspector window on that process.

### The Inspector Window

The Inspector window displays information about a Lisp value. The information displayed varies from the very simple, in the case of a simple data value such as a character, to the complex, in the case of structured data such as lists or CLOS objects. The left-hand column of the window's display shows the names of the object's attributes; the righthand column shows the values associated with those attributes. You can inspect the values in the righthand column by double-clicking them.

Inspecting a value in the righthand column changes the Inspector window to display the double-clicked object. You can quickly navigate the fields of structured data this way, inspecting objects and the objects that they refer to. Navigation buttons at the top left of the window enable you to retrace your steps, backing up to return to previously-viewed objects, and going forward again to objects you navigated into previously.

You can change the contents of a structured object by evaluating expressions in a listener window. The refresh button (marked with a curved arrow) updates the display of the Inspector window, enabling you to quickly see the results of changing a data structure.

## IDE Sources

&CCL; builds the IDE from sources in the "objc-bridge" and "cocoa-ide" directories in the &CCL; distribution. The IDE as a whole is a relatively complicated application, and is probably not the best place to look when you are first trying to understand how to build Cocoa applications. For that, you might benefit more from the examples in the "examples/cocoa/" directory. Once you are familiar with those examples, though, and have some experience building your own application features using Cocoa and the Objective-C bridge, you might browse through the IDE sources to see how it implements its features.

The search path for &CCL;'s `REQUIRE` feature includes the "objc-bridge" and "cocoa-ide" directories. You can load features defined in these directories by using `REQUIRE`. For example, if you want to use the Cocoa features of &CCL; from a terminal session (or from an Emacs session using SLIME or ILISP), you can evaluate `(require :cocoa)`.

## 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)`. &CCL; 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 &CCL;. 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 &CCL; user interface.

`application-class`

  The name of the application's CLOS class. The default value is the class provided by &CCL; for graphical applications. Supply the name of your application class if you implement one. If not, &CCL; uses the default class.

`toplevel-function`

  The toplevel function that runs when the application launches. Normally the default value, which is &CCL;'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 &CCL; 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/".

### 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 &CCL; 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. &CCL; 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 &CCL; 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 &CCL; 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.