Previous Up Next

2.5  How do I write an ECLiPSe program?

You need to use an editor to write your programs. ECLiPSe does not come with an editor, but any editor that can save plain text files can be used. Save your program as a plain text file, and you can then compile the program into ECLiPSe and run it.

Extra support for editing ECLiPSe programs with common editors are available. An eclipse mode for the GNU emacs editor is bundled with the ECLiPSe package. This mode provides syntax highlighting, automatic indentation and many other features. To use this mode, you need to load the eclipse.el file into emacs. This is done by adding the following line to your .emacs file:

(autoload 'eclipse-mode "<eclipsedir>/lib_public/eclipse.el" "ECLIPSE editing mode" t)
where <eclipsedir> is the path to your ECLiPSe installation directory.

With TkECLiPSe, you can specify the editor you want to use, and this editor will be started by TkECLiPSe, e.g. when you select a file in the `Edit' option under the File menu. The default values are the value of the VISUAL environment variable under Unix, or Wordpad under Windows. This can be changed with the Preference Editor under the Tools menu.

2.5.1  Compiling a program

From the File menu, select the Compile ... option. This will bring up a file selection dialogue. Select the file you wish to compile, and click on the Open button. This will compile the file and any others it depends on. Messages indicating which files have been compiled and describing any errors encountered will be displayed in the bottom portion of the TkECLiPSe window (Output and Error Messages).

If a file has been modified since it was compiled, it may be recompiled by clicking on the make button. This recompiles any files which have become out-of-date.
For more information on program compilation and the compiler, please see The Compiler chapter in the user manual.

2.5.2  Executing a query

To execute a query, first enter it into the Query Entry text field. You will also need to specify which module the query should be run from, by selecting the appropriate entry from the drop-down list to the left of the Query Entry field. Normally, the default selection of eclipse will be fine; this will allow access to all ECLiPSe built-ins and all predicates that have not explicitly been compiled into a different module. Selecting another module for the query is only needed if you wish to call a predicate which is not visible from the eclipse module, in which case you need to select that module.
For more information about the module system, please see the Module System chapter in the user manual.
To actually execute the query, either hit the Enter key while editing the query, or click on the run button. TkECLiPSe maintains a history of commands entered during the session, and these may be recalled either by using the drop-down list to the right of the Query Entry field, or by using the up and down arrow keys while editing the Query Entry field.

If ECLiPSe cannot find a solution to the query, it will print No in the Results section of the TkECLiPSe window. If it finds a solution and knows there are no more, it will print it in the Results section, and then print Yes. If it finds a solution and there may be more, it will print the solution found as before, print More, and enable the more button. Clicking on the more button tells ECLiPSe to try to find another solution. In all cases it also prints the total time taken to execute the query.

From Query menu, you can run the query with various analysis tools (see chapter 6): Time Profile option will run the query with the profiler tool; Port Profile option will run the query with the port profiler tool.

Note that a query can be interrupted during execution by clicking on the interrupt button.

2.5.3  Editing a file

If you wish to edit a file (e.g. a program source file), then you may do so by selecting the Edit ... option from the File menu (or use the Edit new ... option if the file does not yet exist). This will bring up a file selection dialogue. Select the file you wish to edit, and click on the Open button.

When you have finished editing the file, save it. After you've saved it, if you wish to update the version compiled into ECLiPSe (assuming it had been compiled previously), simply click on the make button.

You can change which program is used to edit your file by using the TkECLiPSe Preference Editor, available from the Tools menu. Alternatively you can use your editor separately from ECLiPSe.

2.5.4  Debugging a program

To help diagnose problems in ECLiPSe programs, TkECLiPSe provides the tracer. It is activated by selecting the Tracer option from the Tools menu. The next time a goal is executed, the tracer window will become active, allowing you to step through the program's execution and examine the program's state as it executes. A full example is given in chapter 5.

2.5.5  File menu

The File menu of TkECLiPSe provides various options to manipulate files:


Allows the user to select a file to compile into ECLiPSe.

Use module

Allows the user to select and load an ECLiPSe module file into ECLiPSe.


Allows the user to select a file to edit using the default text editor
See section 2.5.3 for more information on editors.

Edit new

Allows the user to specify a new file that will be opened with the default text editor.

Cross referencer

Allows the user to select an ECLiPSe source file and produce a cross reference over it, and display the resulting graph in a new window.

Change directory

Allows the user to change the current working directory.

Change to example directory

Change the current working directory to the example directory in the ECLiPSe distribution.

New module

Allows the user to specify a new module that will be created. The new module becomes the current toplevel module.

Clear toplevel module

Allows the user to clear the current toplevel module, i.e. to erase it and start with a fresh, empty module.


Leave ECLiPSe

2.5.6  Getting help

More detailed help than is provided here can be obtained online for all the features of TkECLiPSe. Simply select the entry from the Help menu on TkECLiPSe's top-level window which corresponds to the topic or tool you are interested in.

Detailed documentation about all the predicates in the ECLiPSe libraries can be obtained through the Library Browser and Help tool. This tool allows you to browse the online help for the ECLiPSe libraries. On the left is a tree display of the libraries available and the predicates they provide. You can also enter a search string or a predicate specification manually in the text entry box at the top right. If there is only one match, detailed help for that predicate is displayed. If there are multiple matches, only very brief help is displayed for each; to get detailed help, try specifying the module and/or the arity of the predicate in the text field.

Alternatively, you can call the help/1 predicate in the query window (which contains the same information as the HTML Reference Manual). It has two modes of operation. First, when a fragment of a built-in name is specified, a list of short descriptions of all built-ins whose name contains the specified string is printed. For example,
?- help(write).
will print one-line descriptions about write/1, writeclause/2, etc. When a unique specification is given, the full description of the specified built-in is displayed, e.g. in
?- help(write/1).
?- help(ic:alldifferent/1).

2.5.7  Other tools

TkECLiPSe comes with a number of useful tools. Some have been mentioned above, but here is a more complete list. Note that we only provide brief descriptions here; for more details, please see the online help for the tool in question.

Compile scratch-pad

This tool allows you to enter small amounts of program code and have it compiled. This is useful for quick experimentation, but not for larger examples or programs you wish to keep, since the source code is lost when the session is exited.

Source File Manager

This tool allows you to keep track of and manage which source files have been compiled in the current ECLiPSe session. You can select files to edit them, or compile them individually, as well as adding new files.

Predicate Browser

This tool allows you to browse through the modules and predicates which have been compiled in the current session. It also lets you alter some properties of compiled predicates.

Source Viewer

This tool attempts to display the source code for predicates selected in other tools.

Delayed Goals

This tool displays the current delayed goals, as well as allowing a spy point to be placed on the predicate and the source code viewed.


This tool provides a graphical browser for inspecting terms. Goals and data terms are displayed as a tree structure. Sub-trees can be collapsed and expanded by double-clicking. A navigation panel can be launched which provides arrow buttons as an alternative way to navigate the tree.

Note that while the inspector window is open, interaction with other TkECLiPSe windows is disallowed. This prevents the term from changing while being inspected. To continue TkECLiPSe, the inspector window must be closed.

Visualisation Client

This starts a new Java visualisation client that allows ECLiPSe programs to be visualised with the visualisation tools. See the Visualisation manual for details on the visualisation tools.

Global Settings

This tool allows the setting of some global flags governing the way ECLiPSe behaves. See also the documentation for the set_flag/2 and get_flag/2 predicates.


This tool displays some statistics about memory and CPU usage of the ECLiPSe system, updated at regular intervals. See also the documentation for the statistics/0 and statistics/2 predicates.

Preference Editor

This tool allows you to edit and set various user preferences. This include parameters for how TkECLiPSe will start up, e.g. the amount of memory it will be able to use, and a initial query to execute; and parameters which affects the appearance of TkECLiPSe, such as the fonts TkECLiPSe uses and which editor it launches.

Previous Up Next