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

Last change on this file since 9388 was 9388, checked in by mikel, 14 years ago

added a section on batching build-application from the command line

File size: 22.2 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  <!-- ================================================================ -->
16  <sect1><title>Introduction</title>
18    <para>&CCL; ships with the complete source code for an integrated
19    development environment written using Cocoa on Mac OS X. This
20    chapter describes how to build and use that environment,
21    referred to hereafter simply as "the IDE".</para>
23    <para>The IDE provides a programmable text editor, listener
24      windows, an inspector for Lisp data structures, and a means of
25      easily building a Cocoa application in Lisp. In addition, its
26      source code provides an example of a fairly complex Cocoa
27      application written in Lisp.</para>
29    <para>The current version of the IDE has seen the addition of numerous
30    features and many bugfixes. Although it's by no means a finished product,
31    we hope it will prove more useful than previous versions, and we
32    plan additional work on the IDE for future releases.</para>
33  </sect1>
35  <!-- ================================================================ -->
36  <sect1><title>Building the IDE</title>
38    <para>Building the &CCL; IDE is now a very simple
39      process.</para>
41    <orderedlist>
42      <listitem>
43        <para>In a shell session, cd to the ccl directory.</para>
44      </listitem>
45      <listitem>
46        <para>Run ccl from the shell. The easiest way to do this is
47          generally to execute the ccl or ccl64 command.</para>
48      </listitem>
49      <listitem>
50        <para>Evaluate the form <code language="lisp">(require :cocoa-application)</code></para>
51      </listitem>
52    </orderedlist>
54    <para>For example, assuming that the &CCL; distribution is
55      installed in "/usr/local/ccl", the following sequence of shell
56      interactions builds the IDE:</para>
58    <programlisting>
59oshirion:ccl mikel$ ccl64
60Welcome to Clozure Common Lisp Version 1.2-r9198M-trunk  (DarwinX8664)!
61? (require :cocoa-application)
62;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
63;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
65[...many lines of "Compiling" and "Loading" omitted...]
67Saving application to /usr/local/ccl/Clozure
69oshirion:ccl mikel$
71    </programlisting>
73    <para>&CCL; compiles and loads the various subsystems that
74      make up the IDE, then constructs a Cocoa application bundle
75      named "Clozure" and saves the Lisp image into
76      it. Normally &CCL; creates the application bundle in the root
77      directory of the &CCL; distribution.</para>
79  </sect1>
81  <!-- ================================================================ -->
82  <sect1><title>Running the IDE</title>
84    <para>After it has been built, you can run the "Clozure"
85      application normally, by double-clicking its icon. When
86      launched, the IDE initially displays a
87      single <glossterm linkend="listener_window">listener
88        window</glossterm> that you can use to interact with Lisp. You
89      can type Lisp expressions for evaluation at the prompt in the
90      listener window. You can also
91      use <glossterm linkend="hemlock">Hemlock</glossterm> editing
92      commands to edit the text of expressions in the listener
93      window.</para>
95  </sect1>
97  <!-- ================================================================ -->
98  <sect1>
99    <title>IDE Features</title>
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>
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>
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>
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>
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>
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 left-hand 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>
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>
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>
175  </sect1>
177  <!-- ================================================================ -->
178  <sect1><title>IDE Sources</title>
180    <para>&CCL; builds the IDE from sources in the "objc-bridge" and
181      "cocoa-ide" directories in the &CCL; distribution. The IDE as a
182      whole is a relatively complicated application, and is probably not
183      the best place to look when you are first trying to understand how
184      to build Cocoa applications. For that, you might benefit more from
185      the examples in the "examples/cocoa/" directory. Once you are
186      familiar with those examples, though, and have some experience
187      building your own application features using Cocoa and the
188      Objective-C bridge, you might browse through the IDE sources to
189      see how it implements its features.</para>
191    <para>The search path for &CCL;'s <code>REQUIRE</code> feature
192      includes the "objc-bridge" and "cocoa-ide" directories. You can
193      load features defined in these directories by
194      using <code>REQUIRE</code>. For example, if you want to use the
195      Cocoa features of &CCL; from a terminal session (or from an Emacs
196      session using SLIME or ILISP), you can evaluate <code>(require
197        :cocoa)</code>.</para>
198  </sect1>
200  <!-- ================================================================ -->
201  <sect1><title>The Application Builder</title>
202    <anchor id="application_builder"/>
203    <para>One important feature of the IDE currently has no Cocoa user
204      interface: the application builder. The application builder
205      constructs a
206      Cocoa <glossterm linkend="application_bundle">application
207        bundle</glossterm> that runs a Lisp image when double-clicked. You
208      can use the application builder to create Cocoa applications in
209      Lisp. These applications are exactly like Cocoa applications
210      created with XCode and Objective-C, except that they are written
211      in Lisp.</para>
213    <para>To make the application builder available, evaluate the
214      expression <code>(require :build-application)</code>. &CCL; loads
215      the required subsystems, if necessary.</para>
217    <para>
218      <indexterm zone="build-application"/>
219      <command><varname id="build-application">BUILD-APPLICATION</varname> <varname>&key;</varname>
220        (<parameter>name</parameter> <replaceable>"MyApplication"</replaceable>)
221        (<parameter>type-string</parameter> <replaceable>"APPL"</replaceable>)
222        (<parameter>creator-string</parameter> <replaceable>"OMCL"</replaceable>)
223        (<parameter>directory</parameter> <replaceable>(current-directory)</replaceable>)
224        (<parameter>copy-ide-resources</parameter> <replaceable>t</replaceable>)
225        (<parameter>info-plist</parameter> <replaceable>NIL</replaceable>)
226        (<parameter>nibfiles</parameter> <replaceable>NIL</replaceable>)
227        (<parameter>main-nib-name</parameter> <replaceable>NIL</replaceable>)
228        (<parameter>application-class</parameter> <replaceable>'GUI::COCOA-APPLICATION</replaceable>)
229        (<parameter>toplevel-function</parameter> <replaceable>NIL</replaceable>)
230        [Function]</command>
231    </para>
233    <para>
234      The <varname>build-application</varname> function constructs an
235      application bundle, populates it with the files needed to satisfy
236      Mac OS X that the bundle is a launchable application, and saves an
237      executable Lisp image to the proper subdirectory of the
238      bundle. Assuming that the saved Lisp image contains correct code,
239      a user can subsequently launch the resulting Cocoa application by
240      double-clicking its icon in the Finder, and the saved Lisp
241      environment runs.
242    </para>
244    <para>The keyword arguments control various aspects of application
245      bundle as <code>BUILD-APPLICATION</code> builds it.</para>
246    <variablelist>
248      <varlistentry>
249        <term><varname>name</varname></term>
250        <listitem>
251          <para>Specifies the application name of the
252            bundle. <code>BUILD-APPLICATION</code> creates an application
253            bundle whose name is given by this parameter, with the
254            extension ".app" appended. For example, using the default
255            value for this parameter results in a bundle named
256            "".</para>
257        </listitem>
258      </varlistentry>
260      <varlistentry>
261        <term><varname>type-string</varname></term>
262        <listitem>
263          <para>Specifies type of bundle to create. You should normally
264            never need to change the default value, which Mac OS X uses to
265            identify application bundles.</para>
266        </listitem>
267      </varlistentry>
269      <varlistentry>
270        <term><varname>creator-string</varname></term>
271        <listitem>
272          <para>Specifies the <glossterm linkend="creator_code">creator
273              code</glossterm>, which uniquely identifies the application
274            under Mac OS X. The default creator code is that of &CCL;. For
275            more information about reserving and assigning creator codes,
276            see
277            Apple's <ulink url="">developer
278              page</ulink> on the topic.</para>
279        </listitem>
280      </varlistentry>
282      <varlistentry>
283        <term><varname>directory</varname></term>
284        <listitem>
285          <para>The directory in which <code>BUILD-APPLICATION</code>
286            creates the application bundle. By default, it creates the
287            bundle in the current working directory. Unless you
288            use <code>CURRENT-DIRECTORY</code> to set the working
289            directory, the bundle may be created in some unexpected place,
290            so it's safest to specify a full pathname for this argument. A
291            typical value might be <code>"/Users/foo/Desktop/"</code>
292            (assuming, of course, that your username is "foo").</para>
293        </listitem>
294      </varlistentry>
296      <varlistentry>
297        <term><varname>copy-ide-resources</varname></term>
298        <listitem>
299          <para>Whether to copy the resource files from the IDE's
300            application bundle. By
301            default, <code>BUILD-APPLICATION</code> copies nibfiles
302            and other resources from the IDE to the newly-created
303            application bundle. This option is often useful when you
304            are developing a new application, because it enables your
305            built application to have a fully-functional user
306            interface even before you have finished designing one. By
307            default, the application uses the application menu and
308            other UI elements of the IDE until you specify
309            otherwise. Once your application's UI is fully
310            implemented, you may choose to pass <literal>NIL</literal>
311            for the value of this parameter, in which case the IDE
312            resources are not copied into your application
313            bundle.</para>
314        </listitem>
315      </varlistentry>
317      <varlistentry>
318        <term><varname>info-plist</varname></term>
319        <listitem>
320          <para>A user-supplied NSDictionary object that defines the
321          contents of the Info.plist file to be written to the
322          application bundle. The default value
323          is <literal>NIL</literal>, which specifies that the
324          Info.plist from the IDE is to be used
325          if <replaceable>copy-ide-resources</replaceable> is true,
326          and a new dictionary created with default values is to be
327          used otherwise. You can create a suitable NSDictionary
328          object using the
329          function <literal>make-info-dict</literal>. For details on
330          the parameters to this function, see its definition in
331          "ccl/cocoa-ide/builder-utilities.lisp".</para>
332        </listitem>
333      </varlistentry>
335      <varlistentry>
336        <term><varname>nibfiles</varname></term>
337        <listitem>
338          <para>A list of pathnames, where each pathname identifies
339            a <glossterm linkend="nibfile">nibfile</glossterm> created
340            with
341            Apple's <glossterm linkend="InterfaceBuilder">InterfaceBuilder</glossterm>
342            application. <code>BUILD-APPLICATION</code> copies each
343            nibfile into the appropriate place in the application bundle,
344            enabling the application to load user-interface elements from
345            them as-needed. It is safest to provide full pathnames to the
346            nibfiles in the list. Each nibfile must be in ".nib" format,
347            not ".xib" format, in order that the application can load
348            it.</para>
349        </listitem>
350      </varlistentry>
352      <varlistentry>
353        <term><varname>main-nib-name</varname></term>
354        <listitem>
355          <para>The name of
356            the <glossterm linkend="nibfile">nibfile</glossterm> to load
357            initially when launching. The user-interface defined in this
358            nibfile becomes the application's main interface. You must
359            supply the name of a suitable nibfile for this parameter, or
360            the resulting application uses the &CCL; user
361            interface.</para>
362        </listitem>
363      </varlistentry>
365      <varlistentry>
366        <term><varname>application-class</varname></term>
367        <listitem>
368          <para>The name of the application's CLOS class. The default
369            value is the class provided by &CCL; for graphical
370            applications. Supply the name of your application class if you
371            implement one. If not, &CCL; uses the default class.</para>
372        </listitem>
373      </varlistentry>
375      <varlistentry>
376        <term><varname>toplevel-function</varname></term>
377        <listitem>
378          <para>The toplevel function that runs when the application
379            launches. Normally the default value, which is &CCL;'s
380            toplevel, works well, but in some cases you may wish to
381            customize the behavior of the application's toplevel. The best
382            source of information about writing your own toplevel is the
383            &CCL; source code, especially the implementations
384            of <code>TOPLEVEL-FUNCTION</code> in
385            "ccl/level-1/l1-application.lisp"</para>
386        </listitem>
387      </varlistentry>
389    </variablelist>
391    <para><code>BUILD-APPLICATION</code> creates a folder named
392      "<replaceable>name</replaceable>.app" in the
393      directory <replaceable>directory</replaceable>. Inside that
394      folder, it creates the "Contents" folder that Mac OS X
395      application bundles are expected to contain, and populates it
396      with the "MacOS" and "Resources" folders, and the "Info.plist"
397      and "PkgInfo" files that must be present in a working
398      application bundle. It takes the contents of the "Info.plist"
399      and "PkgInfo" files from the parameters
400      to <code>BUILD-APPLICATION</code>. If <replaceable>copy-ide-resources</replaceable>
401      is true then it copies the contents of the "Resources" folder
402      from the "Resources" folder of the running IDE.</para>
404    <para>The work needed to produce a running Cocoa application is
405    very minimal. In fact, if you
406    supply <code>BUILD-APPLICATION</code> with a valid nibfile and
407    pathnames, it builds a running Cocoa application that displays
408    your UI. It doesn't need you to write any code at all to do
409    this. Of course, the resulting application doesn't do anything
410    apart from displaying the UI defined in the nibfile. If you want
411    your UI to accomplish anything, you need to write the code to
412    handle its events. But the path to a running application with your
413    UI in it is very short indeed.</para>
415   <para>Please note that <code>BUILD-APPLICATION</code> is a work in
416    progress. It can easily build a working Cocoa application, but it
417    still has limitations that may in some cases prove
418    inconvenient. For example, in the current version it provides no
419    easy way to specify an application delegate different from the
420    default. If you find the current limitations
421    of <code>BUILD-APPLICATION</code> too restrictive, and want to try
422    extending it for your use, you can find the source code for it in
423    "ccl/cocoa-ide/build-application.lisp". You can see the default
424    values used to populate the "Info.plist" file in
425    "ccl/cocoa-ide/builder-utilities.lisp".</para>
427    <para>For more information on how to
428    use <code>BUILD-APPLICATION</code>, see the Currency Converter
429    example in "ccl/examples/cocoa/currency-converter/".</para>
431    <!-- ***************************************************** -->
432    <sect2>
433      <title>Running the Application Builder From the Command
434      Line</title>
436      <para>It's possible to automate use of the application builder
437        by running a call to <literal>CCL:BUILD-APPLICATION</literal>
438        from the terminal command line. For example, the following
439        command, entered at a shell prompt in Mac OS X's Terminal
440        window, builds a working copy of the &CCL; environment called
441        "":</para>
443      <programlisting>
444ccl -b -e "(require :cocoa)" -e "(require :build-application)" -e "(ccl::build-application :name \"Foo\")"
445      </programlisting>
447      <para>You can use the same method to automate building your
448      Lisp/Cocoa applications. &CCL; handles each Lisp expressions
449      passed with a <literal>-e</literal> argument in order, so you
450      can simply evaluate a sequence of Lisp expressions as in the
451      above example to build your application, ending with a call
452      to <literal>CCL:BUILD-APPLICATION</literal>. The call
453      to <literal>CCL:BUILD-APPLICATION</literal> can process all the
454      same arguments as if you evaluated it in a Listener window in
455      the &CCL; IDE.</para>
457      <para>Building a substantial Cocoa application (rather than just
458      reproducing the Lisp environment using defaults, as is done in
459      the above example) is likely to involve a relatively complicated
460      sequence of loading source files and perhaps evaluating Lisp
461      forms. You might be best served to place your command line in a
462      shell script that you can more easily edit and test.</para>
464      <para>One potentially complicated issue concerns loading all
465        your Lisp source files in the right order. You might consider
466        using ASDF to define and load a system that includes all the
467        parts of your application before
468        calling <literal>CCL:BUILD-APPLICATION</literal>. ASDF is a
469        "another system-definition facility", a sort
470        of <literal>make</literal> for Lisp, and is included in the
471        &CCL; distribution. You can read more about ASDF at the ASDF
472        <ulink url="">home
473        page</ulink>.</para>
475      <para>Alternatively, you could use the standard features of
476        Common Lisp to load your application's files in the proper
477        order.</para>
478    </sect2>
479  </sect1>
Note: See TracBrowser for help on using the repository browser.