Quickstart Guide: FusionDebug for Railo

This document should get you up and running with FusionDebug for Railo 3.1 (or higher)

Minimum Software

In order to start debugging Railo, you will need to download the following external components:

• Eclipse – You should download the Eclipse IDE for Java Developers (this contains all the components required for FusionDebug). Eclipse is a software framework that isn’t just for Java – you can use it for ColdFusion too. The package can be found here.

• Railo – You should download a build of Railo Express, available here.

• FusionDebug for Railo – Install/Update Package for Eclipse – This is available here

• Replacement Railo Express start scripts – These scripts run Railo with Java Debugging enabled – required for FusionDebug to connect to Railo. There is a replacement start.bat for Windows, and a replacement start for Mac OS X. They are available here. The replacement scripts instruct Java to start listening for FusionDebug on port 8000. *If your port 8000 is already in use, you can change this value by editing the startup script, but don’t forget to change it later when you create a Railo launch).

Installation

Railo Express

Railo Express doesn’t have an installer and must simply be unpacked to wherever it is required. Once unpacked, locate the appropriate start.bat file (or start for Mac OS X) and replace it with ours.

For the examples coming a little later, we assume you have unpacked Railo into the folder:

• c:\ railo-3.1.0.012-railo-express-6.1.0-3-1-with-jre-windows

Check that Railo starts up using your script. You can leave it running for now.

Eclipse

Eclipse also doesn’t have an installer; simply unpack it into wherever you would like it to live.

When you start Eclipse for the first time, it will ask you to locate a Workspace. This is where new projects will be created by default, and where Eclipse will store some configuration information.

If you have existing projects, Eclipse can be set up to use them wherever they are – they don’t need to be in the Workspace.

Once you have selected a Workspace, Eclipse will start up into the Welcome perspective.

Install FusionDebug into Eclipse

• Inside Eclipse, click on Window -> Open Perspective -> Debug to activate the debugging tools.
• Click on Help -> Software Updates to open the Eclipse P2 Software Updates and Add-ons manager.
• Select Help -> Software Updates -> Find and Install. This will bring up the Install/Update dialog.
• Select “Search for new features in Install” and click Next.
• Select “New Remote Site”. You will see a new dialog
• Enter the following information:
  • Name: FusionDebug Update Site
  • URL: http://www.fusion-reactor.com/fd/fd3update/
• then click OK.
• In the Install/Update dialog, ensure the FusionDebug Update Site is checked, then click Finish.
• The update manager will connect to fusion-reactor.com and locate the plugin. Once found, a new dialog will appear. Place a check mark against the “FusionDebug Update Site” and click Next.
• After you have read and accepted the terms and license agreement, click Next.
• Finally, click Finish to complete the process. When the Feature Verification dialog appears, click Install All.
• Eclipse will ask if it should restart the Workbench. Answer Yes and the workbench will be restarted.

FusionDebug is now installed.

First Session with FusionDebug

Let’s create a useful Debug perspective within Eclipse.

• Eclipse should restart already in the Debug perspective. If not, click on Window -> Open Perspective -> Debug to activate the debugging tools.
• The Debug perspective can be customized to make it a bit more useful than it is right out of the box:
  • Close the Outline view by clicking the X icon on the tab.
  • Add the Project Explorer view to the perspective by clicking Window -> Show View -> Other…, then open General and select Project Explorer. Click OK.
  • Eclipse adds the Project Explorer tab to the lower set. This isn’t much use. Grab the Project Explorer tab and drag it to the left of the central empty space. Eclipse ghosts the region where it will appear. When the ghost rectangle is located where you would like the Project Explorer, release the mouse. The view should then re-open in the new location.

• Ensure FusionDebug is installed by clicking Window -> Preferences. You should see a FusionDebug preference item. Close the preferences window by clicking OK.

Now we should tell Eclipse where our project is. For simplicity, we’ll use the Railo web root as a project. Then any files we create will automatically be created within the Railo web root.

• Right click inside the Project Explorer and select New -> Project. In the New Project wizard, open General and select Project. For the Project Name, enter “Railo Webroot” and uncheck the Use default location checkbox. We don’t want to create a new project in the Workspace.
• Use the Browse button to navigate to the webroot folder within Railo Express. If you unpacked Railo as mentioned above, this will be:
  • C:\railo-3.1.0.012-railo-express-6.1.0-3-1-with-jre-windows\webroot
