Last updated by 5 years ago

Page: Eclipse IDE Integration, Version:8

Eclipse IDE Integration

Importing a Grails Project

Grails automatically creates Eclipse project and classpath files for you. The Groovy plugin is helpful for working with Grails projects, but not required in order to import a project: do not rely on it for assistance.To import a Grails project just right-click in the "Package Explorer" and select "Import" then "Existing project into Workspace" and "Browse" to the location of your project.

Then immediately click "Ok" followed by "Finish" and your project will be set-up. Using other methods of importing the project may prove to be problematic due to compile location.

There is a known issue that Grails will not run properly if you try to use the root directory of your drive as your project, or paths with spaces.

Setting up Eclipse Environment Variables

You will need to create an Eclipse classpath variable called GRAILS_HOME that points to the location where you installed Grails for the project to build successfullly by going to Windows -> Preferences… -> Java -> Build path -> Classpath Variables -> New.

If you don't already have GRAILS_HOME as part of your standard environment, in order to run your Grails project, you will need to establish that value in the Run dialog (Run...) under the Environment tab, to the same value as above.

If your Grails project has Grails plugins installed then you will need to add the directories directly under the plugins/src/ folder to your Eclipse source path. This is done through right clicking on the folder (usually called "Groovy" or "Java") then selecting build path -> source folder. Otherwise you may get errors in the import statements.

Also, if you are using JSP you will need to add your JDK's tools.jar library to your project classpath otherwise jetty will display compilation errors. See this page for info:

If you are using the Eclipse Groovy plugin then make sure you enable the preference 'Disable Groovy Compiler Generating Class Files' (newer versions: Project -> Preferences -> Groovy Project Preferences / older versions: Windows -> Preferences -> Groovy Preferences). By default this option is disabled and generates class files for your groovy files, and stores them in the basedir of your Grails project. When these class files are generated, unexpected behaviour is encountered like not able to generate controllers and views for your domain classes.

THIS DOES NOT APPLY IF YOU INTEND TO USE DEBUGGING (read the section 'Step debugging' below)

Running a Grails application

Grails also automatically creates an Eclipse run configuration for you. To run the project you are in use the "Run" dropdown to open the "Run" dialog then under "Java Applications" find the name of your project select it and click "Run". The Grails application will load embedded inside Eclipse, any changes made inside the Eclipse project can be auto-reloaded.

If you are getting exceptions like

org.mortbay.util.MultiException[ {yourpath}/web-app]
	at org.mortbay.http.HttpServer.doStart(
	at org.mortbay.util.Container.start(
	at grails.util.GrailsMain.main(
then you need to do is run the ant target:
grails dev package
which will package up grails into the web-app directory in the same way as the "grails run-app" command will. This is then used as the base for eclipse to execute.

For some other errors or quirky behavior, it is often helpful to run the command

grails clean

Step Debugging with Eclipse

You can step debug a Grails application if you install the latest build of the Groovy Eclipse plug-in.

Eclipse debugging depends on the class files generated by the Groovy compiler, so make sure 'Disable Groovy Compiler Generating Class Files' is not checked (Project -> Properties -> Groovy Project Properties) and the output folder is set to e.g. "bin-groovy". Then edit the ".classpath" file in your project directory and manually remove the entry for "bin-groovy".
To debug an application, do the following:
  • Open up the Groovy file you want to debug (lets say a controller called {{BookController.groovy}}) then set a break point on the line you want to stop at. (set a breakpoint by double clicking in the far left "gutter")
  • Now debug the application in the same way as you did in the above section on "Running a Grails application" except with the "Debug" menu.
  • Load your browser and navigate to the action that calls the code.
Eclipse should then stop at the appropriate place and you can then inspect variables and step through the code. If you have the Grails source code set-up on your Source path you can step into that code too.

Adding domain classes etc.

You can configure grails as an "External Tool", allowing you to create domain classes etc. from within Eclipse:

  1. Select "Run > External Tools > External Tools...".
  2. Double-click "Program"
  3. Enter a name of "Grails".
  4. Browse the file system for the location of grails or grails.bat.
  5. Set the working directory to "${project_loc}".
  6. Set the arguments as "${string_prompt}".
  7. Under the "Refresh" tab, set to refresh the "project containing the selected resource" upon completion.
  8. Under the "Common" tab, tick "Display in favorites menu".
You can then run Grails by clicking the down arrow next to the external tool icon (run with a suitcase) and selecting "Grails", for example:
  1. Choose "Grails" from the external tools drop-down.
  2. Enter "create-domain-class" in the dialogue box.
  3. In the console window, follow the prompts as normal.
  4. Open your new class from grails-app/domain.

Editing GSP files

The gsp files are just jsp files with a special taglib. The extension gsp has to be added as follows:

  • General -> Editors -> File Associations: add *.gsp and link the JSP Editor to it.
  • General -> Content Types Fold out Text -> JSP and add *.gsp
This enables jsp editing for the gsp files. To enable code completion add the following at the start of the gsp (Grails before version 1.1 only):
<%@ taglib prefix="g" uri="/web-app/WEB-INF/tld/grails.tld" %>
Since Grails 1.1 this no longer works.

Unit Tests

To run Grails/Groovy unit tests, the easiest way is just to create a junit run configuration, but specifying "groovy.util.AllTestSuite" as the main class. More info on general groovy unit testing in grails here

TODO: find out/document how to run single tests from eclipse!


  1. If you getting the following error every time you save *.groovy file in your project:
An internal error occurred during: "Building workspace".
BUG! exception in phase 'conversion' in source unit '...' Error:
duplicate class declaration for name: … and class:

try the following:
    • Right click on package explorer's project name and open "Properties..." dialog.
    • Select "Builders" and make sure that "Groovy Builder" is checked.
    • Select "Java Compiler/Building" and check "Enable project specific settings".
    • Append "*.groovy" to "Filtered Resources" text field, to prevent ".groovy" files being copied to the output directory. Note that the path separator is "," not ";"
    • Apply changes and close dialog.
    • Clean your project. Make sure that the output directory doesn't contain "*.groovy" files
  1. If Eclipse complains that it can not find the sources where breakpoints are set ensure the following:
    • Step filtering is enabled for groovy.*, org.codehaus.* (more about this )
    • Build out put for the project is in a separate folder (say /bin ). Make sure this is present for Project->Properties->Groovy Project Properties
  2. Few other recommendations:
    • Make sure to add all the libraries from grails-app/lib folder to the project
    • Using verbose logging/tracing through until everything works from the Eclipse IDE. Sometimes if some library is not found, unless it is printed in the console, it is difficult to find out what went wrong.
    • Make sure to use the same JDK for tools.jar as well as the runtime jar rt.jar. Do note sometimes using the JRE instead of rt.jar causes problems.
    • Sometimes "launch configuration" generated by grails is not in sync with the way ant's build.xml works. In Grails 0.3 ensure that following VM parameters (do note not program arguments, but VM arguments ) are set "-Dorg.mortbay.xml.XmlParser.NotValidating=true". Without this there will be XML Parser exception thrown when launched from the IDE.

Brute Force method:

If running from IDE has issues, most likely it is because some library is missing. Ensure that all libraries under GRAILS_HOME/dist, GRAILS_HOME/ant/lib, GRAILS_HOME/lib and your project folder/lib are added to the build path of the project.