source: trunk/source/doc/src/ide.xml @ 8981

Last change on this file since 8981 was 8981, checked in by mikel, 12 years ago

additions to ObjC and ffi docs; many mechanical edits; some standardization of XML elements and formatting

File size: 15.9 KB
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3          ""[
4          <!ENTITY rest "<varname>&amp;rest</varname>">
5          <!ENTITY key "<varname>&amp;key</varname>">
6          <!ENTITY optional "<varname>&amp;optional</varname>">
7          <!ENTITY body "<varname>&amp;body</varname>">
8          <!ENTITY aux "<varname>&amp;aux</varname>">
9          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
10          <!ENTITY CCL "Clozure CL">
11          ]>
13<chapter><title>The &CCL; IDE</title>
15  <sect1><title>Introduction</title>
17    <para>&CCL; ships with the complete source code for an integrated
18    development environment written using Cocoa on Mac OS X. This
19    chapter describes how to build and use that environment,
20    referred to hereafter simply as "the IDE".</para>
22    <para>The IDE provides a programmable text editor, listener
23      windows, an inspector for Lisp data structures, and a means of
24      easily building a Cocoa application in Lisp. In addition, its
25      source code provides an example of a fairly complex Cocoa
26      application written in Lisp.</para>
28    <para>The current version of the IDE has seen the addition of numerous
29    features and many bugfixes. Although it's by no means a finished product,
30    we hope it will prove more useful than previous versions, and we
31    plan additional work on the IDE for future releases.</para>
32  </sect1>
34  <sect1><title>Building the IDE</title>
36    <para>Building the &CCL; IDE is now a very simple
37      process.</para>
39    <orderedlist>
40      <listitem>
41        <para>In a shell session, cd to the ccl directory.</para>
42      </listitem>
43      <listitem>
44        <para>Run ccl from the shell. The easiest way to do this is
45          generally to execute the openmcl or openmcl64 command.</para>
46      </listitem>
47      <listitem>
48        <para>Evaluate the form <code language="lisp">(require :cocoa-application)</code></para>
49      </listitem>
50    </orderedlist>
52    <para>For example, assuming that the &CCL; distribution is
53      installed in "/usr/local/ccl", the following sequence of shell
54      interactions builds the IDE:</para>
56    <programlisting>
57      oshirion:ccl mikel$ openmcl64
58      Welcome to Clozure Common Lisp Version 1.2-r8516MS  (DarwinX8664)!
59      ? (require :cocoa-application)
60      ;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
61      ;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
63      [...many lines of "Compiling" and "Loading" omitted...]
65      Saving application to /usr/local/ccl/Clozure
67      oshirion:ccl mikel$
69    </programlisting>
71    <para>&CCL; compiles and loads the various subsystems that
72      make up the IDE, then constructs a Cocoa application bundle
73      named "Clozure" and saves the Lisp image into
74      it. Normally &CCL; creates the application bundle in the root
75      directory of the &CCL; distribution.</para>
77  </sect1>
79  <sect1><title>Running the IDE</title>
81    <para>After it has been built, you can run the "Clozure"
82      application normally, by double-clicking its icon. When
83      launched, the IDE initially displays a
84      single <glossterm linkend="listener_window">listener
85        window</glossterm> that you can use to interact with Lisp. You
86      can type Lisp expressions for evaluation at the prompt in the
87      listener window. You can also
88      use <glossterm linkend="hemlock">Hemlock</glossterm> editing
89      commands to edit the text of expressions in the listener
90      window.</para>
92  </sect1>
94  <sect1>
95    <title>IDE Features</title>
97    <sect2>
98      <title>Editor Windows</title>
99      <para>You can open an editor window either by choosing Open from
100        the File menu and then selecting a text file, or by choosing
101        New from the File menu. You can also evaluate the
102        expression <code>(ed)</code> in the listener window; in that
103        case &CCL; creates a new window as if you had chosen New from
104        the File menu.</para>
106      <para>Editor windows
107        implement <glossterm linkend="hemlock">Hemlock</glossterm>
108        editing commands. You can use all the editing and customization
109        features of Hemlock within any editor window (including listener
110        windows).</para>
111    </sect2>
113    <sect2>
114      <title>The Lisp Menu</title>
115      <para>The Lisp menu provides several commands for interacting
116        with the running Lisp session, in addition to the ways you can
117        interact with it by evaluating expressions. You can evaluate a
118        selected range of text in any editing buffer. You can compile
119        and load the contents of editor windows (please note that in the
120        current version, &CCL; compiles and loads the contents of the
121        file associated with an editor window; that means that if you
122        try to load or compile a window that has not been saved to a
123        file, the result is an error).</para>
125      <para>You can interrupt computations, trigger breaks, and select
126        restarts from the Lisp menu. You can also display a backtrace or
127        open the <link linkend="section_inspector_window">Inspector
128          window</link>.</para>
129    </sect2>
131    <sect2>
132      <title>The Tools Menu</title>
133      <para>The tools menu provides access to the Apropos and
134        Processes windows. The Apropos window searches the running Lisp
135        image for symbols that match any text you enter. You can use the
136        Apropos window to quickly find function names and other useful
137        symbols. The Processes window lists all threads running in the
138        current Lisp session. If you double-click a process entry, &CCL;
139        opens an <link linkend="section_inspector_window">Inspector
140          window</link> on that process.</para>
141    </sect2>
143    <sect2>
144      <title>The Inspector Window</title>
145      <anchor id="section_inspector_window"/>
146      <para>The Inspector window displays information about a Lisp
147        value. The information displayed varies from the very simple, in
148        the case of a simple data value such as a character, to the
149        complex, in the case of structured data such as lists or CLOS
150        objects. The left-hand column of the window's display shows the
151        names of the object's attributes; the righthand column shows the
152        values associated with those attributes. You can inspect the
153        values in the righthand column by double-clicking them.</para>
155      <para>Inspecting a value in the righthand column changes the
156        Inspector window to display the double-clicked object. You can
157        quickly navigate the fields of structured data this way,
158        inspecting objects and the objects that they refer
159        to. Navigation buttons at the top left of the window enable you
160        to retrace your steps, backing up to return to previously-viewed
161        objects, and going forward again to objects you navigated into
162        previously.</para>
164      <para>You can change the contents of a structured object by
165        evaluating expressions in a listener window. The refresh button
166        (marked with a curved arrow) updates the display of the
167        Inspector window, enabling you to quickly see the results of
168        changing a data structure.</para>
169    </sect2>
171  </sect1>
173  <sect1><title>IDE Sources</title>
175    <para>&CCL; builds the IDE from sources in the "objc-bridge" and
176      "cocoa-ide" directories in the &CCL; distribution. The IDE as a
177      whole is a relatively complicated application, and is probably not
178      the best place to look when you are first trying to understand how
179      to build Cocoa applications. For that, you might benefit more from
180      the examples in the "examples/cocoa/" directory. Once you are
181      familiar with those examples, though, and have some experience
182      building your own application features using Cocoa and the
183      Objective-C bridge, you might browse through the IDE sources to
184      see how it implements its features.</para>
186    <para>The search path for &CCL;'s <code>REQUIRE</code> feature
187      includes the "objc-bridge" and "cocoa-ide" directories. You can
188      load features defined in these directories by
189      using <code>REQUIRE</code>. For example, if you want to use the
190      Cocoa features of &CCL; from a terminal session (or from an Emacs
191      session using SLIME or ILISP), you can evaluate <code>(require
192        :cocoa)</code>.</para>
193  </sect1>
195  <sect1><title>The Application Builder</title>
196    <anchor id="application_builder"/>
197    <para>One important feature of the IDE currently has no Cocoa user
198      interface: the application builder. The application builder
199      constructs a
200      Cocoa <glossterm linkend="application_bundle">application
201        bundle</glossterm> that runs a Lisp image when double-clicked. You
202      can use the application builder to create Cocoa applications in
203      Lisp. These applications are exactly like Cocoa applications
204      created with XCode and Objective-C, except that they are written
205      in Lisp.</para>
207    <para>To make the application builder available, evaluate the
208      expression <code>(require :build-application)</code>. &CCL; loads
209      the required subsystems, if necessary.</para>
211    <para>
212      <indexterm zone="build-application"/>
213      <command><varname id="build-application">BUILD-APPLICATION</varname> <varname>&key;</varname>
214        (<parameter>name</parameter> <replaceable>"MyApplication"</replaceable>)
215        (<parameter>type-string</parameter> <replaceable>"APPL"</replaceable>)
216        (<parameter>creator-string</parameter> <replaceable>"OMCL"</replaceable>)
217        (<parameter>directory</parameter> <replaceable>(current-directory)</replaceable>)
218        (<parameter>nibfiles</parameter> <replaceable>NIL</replaceable>)
219        (<parameter>main-nib-name</parameter> <replaceable>NIL</replaceable>)
220        (<parameter>application-class</parameter> <replaceable>'GUI::COCOA-APPLICATION</replaceable>)
221        (<parameter>toplevel-function</parameter> <replaceable>NIL</replaceable>)
222        [Function]</command>
223    </para>
225    <para>
226      The <varname>build-application</varname> function constructs an
227      application bundle, populates it with the files needed to satisfy
228      Mac OS X that the bundle is a launchable application, and saves an
229      executable Lisp image to the proper subdirectory of the
230      bundle. Assuming that the saved Lisp image contains correct code,
231      a user can subsequently launch the resulting Cocoa application by
232      double-clicking its icon in the Finder, and the saved Lisp
233      environment runs.
234    </para>
236    <para>The keyword arguments control various aspects of application
237      bundle as <code>BUILD-APPLICATION</code> builds it.</para>
238    <variablelist>
240      <varlistentry>
241        <term><varname>name</varname></term>
242        <listitem>
243          <para>Specifies the application name of the
244            bundle. <code>BUILD-APPLICATION</code> creates an application
245            bundle whose name is given by this parameter, with the
246            extension ".app" appended. For example, using the default
247            value for this parameter results in a bundle named
248            "".</para>
249        </listitem>
250      </varlistentry>
252      <varlistentry>
253        <term><varname>type-string</varname></term>
254        <listitem>
255          <para>Specifies type of bundle to create. You should normally
256            never need to change the default value, which Mac OS X uses to
257            identify application bundles.</para>
258        </listitem>
259      </varlistentry>
261      <varlistentry>
262        <term><varname>creator-string</varname></term>
263        <listitem>
264          <para>Specifies the <glossterm linkend="creator_code">creator
265              code</glossterm>, which uniquely identifies the application
266            under Mac OS X. The default creator code is that of &CCL;. For
267            more information about reserving and assigning creator codes,
268            see
269            Apple's <ulink url="">developer
270              page</ulink> on the topic.</para>
271        </listitem>
272      </varlistentry>
274      <varlistentry>
275        <term><varname>directory</varname></term>
276        <listitem>
277          <para>The directory in which <code>BUILD-APPLICATION</code>
278            creates the application bundle. By default, it creates the
279            bundle in the current working directory. Unless you
280            use <code>CURRENT-DIRECTORY</code> to set the working
281            directory, the bundle may be created in some unexpected place,
282            so it's safest to specify a full pathname for this argument. A
283            typical value might be <code>"/Users/foo/Desktop/"</code>
284            (assuming, of course, that your username is "foo").</para>
285        </listitem>
286      </varlistentry>
288      <varlistentry>
289        <term><varname>nibfiles</varname></term>
290        <listitem>
291          <para>A list of pathnames, where each pathname identifies
292            a <glossterm linkend="nibfile">nibfile</glossterm> created
293            with
294            Apple's <glossterm linkend="InterfaceBuilder">InterfaceBuilder</glossterm>
295            application. <code>BUILD-APPLICATION</code> copies each
296            nibfile into the appropriate place in the application bundle,
297            enabling the application to load user-interface elements from
298            them as-needed. It is safest to provide full pathnames to the
299            nibfiles in the list. Each nibfile must be in ".nib" format,
300            not ".xib" format, in order that the application can load
301            it.</para>
302        </listitem>
303      </varlistentry>
305      <varlistentry>
306        <term><varname>main-nib-name</varname></term>
307        <listitem>
308          <para>The name of
309            the <glossterm linkend="nibfile">nibfile</glossterm> to load
310            initially when launching. The user-interface defined in this
311            nibfile becomes the application's main interface. You must
312            supply the name of a suitable nibfile for this parameter, or
313            the resulting application uses the &CCL; user
314            interface.</para>
315        </listitem>
316      </varlistentry>
318      <varlistentry>
319        <term><varname>application-class</varname></term>
320        <listitem>
321          <para>The name of the application's CLOS class. The default
322            value is the class provided by &CCL; for graphical
323            applications. Supply the name of your application class if you
324            implement one. If not, &CCL; uses the default class.</para>
325        </listitem>
326      </varlistentry>
328      <varlistentry>
329        <term><varname>toplevel-function</varname></term>
330        <listitem>
331          <para>The toplevel function that runs when the application
332            launches. Normally the default value, which is &CCL;'s
333            toplevel, works well, but in some cases you may wish to
334            customize the behavior of the application's toplevel. The best
335            source of information about writing your own toplevel is the
336            &CCL; source code, especially the implementations
337            of <code>TOPLEVEL-FUNCTION</code> in
338            "ccl/level-1/l1-application.lisp"</para>
339        </listitem>
340      </varlistentry>
342    </variablelist>
344    <para>Please note that <code>BUILD-APPLICATION</code> is a work in
345    progress. It can easily build a working Cocoa application, but it
346    still has limitations that may in some cases prove
347    inconvenient. For example, in the current version it provides no
348    easy way to specify an application delegate different from the
349    default. If you find the current limitations
350    of <code>BUILD-APPLICATION</code> too restrictive, and want to try
351    extending it for your use, you can find the source code for it
352    in "ccl/cocoa-ide/build-application.lisp".</para>
354    <para>For more information on how to
355    use <code>BUILD-APPLICATION</code>, see the Currency Converter
356    example in "ccl/examples/cocoa/currency-converter/".</para>
357  </sect1>
Note: See TracBrowser for help on using the repository browser.