GOAL-Eclipse Quick Start Guide

Created by Wouter
Last updated: Jun 21, 2021 by Vincent Koeman

This page contains a short guide on developing GOAL projects by using the Eclipse plug-in.

Installation

See Download and Install GOAL.

First use

  • After having installed the plug-in, a new 'GOAL Perspective' is now available. Switch Eclipse to this perspective for the first time through 'Windows -> Open Perspective -> Other -> GOAL'. A shortcut will be placed in the top-right corner.
  • We recommend changing the following preferences in Eclipse ('Window > Preferences'):
    • General > Workspace: (1) Refresh using native hooks or polling > Enable (2) Text file encoding > Other: UTF-8.
    • Install/Update > Automatic Updates > Automatically find new updates and notify me > Enable.
    • Run/Debug > Console > Console buffer size (characters) > Set to 999999 (the maximum).

Please note that if you are having performance issues whilst debugging, e.g. with many agents, the console buffer size can be reduced. The consoles for each agents and/or the action history can even be entirely disabled in the 'GOAL > Logging' preference category, where the logging itself can be fully tweaked as well.

Projects and Files

  • Create a new GOAL project through: 'File > New > GOAL Project'. You can also right-click in the 'Script Explorer' to get the same 'New' menu. Enter a project name in the following dialog, and optionally select an existing environment file (.jar) to automatically import into the project. A mas2g file (optionally containing a reference to the specified environment file) will be automatically created in the new project.
  • Import an existing GOAL project through 'File > Import > GOAL Agent Programming > Existing GOAL Project'. Select the relevant mas2g file in the next step, and optionally copy the files into your workspace (the default is just to create a link to them).
  • Create a new file by either using 'File > New' or 'Right-click on your project in the Script Explorer > New'. In the resulting menu, you can select any of the relevant types to create (.mod2g module, .act2g actionspecification .pl knowledge representation, .test2g test, .mas2g MAS, folder), after which you will be asked for a name.

Editing

  • Any errors and warnings will be displayed at their actual location (red or yellow underline). A marker will also be placed in the sidebar, and an item will be added to the 'Problems' tab at the bottom. A full (MAS-level) validation will be performed when saving any file (as opposed to local checks whilst editing).
  • Auto-complete is available through the default 'CTRL+Space' keyboard shortcut.
  • Comments above predicates will be processed and available when hovering on a predicate with the same name.
  • A browseable outline of the current file (in which warning or error markers are also shown) is available in the bottom-left corner.
  • Blocks of code or comments can be folded by using the controls (+/-) in the editor's sidebar.

Running

  • To run a project, any of the following actions can be taken:
    • Right-click on a file or project, and select 'Run As > GOAL'. If this is a .mas2g or .test2g file, or if there is only one such file in the project, this file will be run. Otherwise, you will be asked for the .mas2g or .test2g to run.
    • Use the Run icon in the menu.
  • When running a file, a console (at the bottom of the screen) will be allocated for the output. At the top-right corner of the console, actions like terminating the run are available. You can search in any console as well ('Right click > Find/Replace' or 'Left click > CTRL+F').

Debugging

Debugging has been fully integrated for MAS projects ('.mas2g' files) into Eclipse.

  • To debug a MAS, any of the following actions can be taken:
    • Right-click on a file or project, and select 'Debug As > GOAL'. If this is a .mas2g, or if there is only one such file in the project, this file will be run. Otherwise, you will be asked for the .mas2g to run.
    • Use the Debug icon in the menu.
  • Code stepping is supported for agents that are paused. Three different stepping actions are available:
    • Step Into (F5): Step to the next evaluation point. By default, you will step to the next rule, action, or module that will be executed. The precise evaluation points that are used can be fine-tuned to your own preferences using the 'Window > Preferences > GOAL > Runtime' menu.
    • Step Over (F6): Jumps to the next module or rule and does not show any intermediate steps (of course, all code is evaluated as usual at all times). For example, if the event module is selected, selecting stepping over will jump immediately to the main module without showing any intermediate (evaluation) steps that are performed in the event module. Note in particular that stepping over the main module will have the agent perform a whole cycle; stepping therefore returns again to the main module. Check the Introspector window to see what has changed.
    • Step Return (F7): Skips the remainder of the module the agent is currently executing. Of course, this only influences the stepping process itself. Also note that doing this whilst in the main module will make an agent complete its current cycle.

