source: trunk/source/examples/README-OPENMCL-EXAMPLES @ 11573

Last change on this file since 11573 was 6, checked in by gb, 16 years ago

Initial revision

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.9 KB
Line 
1
2LinuxPPC-specific examples:
3
4Prerequisites.
5  All of these example programs require OpenMCL 0.9 or later.
6  Most additionally require that X11 runtime libraries are installed,
7   and that OpenMCL is running under an X server.
8  Additional libraries may also be required.  One way to check for
9   the presence of a shared library named "LIBNAME.so" is to do:
10
11% /sbin/ldconfig -p | fgrep LIBNAME.so
12
13   If that returns a line of the form:
14
15     LIBNAME.so (<other info>) => /path/to/some/lib/on/your/system
16
17   you're in luck; if it doesn't, you may have to hunt around to
18   find a package (.deb, .rpm, ...) which contains the library in
19   a form that's appropriate for your Linux distribution.  Different
20   distributions package things differently, and packages often
21   depend on other packages; it's hard to be specific about what a
22   given distribution needs, but I'll try to provide some hints.
23
24 Beginning with release 0.9, OpenMCL uses "interface directories",
25  to try to modularize its interface database somewhat.  If any of
26  these examples need interface directories that aren't distributed
27  with OpenMCL, the example's description will note that.  ("interface
28  directories" are subdirectories of "ccl:headers;" that contain -
29  among other things - a set of files whose extension is "db".)
30
31----------------------------------------------------------------------
32file: "opengl-ffi.lisp"
33description: 2d Gasket example  taken from
34  "Interactive Computer Graphics:
35   A Top-Down Approach with OpenGL" by Ed Angel
36contributor: Hamilton Link
37interface-dir: gl       ; distributed with OpenMCL
38libraries:  libGL.so    ; may be part of a "mesa" or "opengl" package
39            libGLU.so   ; may be part of a "mesa" or "opengl" package
40            libglut.so  ; may be part of a "glutg3" or "glutg3-dev" package
41invocation:
42? (require "opengl-ffi")
43? (2dgasket::main)
44notes:
45OpenGL doesn't seem to provide a way to do event handling incrementally
46or concurrently with OpenMCL; when its event handling function finishes
47(when the OpenGL window closes), the OpenMCL process will exit and when
48the OpenGL event-loop is active, OpenMCL isn't responsive.)
49It's possible that the "gtkglarea" package would provide a way of doing
50OpenGL graphics in a way that's a little less intrusive.
51----------------------------------------------------------------------
52file: "gtk-clock.lisp"
53description: A double-buffered analog clock, derived from the
54  double-buffered clock example in "Developing Linux Applications
55  with GDK and GTK+", Eric Harlow, (c) 1999 New Riders Publishing.
56contributor: Clozure
57interface-dir: gtk      ; distributed with OpenMCL
58libraries:  libgtk.so   ; may be part of a "libgtk-1.2" package
59invocation:
60? (require "gtk-clock")
61? (ccl::gtk-clock)
62notes:
63The clock is reentrant: it should be possible to call (ccl::gtk-clock)
64multiple times, and clutter your desktop with way too many
65clocks.
66----------------------------------------------------------------------
67file: "gtk-minesweepr.lisp"
68description: An implementation of the Minesweeper game, derived from the
69  Minesweeper example in "Developing Linux Applications
70  with GDK and GTK+", Eric Harlow, (c) 1999 New Riders Publishing.
71contributor: Clozure
72interface-dir: gtk      ; distributed with OpenMCL
73libraries:  libgtk.so   ; may be part of a "libgtk-1.2" package
74invocation:
75? (require "gtk-minesweeper")
76? (minesweeper:minesweeper)
77notes:
78Minesweeper -isn't- reentrant (too much state is kept in global variables);
79if you try to invoke (minesweeper:minesweeper) while a minesweeper window
80is already active, it'll let you close the old window or abort the attempt
81to open a new one.
82
83I found that there were display issues with the way that GtkToggleButtons
84were used in the original program and made a subclass - GtkQuietToggelButton -
85that handles "enter" and "leave" events differently.  The quiet buttons are
86probably better (you can do
87
88? (setq  MINESWEEPER::*MINESWEEPER-USE-QUIET-TOGGLE-BUTTONS* nil)
89
90to use the original implementation), but some display artifacts remain.
91There may be a better approach to the problem than the one I took, and
92I'd have to assume that GTK is flexible enough to offer a solution.
93
94Maybe not the world's best Minesweeper game, but the only one I know of
95that allows you to develop CL programs while you're playing ...
96
97----------------------------------------------------------------------
98file: "gtk-step.lisp"
99description: An alternate user interface to OpenMCL's STEP command.
100contributor: Clozure
101interface-dir: gtk      ; distributed with OpenMCL
102libraries:  libgtk.so   ; may be part of a "libgtk-1.2" package
103invocation:
104? (require "gtk-step")
105? (step <some form>)
106Notes:
107Since OpenMCL is essentially a "compile-only" implementation, one has
108to take special ... steps to ensure that STEP will step through evaluated
109code.  (This is true regardless of what user interface STEP uses.)
110
111Most of the STEP output is displayed in a GtkText widget; it often feels
112like it's dragging a reluctant vertical scrollbar with it, fighting tooth
113and nail to convince that scrollbar to scroll to where the most recent
114output is.  I sincerely hope that I'm doing something wrong here ...
115
116-------------
117MacOSX-specific examples:
118(These currently depend on the Cocoa application framework, which is part
119of MacOSX.  In the future, they may also work under Linux and/or Darwin
120with the GNUstep application framework (an opensource implementation of
121the OpenSTEP framework on which Cocoa is based.)
122
123----------------------------------------------------------------------
124file: "cocoa.lisp"
125description: A preliminary Cocoa-based lisp development system
126contributor: Clozure
127interface-dir: cocoa    ; distributed with OpenMCL
128libraries:  /System/Library/Frameworks/Cocoa.framework/Cocoa
129invocation:
130? (require "COCOA")
131After a few seconds, an "OpenMCL" dock entry should appear, identifying
132a new window layer in which a Cocoa-based listener and OpenMCL menubar
133should be present.  There's a text editor that supports basic Emacs-style
134key bindings for cursor movement, etc.; it isn't (yet) very lisp-aware.
135
136----------------------------------------------------------------------
137file: "cocoa-inspector.lisp"
138description: A browser-style inspector for the preliminary Cocoa IDE.
139contributor: Clozure
140interface-dir: cocoa    ; distributed with OpenMCL
141libraries:  /System/Library/Frameworks/Cocoa.framework/Cocoa
142invocation:
143? (require "COCOA-INSPECTOR")
144This loads the Cocoa IDE and adds support for graphically inspecting
145Lisp objects:
146? (ccl::cinspect <form>)
147
148Hopefully, we'll be able to tie this in (to the Cocoa editor/listener,
149to the menubar, to the CL:INSPECT function ...) in the near future.
150
151----------------------------------------------------------------------
152file: "cocoa-application.lisp"
153description: Save the "preliminary Cocoa IDE" as a double-clickable
154             MacOSX application bundle
155contributor: Clozure
156interface-dir: cocoa    ; distributed with OpenMCL
157libraries:  /System/Library/Frameworks/Cocoa.framework/Cocoa
158invocation:
159? (require "COCOA-APPLICATION") ; after first carefully reading the
160                                ; comments in that file.
161
162It may be a little premature to worry about this (since the Cocoa IDE
163is still pretty feature-starved.)  It -does- demonstrate that it's
164possible to make .nib-based, double-clickable applications in OpenMCL,
165and I think that it's reasonable to assume that the process will get
166smoother in the future.
167
168Platform-neutral examples:
169
170
171file: "finger.lisp"
172description: An RFC 1288 "finger" protocol client and server
173contributor: Barry Perryman
174interface-dir: libc     ; distributed with OpenMCL
175libraries: 
176invocation: (require "FINGER")
177
178This is a clear, self-contained example of TCP programming in OpenMCL.
179Note that it may not be possible to run a FINGER server on the standard
180port (79), since doing so may require root privileges (and since there
181may already be a finger service running on that port, via inetd/xinetd.)
182
183I suppose that I should also say that one should always exercise caution
184when running any type of server on a machine connected to the Internet.
Note: See TracBrowser for help on using the repository browser.