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) 1994 - 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22% 23% @(#)umsusing.tex 1.10 94/12/06 24% 25% \comment{@(\#)text1.mss 20.4 9/19/88} 26% 27% REL DATE BY DESCRIPTION 28% 2.10 260489 David Miller Convert to LaTeX and update 29% 30 31\newcommand{\guitext}[1]{\mbox{\texttt{#1}}} 32\newcommand{\keyboard}[1]{{\texttt{#1}}} 33%\newcommand{\menu}[1]{{\texttt{#1}}} 34%\newcommand{\menuopt}[1]{{\texttt{#1}}} 35%\newcommand{\button}[1]{{\texttt{#1}}} 36\newcommand{\menu}[1]{\guitext{#1}} 37\newcommand{\menuopt}[1]{\guitext{#1}} 38\newcommand{\button}[1]{\guitext{#1}} 39 40\newcommand{\ignore}[1]{} 41 42%------------------------------------------------------------------------ 43\chapter{Getting started with {\eclipse}} 44%HEVEA\cutdef[1]{section} 45%------------------------------------------------------------------------ 46\label{chapusing} 47 48%------------------------------------------------------------------------ 49\section{How do I install the {\eclipse} system?} 50%------------------------------------------------------------------------ 51Please see the installation notes that came with {\eclipse}. 52For Unix/Linux systems, these are in the file \notation{README_UNIX}. 53For Windows, they are in the file \notation{README_WIN.TXT}. 54 55Please note that choices made at installation time can affect which options 56are available in the installed system. 57 58%------------------------------------------------------------------------ 59\section{How do I run my {\eclipse} programs?} 60%------------------------------------------------------------------------ 61There are two ways of running {\eclipse} programs. 62The first is using \notation{tkeclipse}, which provides an interactive graphical 63user interface to the {\eclipse} compiler and system. 64The second is using \notation{eclipse}, which provides a more traditional 65command-line interface. 66We recommend you use {\tkeclipse} unless you have some reason to prefer a 67command-line interface. 68 69%------------------------------------------------------------------------ 70\section{How do I use \notation{\tkeclipse}?} 71%------------------------------------------------------------------------ 72 73\subsection{Getting started} 74 75To start {\tkeclipse}, either type the command \notation{tkeclipse} at an 76operating system command-line prompt, or select {\tkeclipse} from the 77program menu on Windows. 78This will bring up the {\tkeclipse} top-level, which is shown in 79Figure~\ref{tktop}. 80 81\begin{figure}[bt] 82\begin{center} 83% funny pathname because this chapter gets included from tutorial as well 84\resizebox{0.8\textwidth}{!}{\includegraphics{tktop.eps}} 85\end{center} 86\caption{{\tkeclipse} top-level} 87\label{tktop} 88\end{figure} 89 90Note that help on {\tkeclipse} and its component tools is available from the 91\menu{Help} menu in the top-level window. 92If you need more information than can be found in this manual, try looking 93in the \menu{Help} menu. 94 95%------------------------------------------------------------------------ 96\section{How do I write an {\eclipse} program?} 97%------------------------------------------------------------------------ 98You must use an editor to write your programs. {\eclipse} does not come 99with an editor, but any editor that can save plain text files can be used. 100Save your program as a plain text file, and you can then compile the 101program into {\eclipse} and run it. 102 103With {\tkeclipse}, you can specify the editor you want to use, and this 104editor will be started by {\tkeclipse}, e.g., when you select a file in 105the `Edit' option under the File menu. The default values are the value of 106the VISUAL environment variable under Unix, or Wordpad under Windows. 107This can be changed with the Preference Editor under the Tools menu. 108 109%------------------------------------------------------------------------ 110\subsection{Compiling a program} 111 112From the \menu{File} menu, select the \menuopt{Compile ...} option. 113This will bring up a file selection dialog. 114Select the file you wish to compile, and click on the \button{Open} button. 115This will compile the file and any others it depends on. 116Messages indicating which files have been compiled and describing any errors 117encountered will be displayed in the bottom portion of the {\tkeclipse} 118window (\guitext{Output and Error Messages}). 119 120If a file has been modified since it was compiled, 121it may be recompiled by clicking on the \guitext{make} button. 122This recompiles any files which have become out-of-date. 123 124For more information on program compilation and the compiler, please see 125chapter \ref{chapcompiler}. 126 127%------------------------------------------------------------------------ 128\subsection{Executing a query} 129 130To execute a query, first enter it into the \guitext{Query Entry} 131text field. 132You will also have to specify which module the query should be run from, by 133selecting the appropriate entry from the drop-down list to the left of the 134\guitext{Query Entry} field. 135Normally, the default selection of \guitext{eclipse} will be fine; this will 136allow access to all {\eclipse} built-ins and all predicates that have not 137explicitly been compiled into a different module. 138Selecting another module for the query is only needed if you wish to call a 139predicate which is not visible from the \notation{eclipse} module, in which 140case you must select that module. 141(For more information about the module system, please see chapter 142\ref{chapmodules}.) 143 144To actually execute the query, either hit the \keyboard{Enter} key while 145editing the query, or click on the \guitext{run} button. 146{\tkeclipse} maintains a history of commands entered during the session, and 147these may be recalled either by using the drop-down list to the right of the 148\guitext{Query Entry} field, or by using the up and down arrow keys while 149editing the \guitext{Query Entry} field. 150 151If {\eclipse} cannot find a solution to the query, it will print \notation{No} 152in the \guitext{Results} section of the {\tkeclipse} window. 153If it finds a solution and knows there are no more, it will print it in the 154\guitext{Results} section, and then print \notation{Yes}. 155If it finds a solution and there may be more, it will print the solution 156found as before, print \notation{More}, and enable the \guitext{more} button. 157Clicking on the \guitext{more} button tells {\eclipse} to try to find 158another solution. 159In all cases it also prints the total time taken to execute the query. 160 161Note that a query can be interrupted during execution by clicking on the 162\guitext{interrupt} button. 163 164%------------------------------------------------------------------------ 165\subsection{Editing a file} 166\label{secedit} 167 168If you wish to edit a file (e.g., a program source file), then you may do so 169by selecting the \guitext{Edit ...} option from the \guitext{File} menu. 170This will bring up a file selection dialog. 171Select the file you wish to edit, and click on the \guitext{Open} button. 172 173When you have finished editing the file, save it. 174After you've saved it, if you wish to update the version compiled into 175{\eclipse} (assuming it had been compiled previously), simply click on the 176\guitext{make} button. 177 178You can change which program is used to edit your file by using the 179{\tkeclipse} Preference Editor, available from the \guitext{Tools} menu. 180 181%------------------------------------------------------------------------ 182\subsection{Debugging a program} 183\label{secdebug} 184 185To help diagnose problems in {\eclipse} programs, {\tkeclipse} provides the 186tracer. 187This can be invoked by selecting the \guitext{Tracer} option from the 188\guitext{Tools} menu. 189The next time a goal is executed, the tracer window will become active, 190allowing you to step through the program's execution and examine the 191program's state as it executes. 192 193The tracer displays the current call stack, the program source, and a trace log. 194By using the left mouse button in the \guitext{Call Stack} region of the 195tracer window, you can bring up a menu of additional operations you can 196perform on that goal, such as inspecting it, or setting a spy point on the 197predicate in question. Source breakpoints can be set by marking the 198corresponding line in the tracer's source display. 199Selecting \guitext{Configure filter ...} from the \guitext{Options} menu 200of the tracer will launch the conditional filter. 201This filter allows you to 202specify conditions on which the tracer should stop at a debug port. This 203can be very useful for skipping over unwanted debug ports. 204 205For more information on using the tracer, please see the online help, 206available by selecting \guitext{Tracer Help} from the \guitext{Help} menu. 207 208Other {\tkeclipse} tools which are useful while using the tracer are: 209 210\begin{itemize} 211 212\item the predicate browser (available by selecting the \guitext{Predicate 213Browser} option from the \guitext{Tools} menu), which is useful for setting 214or removing spy points on predicates, or for setting the 215\notation{start_tracing} 216flag which activates the tracer when a particular predicate is called for 217the first time; and 218 219\item the term inspector (available by double left clicking on a term from 220the stack window, or by selecting the \guitext{Inspector} 221option from the \guitext{Tools} menu), which is useful for examining and 222browse the arguments of a term in detail. 223 224\item the delayed goals browser (available by selecting the \guitext{Delayed 225Goals} option from the \guitext{Tools} menu), which allows you to inspect 226the current list of delayed goals. 227 228\item the display matrix (available either from calls in user's code, or by 229interactively selecting terms to be observed from the inspector, tracer or 230delay goals tools), which allows you to monitor any changes to a term and 231its arguments. 232 233\end{itemize} 234 235More information about debugging in {\eclipse} may be found in chapter 236\ref{chapdebug}. 237 238%------------------------------------------------------------------------ 239\subsection{Getting help} 240 241More detailed help than is provided here can be obtained online. 242Simply select the entry from the \guitext{Help} menu on {\tkeclipse}'s 243top-level window which corresponds to the topic or tool you are interested 244in. 245 246%------------------------------------------------------------------------ 247\subsection{Other tools} 248 249{\tkeclipse} comes with a number of useful tools. 250Some have been mentioned above, but here is a more complete list. 251Note that we only provide brief descriptions here; for more details, please 252see the online help for the tool in question. 253 254\subsubsection{Compile scratch-pad} 255 256This tool allows you to enter small amounts of program code and have it 257compiled. 258This is useful for quick experimentation, but not for larger examples or 259programs you wish to keep, since the source code is lost when the session is 260exited. 261 262\subsubsection{Source File Manager} 263 264This tool allows you to keep track of and manage which source files have 265been compiled in the current {\eclipse} session. 266You can select files to edit them, or compile them individually, as well as 267adding new files. 268 269\subsubsection{Predicate Browser} 270 271This tool allows you to browse through the modules and predicates which have 272been compiled in the current session. 273It also lets you alter some properties of compiled predicates. 274 275\subsubsection{Source Viewer} 276 277This tool attempts to display the source code for predicates selected in 278other tools. 279 280\subsubsection{Delayed Goals} 281 282This tool displays the current delayed goals, as well as allowing a spy 283point to be placed on the predicate and the source code viewed. 284 285\subsubsection{Tracer} 286 287As discussed in section \ref{secdebug}, the tracer is useful for debugging 288programs. 289See also chapter \ref{chapdebug}. 290 291\subsubsection{Inspector} 292 293This tool provides a graphical browser for inspecting terms. 294Goals and data terms are displayed as a tree structure. 295Sub-trees can be collapsed and expanded by double-clicking. 296A navigation panel can be launched which provides arrow buttons as an 297alternative way to navigate the tree. 298 299Note that while the inspector window is open, interaction with other 300{\tkeclipse} windows is disallowed. 301This prevents the term from changing while being inspected. 302To continue {\tkeclipse}, the inspector window must be closed. 303 304\subsubsection{Global Settings} 305 306This tool allows the setting of some global flags governing the way 307{\eclipse} behaves. 308See also the documentation for the 309\bipref{set_flag/2}{../bips/kernel/env/set_flag-2.html} and 310\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} predicates. 311 312\subsubsection{Statistics} 313 314This tool displays some statistics about memory and CPU usage of the 315{\eclipse} system, updated at regular intervals. 316See also the documentation for the 317\bipref{statistics/0}{../bips/kernel/env/statistics-0.html} and 318\bipref{statistics/2}{../bips/kernel/env/statistics-2.html} predicates. 319 320\subsubsection{Simple Query} 321 322This tool allows the user to send a simple query to {\eclipse} even while 323{\eclipse} is running some program and the Toplevel Query Entry window 324is unavailable. 325Note that the reply is shown in EXDR format (see the {\eclipse} Embedding 326and Interfacing Manual). 327 328\subsubsection{Library Help} 329 330This tool allows you to browse the online help for the {\eclipse} libraries. 331On the left is a tree display of the libraries available and the predicates 332they provide. 333\begin{itemize} 334\item Double clicking on a node in this tree either expands it or collapses it 335again. 336\item Clicking on an entry displays help for that entry to the right. 337\item Double clicking on a word in the right-hand pane searches for help 338entries containing that string. 339\end{itemize} 340You can also enter a search string or a predicate specification manually 341in the text entry box at the top right. 342If there is only one match, detailed help for that predicate is displayed. 343If there are multiple matches, only very brief help is displayed for each; 344to get detailed help, try specifying the module and/or the arity of the 345predicate in the text field. 346 347\subsection{Preference Editor} 348 349This tool allows you to edit and set various user preferences. This include 350parameters for how {\tkeclipse} will start up, e.g., the amount of memory it 351will be able to use, and an initial query to execute; and parameters which 352affects the appearance of {\tkeclipse}, such as the fonts {\tkeclipse} 353uses. 354 355%------------------------------------------------------------------------ 356\section{How do I use \notation{eclipse}?} 357%------------------------------------------------------------------------ 358 359\subsection{Getting started} 360 361To start {\eclipse}, type the command \notation{eclipse} at an 362operating system command-line prompt. 363This will display something like this: 364\begin{quote} 365\begin{verbatim} 366% eclipse 367ECLiPSe Constraint Logic Programming System [kernel] 368Kernel and basic libraries copyright Cisco Systems, Inc. 369and subject to the Cisco-style Mozilla Public Licence 1.1 370(see legal/cmpl.txt or eclipseclp.org/licence) 371Source available at www.sourceforge.org/projects/eclipse-clp 372GMP library copyright Free Software Foundation, see legal/lgpl.txt 373For other libraries see their individual copyright notices 374Version X.Y #Z, DAY MONTH DD HH:MM YYYY 375[eclipse 1]: 376\end{verbatim} 377\end{quote} 378The list in square brackets on the first line specifies the configuration 379of the running system, i.e., the language extensions that are present. 380The copyright and version information is followed by the prompt 381\notation{[eclipse 1]:}, which tells the user that the top-level loop is waiting 382for a user query in the module \notation{eclipse}. 383The predicate \predspecidx{help/0} gives 384general help and \bipref{help/1}{../bips/kernel/env/help-1.html} gives 385help about specific built-in predicates. 386 387%------------------------------------------------------------------------ 388\subsection{Interacting with the top level loop} 389 390The {\eclipse} prompt \notation{[eclipse 1]:} indicates that {\eclipse} 391is at the top level 392and the opened module is \notation{eclipse}. 393The \aboutidx{top level loop} is a procedure which repetitively 394prompts the user for a query, executes it and reports its 395result, i.e., either the answer variable bindings or the 396failure message. 397There is always exactly one module opened in the top level 398and its name is printed in the prompt. 399From this point it is possible to enter {\eclipse} goals, e.g., to 400pose queries, to enter an {\eclipse} program from the keyboard 401or to compile a program from a file. 402Goals are entered after the prompt and are terminated by fullstop and 403newline. 404 405The {\eclipse} system may be exited by typing \notation{CTRL-D} (UNIX) or 406\notation{CTRL-Z} + \notation{RETURN} (Windows) at the top level prompt, 407\index{Exiting {\eclipse}} 408or by calling either the \bipref{halt/0}{../bips/kernel/opsys/halt-0.html} 409or the \bipref{exit/1}{../bips/kernel/opsys/exit-1.html} predicates. 410 411%------------------------------------------------------------------------ 412\subsection{Compiling a program} 413 414The square brackets \notation{[}\pattern{...}\notation{]} or the 415\bipref{compile/1}{../bips/kernel/compiler/compile-1.html} predicate are used 416to compile {\eclipse} source from a file. 417If the goal 418\begin{quote} 419\begin{verbatim} 420compile(myfile). 421\end{verbatim} 422\end{quote} 423or the short-hand notation 424\begin{quote} 425\begin{verbatim} 426[myfile]. 427\end{verbatim} 428\end{quote} 429is called, either as a query at the top level or within another goal, 430the system looks for the file \notation{myfile} or for a file called 431\notation{myfile.pl} or \notation{myfile.ecl} and compiles it. 432The short-hand notation may also be used to compile several files in 433sequence: 434\begin{quote} 435\begin{verbatim} 436[ file_1, file_2, ..., file_n ] 437\end{verbatim} 438\end{quote} 439The \bipref{compile/2}{../bips/kernel/compiler/compile-2.html} predicate may be 440used to compile a file or list of 441files into a module specified in the second argument. 442 443If a file has been modified since it was compiled, it may be recompiled by 444invoking the \bipref{make/0}{../bips/kernel/env/make-0.html} predicate. 445This recompiles any files which have become out-of-date. 446 447For more information on program compilation and the compiler, please see 448chapter \ref{chapcompiler}. 449 450%------------------------------------------------------------------------ 451\subsection{Entering a program from the terminal} 452 453Programs can be entered directly from the terminal, as well as being read 454from files. 455To do this, simply compile the special file \notation{user}. 456That is, \notation{[user].} or \notation{compile(user).} at a top level 457prompt. 458The system then displays the compiler prompt (which is a blank by default) 459and waits for a sequence of clauses. 460Each of the clauses is terminated by a fullstop.% 461\index{fullstop}\index{clause!termination} 462(If the fullstop is omitted the system just sits 463waiting, because it supposes the clause is not terminated. 464If you omit the fullstop by accident simply type it in on the following line, 465and then proceed to type in the program clauses, each followed by a fullstop and 466carriage return.) 467To return to the top level prompt, 468type CTRL-D (UNIX), CTRL-Z + RETURN (Windows) or enter the atom 469\notation{end_of_file} followed by fullstop and RETURN. 470 471For example: 472\begin{quote} 473\begin{verbatim} 474[eclipse 1]: [user]. 475source_processor.eco loaded in 0.01 seconds 476... 477ecl_compiler.eco loaded in 0.23 seconds 478 father(abraham, isaac). 479 father(isaac, jacob). 480 father(jacob, joseph). 481 ancestor(X, Y) :- father(X, Y). 482 ancestor(X, Y) :- ancestor(X, Z), ancestor(Z, Y). 483 ^D 484 tty compiled 420 bytes in 0.01 seconds 485 486Yes (0.24s cpu) 487[eclipse 2]: 488\end{verbatim} 489\end{quote} 490The two predicates \predspec{father/2} and \predspec{ancestor/2} are now 491compiled 492and can be used. 493 494%------------------------------------------------------------------------ 495\subsection{Executing a \Index{query}} 496 497Once a set of clauses has been compiled, 498it may be queried in the usual Prolog manner. 499If there are uninstantiated \Index{variables} in the query, 500the system will attempt to find an instantiation of them which will 501satisfy the query, and if successful it will 502display one such instantiation. 503If potentially there is another solution, the top level 504will then wait for a further instruction: either a \notation{<CR>} 505(``newline'' or ``return'') or a semi-colon (\notation{;}). 506A return will end the query successfully. 507A semi-colon will initiate \Index{backtracking} 508in an attempt to find another solution to the query. 509Note that it is not necessary to type a new line after the semicolon 510--- one keystroke is enough. 511When the top level loop can detect 512that there are no further solutions, it does not wait for the semicolon 513or newline, but it displays directly the next prompt. 514For example in a query on 515a family database: 516\begin{quote} 517\begin{verbatim} 518[eclipse 3]: father(X, Y). 519 520X = abraham 521Y = isaac 522Yes (0.00s cpu, solution 1, maybe more) ? ; (user types ';') 523 524X = isaac 525Y = jacob 526Yes (0.00s cpu, solution 2) 527[eclipse 4]: 528\end{verbatim} 529\end{quote} 530 531Queries may be extended over more than one line. When this is done the prompt 532changes to a tabulation character, i.e., the input is indented to 533indicate that the query is not yet completed. 534The fullstop marks the end of the input. 535 536%------------------------------------------------------------------------ 537\subsection{Interrupting the execution\index{interrupt}} 538 539If a program is executing, it may be interrupted by 540typing \notation{CTRL-C} (interrupt in the UNIX environment). 541This will invoke the corresponding interrupt handler 542(see section \ref{sectinterrupts}). 543By default, the system prints a menu offering some alternatives: 544\begin{quote} 545\begin{verbatim} 546^C 547interruption: type a, b, c, e, or h for help : ? h (user types 'h') 548help 549 a : abort 550 b : break level 551 c : continue 552 e : exit 553 h : help 554 555 556interruption: type a, b, c, e, or h for help : ? 557\end{verbatim} 558\end{quote} 559The \notation{a} option returns to the toplevel, \notation{b} starts a nested 560toplevel, 561\notation{c} continues the interrupted execution, and \notation{e} is an 562emergency 563exit 564of the whole {\eclipse} session. If the debugger is running, an additional 565option \notation{d} is displayed: it switches the debugger to creep mode. 566 567The execution of {\eclipse} may be suspended by typing \notation{CTRL-Z} 568(suspend) or by calling \bipref{pause/0}{../bips/kernel/opsys/pause-0.html}. 569This will suspend the {\eclipse} process and return the UNIX prompt. 570Entering the shell command \notation{fg} will return to {\eclipse}. 571Note that this feature may not be available on all systems. 572 573%------------------------------------------------------------------------ 574\subsection{Debugging a program} 575 576Please see the chapters on debugging in the tutorial and user manuals for 577more details. The tutorial chapter covers the {\tkeclipse} debugging in a 578tutorial style tour, and the user manual chapter covers 579 debugging in 580general and the command-line debugger in particular. 581 582%------------------------------------------------------------------------ 583\subsection{The \Index{history} mechanism} 584The {\eclipse} toplevel loop provides a simple history mechanism which allows 585the examination and repetition of previous queries. 586The history list is printed with the command \notation{h}. 587A previous query is invoked by typing either its absolute number or its 588relative negative offset from the current query number (i.e., --1 will 589execute the previous query). 590The current query number is displayed in the toplevel prompt. 591 592The history is initialized from the file \notationidx{.eclipse_history} 593in the current directory or in the home directory. 594This file contains the history goals, each ended by a fullstop. 595The current history can be written using the predicate 596\bipref{write_history/0}{../bips/lib/toplevel/write_history-0.html} from the 597\notation{util} library. 598 599%------------------------------------------------------------------------ 600\subsection{Getting \Index{help}} 601Detailed documentation about all the predicates in the {\eclipse} libraries 602can be obtained online through the help facility. 603It has two modes of operation. 604First, when a fragment of a built-in name is specified, a list of short 605descriptions of all built-ins whose name contains the specified string 606is printed. 607For example, 608\begin{quote} 609\begin{verbatim} 610:- help(write). 611\end{verbatim} 612\end{quote} 613will print one-line descriptions about \predspec{write/1}, 614\predspec{writeclause/2}, etc. 615When a unique specification is given, the full description of the 616specified built-in is displayed, e.g., in 617\begin{quote} 618\begin{verbatim} 619:- help(write/1). 620\end{verbatim} 621\end{quote} 622 623%------------------------------------------------------------------------ 624\section{How do I make things happen at compile time?} 625%------------------------------------------------------------------------ 626 627A file being compiled may contain queries.\index{query} 628These are goals preceded by the symbol ``:-''. 629As soon as a query is encountered in the compilation of a file, 630the {\eclipse} system will try to satisfy it. 631Thus by inserting goals in this fashion, things can be made to happen at 632compile time. 633 634In particular, a file can contain a directive to the system 635to compile another file, and so large programs can be split between files, 636while still only requiring a single simple command to compile them.% 637\index{compilation!nesting compile commands} 638When this happens, {\eclipse} interprets the pathnames of the nested 639compiled files relative to the directory of the parent compiled file; 640if, for example, the user calls 641\begin{quote} 642\begin{verbatim} 643[eclipse 1]: compile('src/pl/prog'). 644\end{verbatim} 645\end{quote} 646and the file src/pl/prog.pl contains a query 647\begin{quote} 648\begin{verbatim} 649:- [part1, part2]. 650\end{verbatim} 651\end{quote} 652then the system searches for the files \notation{part1.pl} and 653\notation{part2.pl} 654in the 655directory \notation{src/pl} and not in the current directory. 656Usually larger {\eclipse} programs have one main file which contains 657only commands to compile all the subfiles. 658In {\eclipse} it is possible to compile this main file from any directory. 659(Note that if your program is large enough to warrant breaking into multiple 660files (let alone multiple directories), it is probably worth turning the 661constituent components into modules --- see chapter \ref{chapmodules}.) 662 663%------------------------------------------------------------------------ 664\section{How do I use {\eclipse} \Index{libraries} in my programs?} 665%------------------------------------------------------------------------ 666 667A number of files containing library predicates are supplied with 668the {\eclipse} system. 669These predicates provide utility functions for general use. 670They are usually installed in an {\eclipse} library directory (or 671directories). 672These predicates are either loaded automatically by {\eclipse} or may be 673loaded ``by hand''. 674 675During the execution of an {\eclipse} program, the system may dynamically 676load files containing library predicates. When this happens, the user is 677informed by a compilation or loading message. 678It is possible to explicitly force this loading to occur by use 679of the \bipref{lib/1}{../bips/kernel/compiler/lib-1.html} or 680\bipref{use_module/1}{../bips/kernel/modules/use_module-1.html} predicates. 681e.g., to load the library 682called \notation{lists}, use one of the following goals: 683\begin{quote} 684\begin{verbatim} 685lib(lists) 686use_module(library(lists)) 687\end{verbatim} 688\end{quote} 689This will load the library file unless it has been already loaded. 690In particular, a program can ensure that a given library is loaded when it 691is compiled, by including an appropriate directive in the source, e.g., 692\notation{:- lib(lists).} 693 694Library files are found by searching the 695\Index{library path}\index{library search path} 696and by appending a suffix to the library name. 697The search path used when loading libraries is 698specified by the global flag \notation{library_path} using the 699\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} and 700\bipref{set_flag/2}{../bips/kernel/env/set_flag-2.html} predicates. 701This flag contains a list of strings containing the pathnames of the 702directories to be searched when loading a library file. 703User libraries may be be added to the system simply by copying the 704desired file into the {\eclipse} library directory. 705Alternatively the \notation{library_path} flag may be updated to point 706at a number of user specific directories. The following example illustrates 707how a directive may be added to a file to add a user-defined library in front 708of any existing system libraries. 709\begin{quote} 710\begin{verbatim} 711?- get_flag(library_path,Path), 712 set_flag(library_path, ["/home/myuser/mylibs" | Path]). 713\end{verbatim} 714\end{quote} 715The UNIX environment variable \notationidx{ECLIPSELIBRARYPATH} may also be used 716to 717specify the initial setting of the library path. 718The syntax is similar to the syntax of the UNIX PATH variable, i.e., 719a list of directory names separated by colons. 720The directories will be prepended to the standard library path in the 721given order. 722 723%------------------------------------------------------------------------ 724\section{How do I make my programs run faster?} 725%------------------------------------------------------------------------ 726 727By default, {\eclipse} compiles programs as \about{traceable}, which 728means that they can be traced using the built-in debugger. 729To obtain maximum efficiency, the directive 730\bipref{nodbgcomp/0}{../bips/kernel/obsolete/nodbgcomp-0.html} 731should be used, which will set some flags to produce a more efficient 732and shorter code: 733\begin{quote} 734\begin{verbatim} 735[eclipse 2]: nodbgcomp. 736 737yes. 738[eclipse 3]: [user]. 739 father(abraham, isaac). 740 father(isaac, jacob). 741 father(jacob, joseph). 742 ancestor(X, Y) :- father(X, Y). 743 ancestor(X, Y) :- ancestor(X, Z), ancestor(Z, Y). 744 user compiled optimized 396 bytes in 0.02 seconds 745 746yes. 747[eclipse 4]: 748\end{verbatim} 749\end{quote} 750 751Section \ref{secefficientcode} contains more detailed discussion on other 752techniques which can be used to optimise your programs. 753 754 755%------------------------------------------------------------------------ 756\section{Other tips} 757%------------------------------------------------------------------------ 758 759%------------------------------------------------------------------------ 760\subsection{Initialization at start-up} 761 762If you wish to have {\eclipse} do or execute things at startup time, you 763can achieve this in {\tkeclipse} by setting the initial query call in the 764Preference editor; and in the command-line \notation{eclipse} by putting via a 765\notation{.eclipserc} file. 766 767For \notation{eclipse}, 768before displaying the initial prompt, the system checks whether there is a file 769called \notationidx{.eclipserc}\index{initialization file}\label{eclipserc} 770in the current directory and if not, in the user's home 771directory. If such a file is found, {\eclipse} compiles it first. 772Thus it is possible to put various initialization commands into 773this file. 774{\eclipse} has many possibilities to change its default behaviour and 775setting up a \notation{.eclipserc} file is a convenient way to achieve this. 776A different name for the initialization file can be specified 777in the environment variable \notationidx{ECLIPSEINIT}. 778If \notation{ECLIPSEINIT} is set to an empty string, no initialization is done. 779If the system is started with a -e option, then the \notation{.eclipserc} file 780is ignored. 781 782For {\tkeclipse}, the system will make the initial query call as set in the 783Preference Editor before giving control to the user. This call can be set 784to compile an initialization file. This can be the \notation{.eclipserc} file, 785or some other file if the user wants to initialize the system differently in 786{\tkeclipse}. 787 788%------------------------------------------------------------------------ 789\subsection{Recommended file names} 790 791It is recommended programming practice to give the Prolog source programs 792the suffix \notation{.pl}, or \notation{.ecl} if it contains {\eclipse} specific 793code. 794It is not enforced by the system, but it simplifies managing the source 795programs. 796The \bipref{compile/1}{../bips/kernel/compiler/compile-1.html} predicate 797automatically adds the suffix to the 798file name, so that it does not have to be specified; 799if the literal file name can not be found, the system tries appending 800each of the valid suffixes in turn and tries to find the resulting file name. 801The system's list of valid Prolog suffixes is in the global flag 802\notationidx{prolog_suffix} and can be examined and modified 803using \bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} and 804\bipref{set_flag/2}{../bips/kernel/env/set_flag-2.html}. 805For example, to add the new suffix \notation{.pro} use: 806\begin{quote} 807\begin{verbatim} 808get_flag(prolog_suffix, Old), set_flag(prolog_suffix, [".pro"|Old]). 809\end{verbatim} 810\end{quote} 811 812%HEVEA\cutend 813