• Click Finish. You should see that Eclipse has found the existing webroot, and it contains only the default Railo index.cfm.

• Open the default index.cfm file by double-clicking it. If another application opens the file (perhaps because .cfm is associated with another application), you can open the file within Eclipse by either:
  • dragging it into the gray editor area, or
  • right-click the file and select Open With -> Text Editor
• Make sure you can run the index file in a browser. With Railo Express started, navigate to *http://localhost:8888/index.cfm* … you should see Railos colorful default dump page.

Now the file is open in Eclipse, we can try to debug it. We first need to set up a Debug Configuration. This is a FusionDebug configuration specific to the server you want to debug.

• On the Eclipse toolbar, you can see a small green bug icon with a black down-arrow. Click the arrow and select Debug Configurations.
• Right-click on the FusionDebug icon and select New
• Give the configuration a useful name: Railo 3.1.0 on Localhost (for instance).
• In the Connect tab, ensure the details are correct – in particular the port (if you changed it earlier in the start script) and the checkbox for the server type. Leave it checked for Windows, unchecked for Unix.
• We have to tell FusionDebug how to map pages that run on the server to the projects in our Project Explorer view. Click on the Source Code Lookup tab.
• Since we only have one project, we can use the default <All Projects> mapping. In the upper area, enter the path to the Railo webroot (in our example this was C:\railo-3.1.0.012-railo-express-6.1.0-3-1-with-jre-windows\webroot), and click Add. Now click Apply.
• With the Debug Configurations wizard still open, click Debug.

If all has gone well, you should see FusionDebug (localhost:8000) (Connected) in the Debug view.

Let’s put a breakpoint in the page. Execution will stop when it hits a breakpoint.

• Find the line (it’s line 21) that says <cfdump var=”#test#” label=”test”> and left click to put the cursor on it.
• Now right-click on that line and select Toggle Line Breakpoint.
• You should see a small blue circle appear in the gutter margin. If you select the Breakpoints tab, you should see an entry describing it too – along with where FusionDebug thinks the exact file is on the server.
• In a browser, run the index.cfm page again.

Execution halts on the breakpoint.

• If you switch back to Eclipse, you can see:
  • The Debug view shows a stopped thread (probably named btpool0-something), with the index.cfm page, the line number and the project file.
  • The Editor has highlighted the line.

Let’s look at the Variables view.

• Click the Variables tab to bring the view into focus. This view is showing all the active CFML scopes.
• You can see that the three lines above where we’re stopped set three variables in three different scopes.
• Open these scopes (variables, url and form).

You can inspect any expression without locating it in the Variables view first.

• In the editor, select the text url.test, then right-click and select Inspect Expression.
  • A small dialogue should open with the result of the expression: “Hallo URL”.
  • If you instead see (not visible), Railo couldn’t work out what you wanted to inspect – check you’ve selected the exact text url.test.

Stepping. You can now step the page in three ways. Stepping executes one instruction at a time.

• The step functions correspond to the three yellow arrows at the top of the Debug view.
  • The first is Step Into. If you were on a statement which called another CF page (e.g. CFC method invoke, or cfinclude), Step Into will take you into that page.
  • The second is Step Over. This will execute the instruction under the cursor and go to the next one, but it won’t descend into any CFCs, UDFs or CFIncluded pages.
  • The third is Step Return. If you found yourself within a UDF, CFC or CFIncluded page, this step would execute all the remaining script within the UDF/CFC etc., and return you to the calling page.
• Try it out by clicking Step Over (the middle arrow) a few times: you can see execution advance, line by line, while variables are updated in real time.

If you step all the way to the end of the page, you’ll see the page complete and it will disappear from the Debug view. If you don’t want to wait, click the green Resume arrow at the top of the debug view. Provided no further breakpoints are hit, the page should complete.

When you are ready to finish your debug session, right-click on the name of the configuration in the Debug view (“Railo 3.1.0 on Localhost”, if you used our example) and select Disconnect.