This guide is intended mostly for those who wish to contribute to eclim by fixing bugs or adding new functionality, but the first section is also useful for users who would like to use the latest development version of eclim.
$ git clone git://eclim.git.sourceforge.net/gitroot/eclim/eclimOnce you have a local git repository you can utilize the extensive local git functionality allowing you to commit code locally, create local branches, etc. For guidelines on managing patches and submitting them, please see the patch guide below.
$ cd eclim $ ant -Declipse.home=<your eclipse home dir>Note
If your eclipse home path contains a space, be sure to quote it:
> ant “-Declipse.home=C:/Program Files/eclipse”This will build and deploy eclim to your eclipse and vim directories. If you don’t want to supply the eclipse home directory every time, you can set the environment variable ECLIM_ECLIPSE_HOME which the build script will then utilize.
Note
If your vimfiles directory is not located at the default location for your OS, then you can specify the location using the “vim.files” property:
$ ant -Dvim.files=<your vimfiles dir>By default the above ant call will build all the eclim plugins, requiring you to have all the related dependencies already installed in your eclipse distribution. However, if you only want a subset of the eclim plugins to be built, you can specify so using the ‘plugins’ system property:
# build only ant and jdt (java) support $ ant -Dplugins=ant,jdt # build only cdt (c/c++) support $ ant -Dplugins=cdt # build only pdt (php) support (requires wst and dltk) $ ant -Dplugins=wst,dltk,pdt # build only ruby support (requires dltk) $ ant -Dplugins=dltk,dltkrubyNote
On windows you will need to quote the plugins argument if you are building more than one plugin:
> ant “-Dplugins=ant,jdt”The currently available list of plugin names include:
- jdt: java support using the eclipse jdt.
- ant: ant support.
- maven: maven support.
- wst: web development support using the eclipse wst.
- cdt: c/c++ support using the eclipse cdt.
- dltk: base support for dltk based lanugages (currently php and ruby).
- pdt: php support using the eclipse pdt.
- dltkruby: ruby support using the eclipse dltk-ruby.
Before you start writing any code you should first familiarize yourself with the preferred means of submitting patches, and if you plan on contributing anything non-trivial, the preferred means of managing those patches.
Submitting Patches
Any patches you submit should be in the form of diff against the current git head using git’s format-patch command:
$ git format-patch -M origin/master
Running the above command will generate a series of patch files which can be submitted to the eclim development group.
If you use git, without stgit, please be aware that the diff will generate a patch entry for every commit you’ve made. So unless each commit represents a change that you are willing to submit independently of the others, please consolidate all your commits for a given patch into a single commit prior to generating the patch file (using git rebase -i for instance). If you don’t do so then the patch file will contain all your trial and errors, dead ends, etc. and evaluating a patch with an entire history like that can be very difficult.
Managing Patch Development
Although you can manage patches and format “clean” patch files by manually rewriting git’s history, you might find it easier to manage your patches using an external patch management tool like Stacked Git (StGit). StGit can make creating, managing, and submitting patches easier for some users. If you decide to not use StGit, then you should read the section in the git manual regarding managing of patch series which provides some very nice guidelines and useful tips.
Example Patch Workflow
To fully illustrate creating and submitting a patch, let’s walk through making a small change, from start to finish. In this example we will modify the :PingEclim command to print “Pong” along with the version numbers normally returned.
This example will use stgit, but the same result can be accomplished with git alone.
$ git clone git://eclim.git.sourceforge.net/gitroot/eclim/eclim
$ cd eclim $ stg init
$ stg new -m "Alter :PingEclim to print 'Pong'" pong
$ vim src/java/org/eclim/plugin/core/command/admin/PingCommand.java ... $ git diff diff --git a/src/java/org/eclim/plugin/core/command/admin/PingCommand.java b/src/java/org/eclim/plugin/core/command/admin/PingCommand.java index bb5c569..b2f2ebc 100644 --- a/src/java/org/eclim/command/admin/PingCommand.java +++ b/src/java/org/eclim/command/admin/PingCommand.java @@ -65,7 +65,7 @@ public class PingCommand version = eclim_version + '\n' + eclipse_version; } - return version; + return "Pong!\n" + version; } private String getVersion()
$ ant ... $ $ECLIPSE_HOME/eclimd ... $ vim -c ":PingEclim" ... Pong! eclim 1.4.4 eclipse 3.5.0 Press ENTER or type command to continue
$ stg refresh Checking for changes in the working directory ... done Refreshing patch "pong" ... done
$ git format-patch -M origin/master
At this point all that is left is submitting the patch to the eclim development group.
Pulling Updates
At some point you’ll need to pull updates from the remote git repository. If you’re using git without stgit, then you can pull updates in the standard git fashion (using rebase in this example to help keep the history cleaner):
$ git pull --rebaseIf you’re using stgit on top of git, then the preferred method is to pull via stgit:
$ stg pull -m
Now that you’re familiar with the basics of building and patching eclim, the next step is to familiarize yourself with the eclim architecture and to review the detailed docs on how new features are added.
All of that and more can be found in the eclim development docs.