4.2 Using the development tools in applications
The user can develop their own ECLiPSe applications using the
development tools independent of the TkECLiPSe toplevel. There are two
ways to do this, depending on if the user is also using the embedding Tcl/Tk
interface (see the Embedding and Interfacing Manual) to provide a graphical
front end:
-
The user is using the embedding Tcl/Tk interface, and is thus
developing a graphical front end in Tk. In this case the user can use the
development tools via the embedding interface. This is described in
section 4.2.1.
- The user is not using the embedding Tcl/Tk interface. In this case
the user can use the development tools remotely, by using the remote_tools
library. This is described in section 4.2.2.
4.2.1 Using the Development tools in the Tcl/Tk Embedding Interface
The development tool suite was
designed to be independent of the TkECLiPSe top-level so that they can be
used in a user's application. In effect, the user can replace the
TkECLiPSe
top-level with their own alternative top-level. Two simple examples in
which this is done are provided in the lib_tcl
library as
example.tcl
and example1.tcl
. In addition, tkeclipse
itself, in the file tkeclipse.pl
, can be seen as a more complex
example usage of the interface.
In order to use the Tcl/Tk interface, the system must be initialised as
described in the Embedding manual. In addition, the user's Tcl code should
probably also be provided as a package using Tcl's package facility, in
order to allow the program to run in a different directory. See the
Embedding manual and the example programs for more details on the
initialisation needed.
The user should most likely provide a connection for the output stream
of ECLiPSe so that output from ECLiPSe will go somewhere in the GUI. In
addition, especially during the development, it is also useful to connect
the error stream to some window so that errors (such as ECLiPSe
compilation errors) are seen by the user. This can be done using the
ec_queue_connect
Tcl command described in the embedding manual.
Output from ECLiPSe need not be sent to a Tk window directly. The Tcl/Tk
code which receives the output can operate on it before displaying it. It
is intended that all such graphical operations should be performed on the
Tcl side, rather than having some primitives provided on the ECLiPSe side.
The user can also provide balloon-help to his/her own application. The
balloon help package is part of the Megawidget developed by Jeffrey Hobbs
and used in TkECLiPSe. In order to define a balloon help for a particular
widget, the following Tcl code is needed:
balloonhelp <path> <text>
where <path>
is the pathname of the widget, and <text>
is the
text that the user wants to display in the balloon.
4.2.2 Using the Remote Development Tools
The user can also use the development tools via the remote_tools
library. In this case, the development tools are run as a separate program
from the ECLiPSe session, and is attached to it via the Tcl/Tk remote
interface (see the Embedding and Interfacing Manual). This allows any
ECLiPSe session to use the development tools,
as long as there is the capability for graphical display.
The main purpose for the remote_tools library is to allow the user to
use the development tools in situations where (s)he cannot use the Tcl/Tk
embedding interface, e.g. if ECLiPSe is already embedded into another
programming language, or if the user needs to use the tty interface for
ECLiPSe.
Figure 4.3: Remote Development Tools Toplevel (left: ECLiPSe active; right:
remote tools active)
Once attached to an ECLiPSe session, the remote development tools has
its own window as shown in Figure 4.3. The Tools menu is the
same as in TkECLiPSe, providing access to the same suite of development
tools. The main body of the window consists of one button and a status
indicator. The indicator shows wheather the tools can be used or not (the
tools cannot be used when the ECLiPSe is active), and the button
is used to pass control explicitly to ECLiPSe.
The ECLiPSe session and the development tools are two separate processes
(and in fact they can be running on different machines) that are connected
to each other via the remote Tcl/Tk interface. The interactions of the two
processes are synchronised in that there is a thread-like flow of control
between them: only one process can be `active' at any time. The interaction
is similar to the standard interaction between a debugger and the program
being debugged – debugging commands can only be issued
while the execution of the program is suspended. In the same way, the user
can only interact with the remote tools window when execution in the
ECLiPSe session is suspended. The toplevel window of the remote tools
has an indicator showing which side has control (see Figure 4.3).
To allow ECLiPSe to resume execution, control is transferred back from
the remote tools to ECLiPSe. This can either be
done automatically from the tools (e.g. when one of the debug buttons is
pressed in the tracer tool), or control can be transferred explicitly back
to ECLiPSe via the “Resume ECLiPSe” button on the remote tools window.
Starting Remote Tools
To use the remote tools, the user must first load the remote_tools library
with lib(remote_tools)
. After loading the library, the user can
start the remote tools by
starting the development tools as a separate program and then manually
attach the program to the ECLiPSe session. This allows the development
tools to be run on a different machine from the ECLiPSe session. In this
case, the user initiates the attachment in ECLiPSe with
attach_tools/0:
[eclipse 2]: attach_tools.
Socket created at address holborn.icparc.ic.ac.uk/22849
ECLiPSe prints the host and port address it expects the remote tools to
attach to, and execution is now suspended waiting for the remote tools to
attach. This is done by running the tktools program, which is located
with the other ECLiPSe executables. As stated, this program can be run
on a different machine from the ECLiPSe session, as long as the two are
connected via a network such as the internet. A connection window is then
displayed as shown:
The same `host' and `port' fields as printed by the ECLiPSe session should
be entered. The default `host' field is `localhost'. This will work if the
remote tools are ran on the same machine as the ECLiPSe
session. Otherwise the full name of the `host' as given by attach_tools/0 needs to be entered:
Typing return in the `port' field will start the attachment, and with
success, the remote tools window (see Figure 4.3) will be
displayed. The attach_tools/0 predicate will also return.
The user is not able to immediately interact directly with the remote
tools, as the ECLiPSe session is initially given control. The user can
use the ECLiPSe session as normal, with the additional availability of
the development tools. For example, the display matrix predicates can be
used as in TkECLiPSe. Also, the tracer tool replaces the previous
tracing facilities of the ECLiPSe session (this would typically be the
command-line debugger).
The tools can be triggered by events in the ECLiPSe session as described
above. In order to use the tools in a more interactive way, control should
be handed over to the remote tools. This can be done by calling the
tools/0 predicate. When the remote tools have control, the user can
now interactively select development tools from the Tools menu.
The remote_tools library provides several predicates to facilitate the use
of the remote development tools:
-
tools
- Explicitly hands over control to the remote development
tools. The tools window can then be used interactively. Execution on the
ECLiPSe session is suspended until the remote tools allows ECLiPSe to
resume, at which point the predicate succeeds. The predicate will abort if
the development tools is disconnected from the ECLiPSe session.
- attached(?ControlStream)
-
Checks if the remote development tools have been attached to this
ECLiPSe session or not. If attached, the predicate succeeds and
unifies ControlStream with the stream name of the control
stream. If not attached, th predicate fails.
Once attached, the remote development tools should be connected until the
user quits the session. Although it is possible to disconnect the tools
from the ECLiPSe session (from the File menu in the development tools
window). This is not recommended, as there would not be any debugging
facilities available after the disconnection – the original tracer would
not be restored.
It is possible to attach the remote development tools to any ECLiPSe
session, including one that is using the embedding Tcl/Tk interface (and
indeed, to TkECLiPSe itself). However, using the tools via the embedding
interface is usually the better option if available, because the tools are
more tightly coupled to ECLiPSe in this case. This means that the
communications between ECLiPSe and the tools are more efficient (and
hence something like the display matrix would perform more efficiently).