Code stepping inside a module depends on the rule evaluation order that is used in that module. For example, in the event module that by default uses the linearall order, stepping into will step from one rule to the next rule and exit the module only after having finished the evaluation of the last rule. In the main module that by default uses the linear order, stepping into will step from one rule to the next until a rule that is applicable has been found; after applying this rule the module is left. In a module that uses the random order, a rule that is applicable is randomly selected; code stepping thus does not need to start with the first rule! Finally, also note that a module may be re-entered immediately again if an exit option different from 'always' has been set.

  • Breakpoints: breakpoints can be set at any time in any file (before or during debugging, in any of the two GOAL perspectives). This can be done by double-clicking in the sidebar at the relevant line. This will first make a line breakpoint, indicated by a red icon. This will make an agent pause at all times when reaching a statement at that line. Double-clicking the same breakpoint will turn it into a conditional breakpoint, indicated by a yellow icon. This will make an agent pause at that line only when the related condition holds (at least one instance of it is true). Double-clicking on a conditional breakpoint will remove the breakpoint again. An overview of breakpoints that have been set can be found in the Breakpoints tab in the top left window. Note that breakpoints are not saved when you quit Eclipse.
  • Debug Perspective: When debugging, Eclipse will automatically switch to the GOAL Debug Perspective, and place a shortcut to this perspective in the top-right corner (if it was not there yet). If you use the GOAL Debug Perspective for the first time, you will be asked if you want to open it. You should select Remember my decision and Yes in order to debug properly. The debug perspective contains the following elements:
    • MAS Overview: At the top left, an overview of the current MAS and its agents is shown in the Debug tab. Each agent has its own item listed under the GOAL Debugging Engine node. These items show the current running state (running, paused or killed) of each agent between square brackets after the agent's name and the current line number code position where execution is at (if applicable). Selecting an agent in this Debug tab influences the content of all other views, and the effect of a selected action in most cases also depends on the agent that has been selected as well. Selecting the GOAL Debugging Engine results in all selected actions being performed by all agents automatically (e.g., stepping will affect all agents).
    • Code Stepping Window: In the window centered to the left below the overview of a MAS, the code of the agent that is selected is shown. If the agent is paused, the code line that the agent is at is highlighted. Stepping will proceed from that point on. Please note that editing files is not possible during debugging, but breakpoints can be changed at any time (see also above).
    • Console Area: At the bottom left, a general Console and a tab per agent is available. The general console contains output from GOAL and the environment, and each agent tab contains a log of its cycles and the actions it performed.
    • Introspector: At the top right, again depending on the currently selected agent, information about the agent's beliefs, goals, percepts and mails is available (sorted alphabetically) when the agent is paused. Note that searching is possible in all of these bases ('Right click > Find' or 'Left click > CTRL+F').
    • Evaluation Window: Below the overview of the agent's bases, the current evaluation is shown when an agent is paused. What is shown depends on the current agent's code position and provides information related to code stepping as discussed above. More concretely, the window shows for which variable instances a rule condition holds (if any), or it shows whether a precondition of the selected action holds or not. Using 'Right click > Find' or 'Left click > CTRL+F' this view can also be searched.
    • Interactive Console: At the bottom right, an interactive console is available. Here, queries can be posed that will be 'answered' by the currently selected agent. For example, a query 'bel(me(X))' will return the name of the agent. Also, actions are automatically recognized (e.g., 'insert(test(123))'. Note that this is only possible when an agent is paused.
    • Watch Expressions: By opening the Expressions tab and adding a new expressions, queries can be added (just like in the interactive console) that will be continuously evaluated for all agents. In this way, specific elements of an agent's mental state can be inspected, even when the agent is running.

Troubleshooting

Note that we have a Q&A site available at https://goalapl.atlassian.net/wiki/display/GOAL/questions/all. We also have a GOAL Service Desk (requires registration first). The following steps troubleshoot most problems:

  • Reset the GOAL and/or GOAL Debug perspective(s) by selecting 'Window > Reset Perspective' when the perspective is opened.
  • Restore the default GOAL preferences through 'Window > Preferences > GOAL > Logging > Restore Defaults > Apply', and do the same for the 'Runtime' category.
  • Follow the 'First use' section above.

In addition, make sure you do not use any special characters in file paths, as this interferes with the debugging engine.

Further documentation

For more extensive documentation on the GOAL programming language itself or the use of the Eclipse plug-in (including debugging and testing), see the GOAL Programming Guide and the GOAL-Eclipse User Manual.