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

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

added more discussion of the IDE and its UI

File size: 8.5 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
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 "<literal>CCL</literal>">
11          ]>
12
13<chapter><title>The &CCL; IDE</title>
14 
15  <sect1><title>Introduction</title>
16   
17    <para>Clozure CL ships with the source code for a simple Cocoa
18      integrated development environment that runs on Mac OS X. This
19      chapter describes how to build and use that environment,
20      referred to hereafter simply as "the IDE".</para>
21
22    <para>The IDE is still in a preliminary state, and may lack many
23    features you would expect to find in a polished Cocoa
24    application. It does, however, provide a text editor and listener
25    windows, an inspector for Lisp data structures, and a means of
26    easily building a Cocoa application in Lisp. In addition, its
27    source code provides an example of a fairly complex Cocoa
28    application written in Lisp.</para>
29
30    <para>A more rudimentary version of the Clozure CL IDE has been
31      included for several years with the distribution. The current
32      version of the IDE has seen the addition of numerous features
33      and many bugfixes. Although it's by no means a finished product,
34      we hope it will prove more useful than previous versions, and we
35      plan additional work on the IDE for future releases.</para>
36  </sect1>
37
38  <sect1><title>Building the IDE</title>
39   
40    <para>Building the Clozure CL IDE is now a very simple
41    process.</para>
42
43    <orderedlist>
44      <listitem>
45        <para>In a shell session, cd to the ccl directory.</para>
46      </listitem>
47      <listitem>
48        <para>Run ccl from the shell. The easiest way to do this is
49        generally to execute the openmcl or openmcl64 command.</para>
50      </listitem>
51      <listitem>
52        <para>Evaluate the form <code language="lisp">(require :cocoa-application)</code></para>
53      </listitem>
54    </orderedlist>
55
56    <para>For example, assuming that the &CCL; distribution is
57    installed in "/usr/local/ccl", the following sequence of shell
58    interactions builds the IDE:</para>
59
60    <programlisting>
61oshirion:ccl mikel$ openmcl64
62Welcome to Clozure Common Lisp Version 1.2-r8516MS  (DarwinX8664)!
63? (require :cocoa-application)
64;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
65;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
66
67  [...many lines of "Compiling" and "Loading" omitted...]
68
69Saving application to /usr/local/ccl/Clozure CL.app/
70
71oshirion:ccl mikel$
72
73    </programlisting>
74
75    <para>Clozure CL compiles and loads the various subsystems that
76      make up the IDE, then constructs a Cocoa application bundle
77      named "Clozure CL.app" and saves the Lisp image into
78      it. Normally &CCL; creates the application bundle in the root
79      directory of the &CCL; distribution.</para>
80
81  </sect1>
82
83  <sect1><title>Running the IDE</title>
84   
85    <para>After it has been built, you can run the "Clozure CL.app"
86      application normally, by double-clicking its icon. When
87      launched, the IDE initially displays a
88      single <glossterm linkend="listener_window">listener
89      window</glossterm> that you can use to interact with Lisp. You
90      can type Lisp expressions for evaluation at the prompt in the
91      listener window. You can also
92      use <glossterm linkend="hemlock">Hemlock</glossterm> editing
93      commands to edit the text of expressions in the listener
94      window.</para>
95
96  </sect1>
97
98  <sect1>
99    <title>IDE Features</title>
100
101    <sect2>
102      <title>Editor Windows</title>
103      <para>You can open an editor window either by choosing Open from
104        the File menu and then selecting a text file, or by choosing
105        New from the File menu. You can also evaluate the
106        expression <code>(ed)</code> in the listener window; in that
107        case &CCL; creates a new window as if you had chosen New from
108        the File menu.</para>
109
110      <para>Editor windows
111      implement <glossterm linkend="hemlock">Hemlock</glossterm>
112      editing commands. You can use all the editing and customization
113      features of Hemlock within any editor window (including listener
114      windows).</para>
115    </sect2>
116   
117    <sect2>
118      <title>The Lisp Menu</title>
119      <para>The Lisp menu provides several commands for interacting
120      with the running Lisp session, in addition to the ways you can
121      interact with it by evaluating expressions. You can evaluate a
122      selected range of text in any editing buffer. You can compile
123      and load the contents of editor windows (please note that in the
124      current version, &CCL; compiles and loads the contents of the
125      file associated with an editor window; that means that if you
126      try to load or compile a window that has not been saved to a
127      file, the result is an error).</para>
128
129      <para>You can interrupt computations, trigger breaks, and select
130      restarts from the Lisp menu. You can also display a backtrace or
131      open the <link linkend="section_inspector_window">Inspector
132      window</link>.</para>
133    </sect2>
134
135    <sect2>
136      <title>The Tools Menu</title>
137      <para>The tools menu provides access to the Apropos and
138      Processes windows. The Apropos window searches the running Lisp
139      image for symbols that match any text you enter. You can use the
140      Apropos window to quickly find function names and other useful
141      symbols. The Processes window lists all threads running in the
142      current Lisp session. If you double-click a process entry, &CCL;
143      opens an <link linkend="section_inspector_window">Inspector
144      window</link> on that process.</para>
145    </sect2>
146
147    <sect2>
148      <title>The Inspector Window</title>
149      <anchor id="section_inspector_window"/>
150      <para>The Inspector window displays information about a Lisp
151      value. The information displayed varies from the very simple, in
152      the case of a simple data value such as a character, to the
153      complex, in the case of structured data such as lists or CLOS
154      objects. The lefthand column of the window's display shows the
155      names of the object's attributes; the righthand column shows the
156      values associated with those attributes. You can inspect the
157      values in the righthand column by double-clicking them.</para>
158
159      <para>Inspecting a value in the righthand column changes the
160      Inspector window to display the double-clicked object. You can
161      quickly navigate the fields of structured data this way,
162      inspecting objects and the objects that they refer
163      to. Navigation buttons at the top left of the window enable you
164      to retrace your steps, backing up to return to previously-viewed
165      objects, and going forward again to objects you navigated into
166      previously.</para>
167
168      <para>You can change the contents of a structured object by
169      evaluating expressions in a listener window. The refresh button
170      (marked with a curved arrow) updates the display of the
171      Inspector window, enabling you to quickly see the results of
172      changing a data structure.</para>
173    </sect2>
174
175  </sect1>
176 
177  <sect1><title>IDE Sources</title>
178   
179    <para>&CCL; builds the IDE from sources in the "objc-bridge" and
180    "cocoa-ide" directories in the &CCL; distribution. The IDE as a
181    whole is a relatively complicated application, and is probably not
182    the best place to look when you are first trying to understand how
183    to build Cocoa applications. For that, you might benefit more from
184    the examples in the "examples/cocoa/" directory. Once you are
185    familiar with those examples, though, and have some experience
186    building your own application features using Cocoa and the
187    Objective-C bridge, you might browse through the IDE sources to
188    see how it implements its features.</para>
189
190    <para>The search path for &CCL;'s <code>REQUIRE</code> feature
191    includes the "objc-bridge" and "cocoa-ide" directories. You can
192    load features defined in these directories by
193    using <code>REQUIRE</code>. For example, if you want to use the
194    Cocoa features of &CCL; from a terminal session (or from an Emacs
195    session using SLIE or ILISP), you can evaluate <code>(require
196    :cocoa)</code>.</para>
197  </sect1>
198
199
200</chapter>
Note: See TracBrowser for help on using the repository browser.