What is the Source Code Lookup tab?
The Source Lookup tab is used to tell FusionDebug where the source files in your Eclipse projects are placed on to your CF server.
FusionDebug uses the source code lookups to tell the CF server where to set breakpoints and to tell Eclipse which source code to display when a breakpoint is hit. Breakpoints are set within Eclipse but must also be transferred to the CF server for them to become active.
By configuring your Source Code Lookups, FusionDebug can support multiple Eclipse projects, mapped CFCs, include files and provide support for the various frameworks that can be used with CF.
What is a lookup?
Often, the structure of the files in your Eclipse projects are not the same as the structure when deployed to your CF server. This leads to the problem that FusionDebug is unable to work out which files in Eclipse relate to which files on your CF server. This problem is solved by creating Source Code Lookups in your FusionDebug configuration. Each lookup consists of an Eclipse project path and the absolute path to the folder on the CF Server that contains the same files.
If you take the Eclipse Project/Folder paths and absolute CF server paths from the above example then your Source Code Lookups will look like this:
How do I find the Source Code Lookup tab?
There are two ways to get to the Source Code Lookup tab. Firstly, you can open the Run menu and then select the Debug... item.
Alternatively, you can go to the little green debug icon in your Eclipse toolbar and click the small arrow on its right-hand side. This brings up a small menu and you can select the Debug... item from there.
Once the debug dialog is visible you can bring up the Source Code Lookup tab by opening the FusionDebug item and clicking on an existing debug profile, or by right-clicking on the FusionDebug item and selecting New from the menu.
How do I use the Source Code Lookup tab?
The Source Code Lookup tab is split into two main sections. The top section allows you to add or modify lookups.
The bottom section lists all of the lookups currently configured.
To add a lookup, first select an Eclipse project and optionally a folder within that project. Next, type in the file path of the folder under your CF server that you want to associate with this Eclipse path. (This is the actual path on the server itself, not the URL which you would type into a browser.)
Example configurations
Single Machine Setup
The simplest configuration of FusionDebug would be if you had set up your Eclipse workspace to be the same as your CF webserver root. You would be editing the same files that are being served and you would only need a single lookup.
Remote Debugging Setup
If you copy your project source files directly to a remote server without changing the structure then the configuration is equally simple. You create a single lookup from your Eclipse project to the CF webserver root on that machine.
Multiple Project Setup
Lets say that you have an application which uses a tag library. In Eclipse that tag library is a separate project which has two folders within it. On the webserver, the contents of both of these folders end up in a single folder called "tags". You would need three lookups in this case. One from your application project to the CF webserver root and then another two from each folder in the library project to the "tags" folder.
CF Mappings Setup
From the CF Administrator you can set up Mappings. These allow you to store cfm code in any folder on your server. They can then be referenced within your CF pages by using their logical path. To debug these files you need to add a lookup to the directory path specified in the CF mapping.
Alternative Webserver Setup
For simplicity, all of the examples so far have used the CF internal webserver. This doesn't mean that you can't use other web servers. Below is an example of a lookup for IIS:
Below is a lookup for Apache:
Both of the above examples use the default directory for each webserver but you can also configure these webservers to use any folder (Virtual Directories). In this case you can just create a lookup to that folder:
Linux and UNIX Setup
For simplicity, all of the examples so far have used a CF server on a Windows machine but FusionDebug can also debug CF servers running on Solaris and UNIX systems. Below you will see a lookup to a UNIX machine running Apache.
NOTE: You must tell FusionDebug when you are debugging a Linux or UNIX system. To do this, go to the Connect tab (next to the Source Code Lookup tab) and uncheck the item which says "CF Server is on Windows (uncheck if the CF Server is on Linux or Unix)".
ALSO NOTE: The paths you enter into your lookups on UNIX systems must not include symbolic links. In the case where you are using a path with a symbolic link in, please use the full path instead.
Why are my breakpoints not active?
If you look at the breakpoint view in Eclipse and see something like this:
In this case, you need to check your lookups in the Source Code Lookup tab. What this error is telling you is that, although you have told Eclipse that you want to set a breakpoint, FusionDebug couldn't work out which file on your CF Server to actually set that breakpoint in. Go back to the Source Code Lookup tab and make sure that your project is associated with the correct folder on the server.
Why is FusionDebug unable to display my source code?
If you step into a file while debugging and instead of seeing your source code, you see something like this:
then you need to check your lookups in the Source Code Lookup tab. What this page is telling you is that the server stepped into a file but FusionDebug couldn't work out which file in your Eclipse projects was associated with the one on the server. There are two possible reasons for this:
- The project containing the source file is closed: If you read through the page, it will tell you which lookups it tried and will also let you know if you have any closed projects. FusionDebug cannot show source code from closed projects. Make sure all related projects are open.
- You are missing a mapping or have an incorrect lookup. At the top of the page you will see a button which will take you directly to the Source Code Lookup dialog. If you click on this then you will see that the CF Server Folder has already been filled out. All you need to do is enter the Eclipse Project/Folder information and you can add a new lookup.
For more information...
With this mechanism, FusionDebug is able to support very complex development environments by simply adding as many lookups as required. For more detailed information about the new Source Code Lookup mechanism, please refer to the FusionDebug User Guide.
