Eclipse Setup for Grails 1.1 Development
Overall I have enjoyed the development experience with Grails and I am excited about its future. I am a heavy Eclipse user so along with a number of folks in the community I have been a bit disappointed with the support in my favorite IDE. However, instead of letting that stop me I spent some time getting Eclipse to work better with Grails.
I realize that SpringSource is working to get better Grails support in Eclipse, but until then here are some tips and tricks that should help you have a more pleasant development experience. I break the setup instructions into the following:
- Eclipse Workspace Setup
- Import and Configure Grails Project in Eclipse
- Debugging Your Grails Application
- Resolving Eclipse Classpath Problems: Grails Project with Grails Plug-in Dependencies
- Running Grails Unit Tests in Eclipse
Versions I Used for this Setup
Eclipse 3.4.2
Grails 1.1
Groovy Eclipse Plug-in 1.5.7 (Eclipse Update Site: http://dist.codehaus.org/groovy/distributions/update/)
Basic Setup – Reference Material
The Grails Wiki offers some basic setup instructions for Eclipse/Grails development. These are helpful instructions to get you started but are lacking in areas. You can find these instructions at: http://grails.org/Eclipse+IDE+Integration. Although these are a bit dated, it provides a helpful reference.
Grails 1.1 Helpful Info – Where does Grails put my generated files and dependent artifacts?
I find it is helpful to know where Grails is generating all the artifacts necessary to compile, test, run, and deploy your application.
- Grails writes its files (including installed plug-ins) into your user home directory by default: {user_home)/.grails/1.1
- Downloaded/Packaged Grails Plug-ins are in {user_home)/.grails/1.1/plug-ins
- Grails app projects that are created via grails create-app <name> are found in {user_home)/.grails/1.1/projects directory. *This location has all the generated classes, plug-in artifacts, dependent jars for your application. This is important to know – as you will see – as there will be cases where you will have to modify the Eclipse classpath for your project in order to resolve compile errors in Eclipse.
Eclipse WorkSpace Setup
So you have Eclipse 3.4, the Groovy plug-in installed and a workspace created and ready to get going on starting development on a new Grails project. Where to start?
Before getting too far let’s prepare the Workspace for Grails development.
- Set your Windows->Preferences->Groovy Preferences.
Default Groovy compiler output location: bin-groovy
Check the option Disable Check Package Matches Source Directory
- Need the GRAILS_HOME Environment variable set. Goto Windows->Preferences->Java->Build Path->Classpath Variables ->New.
- That is it – for now!!
Import/Configure Grails Project in Eclipse
Here are the steps to follow to get a new Grails project into Eclipse:
- Open a command-line to the desired location you would like your Grails project to reside. Create your Grails project: grails create-app someAppName
- Within your Eclipse workspace’s Java Perspective:
Right-click in the Package Explorer and select Import
Select General->Existing Projects into Workspace
Choose the directory where you created the Grails project
Select the project *Do Not check the option: Copy projects into workspace
Click Finish
Grails does generate an Eclipse-friendly project for importing. However this is where “tweaking” is required to get Grails working effectively within Eclipse.
Overriding Groovy Project Properties
Now you must set the Groovy plug-in settings for your newly imported project. When Grails creates your project it sets some defaults that we must re-configure – this is one of them.
- Open the Project’s Properties
- Select Groovy Project Properties and do the following:
Default Groovy compiler output location: bin-groovy
Uncheck the option Disable Groovy Compiler Generating Class Files
Check the option Disable Check Package Matches Source Directory
- Apply the new property settings
You will notice that the project rebuilt, and generated Groovy classes are output to bin-groovy.
Create Grails External Tool
To avoid switching from Grails command-line to Eclipse you can setup an external tool configuration within Eclipse to run Grails commands and refresh the workspace resources automatically.
- Open External Tools Configurations
- Right Click Program and select New
- Name the Program Grails
- Enter the path to the Grails exe or script (eg: GRAILS_HOME/bin/grails.bat for Windows)
- Enter ${project_loc} in the Working Directory
- In arguments enter ${string_prompt}
- On the Refresh tab, check Refresh resources upon completion. Select the option The project containing the selected resource
- On the Common tab check the option to select display in favorites menu
- Done. Test this out by:
Selecting the project in the Package Explorer
Run the External Tool
Enter string: create-domain-class TestDomain
You should see a TestDomain.groovy file in grails-app/domain source folder.
Now you can run any Grails commands on your project to start generating your various artifacts!
You can use this same approach to setup any number of useful external tools for common Grails commands to further reduce command typing.
Debugging Your Grails Application
Let’s start with creating a Run Configration for the project. One nice thing is when Grails generated the initial project, it created “most” of what we need to setup a run configuration in Eclipse. We will have to tweak it a bit:
- Open Run Configurations
- Select Java Applications->{your project should be in the list}
- On Environment tab you have to add a JAVA_HOME and GRAILS_HOME environment variable.
- On Source tab add your Java Project for debugging purposes
- On Common tab Display in Run and Debug Favorites menus
- Apply and Done
- Test the run, by selecting the run configuration in the Run menu
- Verify the Grails app is running by looking at the Eclipse Console
- Browse to http://localhost:8080/<yourAppName>
- You see your app come up. Great!!
- Stop the application from Eclipse console.
Just to verify that you can debug your Grails project within Eclipse, let’s carry through with the example started in the previous steps.
- Open the TestDomain.groovy class and add a property – how about String testString. Save the file
- Select the project, and with the Grails External Tool enter generate-all TestDomain to generate all the wonderful Grails scaffolding for you domain
- Open the TestDomainController. Create a private method testDebug with a few lines code so you can set a breakpoint within this method. within the list closure call this newly created method
- Start the application in Debug mode – from the Debug Run configuration menu
- Open the application in the browser
- Select the controller link. You should be directed to the Eclipse debugger where it is stopped at your breakpoint.
Run Configuration VM Settings
There may be a need to override the VM settings configured for your Run Configuration. To change these settings, open the Run Configurations, select your Grails project run configuration, and navigate to the Arguments tab. From here you can change VM settings to change to common things such as max heap and perm size. Here is an example:
-Dbase.dir=”${project_loc:<your-project>}” -Dserver.port=8080 -Dgrails.env=development -Xms512M -Xmx768M -XX:PermSize=64M -XX:MaxPermSize=128M
Project Source Directories for Easy Navigation
Sometimes I add directories to the project source directories allowing me to more easily navigate to key areas of my Grails project. Some directories I add are:
- grails-app/views
- web-app/js (JavaScript files)
WARNING: Be careful not to place any groovy or java files in these source directories as Eclipse will pick them up as part of your runtime classes (small price to pay for easier navigation).
Resolving Eclipse Classpath Problems: Grails Project with Grails Plug-in Dependencies
I ran into this issue when I had a Grails project that depended on the Grails Acegi (Spring Security) Plug-in. When working with the project in Eclipse I was getting all sorts of compile problems until I found a way to make Eclipse’s classpath happy so I could continue using Eclipse for Grails development.
Grails Acegi 0.5.1 Plug-in and Eclipse
Let’s say you have a Grails project that uses the Acegi plug-in for security, and has generated security controllers and domain classes – as per the Acegi plug-in instructions. When the Grails project is brought into Eclipse you will notice all sorts of compile errors.
This will force you to modify the Eclipse classpath to resolve these errors. Make sure that any entries you add to the Eclipse classpath are not exported for dependency projects in Eclipse (see screen shot below). Here is how it is done:
- Remember that Grails 1.1 manages your project’s artifacts in the directory {user_home)/.grails/1.1/projects.
- In order to resolve Acegi plug-in errors add the following to your project’s Java Build Path->Libraries (you may not need all of these):
- {user_home)/.grails/1.1/projects/{your project}/classes. *Important: The “grails compile” may have to be performed periodically to refresh the classes in this directory.
- {user_home)/.grails/1.1/projects/{your project}/plug-ins/acegi-0.5.1/lib/spring-ldap-1.2.1.jar
- {user_home)/.grails/1.1/projects/{your project}/plug-ins/acegi-0.5.1/lib/spring-ldap-tiger-1.2.1.jar
- {user_home)/.grails/1.1/projects/{your project}/plug-ins/acegi-0.5.1/lib/spring-security-cas-client-2.0.4.jar
- {user_home)/.grails/1.1/projects/{your project}/plug-ins/acegi-0.5.1/lib/spring-security-core-2.0.4.jar
- {user_home)/.grails/1.1/projects/{your project}/plug-ins/acegi-0.5.1/lib/spring-security-core-tiger-2.0.4.jar
- {user_home)/.grails/1.1/projects/{your project}/plug-ins/acegi-0.5.1/lib/ spring-securityntlm-2.0.4.jar
- {user_home)/.grails/1.1/projects/{your project}/plug-ins/acegi-0.5.1/lib/spring-security-openid-2.0.4.jar
That should be it! Your compile errors go away and you can continue to use Eclipse with your Grails Project.
Other Classpath Issues with Plug-ins
A similar technique can be applied to resolve other classpath inconsistencies between Eclipse and Grails that you run across.
Running Grails Unit Tests in Eclipse
Since you specified to generate groovy class files to a directory (ie: bin-groovy) that should be enough to run Grails unit tests in Eclipse. Running unit tests from eclipse is a lot faster than running them from the command line, because eclipse will generate the class files needed as you develop. It’s really nice to have.
Grails integration tests require the Grails environment to be loaded and therefore must be executed via the Grails command line or via the Grails external tool you created in Eclipse. I find the external tool, with automatic refresh does the job just fine for integration tests.
One step I left out (or at least implied) in order to run unit tests in Eclipse. You need to ensure that your project’s bin-groovy directory is on the Eclipse project’s classpath.
This will allow you to make changes to your groovy files in Eclipse, compile changes are made in bin-groovy and groovy unit tests can be re-run with these changes.
A post that details these unit testing steps further can be found at: http://www.objectpartners.com/2009/02/16/unit-testing-grails-in-eclipse/
I followed your instructions on
Eclipse 3.4.1 on Ubuntu 9.04 with Java 6
so maybe some other Ubuntu people will find this helpful
————
comments to “Versions I Used for this Setup”
I used
http://dist.codehaus.org/groovy/distributions/updateDev/
which seems to have Groovy 1.6
————
comments to “Eclipse WorkSpace Setup”
I have Ubuntu and used http://code.google.com/p/ant-deb-task/ to get a debian package
using your linux console you can find out where grails is installed.
$ grails
Grails home is set to: /usr/share/grails
I had problems with enviroment variables so I used a lot of global paths
————
comments to “Create Grails External Tool”
I had problems with my JAVA_HOME so I set it manually in the environment tab of the External-Config, and set it to “replace native …”
My grails command was not set to executable so I followed http://jamesladdcode.com/?p=97 not sure if this is a wise idea, but it got we forward
/usr/share/grails/bin$ sudo chmod +x grails
so the command is
/usr/share/grails/bin/grails
————
comments to “Debugging Your Grails Application”
I asssume we have the same limitation like in NetBeans6.7 that we can’t set breakpoint in closures and step throug them, right?
————
comments to “Resolving Eclipse Classpath Problems: Grails Project with Grails Plug-in Dependencies”
I skipped this, for the moment, but we are using this plugin too, so it seems I will come back to this soon.
————
comments to “Running Grails Unit Tests in Eclipse”
I had the problem that Eclipse complained the bin-groovy is not in the classpath. I added it manually in the “configure build path”->”Libraries Tab”->”Add Class Folder Button”
————
Result: Ready for Mylyn + Grails
I am wondering if you have tried or had success in debugging grails integration tests within eclipse, or seen and reference regarding how to do this. Unit tests can be debuged with no problem. For integration tests, I have only seen references to running grails-debug from the command line and then attaching an eclipse debugger.
Running Grails Integration Tests in Eclipse
Although not ideal IDE integration, by setting up a Run Configuration for your Grails project in Eclipse, you will be able to run and debug Grails integration JUnit tests within Eclipse. Here is how:
– Open Run Configurations
– Select Java Applications->New
– On the Main tab:
Project: Select your Grails project
Main class: org.codehaus.groovy.grails.cli.support.GrailsStarter
– On Arguments tab:
Program args (Including the quotes):
“test-app ${string_prompt} -integration”
VM Arguments: -Dgrails.home=${grails_home}
-Dbase.dir=”${project_loc:}”
-Dgrails.env=development -Xms512M -Xmx768M
-XX:PermSize=64M -XX:MaxPermSize=128M
– On Classpath tab
User Entries add your project
User Entries add all $GROOVY_HOME/dist and
$GROOVY_HOME/lib jar files (to be safe)
– On Source tab add your Java Project for debugging purposes
– On Environment tab you have to add a JAVA_HOME and
GRAILS_HOME environment variable.
– On Common tab Display in Run and Debug Favorites menus
– Apply and Done
Try it out. Let’s say you have integration tests for a controller called SomeController. When you run this new run configuration, when prompted type in SomeController. The results of test will be shown in the console and the test report will be generated in /test/reports (you will have to manually re-sync to refresh the reports.
Now try setting a breakpoint in a test within the integration test case for SomeController. Now run the debug configuration version of the setup you did above. Again, when prompted enter SomeController. Eclipse should stop at your breakpoint. Now you can debug your integration test within Eclipse without having to manually setup a remote debugger.