*guides-install*


Installing / Upgrading
**********************


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

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

- Java Development Kit
  (http://java.sun.com/javase/downloads/index.html) 1.5 or greater

- Eclipse 3.5.x (Galileo) (http://eclipse.org/downloads/index.php)

- Vim 7.1.x (http://www.vim.org/download.php)

  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:

    >
       :echo &compatible

    <

    Which should output '0'.

  - 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'.

*installer*


Eclim Graphical Installer
=========================


Step 1: Download the eclim installer for your platform.
-------------------------------------------------------

- Linux / Mac / BSD (and other unix based systems): eclim_version.sh (
  http://sourceforge.net/project/platformdownload.php?group_id=145869&
  sel_platform=15823)

- Windows: eclim_version.exe (http://sourceforge.net/project/platformd
  ownload.php?group_id=145869&sel_platform=15821)


Step 2: Run the installer.
--------------------------

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

- Linux / Mac / BSD (and other unix based systems): You can start the
  installer by running the script you downloaded (note: you may have
  to make it executable first).

  >
     $ chmod 755 eclim_version.sh
     $ ./eclim_version.sh

  <

  Note: 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 (|eclim-proxy|) as
    well):>

       $ FORMIC_OPTS="-Dhttp.proxyHost=my.proxy -Dhttp.proxyPort=8080" ./eclim_version.sh

    <


    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:>

       $ FORMIC_OPTS="-Djava.net.useSystemProxies=true" ./eclim_version.sh

    <


- Windows: On Windows systems, simply double click the
  eclim_version.exe file you downloaded.

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

       C:\...> set FORMIC_OPTS=-Dhttp.proxyHost=my.proxy -Dhttp.proxyPort=8080
       C:\...> eclim_version.exe

    <


    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:>

       C:\...> set FORMIC_OPTS=-Djava.net.useSystemProxies=true
       C:\...> eclim_version.exe

    <


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

Note: 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 a sun jvm 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:

     >
        $ FORMIC_OPTS="-Djava.ext.dirs" ./eclim_1.4.0.sh

     <


Step 3: Testing 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.

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

- start eclipse with the -clean option

  >
     $ eclipse -clean

  <

  Note: You should only need to start eclipse with the -clean option the
    first time after installing or upgrading eclim.

- open the eclimd view

  Window -> Show View -> Other -> Eclim -> eclimd

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|.  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 (|guides-troubleshoot|) or feel free to post
  your issue on the eclim user
  (http://groups.google.com/group/eclim-user) mailing list.

     Example of successful ping:

     [image]

     Example of 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.

  <


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

Now that you have eclim installed, the next step is to familiarize
yourself with at least the core set of commands that eclim provides,
all of which are found at the index of the eclim documentation
(|vim-index|).

After doing that you can then proceed to getting started guide
(|gettingstarted|).


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 files in the eclim eclipse plugins and the files eclim adds to
your .vim or vimfiles directory. So if you made any alterations to any
of these files, be sure to back them up prior to upgrading.


Building from source
====================

If you would like to use the bleeding edge development version of
eclim or you would like to contribute code, then you can checkout and
build eclim from source.  Instructions on doing so can be found in the
developers guide (|development-build|).

*install-automated*


Unattended (automated) install
==============================

As of eclim 1.5.5 users on unix based machines (linux, OSX, etc.) can
use the eclim installer to run an automated install without launching
the installer gui.

Warning: When using this method no validation is performed to ensure that you
  have the required third party eclipse plugin dependencies necessary
  for the eclim features you've chosen to install.  It is the
  responsibility of the user, or the script which launches the
  installer, to validate the dependencies prior to installation.  This
  installation method is primarily provided for those wishing to
  package eclim for inclusion in a package management system.

Here is an example of installing eclim with only java and ant support
using this method:

>

   $ ./eclim_1.5.5.sh install \
     -Declipse.home=/opt/eclipse \
     -Dvim.files=$HOME/.vim \
     -DfeatureList.ant=true \
     -DfeatureList.jdt=true

<


As you can see by the example, the values normally obtained from the
user by the graphical installer are supplied using java system
properties.  This method of installation has only two required
properties that must be set and various optional properties to enable
features, etc.

Required:

- eclipse.home - The absolute path to the eclipse installation.

- vim.files - The absolute path to the vim files directory.

Optional:

- eclipse.local - When installing for a single user, some eclipse
  installations have a user local location where eclipse plugins are
  installed.  This property can be set to that location.

- eclim.gvim - The location of the gvim executable to be set as the
  default for embedding gvim inside of eclipse.

Optional Feature Properties: All of the following properties must have
the value 'true' to enable the feature.  All other values, or no value
at all will result in the exclusion of that feature.  Also, some
features require that other features be enabled, as noted below:

- featureList.ant (requires jdt)

- featureList.cdt

- featureList.dltk

- featureList.dltkruby (requires dltk)

- featureList.jdt

- featureList.maven

- featureList.pdt (requires wst and dltk)

- featureList.python

- featureList.wst

vim:ft=eclimhelp