*eclimd.html*

The Eclim Daemon
****************

*eclimd-headless*


Headless eclipse server
=======================

The most mature usage scenario that eclim provides, is the running of
a headless eclipse server and communicating with that server inside of
vim. Starting and stopping of the headless eclipse instance is
detailed below.

*eclimd-start*

Starting eclimd

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

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

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

Note: Even though an eclipse gui is not started in eclim's headless
  mode, eclipse still requires a running X server to function.  To run
  eclimd on a truely headless server, please see the headless guide
  (install#install-headless).

*eclimd-stop*

Stopping eclimd

To cleanly shutdown eclim use any one of the following.

- From Vim:
  >
     :ShutdownEclim

  <

- From a console:
  >
     $ $ECLIPSE_HOME/eclim -command shutdown

  <

- Lastly you can use Ctrl-C at the console if you are running eclimd
  in the foreground, or issue a kill to the eclimd java process.
  >
     $ kill *pid*

  <

  You will need to kill the java process since killing the eclimd or
  eclipse process will not do so.  While eclim provides a shutdown
  hook to support a clean shutdown when the java process is killed in
  this manner, it is still recommended that you utilize one of the
  first two methods instead, and reserve this as a last resort. Also
  note that when killing the java process eclipse will pop up an alert
  dialog notifying you that the java process was terminated underneath
  it.  This is nothing to be alarmed about.

*eclimd-headed*


Headed eclipse server
=====================

For users that find themselves periodically needing the eclipse gui,
or otherwise wanting to keep the gui open while using eclim, there is
support for running the eclim server inside of a headed eclipse
instance.

Starting eclimd

The eclim daemon inside of eclipse is implemented as an eclipse view
which can be found via:

Window ‣ Show View ‣ Other ‣ Eclim ‣ eclimd

The view will be opened in a new tab in the same pane as the
"Problems" tab, as shown below.

[image]

Note: By default, if you open an instance of gvim from within
  eclipse, the eclimd view will be opened for you if necessary.  This
  behavior is configurable via the Vimplugin preferences.

Stopping eclimd

As long as the eclimd tab is open then the eclim daemon will be
running. Stopping the eclim daemon is just a matter of closing the
eclimd tab.  Also note that leaving the tab open and closing eclipse
will shutdown the daemon as well, and on the next start of eclipse the
tab will be opened, but the eclim daemon will not start until the tab
is forced to display itself. In other words, the daemon will not start
until the eclimd tab is the active tab in that group.

*gvim-embedded*


Embedded gvim
=============

Note: Embedding is only supported on Windows and Unix systems (where
  gvim is compiled with the gtk gui).Embedding of macvim for OSX is
  not supported since macvim does not currently have the ability to be
  embedded like gvim. Macvim can still be used to open files from
  eclipse, but macvim will open as an external editor. Also note that
  macvim snapshots 56 through 63 contain a bug
  (https://github.com/b4winckler/macvim/pull/22) where opening a file
  from eclipse will open an instance of macvim, but the file will not
  be loaded into that instance.

Another feature provided by eclim for those who prefer to work inside
of the eclipse gui, is the embedding of gvim inside of eclipse.  This
feature is provided by an eclim local fork of vimplugin
(http://vimplugin.org).  The feature adds a new editor to eclipse
which allows you to open files in gvim by right clicking the file name
in the eclipse tree and then selecting:

Open With ‣ Vim

[image]

Please note that if you want to use supported eclipse features (code
completion, validation, searching, etc.) from the embedded gvim
editor, you must have the eclimd view open.

Note: If you'd like to have the embedded gvim editor as the default
  for one or more file types, you can configure it to be in your
  eclipse preferences:Window ‣ Preferences ‣ General ‣ Editors ‣ File
  Associations

The eclim installer should take care of locating your gvim
installation for use inside of eclipse, but in the event that it could
not locate it, you can set the location and other settings via the
vimplugin preferences:

Window ‣ Preferences ‣ Vimplugin

For MacVim users on OSX, the eclim installer will attempt to locate
MacVim's mvim script on your path. If it's not found you can set the
location of that script in the Vimplugin preferences:

Eclipse ‣ Preferences ‣ Vimplugin

Note: If you have a non-eclim version of vimplugin installed you
  should remove it prior to using the eclim version.

Note: Some users have reported issues with the embedded gvim's
  command line being cut off or possible rendering issues when
  scrolling through the file.  If you experience either of these
  issues, try adding the following to your vimrc file, which should
  hopefully resolve those problems:>

     set guioptions-=m " turn off menu bar
     set guioptions-=T " turn off toolbar

  <


  Additionally, some users have reported that gvim's left scrollbar
  may also need to be disabled:>

     set guioptions-=L " turn off left scrollbar
     set guioptions-=l

  <


*eclim-gvim-embedded-focus*

Embedded gvim focus

In some windowing environments, the embedded gvim is treated more like
a separate window. The result of this is that clicking the eclipse tab
(or using tab focusing keyboard shortcuts) may focus that tab, but it
won't focus the embedded gvim on that tab. Eclim adds a setting to
vimplugin which when enabled, will attempt to simulate a click on the
embedded gvim window to force it to focus:

Window ‣ Preferences ‣ Vimplugin ‣ Force gvim focus via automated
click

*eclim-gvim-embedded-shortcuts*

Eclipse/Vim key shortcuts in embedded gvim

Depending on your OS and windowing system, when the embedded gvim has
focus, you will fall into one of two groups:

1. In the first group of users, all key presses are received by
   eclipse prior to sending them to gvim.
   For this group, when typing a possible key shortcut (ctrl-n for
   example), eclipse will first evaluate that key stroke to see if
   there are any eclipse key bindings registered.  If there are, then
   eclipse will run the associated command and the key stroke is never
   sent to gvim.  If no key binding is found, then eclipse will pass
   the key stroke through to gvim.  What this means for you is that
   for any gvim key mappings that you use that have an eclipse key
   binding, they will not be evaluated inside of gvim.  So, if you
   encounter this issue, you'll need to remap the keys in vim or
   eclipse.  To remove the key binding from the eclipse side, simply
   open the "Keys" preferences page:

   Window ‣ Preferences ‣ General ‣ Keys

   Then find the entry in the list that corresponds with the key
   binding you want to remove, select it, and hit the "Unbind Command"
   button.

   Note: By default eclim will auto-remove a couple of the standard
     eclipse bindings whenever an embedded gvim editor has focus and
     then restore them with a non-gvim editor gains focus:

     - Ctrl+U: in eclipse this runs "Execute", but in gvim this is
       needed to run code completion (ex. ctrl-x ctrl-u).
     - Ctrl+N: in eclipse this runs the "New" wizard, but in gvim
       this is also needed as a part of code completion, to scroll
       through the results.
     - Ctrl+V: in eclipse this pastes text from the clipboard
       (though not into gvim), but in gvim this is needed for column
       wise visual selections.
     - Ctrl+W: in eclipse this closes a tab, but in gvim this is
       needed to switch windows (ex. ctrl-w j).
     - Ctrl+X: in eclipse this cuts a selection to the clipboard,
       but in gvim this is needed to start various insert completions
       (ex. ctrl-x ctrl-u).
     - Delete: prevent the eclipse delete key binding from
       suppressing delete attempts in the embedded gvim.
*FeedKeys*

2. In the second group, all key presses are received by gvim and
   not evaluated at all by eclipse.
   For this group of users, you may have an eclipse key shortcut that
   you like to use (Shift+Ctrl+R for example), but when you hit that
   key combination, it will be evaluated by gvim instead of eclipse.
   To remedy this situation, eclim provides a means to map eclipse
   shortcuts inside of gvim.  To register a shortcut, simply add your
   mappings to your vimrc, gvimrc, or other standard gvim file like
   so:

   >
      " maps Ctrl-F6 to eclipse's Ctrl-F6 key binding (switch editors)
      nmap <silent> <c-f6> :call eclim#vimplugin#FeedKeys('Ctrl+F6')<cr>

      " maps Ctrl-F7 to eclipse's Ctrl-F7 key binding (switch views)
      nmap <silent> <c-f7> :call eclim#vimplugin#FeedKeys('Ctrl+F7')<cr>

      " maps Ctrl-F to eclipse's Ctrl-Shift-R key binding (find resource)
      nmap <silent> <c-f> :call eclim#vimplugin#FeedKeys('Ctrl+Shift+R')<cr>

      " maps Ctrl-M to eclipse's Ctrl-M binding to maximize the editor
      nmap <silent> <c-m> :call eclim#vimplugin#FeedKeys('Ctrl+M', 1)<cr>

   <

   The value supplied to the FeedKeys function must be an eclipse
   compatible key binding string as found in:

   Windows ‣ Preferences ‣ General ‣ Keys

   Be sure to notice the extra argument to the FeedKeys function in
   the last mapping. Supplying 1 as the arg will result in the
   refocusing of gvim after the eclipse key binding has been executed.

*eclimrc*


~/.eclimrc
==========

On unix platforms (linux, mac, bsd) eclim supports an optional
.eclimrc file located in your home directory.  In this file you may
supply any system properties or vm args which you would like passed to
eclimd at startup.  The format of this file is the same as the
standard java properties file format with the exception of any vm args
which you would like to include.

Ex.

>

   # Bind eclimd to all interfaces
   nailgun.server.host=0.0.0.0

   # Specifies the port that nailgun / eclimd listens on for client requests.
   nailgun.server.port=10012

   # Specifies the workspace directory to use
   # See $ECLIPSE_HOME/configuration/config.ini for other osgi properties.
   osgi.instance.area.default=@user.home/myworkspace

   # increase heap size
   -Xmx256M

<


The eclim client will also utilize this file, but only to determine
the nailgun server port should you choose to change the default.

Note: Your system must have perl and sed available so that eclim can
  process your .eclimrc file.

Both the eclim and eclimd scripts also support a -f argument allowing
you to specify an alternate location for your .eclimrc:

>

   $ eclimd -f ~/.my_eclimrc
   $ eclim -f ~/.my_eclimrc -command ping

<



eclimd logging
==============

Eclimd utilizes log4j for all of its logging.  As such, the logging
can be configured via the
$ECLIPSE_HOME/plugins/org.eclim_version/log4j.xml file.

By default, eclimd writes all logging info to both the console and to
a log file in your workspace: <workspace>/eclimd.log

*eclimd-multiworkspace*


Multiple Workspaces
===================

Running eclim against more than one eclipse workspace can be
accomplished by running multiple eclimd instances. You must configure
each instance to run nailgun on a unique port and supply the path to
the workspace you which that instance to use. Once your eclimd
instances are up and running the vim client will automatically
determine which server to send requests to based on your context. In
some cases you may be prompted for which workspace to use if one
cannot be determined for you.

Below are some different ways in which you can configure your eclimd
instances:

1. All Users: Supply the nailgun port and eclipse workspace path
   when starting eclimd:
   >
      $ eclimd -Dosgi.instance.area.default=@user.home/workspace1 -Dnailgun.server.port=9091
      $ eclimd -Dosgi.instance.area.default=@user.home/workspace2 -Dnailgun.server.port=9092

   <

   If you are using the eclimd view in the eclipse gui, then you can
   start the eclipse gui with the desired nailgun server port (note
   that you must place the -vmargs option before the list of jvm
   arguments):

   >
      $ eclipse -vmargs -Dnailgun.server.port=9092

   <

2. Linux, OSX, BSD Users: Specify the port and workspace in eclimrc
   files and start eclimd with the -f or --file argument:
   >
      $ vim ~/.eclimrc1
      osgi.instance.area.default=@user.home/workspace1
      nailgun.server.port=9091

      $ vim ~/.eclimrc2
      osgi.instance.area.default=@user.home/workspace2
      nailgun.server.port=9092

      $ eclimd -f ~/.eclimrc1
      $ eclimd --file ~/.eclimrc2

   <

   Note: The -f/--file argument is not supported by eclipse so the
     above option is only available when using a headless eclimd
     instance.

3. Windows Users: Create Windows shortcuts:
   - In Windows Explorer, open your eclipse folder.
   - Hold down the right mouse button and drag the eclimd.bat file
     to where you want the shortcut to exist (like your desktop) and
     release the right mouse button.
   - Choose "Create Shortcut(s) Here"
   - Right click the shortcut and choose "Properties"
      - On the "Shortcut" tab edit the "Target:" field and append:
        -Dosgi.instance.area.default=@user.home/workspace1
        -Dnailgun.server.port=9091
   - Repeat this process for your other workspaces.
*eclimd-extdir*


Hosting third party nailgun apps in eclimd
==========================================

Since nailgun provides a simple way to alleviate the startup cost of
the jvm, other projects utilize it as well.  However, running several
nailgun servers isn't ideal, so eclim supports hosting other nailgun
apps via an ext dir where you can drop in jar files which will be made
available to eclim's nailgun server.

The ext dir that eclim reads from is located in your vim files
directory:

Linux / BSD / OSX:

>

   ~/.eclim/resources/ext

<


Windows:

>

   $HOME/.eclim/resources/ext

<

vim:ft=eclimhelp