Debugging Liferay in Eclipse

When should you use a debugger during development? At ALL times! At least that's my view.

Isn't that a hassle? Well debugging sure can be, but if you setup your environment in a specific way, it can actually become very fast and almost transaprent. I like transparent!

Here are steps I take to configure my tomcat (I've followed the same steps with JBoss):

1. Note the deployment path of tomcat (in my case I'll use /bundles/tomcat-6.0.x)
2. In Eclipse, open the "Run Configurations" manager (Run -> Run Configurations...)
3. On the "Java Application" node, right click and choose "New".
4. On the first tab (Main) select the project you are running in tomcat
5. In the Main Class field enter org.apache.catalina.startup.Bootstrap

6. On the Arguments tab, in the Program Arguments field enter start
7. In the VM arguments field enter the following:
   
   -Xms1024m
-Xmx1024m
-XX:PermSize=128m
-XX:MaxPermSize=256m
-XX:+CMSClassUnloadingEnabled
-Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=true
-Dcatalina.base=/bundles/tomcat-6.0.x
-Dcatalina.home=/bundles/tomcat-6.0.x
-Djava.io.tmpdir=/bundles/tomcat-6.0.x/temp
-Dexternal-properties=${workspace_loc:portal}/portal-web/docroot/WEB-INF/src/portal-developer-tomcat.properties
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
-Djava.util.logging.config.file=/bundles/tomcat-6.0.x/conf/logging.properties
   
   You many notice that I included a reference to my portal project's portal-developer-tomcat.properties file. This way I can change portal settings and only need to restart the portal without a redeploy, which is very convenient.
   
   You may also notice that I included tomcat's juli log manager so that all the normal web app configurations work as expected and in the Eclipse console, which is also very nice.
   
   Adjust your heap settings as desired, but the above settings have worked for me in 99.999% of cases.
    
8. In the Working directory field choose "Other" and enter /bundles/tomcat-6.0.x/bin. Notice that this is the tomcat path, plus the /bin folder.
9. The JRE tab should be already set properly, but you can choose any JRE that is installed that is 1.5+.
10. On the Classpath tab, remove any entries under User Entries and then choose "Add External JARs...".
11. Select the 3 jars located in /bundles/tomcat-6.0.x/bin.
12. On the Source tab make sure that you have both Default, as well as your project in the list.
    
    Optionally here you can add any plugin projects that you are working on, as well as adding the path to the jsp java classes (typically /bundles/tomcat-6.0.x/work/Catalina/localhost/_)
13. On the Common tag choose at least Debug and Run under "Display in favorites menu".
14. Click "Apply" near the bottom of the dialog.
15. Finally, to start the portal in debug mode, click the Debug menu in the Eclipse toolbar, and choose the run config you jsut created.
    
    You should see at this point output on the Eclipse console showing that tomcat is starting up.

I've been using this techinque for at least 3 years and I run the portal this way 99.999% of the time. By doing so, I can at any point in time add a breakpoint and start trouble shooting and I don't have to worry about re-connecting to or restarting the portal in debug mode, I know it's already done.

If you want to add any other java apps this way, the simples technique is to first run the app in the traditional way, then observe the process log to see what the full command that was actually used to start it, and from where. Once you know that, you can add any app to Eclipse Run Configuration.