-
Notifications
You must be signed in to change notification settings - Fork 192
Groovy Eclipse Architecture
When working on the Groovy-Eclipse code base it is important to know about its broad architecture.
The best place to get an overview of the conceptual architecture is in this post and this post.
After reading about the high-level concepts, you may still be left wondering about how and where these architectural concepts live in the codebase.
There are two kinds of 'patching' going on in the code base. By 'patching' we mean that there is a copy being taken of someone else's code, then this code is modified to make it somehow 'eclipse compatible' (i.e. the architecture explained in the Blog article).
Two things are being patched:
- The Eclipse JDT compiler (ecj): it is patched to provide hooks so that JDT can compile both Groovy / Java code. To the rest of eclipse it makes it look like Groovy = Java.
- The Groovy command-line compiler (groovyc): various bits of code from groovyc is called on by the JDT patch to parse and compile groovy code. groovyc is patched to make this interoperability possible (e.g. so groovyc can understand Java types compiled by JDT).
The patch consists of a 'feature' bundle and two 'plugin' bundles. The patch is specific to a particular version of eclipse. That is, it targets a very specific eclipse version.
Care should be taken to compile / test / install always the right version of the patch according to the host eclipse version.
The patch is found on disk in these directories:
- jdt-patch/e419
- jdt-patch/e420
- jdt-patch/e421
- jdt-patch/e422
- jdt-patch/e423
- jdt-patch/e424
- jdt-patch/e425
- jdt-patch/e426
- jdt-patch/e427
- jdt-patch/e428
- jdt-patch/e429
- jdt-patch/e430
- jdt-patch/e431
- jdt-patch/e432
- jdt-patch/e433
Directory names indicate the target version of Eclipse.
The 'org.eclipse.jdt.core' plugin is a a copy of an eclipse bundle with the same name. This bundle is the 'core' of the JDT compiler. We patch and replace it via a JDT feature patch.
Making changes in this code is very sensitive because it effectively replaces the Eclipse JDT compiler with our patched version.
It very important that any changes in this code preserve the Java language semantics. Even when people are not using Groovy at all, the patched compiler is still active!
All changes we make in these files must be marked with special comments to identify them as 'our changes'.
This is a supporting companion to 'org.eclipse.jdt.core'. All the code in here belongs to groovy eclipse, but is still a part of our JDT patch.
Since all code in this bundle is 'ours' it is not necessary to mark changes with special comments here.
This is an eclipse patch feature. When installed into eclipse, it replaces the original 'org.eclipse.jdt.core' with our patched version of 'org.eclipse.jdt.core' and its companion 'org.eclipse.jdt.groovy.core'.
Besides patching eclipse JDT we also patch Groovyc.
These numbered bundles patch different versions of Groovy:
- org.codehaus.groovy30
- org.codehaus.groovy40
- org.codehaus.groovy50
Each one of these bundles contains a 'patch' of the Groovy runtime for a specific version of groovyc.
The names of the project are numbered, however they contain different versions of an eclipse plugin with the same id: 'org.codehaus.groovy'. The plugin version and project name reflects the version of groovyc they are patching. Only one of these bundles can be active at the same time at runtime. Though several of them can be installed at the same time in the same Eclipse instance. Switching compiler requires a restart of Eclipse to activate a different bundle.
The 'patch' works via a classloader trick. The 'groovy-all jar' containing the original groovyc is on the classpath. The code that needs patching is copied into a source folder and modified. The source folder's compiled code will be found by the classloader before searching the jar so it replaces the original code at runtime.
Changes in these plugins are sensitive because they could change the behavior of groovyc. When making changes here the intention should generally be to preserve the Groovy language semantics, but make the compiler 'play nice' with eclipse.
For each 'org.codehaus.groovyXX' plugin there is a corresponding eclipse feature:
- Feature-org.codehaus.groovy30.feature
- Feature-org.codehaus.groovy40.feature
- Feature-org.codehaus.groovy50.feature