*development-gettingstarted.html*

Developers Guide
****************

This guide is intended for those who wish to contribute to eclim by
fixing bugs or adding new functionality.


Checking out the code and building it.
======================================


1. Check out the code:
----------------------

>

   $ git clone git://github.com/ervandew/eclim.git

<



2. Build eclim:
---------------

>

   $ cd eclim
   $ ant -Declipse.home=/your/eclipse/home/dir

<


This will build and deploy eclim to your eclipse and vim directories.

Warning: Building eclim as root is highly discouraged. If your
  eclipse install is only writable as root, you can supply the
  eclipse.local property to tell eclim where your eclipse user local
  directory is located and eclimd will be installed there (make sure
  to replace <version> portion of the path below accordingly):>

     $ ant \
         -Declipse.home=/opt/eclipse \
         -Declipse.local=$HOME/.eclipse/org.eclipse.platform_<version>

  <


  If you do not yet have a .eclipse directory in your home directory,
  you can run either of the following commands to create it:>

     $ ant -Declipse.home=/opt/eclipse eclipse.init

  <


  or>

     $ /path/to/eclipse/eclipse -initialize

  <


Note: If your eclipse home path contains a space, be sure to quote
  it:>

     > ant "-Declipse.home=C:/Program Files/eclipse"

  <


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>

  <


When the build starts, it will first examine your eclipse installation
to find what eclipse plugins are available. It will then use that list
to determine which eclim features/plugins should be built and will
output a list like the one below showing what will be built vs what
will be skipped:

>

   [echo] ${eclipse}: /opt/eclipse
   [echo] # Skipping org.eclim.adt, missing com.android.ide.eclipse.adt
   [echo] # Skipping org.eclim.dltk, missing org.eclipse.dltk.core
   [echo] # Skipping org.eclim.dltkruby, missing org.eclipse.dltk.ruby
   [echo] # Skipping org.eclim.pdt, missing org.eclipse.php
   [echo] Plugins:
   [echo]   org.eclim.cdt
   [echo]   org.eclim.jdt
   [echo]   org.eclim.pydev
   [echo]   org.eclim.sdt
   [echo]   org.eclim.wst

<


In this case we can see that four eclim plugins will be skipped along
with the eclipse feature that would be required to build those
plugins.

If you don't want to supply the eclipse home directory, or any other
properties, on the command line every time you build eclim, you can
create a user.properties file at the eclim source root and put all
your properties in there:

>

   $ vim user.properties
   eclipse.home=/opt/eclipse
   eclipse.local=${user.home}/.eclipse/org.eclipse.platform_<version>
   vim.files=${user.home}/.vim/bundle/eclim

<


Note: The eclim vim help files, used by the :EclimHelp
  (|vim-core-eclim#:EclimHelp|) command, are not built by default. To
  build these you first need to install sphinx
  (http://sphinx-doc.org), then run the following command:>

     $ ant vimdocs

  <


  This target also supports the vim.files property if you want the
  docs deployed to a directory other than the default location.

  Warning: Debian/Ubuntu users: The debian version of sphinx has
    unfortunately been patched to behave differently than the upstream
    version, resulting in one or more eclim supplied sphinx extensions
    not loading. Another issue you may run into is the docutils
    package, which sphinx depends on, is outdated on debian/ubuntu,
    resulting in another set of errors.So to get around these issues
    you'll need to install sphinx using pip
    (http://pip.readthedocs.org/en/latest/index.html) or similar.

*coding-style*


Coding Style
============

When contributing code please try to adhere to the coding style of
similar code so that eclim's source can retain consistency throughout.
For java code, eclim includes a checkstyle configuration which can be
run against the whole project:

>

   $ ant checkstyle

<


or against the current java file from within vim:

>

   :Checkstyle

<


*development-patches*


Developing / Submitting Patches
===============================

The preferred means of developing and submitting patches is to use a
github fork. Github provides a nice guide to forking
(http://help.github.com/forking/) which should get you started.

Although using a github fork is preferred, you can of course still
submit patches via email 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
(http://groups.google.com/group/eclim-dev).


Building the eclim installer
============================

It should be rare that someone should need to build the eclim
installer, but should the need arise here are the instructions for
doing so.

To build the installer you first need a couple external tools
installed:

- sphinx (http://sphinx-doc.org): Sphinx is used to build the eclim
  documentation which is included in the installer.
  Eclim also uses a custom sphinx theme which is included in eclim as
  a git submodule. So before you can build the installer you will need
  to initialize the submodule:

  >
     $ git submodule init
     $ git submodule update

  <

- graphviz (http://www.graphviz.org/):  The docs include a few uml
  diagrams which are generated using plantuml
  (http://plantuml.sourceforge.net/) (included in the eclim source
  tree) which in turn requires graphviz (http://www.graphviz.org/).
- formic (http://github.com/ervandew/formic): The eclim installer
  has been developed using the formic framework, and requires it to
  build the installer distributables.  Formic doesn't currently have
  an official release, so you'll need to check out the source code:
  >
     $ git clone git://github.com/ervandew/formic.git

  <

  After checking out the code, you'll need to build the formic
  distribution:

  >
     $ cd formic
     $ ant dist

  <

  Then extract the formic tar to the location of your choice

  >
     $ tar -zxvf build/dist/formic-0.2.0.tar.gz -C /location/of/your/choice

  <

Once you have installed the above dependencies, you can then build the
eclim installer with the following command.

>

   $ ant -Dformic.home=/your/formic/install/dir dist

<


In lieu of supplying the formic home on the command line, you can
instead put it in a user.properties file at the eclim source root:

>

   $ vim user.properties
   formic.home=/your/formic/install/dir

<



What's Next
===========

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
(|development-index|).

vim:ft=eclimhelp