1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22% 23% $Id: umsusing.tex,v 1.2 2009/07/16 09:11:24 jschimpf Exp $ 24% 25% Imported from the user manual 26 27 28\newcommand{\guitext}[1]{\mbox{\texttt{#1}}} 29\newcommand{\keyboard}[1]{{\texttt{#1}}} 30%\newcommand{\menu}[1]{{\texttt{#1}}} 31%\newcommand{\menuopt}[1]{{\texttt{#1}}} 32%\newcommand{\button}[1]{{\texttt{#1}}} 33\newcommand{\menu}[1]{\guitext{#1}} 34\newcommand{\menuopt}[1]{\guitext{#1}} 35\newcommand{\button}[1]{\guitext{#1}} 36 37\newcommand{\ignore}[1]{} 38 39%------------------------------------------------------------------------ 40\chapter{Getting started with {\eclipse}} 41%------------------------------------------------------------------------ 42\label{chapusing} 43%HEVEA\cutdef[1]{section} 44 45%------------------------------------------------------------------------ 46\section{How do I install the {\eclipse} system?} 47%------------------------------------------------------------------------ 48Please see the installation notes that came with {\eclipse}. 49For Unix/Linux systems, these are in the file \texttt{README_UNIX}. 50For Mac~OS~X, they are in the file \texttt{README_MACOSX}. 51 52For Windows, the installation process is usually via an automatic 53installer. Instructions for manual installation can be found in 54\texttt{README_WIN.TXT}. 55 56Please note that choices made at installation time can affect which 57options are available in the installed system. 58 59%------------------------------------------------------------------------ 60\section{How do I read the online documentation?} 61%------------------------------------------------------------------------ 62Under Unix and Mac~OS~X, use any HTML browser to open the file \verb+doc/index.html+ 63in the \eclipse{} installation directory. 64Under Windows, select the menu entry 65\begin{verbatim} 66Start - Programs - ECLiPSe - Documentation 67\end{verbatim} 68 69%------------------------------------------------------------------------ 70\section{How do I run my {\eclipse} programs?} 71%------------------------------------------------------------------------ 72There are two ways of running {\eclipse} programs. The first is using 73\texttt{tkeclipse}, which provides an interactive graphical user 74interface to the {\eclipse} compiler and system. The second is using 75\texttt{eclipse}, which provides a more traditional command-line 76interface. We recommend you use {\tkeclipse} unless you have some 77reason to prefer a command-line interface. 78 79%------------------------------------------------------------------------ 80\section{How do I use \texttt{tkeclipse}?} 81%------------------------------------------------------------------------ 82 83\subsection{Getting started} 84 85To start {\tkeclipse}, either type the command \texttt{tkeclipse} at 86an operating system command-line prompt, or select {\tkeclipse} from 87the program menu on Windows. This will bring up the {\tkeclipse} 88top-level, which is shown in Figure~\ref{tktop}. 89 90\begin{figure}[bt] 91\begin{center} 92% funny pathname because this chapter gets included from tutorial as well 93\resizebox{0.6\textwidth}{!}{\includegraphics{../userman/tktop.eps}} 94\end{center} 95\caption{{\tkeclipse} top-level} 96\label{tktop} 97\end{figure} 98 99Note that help on {\tkeclipse} and its component tools is available 100from the \menu{Help} menu in the top-level window. 101 102%------------------------------------------------------------------------ 103\section{How do I write an {\eclipse} program?} 104%------------------------------------------------------------------------ 105You need to use an editor to write your programs. {\eclipse} does not come 106with an editor, but any editor that can save plain text files can be used. 107Save your program as a plain text file, and you can then compile the 108program into {\eclipse} and run it. 109 110Extra support for editing {\eclipse} programs with common editors are 111available. An eclipse mode for the GNU emacs editor is bundled with the 112{\eclipse} package. This mode provides syntax highlighting, automatic 113indentation and many other features. To use this mode, you need to load the 114\texttt{eclipse.el} file into emacs. This is done by adding the following 115line to your \texttt{.emacs} file: 116 117\begin{small} 118\begin{verbatim} 119(autoload 'eclipse-mode "<eclipsedir>/lib_public/eclipse.el" "ECLIPSE editing mode" t) 120\end{verbatim} 121\end{small} 122 123where \texttt{<eclipsedir>} is the path to your {\eclipse} installation 124directory. 125 126With {\tkeclipse}, you can specify the editor you want to use, and this 127editor will be started by {\tkeclipse}, e.g. when you select a file in 128the `Edit' option under the File menu. The default values are the value of 129the VISUAL environment variable under Unix, or Wordpad under Windows. 130This can be changed with the Preference Editor under the Tools menu. 131 132%------------------------------------------------------------------------ 133\subsection{Compiling a program} 134 135\index{compile} 136From the \menu{File} menu, select the \menuopt{Compile ...} option. 137This will bring up a file selection dialogue. Select the file you wish 138to compile, and click on the \button{Open} button. This will compile 139the file and any others it depends on. Messages indicating which 140files have been compiled and describing any errors encountered will be 141displayed in the bottom portion of the {\tkeclipse} window 142(\guitext{Output and Error Messages}). 143 144If a file has been modified since it was compiled, it may be 145recompiled by clicking on the \guitext{make} button. This recompiles 146any files which have become out-of-date. 147 148\See{For more information on program compilation and the compiler, 149please see \textbf{The Compiler} chapter in the user manual.} 150 151%------------------------------------------------------------------------ 152\subsection{Executing a query} 153 154\index{query} 155To execute a query, first enter it into the \guitext{Query Entry} text 156field. You will also need to specify which module the query should be 157run from, by selecting the appropriate entry from the drop-down list 158to the left of the \guitext{Query Entry} field. Normally, the default 159selection of \guitext{eclipse} will be fine; this will allow access to 160all {\eclipse} built-ins and all predicates that have not explicitly 161been compiled into a different module. Selecting another module for 162the query is only needed if you wish to call a predicate which is not 163visible from the {\tt eclipse} module, in which case you need to 164select that module. \See{For more information about the module 165system, please see the \textbf{Module System} chapter in the user 166manual.} 167 168To actually execute the query, either hit the \keyboard{Enter} key 169while editing the query, or click on the \guitext{run} button. 170{\tkeclipse} maintains a history of commands entered during the 171session, and these may be recalled either by using the drop-down list 172to the right of the \guitext{Query Entry} field, or by using the up 173and down arrow keys while editing the \guitext{Query Entry} field. 174 175If {\eclipse} cannot find a solution to the query, it will print 176\texttt{No} in the \guitext{Results} section of the {\tkeclipse} 177window. If it finds a solution and knows there are no more, it will 178print it in the \guitext{Results} section, and then print 179\texttt{Yes}. If it finds a solution and there may be more, it will 180print the solution found as before, print \texttt{More}, and enable 181the \guitext{more} button. Clicking on the \guitext{more} button 182tells {\eclipse} to try to find another solution. In all cases it 183also prints the total time taken to execute the query. 184 185From \menu{Query} menu, you can run the query with various analysis tools 186(see chapter~\ref{sec:program-analysis}): \menuopt{Time Profile} option 187will run the query with the profiler tool; \menuopt{Port Profile} option 188will run the query with the port profiler tool. 189 190Note that a query can be interrupted during execution by clicking on 191the \guitext{interrupt} button. 192 193%------------------------------------------------------------------------ 194\subsection{Editing a file} 195\label{secedit} 196 197If you wish to edit a file (e.g. a program source file), then you may 198do so by selecting the \guitext{Edit ...} option from the 199\guitext{File} menu (or use the \guitext{Edit new ...} option if the file 200does not yet exist). This will bring up a file selection dialogue. 201Select the file you wish to edit, and click on the \guitext{Open} 202button. 203 204When you have finished editing the file, save it. After you've saved 205it, if you wish to update the version compiled into {\eclipse} 206(assuming it had been compiled previously), simply click on the 207\guitext{make} button. 208 209You can change which program is used to edit your file by using the 210{\tkeclipse} Preference Editor, available from the \guitext{Tools} 211menu. Alternatively you can use your editor separately from 212\eclipse{}. 213 214%------------------------------------------------------------------------ 215\subsection{Debugging a program} 216\label{secdebug} 217 218To help diagnose problems in {\eclipse} programs, {\tkeclipse} 219provides the tracer. It is activated by selecting the 220\guitext{Tracer} option from the \guitext{Tools} menu. The next time 221a goal is executed, the tracer window will become active, allowing you 222to step through the program's execution and examine the program's 223state as it executes. A full example is given in 224chapter~\ref{chapdebug}. 225 226%------------------------------------------------------------------------ 227\subsection{File menu} 228 229The \guitext{File} menu of {\tkeclipse} provides various options to 230manipulate files: 231 232\subsubsection{Compile} 233Allows the user to select a file to compile into {\eclipse}. 234 235\subsubsection{Use module} 236Allows the user to select and load an {\eclipse} module file into 237{\eclipse}. 238 239\subsubsection{Edit} 240Allows the user to select a file to edit using the default text editor 241\See{See section~\ref{secedit} for more information on editors.}. 242 243\subsubsection{Edit new} 244Allows the user to specify a new file that will be opened with the default 245text editor. 246 247\subsubsection{Cross referencer} 248Allows the user to select an {\eclipse} source file and produce a cross 249reference over it, and display the resulting graph in a new window. 250 251\subsubsection{Change directory} 252Allows the user to change the current working directory. 253 254\subsubsection{Change to example directory} 255Change the current working directory to the example directory in the 256{\eclipse} distribution. 257 258\subsubsection{New module} 259Allows the user to specify a new module that will be created. The new 260module becomes the current toplevel module. 261 262 263\subsubsection{Clear toplevel module} 264Allows the user to clear the current toplevel module, i.e. to erase it and 265start with a fresh, empty module. 266 267\subsubsection{Exit} 268 Leave {\eclipse} 269 270 271%------------------------------------------------------------------------ 272\subsection{Getting help} 273 274\index{help} 275More detailed help than is provided here can be obtained online for 276all the features of {\tkeclipse}. Simply select the entry from the 277\guitext{Help} menu on {\tkeclipse}'s top-level window which 278corresponds to the topic or tool you are interested in. 279 280Detailed documentation about all the predicates in the 281{\eclipse} libraries can be obtained through the 282\guitext{Library Browser and Help} tool. 283This tool allows you to browse the online help for the {\eclipse} 284libraries. On the left is a tree display of the libraries available 285and the predicates they provide. 286\begin{itemize} 287\item Double clicking on a node in this tree either expands it or 288collapses it again. 289\item Clicking on an entry displays help for that entry to the right. 290\item Double clicking on a word in the right-hand pane searches for 291help entries containing that string. 292\end{itemize} 293You can also enter a search string or a predicate specification 294manually in the text entry box at the top right. If there is only one 295match, detailed help for that predicate is displayed. If there are 296multiple matches, only very brief help is displayed for each; to get 297detailed help, try specifying the module and/or the arity of the 298predicate in the text field. 299 300Alternatively, you can call the help/1 predicate in the query window 301(which contains the same information as the HTML Reference Manual). 302It has two modes of operation. First, when a fragment of a built-in 303name is specified, a list of short descriptions of all built-ins whose 304name contains the specified string is printed. For example, 305\begin{quote} 306\begin{verbatim} 307?- help(write). 308\end{verbatim} 309\end{quote} 310will print one-line descriptions about {\bf \tt write/1}, {\bf \tt 311writeclause/2}, etc. When a unique specification is given, the full 312description of the specified built-in is displayed, e.g.\ in 313\begin{quote} 314\begin{verbatim} 315?- help(write/1). 316\end{verbatim} 317\end{quote} 318or 319\begin{quote} 320\begin{verbatim} 321?- help(ic:alldifferent/1). 322\end{verbatim} 323\end{quote} 324 325 326%------------------------------------------------------------------------ 327\subsection{Other tools} 328 329{\tkeclipse} comes with a number of useful tools. Some have been 330mentioned above, but here is a more complete list. Note that we only 331provide brief descriptions here; for more details, please see the 332online help for the tool in question. 333 334\subsubsection{Compile scratch-pad} 335 336This tool allows you to enter small amounts of program code and have 337it compiled. This is useful for quick experimentation, but not for 338larger examples or programs you wish to keep, since the source code is 339lost when the session is exited. 340 341\subsubsection{Source File Manager} 342 343This tool allows you to keep track of and manage which source files 344have been compiled in the current {\eclipse} session. You can select 345files to edit them, or compile them individually, as well as adding 346new files. 347 348\subsubsection{Predicate Browser} 349 350This tool allows you to browse through the modules and predicates 351which have been compiled in the current session. It also lets you 352alter some properties of compiled predicates. 353 354\subsubsection{Source Viewer} 355 356This tool attempts to display the source code for predicates selected 357in other tools. 358 359\subsubsection{Delayed Goals} 360 361This tool displays the current delayed goals, as well as allowing a 362spy point to be placed on the predicate and the source code viewed. 363 364\subsubsection{Inspector} 365 366This tool provides a graphical browser for inspecting terms. Goals 367and data terms are displayed as a tree structure. Sub-trees can be 368collapsed and expanded by double-clicking. A navigation panel can be 369launched which provides arrow buttons as an alternative way to 370navigate the tree. 371 372Note that while the inspector window is open, interaction with other 373{\tkeclipse} windows is disallowed. This prevents the term from 374changing while being inspected. To continue {\tkeclipse}, the 375inspector window must be closed. 376 377\subsubsection{Visualisation Client} 378 379This starts a new Java visualisation client that allows {\eclipse} programs 380to be visualised with the visualisation tools. See the Visualisation manual 381for details on the visualisation tools. 382 383\subsubsection{Global Settings} 384 385This tool allows the setting of some global flags governing the way 386{\eclipse} behaves. See also the documentation for the 387\bipref{set_flag/2}{../bips/kernel/env/set_flag-2.html} and 388\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} predicates. 389 390\subsubsection{Statistics} 391 392This tool displays some statistics about memory and CPU usage of the 393{\eclipse} system, updated at regular intervals. See also the 394documentation for the 395\bipref{statistics/0}{../bips/kernel/env/statistics-0.html} and 396\bipref{statistics/2}{../bips/kernel/env/statistics-2.html} 397predicates. 398 399\subsubsection{Preference Editor} 400 401This tool allows you to edit and set various user preferences. This 402include parameters for how {\tkeclipse} will start up, e.g. the amount 403of memory it will be able to use, and a initial query to execute; and 404parameters which affects the appearance of {\tkeclipse}, such as the 405fonts {\tkeclipse} uses and which editor it launches. 406 407 408%------------------------------------------------------------------------ 409\section{How do I make things happen at compile time?} 410%------------------------------------------------------------------------ 411 412A file being compiled may contain queries. These are goals 413\index{query} preceded by either the symbol ``?-'' or the symbol 414``:-''. As soon as a query or command is encountered in the 415compilation of a file, the {\eclipse} system will try to satisfy it. 416Thus by inserting goals in this fashion, things can be made to happen 417at compile time. 418 419In particular, a file can contain a directive to the system to compile 420another file, and so large programs can be split between files, while 421still only requiring a single simple command to compile them. 422\index{compilation!nesting compile commands} When this happens, 423{\eclipse} interprets the pathnames of the nested compiled files 424relative to the directory of the parent compiled file; if, for 425example, the user calls 426\begin{quote} 427\begin{verbatim} 428[eclipse 1]: compile('src/pl/prog'). 429\end{verbatim} 430\end{quote} 431and the file src/pl/prog.pl contains a query 432\begin{quote} 433\begin{verbatim} 434:- [part1, part2]. 435\end{verbatim} 436\end{quote} 437then the system searches for the files {\tt part1.pl} and {\tt 438part2.pl} in the directory {\tt src/pl} and not in the current 439directory. Usually larger {\eclipse} programs have one main file 440which contains only commands to compile all the subfiles. In 441{\eclipse} it is possible to compile this main file from any 442directory. (Note that if your program is large enough to warrant 443breaking into multiple files (let alone multiple directories), it is 444probably worth turning the constituent components into modules.) 445\See{See section~\ref{secmodules} for more information about modules.} 446 447%------------------------------------------------------------------------ 448\section{How do I use {\eclipse} libraries in my programs?} 449\index{libraries} 450%------------------------------------------------------------------------ 451 452A number of files containing library predicates are supplied with the 453{\eclipse} system. They are usually installed in an {\eclipse} 454library directory. These predicates are either loaded automatically 455by {\eclipse} or may be loaded ``by hand''. 456 457During the execution of an {\eclipse} program, the system may 458dynamically load files containing library predicates. When this 459happens, the user is informed by a compilation or loading message. It 460is possible to explicitly force this loading to occur by use of the 461\bipref{lib/1}{../bips/kernel/compiler/lib-1.html} or 462\bipref{use_module/1}{../bips/kernel/modules/use_module-1.html} 463predicates. E.g.\ to load the library called {\tt lists}, use one of 464the following goals: 465\begin{quote} 466\begin{verbatim} 467:- lib(lists) 468:- use_module(library(lists)) 469\end{verbatim} 470\end{quote} 471This will load the library file unless it has been already loaded. In 472particular, a program can ensure that a given library is loaded when 473it is compiled, by including an appropriate directive in the source, 474e.g.\ {\tt :- lib(lists).} 475 476 477%------------------------------------------------------------------------ 478\section{Other tips} 479%------------------------------------------------------------------------ 480\subsection{Recommended file names} 481 482It is recommended programming practice to give the Prolog source 483programs the suffix {\bf .pl}, or {\bf .ecl} if it contains {\eclipse} 484specific code. It is not enforced by the system, but it simplifies 485managing the source programs. The 486\bipref{compile/1}{../bips/kernel/compiler/compile-1.html} predicate 487automatically adds the suffix to the filename, so that it does not 488need to be specified; if the literal filename can not be found, the 489system tries appending each of the valid suffixes in turn and tries to 490find the resulting filename. 491 492 493%HEVEA\cutend 494