Debugging with Eclipse
Debugging allows you to interrupt Excel while it’s running your code by setting breakpoints, allowing you to step through the code and inspect variables.
A breakpoint in the source code specifies where the execution of the program should stop during debugging. Once the program is stopped you can investigate variables, change their content, etc.
Debugging support for Eclipse in Jinx
Jinx allows you to specify the Java options used when it initializes the JVM. These are set in the JAVA section of the jinx.ini config file.
Debugging with Eclipse requires the following JVM option to be set. When set, the JVM listens for debuggers trying to connect (attach) to it. You must set this option in your own jinx.ini file.
[JAVA]
java_opts = -agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n
The agentlib option has some additional parameters that control how the debugger will behave. For example, if you wanted to use a different port to connect Eclipse to Excel you would change the address parameter above. The default port used by Eclipse is 8000.
The debugger can suspend the JVM when starting by setting suspend=y. This can be useful if you don’t want any code to run before you have attached the debugger.
To set multiple Java options, put each option on a separate line in the config (as shown in the example jinx.ini file).
See the Configuration section of the user guide for more information about configuring Jinx.
Configuring Eclipse for Remote Debugging
Select the Run→Debug Configurations… from the workbench menu bar in Eclipse.
Right click on the Remote Java Application option on the left side and choose New, or you can click the New toolbar button.
In the Name section give the debugging configuration a name so you can identify it easily later.
The Connection Properties section of the Connect tab are what Eclipse will use to connect to the Excel process. Host should be localhost, and the Port should match the port that you set in your jinx.ini file as described above. By default it will be 8000.
In the Project field of the Connect tab, type or browse to select the project to use as a reference for the launch (for source lookup). A project does not need to be specified.
Press Apply to save the debugging configuration.
Start Excel and when you click Debug Eclipse will connect to Excel. If Excel was already running when you made the changes to your jini.ini file you will need to restart Excel (reloading the Jinx add-in is not sufficient after a change to the Java options).
Attaching the Debugger
Now you have the debugging configuration saved you can select it from the Debug button in Eclipse. If you have not yet run the new debugging configuration then you can go to Debugging Configurations and run it from there. After it has been run once it will appear in the list of recently used debugging configurations, and will be the default configuration to use when you press the debug button.
Before you can start debugging make sure Excel is running. If Excel was already running when you made the changes to your jini.ini file you will need to restart Excel (reloading the Jinx add-in is not sufficient after a change to the Java options).
With the debugger successfully attached Excel will be suspended whenever any of your breakpoints are hit, and you can debug your code in exactly the same way you would usually when debugging with Eclipse.
Rebuilding and Reloading
When you make changes to your project and want to test those changes out in Excel, you do not need to restart Excel.
Make sure you have the shadow_path set in your jinx.ini file (see Configuration). This copies all of your jar files listed on the classpath to a shadow folder, enabling the original jars to be overwritten when you rebuild your artifacts.
Once you have rebuilt your project artifacts you can tell the Jinx add-in to reload your jar files by selecting the Reload menu item from the Jinx menu, which you can find in the Add-Ins tab in Excel. If that tab doesn’t exist, right click on the ribbon and go to Customize the Ribbon, and in there you can add the Add-Ins tab to your ribbon.
