November 20, 2007

This directory contains sources and other resources needed to build
a Cocoa-based IDE for Clozure CL on OSX.

The IDE uses the ObjC bridge (in ccl/objc-bridge/) to communicate
with the ObjC runtime.

The "./ide-contents" directory contains nib files, icons and other
resources used by the IDE.  These are copied to the application bundle
by the build process.

The "./hemlock" directory contains a hacked up version of Portable
Hemlock (forked from the main Portable Hemlock tree some years ago.)
Hemlock is public domain Emacs-like editor that comes with CMUCL;
Portable Hemlock is an attempt to "free Hemlock from its CMUCL prison"
(e.g., remove dependencies on CMUCL).  Hemlock (and Portable Hemlock)
were designed to use CLX for display and event processing; the version
distributed here uses the Cocoa text system for that functionality.
Much of the initial work on Portable Hemlock was done by Gilbert Baumann.

To run the IDE from within a ccl command-line session (a shell, Emacs shell
buffer, under SLIME or ILisp or ...), do:

? (require "COCOA")

The first time this is run, it'll compile the sources, generating lots
of compiler warnings.  You'll also see messages noting that various
new ObjC-callable methods are being defined.  When the loading process
completes, it creates a temporary application bundle in "ccl:temp
bundle.app" and activates it.  You should see a new menubar, a
listener window, and a Clozure CL icon in the Dock. The non-GUI
listener process from which the REQUIRE was issued will remain active;
you may see warning/diagnostic/error messages from the IDE directed to
the standard output/error streams associated with that listener.
(Under SLIME, these messages might appear in the *inferior lisp*
buffer.)

It's also possible to save the loaded IDE in a populated bundle,
effectively making it a double-clickable application.  To do this, you
can do:

? (require "COCOA-APPLICATION")

which will create an application bundle in "ccl:Clozure CL.app"
and save an executable lisp image inside it. Double-clicking on
that bundle in the Finder will launch the IDE; any diagnostic
messages/warnings/etc. will be written to the system log, which
can be examined with the Console application.

The IDE depends on functionality introduced in OSX 10.4 (Tiger).



*Two kinds of IDE application

(require :cocoa-application) builds a double-clickable "ClozureCL.app"
in the CCL directory.  It must stay there: it uses the
sources (for M-.  and cl:require) and the FFI/ObjC interface
definition databases (the .cdb files used by #_ and #$) from the CCL
directory.  Rebuild it after updating the CCL sources.

"make -C cocoa-ide app" builds a standalone, universal (arm64 and
x86-64) "Clozure CL.app" in ccl/cocoa-ide/build/.  It contains its own
copies of the system sources and interfaces (in
$app/Contents/Resources/ccl/), so it can be moved anywhere, e.g. to
the Applications folder.  It always uses its own interfaces, so that
they match its image.  The Makefile can also sign and notarize it; see
the comments there.

*Note: CCL directory and IDE Preferences

When the IDE starts, the "ccl:" logical host refers to the first of
the following locations that contains CCL sources:

 1. the "CCL sources" directory as specified in the General pane of the
    Preferences window (the "CCLDirectory" preference)
 2. the directory containing Clozure CL.app
 3. Clozure CL.app/Contents/Resources/ccl/

The values of changed application preferences are stored in
"~/Library/Preferences/com.clozure.ccl-ide.plist".
