dotfiles/vim/bundle/eclim/doc/install.txt

593 lines
17 KiB
Plaintext

*install*
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 sourceforge
downloads page (https://sourceforge.net/projects/eclim/files/eclim/):
- eclim_2.4.0.jar
(http://sourceforge.net/projects/eclim/files/eclim/2.4.0/eclim_2.4.0.jar/download)
Third Party Packages
--------------------
As an alternative to the official installer, there are also some
packages maintained by third parties:
- Arch: aur (eclim) (http://aur.archlinux.org/packages.php?ID=7291),
aur (eclim-git) (http://aur.archlinux.org/packages.php?ID=33120)
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.4.0.jar
(http://sourceforge.net/projects/eclim/files/eclim/2.4.0/eclim_2.4.0.jar/download)
- Next run the installer:
>
$ java -jar eclim_2.4.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 (|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 (|eclim-proxy|) as well):
>
$ java -Dhttp.proxyHost=my.proxy -Dhttp.proxyPort=8080 -jar eclim_2.4.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.4.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.4.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.4.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
<
Note: If you are still using Eclipse 3.7 (Indigo) you will need to
checkout the eclim indigo branch before attempting to build eclim:>
$ cd eclim
$ git checkout indigo
<
2. Build eclim:
~~~~~~~~~~~~~~~
>
$ 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.
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 see an eclipse feature in that list that you know you
have, it may be the case that you installed it as a regular user, so
that feature was installed in your user local eclipse directory. In
that case you will need to notify the build of that directory so it
can examine it as well (just replace the <version> portion below with
the actual version found in your ~/.eclipse directory):
>
$ ant \
-Declipse.home=/opt/eclipse \
-Declipse.local=$HOME/.eclipse/org.eclipse.platform_<version>
<
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
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.
*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.4.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.4.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.4.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