*install.html*

Download / Install
******************


Requirements
============

Before beginning the installation, first confirm that you have met the
following requirements.

- Java Development Kit
  (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
  1.7 or greater
- Vim (http://www.vim.org/download.php) 7.1 or greater
- Eclipse eclipse_version (http://eclipse.org/downloads/index.php)
- Mac and Linux users must also have make and gcc installed.
  Minimum Vim Settings: In order for eclim to function properly, there
  is a minimum set of vim options that must be enabled in your vimrc
  file (:h vimrc).

  - set nocompatible
    Execute :h ‘compatible’ for more info.  You can confirm that
    compatibliity is turned off by executing the following in vim:

    >
       :echo &compatible

    <

    Which should output ‘0’, but if not, then add the following to
    your ~/.vimrc files (_vimrc on Windows):

    >
       set nocompatible

    <

  - filetype plugin on
    Execute :h filetype-plugin-on for more info.  You can confirm that
    file type plugins are enabled by executing the following:

    >
       :filetype

    <

    Which should output ‘filetype detection:ON  plugin:ON indent:ON’,
    showing at least ‘ON’ for ‘detection’ and ‘plugin’, but if not,
    then update your ~/.vimrc (_vimrc on Windows) to include:

    >
       filetype plugin indent on

    <


Download
========

You can find the official eclim installer on eclim’s github releases
page (https://github.com/ervandew/eclim/releases/):

- eclim_2.7.0.jar
  (https://github.com/ervandew/eclim/releases/download/2.7.0/eclim_2.7.0.jar)

Third Party Packages
--------------------

As an alternative to the official installer, there are also some
packages maintained by third parties:

- Arch: aur (eclim) (https://aur.archlinux.org/packages/eclim/), aur
  (eclim-git) (https://aur.archlinux.org/packages/eclim-git/)

Installing / Upgrading
======================

Eclim can be installed a few different ways depending on your
preference and environment:

- Graphical Installer
- Unattended (automated) Installer
- Build from source
- Install on a headless server
*installer*


Graphical Installer
-------------------


Step 1: Run the installer
~~~~~~~~~~~~~~~~~~~~~~~~~

Note: If you have eclipse running, please close it prior to starting
  the installation procedure.

- First download the installer:  eclim_2.7.0.jar
  (https://github.com/ervandew/eclim/releases/download/2.7.0/eclim_2.7.0.jar)
- Next run the installer:
  >
     $ java -jar eclim_2.7.0.jar

  <

  Windows and OSX users should be able to simply double click on the
  jar file to start the installer.

  After the installer starts up, simply follow the steps in the wizard
  to install eclim.

  If your machine is behind a proxy, take a look at the instructions
  for running the installer behind a proxy.

  If you encounter an error running the installer, then consult the
  known potential issues below.


Step 2: Test the installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To test eclim you first need to start the eclim daemon.  How you start
the daemon will depend on how you intend to use eclim.

Note: More info on running the eclim daemon can be found in the
  eclimd (eclimd) docs.

If you plan on using eclim along with the eclipse gui, then simply
start eclipse and open the eclimd view:

Window ‣ Show View ‣ Other ‣ Eclim ‣ eclimd

By default the eclimd view will also be auto opened when you open a
file using:

Open With ‣ Vim

If you plan on using eclim without the eclipse gui, then:

- start the eclimd server.
  - Linux / Mac / BSD (and other unix based systems): To start
    eclimd from linux, simply execute the eclimd script found in your
    eclipse root directory:
    >
       $ $ECLIPSE_HOME/eclimd

    <

  - Windows: The easiest way to start eclimd in windows is to double
    click on the eclimd.bat file found in your eclipse root directory:
    >
       %ECLIPSE_HOME%/eclimd.bat

    <

Once you have the eclim daemon (headed or headless) running, you can
then test eclim:

- open a vim window and issue the command, :PingEclim
  (|vim-core-eclim#:PingEclim|).  The result of executing this command
  should be the eclim and eclipse version echoed to the bottom of your
  Vim window.  If however, you receive unable to connect to eclimd -
  connect: Connection refused, or something similar, then your eclimd
  server is not running or something is preventing eclim from
  connecting to it.  If you receive this or any other errors you can
  start by first examining the eclimd output to see if it gives any
  info as to what went wrong.  If at this point you are unsure how to
  proceed you can view the troubleshooting guide (faq#troubleshooting)
  or feel free to post your issue on the eclim-user
  (http://groups.google.com/group/eclim-user) mailing list.
  Example of a successful ping:

  [image]
  Example of a failed ping:

  [image]
- Regardless of the ping result, you can also verify your vim
  settings using the command :EclimValidate.  This will check various
  settings and options and report any problems. If all is ok you will
  receive the following message:
  >
     Result: OK, required settings are valid.

  <

*installer-proxy*


Running The Installer Behind a Proxy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are behind a proxy, you may need to run the installer like so
(be sure to take a look at the related faq (faq#eclim-proxy) as well):

>

   $ java -Dhttp.proxyHost=my.proxy -Dhttp.proxyPort=8080 -jar eclim_2.7.0.jar

<


If your proxy requires authentication, you’ll need to supply the
-Dhttp.proxyUser and -Dhttp.proxyPassword properties as well.

You can also try the following which may be able to use your system
proxy settings:

>

   $ java -Djava.net.useSystemProxies=true -jar eclim_2.7.0.jar

<


*installer-issues*


Potential Installation Issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In some rare cases you might encounter one of the following errors:

1. Any exception which denotes usage of gcj.
   >
      java.lang.NullPointerException
        at org.pietschy.wizard.HTMLPane.updateEditorColor(Unknown Source)
        at org.pietschy.wizard.HTMLPane.setEditorKit(Unknown Source)
        at javax.swing.JEditorPane.getEditorKit(libgcj.so.90)
        ...

   <

   Gcj (GNU Compile for Java), is not currently supported.  If you
   receive any error which references libgcj, then gcj is your current
   default jvm. So, you’ll need to install the openjdk or a jdk from
   oracle to resolve the installation error.

2. >
      java.lang.IncompatibleClassChangeError
        at org.formic.ant.logger.Log4jLogger.printMessage(Log4jLogger.java:51)
        ...

   <

   This is most likely caused by an incompatible version of log4j
   installed in your jave ext.dirs.  To combat this you can run the
   installer like so:

   >
      $ java -Djava.ext.dirs -jar eclim_2.7.0.jar

   <

If you encounter an error not covered here, then please report it to
the eclim-user (http://groups.google.com/group/eclim-user) mailing
list.

*installer-automated*


Unattended (automated) install
------------------------------

As of eclim 1.5.6 the eclim installer supports the ability to run an
automated install without launching the installer gui.  Simply run the
installer as shown below, supplying the location of your vim files and
your eclipse install via system properties:

>

   $ java \
     -Dvim.files=$HOME/.vim \
     -Declipse.home=/opt/eclipse \
     -jar eclim_2.7.0.jar install

<


Please note that when using this install method, the installer will
only install eclim features whose third party dependecies are already
present in your eclipse installation.  So before installing eclim, you
must make sure that you’ve already installed the necessary
dependencies (for a full list of dependencies, you can reference
eclim’s installer dependencies
(https://github.com/ervandew/eclim/blob/master/org.eclim.installer/build/resources/dependencies.xml)
file).

Required Properties:

- eclipse.home - The absolute path to your eclipse installation.
- vim.files (or vim.skip=true) - The absolute path to your vim files
  directory. Or if you want to omit the installation of the vim files
  (emacs-eclim users for example) you can supply -Dvim.skip=true
  instead.
*install-source*


Building from source
--------------------


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.

*install-headless*


Installing on a headless server
-------------------------------

The eclim daemon supports running both inside of the eclipse gui and
as a “headless” non-gui server. However, even in the headless mode,
eclipse still requires a running X server to function. If you are
running eclim on a desktop then this isn’t a problem, but some users
would like to run the eclim daemon on a truly headless server. To
achieve this, you can make use of X.Org’s Xvfb server.

Note: This guide uses the Ubuntu server distribution to illustrate
  the process of setting up a headless server, but you should be able
  to run Xvfb on the distro of your choice by translating the package
  names used here to your distro’s equivalents.

The first step is to install the packages that are required to run
eclipse and eclim:

- Install a java jdk, xvfb, and the necessary build tools to compile
  eclim’s nailgun client during installation (make, gcc, etc).
  >
     $ sudo apt-get install openjdk-6-jdk xvfb build-essential

  <

Then you’ll need to install eclipse. You may do so by installing it
from your distro’s package manager or using a version found on
eclipse.org (http://eclipse.org/downloads/). If you choose to install
a version from you package manager, make sure that the version to be
installed is compatible with eclim since the package manager version
can often be out of date. If you choose to install an eclipse.org
(http://eclipse.org/downloads/) version, you can do so by first
downloading eclipse using either a console based browser like elinks,
or you can navigate to the download page on your desktop and copy the
download url and use wget to download the eclipse archive. Once
downloaded, you can then extract the archive in the directory of your
choice.

>

   $ wget <eclipse_mirror>/eclipse-<version>-linux-gtk.tar.gz
   $ tar -zxf eclipse-<version>-linux-gtk.tar.gz

<


Note: Depending on what distribution of eclipse you installed and
  what eclim features you would like to be installed, you may need to
  install additional eclipse features.  If you installed eclipse from
  your package manager then your package manager may also have the
  required dependency (eclipse-cdt for C/C++ support for example). If
  not, you can install the required dependency using eclipse’s p2
  command line client. Make sure the command references the correct
  repository for your eclipse install (juno in this example) and that
  you have Xvfb running as described in the last step of this guide:>

     DISPLAY=:1 ./eclipse/eclipse -nosplash -consolelog -debug
       -application org.eclipse.equinox.p2.director
       -repository http://download.eclipse.org/releases/juno
       -installIU org.eclipse.wst.web_ui.feature.feature.group

  <


  For a list of eclim plugins and which eclipse features they require,
  please see the installer dependencies
  (https://github.com/ervandew/eclim/blob/master/org.eclim.installer/build/resources/dependencies.xml).
  Note that the suffix ‘.feature.group’ must be added to the
  dependency id found in that file when supplying it to the
  ‘-installIU’ arg of the above command.

Once eclipse is installed, you can then install eclim utilizing the
eclim installer’s automated install option (see the Unattended
(automated) install section for additional details):

>

   $ java \
     -Dvim.files=$HOME/.vim \
     -Declipse.home=/opt/eclipse \
     -jar eclim_2.7.0.jar install

<


The last step is to start Xvfb followed by eclimd:

>

   $ Xvfb :1 -screen 0 1024x768x24 &
   $ DISPLAY=:1 ./eclipse/eclimd -b

<


When starting Xvfb you may receive some errors regarding font paths
and possibly dbus and hal, but as long as Xvfb continues to run, you
should be able to ignore these errors.

The first time you start eclimd you may want to omit the ‘start’
argument so that you can see the output on the console to ensure that
eclimd starts correctly.

Note: When starting the eclim daemon, you must start it as the same
  user who will be running vim.


Upgrading
---------

The upgrading procedure is the same as the installation procedure but
please be aware that the installer will remove the previous version of
eclim prior to installing the new one.  The installer will delete all
the org.eclim* eclipse plugins along with all the files eclim adds to
your .vim or vimfiles directory (plugin/eclim.vim, eclim/**/*).

*uninstall*


Uninstall
=========

To uninstall eclim you can use any eclim distribution jar whose
version is 1.7.5 or greater by running it with the ‘uninstaller’
argument like so:

>

   $ java -jar eclim_2.7.0.jar uninstaller

<


That will open a graphical wizard much like the install wizard which
will ask you again for the location of your vimfiles and eclipse home
where you’ve installed eclim and will then remove the eclim
installation accordingly.

Note: The uninstaller is backwards compatible and can be used to
  uninstall older versions of eclim.

*uninstall-automated*


Unattended (automated) uninstall
--------------------------------

Like the installer, the uninstaller also supports an unattended
uninstall. You just need to supply your vim files and eclipse paths as
system properties:

>

   $ java \
     -Dvim.files=$HOME/.vim \
     -Declipse.home=/opt/eclipse \
     -jar eclim_2.7.0.jar uninstall

<


Required Properties:

- eclipse.home - The absolute path to your eclipse installation.
- vim.files (or vim.skip=true) - The absolute path to your vim files
  directory. Or if you never installed the vim files (emacs-eclim
  users for example) you can supply -Dvim.skip=true instead.

vim:ft=eclimhelp