Setting up an IntelliJ IDEA project to build Groovy from sources
Checking out sources
You must have checked out the sources from the Codehaus git repository, or if you wish you could use the GitHub mirror.
Creating an IntelliJ IDEA project
- Choose "Create project from existing sources"
- Set the project files location to the "src" subdirectory and choose a project name
- unmark all sources but "src/main"
- no library should be found, click next
- click next on module review
- web facets should be detected, but they are not necessary. Uncheck them
- click on "finish"
If you tried to compile now, it would definitely fail. We have to update the project structure to make it work properly.
Tweak the project configuration
Edit the project structure
- Open the project structure window
- Choose a 1.6 version of the JDK
- Under the modules section, make the "test" folder a "test sources" folder
Perform an Ant build
At this step, the project structure does not include the necessary third party libraries to build groovy. Furthermore, IntelliJ IDEA requires a valid Groovy installation in order to build Groovy files. As the project is the Groovy project itself, normally the groovy build first compiles the minimal compiler written in Java then uses it to compile the remaining groovy files. Here, we'll have to workaround IntelliJ IDEA ignoring this. The first thing to do is to disable unit tests so that your local Groovy build runs faster (you can be confident that a checked out groovy project passes all unit tests ).
Create a file called local.build.properties at the root of the checked out project (this is also where you can find the build.xml file) containing the following line :
Then register the build.xml file in IntelliJ IDEA (Ant build tab on the right of the screen, "plus" button). You'll be able to launch the Ant build from IntelliJ IDEA now (use the "run" button from the Ant build tab). You could choose to run the Ant build externally, that is not a problem.
IntelliJ IDEA will run the ant build which will download the required third party libraries for you. Build duration depends on whether you already have the dependencies in a local maven repository.
Now your base directory includes a "target" directory where you will find various build artifacts :
Update the project structure
We will make use of those artifacts to create a working Groovy build from IntelliJ IDEA. To illustrate this, we will try to compile and debug (add a breakpoint) to the groovy.json.JsonBuilderTest which can be found under the test directory. Open this file in IDEA (tip, use CTRL+N, then type JBT, IntelliJ will find the class for you) :
You will notice the message at the top of the editor window which states that the Groovy SDK is not found. This is for the reasons we explained sooner : IntelliJ IDEA wants to build your Groovy files with the Groovy SDK you choose. As the project you are building is Groovy itself, it is a nonsense, so we must workaround this.
If you are used to using IDEA, you would want, at this step, to create a Run/Debug configuration for this unit test so that you can run it from IDEA. However, you will remember that we did not include any third party library at this step, which includes JUnit libraries. So IDEA will not let you create a build configuration for the JsonBuilderTest. Before, we will have to setup Groovy.
- Open the project structure
- Under the "modules" section, choose the "dependencies" tab then click on the "add" button
- choose "2. library" : we are going to create a library for building groovy
- name it "Groovy local build"
- attach classes, and choose the target/dist/groovy-all.jar file
- attach jar directories, and choose the target/lib/compile, target/lib/runtime and target/lib/test directories
With this library attached to the project, you will be able to start building Groovy from sources. However, there are still little modifications to be done.
Create a run/debug configuration for your unit test
Now if you right click on the class name of the JsonBuilderTest, you will notice that IntelliJ IDEA suggests to create a run configuration for the test. Do it. If you try to run it, IDEA will start building Groovy from sources, but you will fail with those errors :
The first errors are there because 3 files (BSFTest, CacheBSFTest and MBeanTest) are outside the scope of the project we created (they are not inside the Groovy src directory). To have IDEA build the project, you can exclude those files from the build by right clicking on each file where there is a problem in the build console and choose "Exclude from compile". The last error is an IDEA stub compilation error that you can safely ignore too. If you were to run the test configuration again, it would fail on UberTestCaseJavaSourceCodehausPackages and UberTestCaseJavaSourceGroovyPackagesNonSecurity because of the files we just have excluded, so exclude them from compilation too.
Now run the test configuration again: now it works ! Congratulations, you have successfully setup IDEA to build Groovy from sources !
You can add a breakpoint in JsonBuilderTest, and run the test configuration in debug mode. You will notice that IDEA performs a breakpoint as needed :
Updating the compiler itself
Now imagine the class you are working is related to the compiler. As the class you are updating is directly related to the compilation process, will IDEA use the class from the jar in target/dist/groovy-all.jar or the class you have just updated ? For reasons we ignore, it seems that IDEA just does it fine : if you update a compiler class, the compilation process itself will use this class instead of the one in the jar file. To check this, update the AsmClassGenetator class and add this line at the beginning of the public void visitClass(ClassNode classNode) method :
if (true) throw new NullPointerException();
Now run your test again (you must update the test file so that intellij idea builds it again). You will notice that the build process will fail as expected, so everything is fine !