SMILA/Documentation/Scripting/Debugging

Debugging JavaScripts Running in SMILA

You can use the Eclipse JSDT Debug tools to connect to a SMILA process and debug the JavaScripts.

Enabling Debugging Support

Support for the JSDT debugger must be enabled at program start using system property smila.scripting.debug, for example:

SMILA -Dsmila.scripting.debug=transport=socket,suspend=n,address=9000

See JSDT/Debug/Rhino/Embedding_Rhino_Debugger#The_Connection_String for the full description of this string. The short version:

• address: The port number to open for the debugger to communicate on. No error will occur or be logged if the port is already in use.
• suspend: When set to y or true the scripting service will wait for a debugger to connect when initialized. However, as this happens during activation of a Declarative Service, which is limited by a timeout in the DS runtime, an error will occur if you do not connect a debugger within 30 seconds. Thus, suspend=n is usually the better choice.
• transport: Must be set to socket.

Setting up the Debugger

• Make sure that the "JavaScript Development Tools" are installed in your Eclipse installation (Use "Install New Software" from Menu "Help". We tested this with version 1.6.)
• Create a launch configuration for the debugger:
  • Go to "Run" -> "Debug Configurations..."
  • Create a new configuration under "Remote JavaScript". As Connector, select "Mozilla Rhino - Attaching Connector" and enter the SMILA host (e.g. "localhost") and the port you configured above (e.g. 9000).
• Click "Apply" and "Close".
• Check the preferences of the "JavaScript Debugger":
  • Go to "Window" -> "Preferences..."
  • Select "JavaScript" -> "Debug".
  • You may want to enable the option "Suspend for all script loads" so that the debugger stops the script execution immediately when a script is loaded.

Using the Debugger with Scripts Available in Workspace

This should work if you have the scripts running in SMILA available in the workspace, e.g. by having the SMILA.application project from the source code open. So this should be the usual way to work within the SMILA development environment.

• Start SMILA with debugging enabled (see above).
• Start the debugger by using the "Remote JavaScript" configuration you created above.
  • Disable the "Suspend for all script loads" option in the "JavaScript Debug" preferences, at least for the time being.
• Open the script to debug and set a breakpoint (just like setting breakpoints in Java files: double-click in the grey column at the left hand-side of the editor).
• Execute the script (e.g. invoke it via http://localhost:8080/smila/script/<script>.<function>).
• Eclipse should switch to the "Debug" perspective (it may display a dialog asking you to confirm the switch).
• The editor should show a copy of the script to debug and the line in which you have set the breakpoint should be marked. You can set additional breakpoints in both versions of the script. However, changes to the script must be done in the original version in SMILA.application.
  • The script copy will be part of a new project "External JavaScript Sources" in your workspace. You can safely delete this project when you are finished with debugging (there is even a preference option so that Eclipse will remove it automatically when you exit the workbench).
  • If you change the original script used by the SMILA process, you must delete the script copy from the "External JavaScript Sources" project so that the changes are reflected next time you debug this script.
• Use the debugger just like when debugging Java code.

Using the Debugger from a Completely Different Workspace

You can use the debugger even without the original scripts the workspace. This may be helpful to debug a remote server.

• Start SMILA with debugging enabled (see above).
• Start the debugger by using the "Remote JavaScript" configuration you created above.
  • Enable the "Suspend for all script loads" option in the "JavaScript Debug" preferences.
• Execute the script (e.g. invoke it via http://localhost:8080/smila/script/<script>.<function>).
• Eclipse should switch to the "Debug" perspective (it may display a dialog asking you to confirm the switch).
• In the "Debug" view a line like this should be marked: "Thread [Rhino 1] (suspended loading script: file:/....)"
• Press the "Step into" button in the toolbar. An editor window with the invoked script should open with the "function ..." line marked.
  • This script is part of the "External JavaScript Sources" project created by the JavaScript debugger in your workspace. You can safely delete this project when you are finished with debugging (there is even a preference option so that Eclipse will remove it automatically when you exit the workbench).
• You should now set a breakpoint in this function because the "Suspend on load" will not happen anymore until the script is changed in the SMILA installation.
• Use the debugger just like when debugging Java code.
  • If you change the original script used by the SMILA process, you must delete the script copy in the "External JavaScript Sources" project so that the changes are reflected next time you debug this script.