sponsor Vim development Vim logo Vim Book Ad

vimside : Vimside - Vim Scala Ide

 script karma  Rating 39/12, Downloaded by 6138  Comments, bugs, improvements  Vim wiki

created by
richard emberson
script type

This is the alpha release of Vimside (Vim Scala IDE).  Vimside is
built upon the ENSIME server: github: https://github.com/aemoncannon/ensime
manual: http://aemoncannon.github.com/ensime/index.html

Two outstanding Ensime features to be implemented are more
regression tests and debugging. I also hope to port the latest
verion of InSynth over to Ensime.

With this release there has been added the ActWin (Action Window)
which can be used to display compile errors (generated by either
Ensime or SBT) (a quickfix window replacement) and the result of
the command "use-of-symbol-at-point" can use the ActWin (rather
than quickfix window). The ActWin is highly configurable.
Also, User and Project Options can now be defined
in Java-like properties files (rather than in the option.vim files).
By default the

With previous releases a variable at bottom of the plugin/vimside.vim file
have been added which allows one to turn on logging during Vimside Option
loading. For the Vimside logger, Options must first be loaded
in order to configure it. Thus, no logging when loading Options.
So, I added a non-configurable logger that only logs in the
vimside#options#manager.vim file. Hopefully, this will help
users figure out whats happening during option loading.

Also, the example project code has been moved under the directory
data/vimside/projects - since there are now two example projects
and will be a couple more in the future. Additionally, the tests
have been moved under data/vimside/tests. I will be adding more
unit/regression tests in the future.

I expect to continue to update the sources on github frequently, flushing
out the features.  https://github.com/megaannum/vimside

Vimside communicates with the Ensime server using Shougo vimproc
( git://github.com/Shougo/vimproc ),
a very clean and elegant C-language binding to sockets (and also pipes,
ptys, files, etc.).  Vimside also uses Shougo vimshell to launch and
communicate with the Scala Repl.

The current pre-alpha has only be run against the Ensime pre-built
ensime_2.9.2- and ensime_2.10.0-

Look at the plugin/vimside.vim file for key mappings: how to start the
Ensime server and the currently supported commands.


Vimside is based upon Ensime and, as a result, at the core of Vimside
are the capabilities of Ensime. These are reflected in the Ensime
commands supported by Vimside. The full set of Emacs Ensime commands
and key bindings can be found in comments in the Vimside file
plugin/Vimside.vim. Of those commands, those with Vim key mappings
are also in that file and they, basically, reflect that part of Ensime
that is currently implemented in Vimside. I mirrored the Vim key
mappings to reflect the Emacs-Ensime key bindings but the user is free
to define their own mappings. At the top of the Vimside plugin file
there is code that will source a file called 'plugin_user.vim' located
in the Vimside 'data' directory: ../data/vimside/plugin_user.vim
instead of the plugin file if it exists.

Current Supported Ensime Commands:

  Start Ensime
    This makes sure that the current environment and Option settings are
    correct and then launches the Ensime backend server. The Ensime server
    writes a file where it puts the socket port that its client should use.
    Vimside reads that file, gets the port number, and provides Ensime
    with configuration information.

  Stop Ensime
    There is also an autocmd that will kill the Ensime server when the
    user exists Vim.

  Map <Tab> to Omni-Code Completion in insert mode
    This mapping maybe overridden by the mapping is some other plugin
    (like a snipmate binding), So, if it does not seem to work for you
    list the current mappings and see what is overriding it.
    Very Useful.

  Symbol At Point
    With cursor on variable, jump to the definition of its symbol.
    One can easily jump back and forth.
    The Emacs key binding uses the Meta key. In GVim I could get this
    to work and so in GVim the key mapping mirrors the Emacs Ensime
    key binding. But, with Vim in an XTerm, I could not get the Meta/Alt
    key to be recognized (and there is NO single place where there is
    a definitive, failsafe guide for getting Meta/Alt key mappings to
    work, so I have a different binding for Vim.
    Very useful.
    Implementations: 1

  Selection Expand/Contract
    Select the surrounding syntactic context and easily shrink/grow the
    Implementations: 2

  Global Public Search
    Search for method or types through project code using space separated
    search terms.
    Implementations: 1

  Hover To Symbol
    Place cursor (or mouse) over a variable and its Symbol will be
    Cute but requires frequent server polling.
    Implementations: 3

  Open Browser Info
    With cursor over Scala/Java variable, type, etc. invoke the associated
    on-line web api documentation (if it exists).
    Implementations: 1

  Use of Symbol At Point
    List all references to the symbol under the cursor.
    Very useful.
    Implementations: 1

  SBT Command-Line
    Switch to the sbt command-line (works for sbt projects only)
    Implementations: 2

  Launch Repl
    Switch to the Scala interpreter, with project classes in the classpath.
    TBD: cut/paste code fragments into Repl.
    Implementations: 1

  Typecheck Current File
    Typecheck the current file and display errors and warnings.
    Very useful.
    Implementations: 1

  Typecheck All Files
    Typecheck the all files and display errors and warnings.
    Very useful.
    Implementations: 1

  Re-Show Errors/Warnings
    Show all errors and warnings in the project.
    Very useful.
    Implementations: 1

  Format Source
    Format the current Scala source file.
    Implementations: 1

    Rename the symbol at point.
    Organize imports.
    Extract local.
    Extract method.
    Inline local.
    Add import for type at point.
    Import suggestions
    Implementations: 1

    Build the entire project.
    Rebuild the project incrementally.
    Implementations: 1

  Popup Menu
    Bring up Popup menu with all Vimside commands (requires Forms library).
    Useful for folks who have not yet learned the key mappings.
    Implementations: 1

  Browse Source Roots
    Directory browser of project sources (project code base).
    Implementations: 2

  Browse Reference Source Roots
    Directory browser of project reference sources (Java and Scala libraries).
    Implementations: 2

  Option Viewer/Editor
    Bring up the Option Viewer/Editor (requires Forms library). Lets one
    see all of the Vimside configurable Options and their current value.
    To be implemented will be an Editor allowing for the modification of
    some "dynamic" Options at runtime.
    Implementations: 1

    OmmiCompletions using <c-x><c-o>.
    Very Useful.
    Implementations: 1

  Package Inspector
    Inspect imported package, current file's package and the package
    specified in the ensime configuration ':package'.
    Very Useful.
    Implementations: 1

  Type Inspector
    Click on type and see information, Click on information and see its
    information. Move about Inspector history.
    Very Useful.
    Implementations: 1

Ensime Capabilities to be Supported:

    Seems to be a dead project (see: http://scalex.org/)

  Run Application

  Debug Application
    Start and run the debugger.
    Start and run the debugger.
    Set a breakpoint.
    Clear a breakpoint.
    Step over.
    Step out.
    Continue from a breakpoint.
    Kill the debug session.
    Inspect the local variable at cursor.
    Show backtrace.

  And others

Key Mappings
  " Start Ensime
  if has("gui_running")
  " Stop Vimside

  " TAB
  "   Start completing a method/variable.

  " Inspect the type of the expression under the cursor.
  " Inspect package at point
  " Inspect the project package if set in envime configure file.

  " M-. (dot)
  "   Jump to definition of symbol under cursor.
  "   Note that the Meta/Alt keys, while easy to use with GVim, are,
  "   at best, an advanture and, at worst, impossible, to get working
  "   with non-GVim - thus the mapping is different for non-gui-running.
  if has("gui_running")

  " M-, (comma)
  "   Pop back to previously visited position.
  if has("gui_running")

  " Select the surrounding syntactic context. Subsequent taps of '.'
  "   and ',' will grow and shrink the selection, respectively.

  " Search globally for methods or types.

  " Scalex search for methods or types.

  " Show (web api) documentation for symbol at point

  " Mouse Hover
  "   Echo the type of the expression under the cursor.

  "   Inspect the package of the current source file.

  " List all references to the symbol under the cursor.

  " Switch to the sbt command-line (works for sbt projects only)
  "     s sbt switch
  " sbt do compile
  " sbt do clean
  " sbt do package
  " sbt do exit

  " invoke the sbt command interpreter

  " Switch to the scala interpreter, with project classes in the classpath.

  " Typecheck the current file.

  " Typecheck all files in the project.

  " (Re-)Show all errors and warnings in the project.

  " Format the current Scala source file.

  " Undo a refactoring or formatting change.

  " Go to the next compilation note in the current buffer.

  " C-c C-d x
  "   Where x is one of:
  "     d Start and run the debugger.
  "     r Start and run the debugger.
  "     b Set a breakpoint.
  "     u Clear a breakpoint.
  "     s Step.
  "     n Step over.
  "     o Step out.
  "     c Continue from a breakpoint.
  "     q Kill the debug session.
  "     i Inspect the local variable at cursor.
  "     t Show backtrace.
  "     a Clear all breakes

  "   Where x is one of:
  "     r Rename the symbol at point.
  "     o Organize imports.
  "     l Extract local.
  "     m Extract method.
  "     i Inline local.
  "     t Add import for type at point.

  " Import suggestions

  "   Where x is one of:
  "     b Build the entire project.
  "     r Rebuild the project, incrementally.

  " Reload the .ensime file and recompile the project. Useful if you hit
  "   a server bug.

  " Start the automatic configuration file generator.

  " Make PopUp

  " browse source roots
  " browse referenct source roots

  " option editor

install details
There are two ways to install Vimside: 1) the traditional Vim manual
download-the-zip-file and manual download-all-dependency-zip-files
and unzip everything in the right place and 2) use a third-party
plugin manager. I would recommend using a plugin manager since you are
notified when updates are available and its just plain easier to to
installs and updates with such a manager.

One must also install Ensime, the backend compilation server:
This is discussed below under "Ensime Install"

After installing Vimside and directory layout should look like:

          " vimside code
        " data that persists between invocations of a plugin
            " examples, local test Scala/Java source tree

== Vim.org Install Plugin:

Anyway, to get the Vimside zip file from vim.org go to
and download the latest version. Unzip it in your '.vim'
directory (on Linux systems).

Now, Vimside depends upon Vimshell and Vimproc.  It is recommended that
you get the latest releases of these since they both were modified to add
some support for capabilities identified while creating Vimside. They are
located at:
Download them both and unzip them.

For Vimproc, there is an additional step because it includes a C-language
library. You must compile the library for your machine.  Vimproc comes with
a number of make-files. Pick the right one and build the library. Since
Vimside is for Scala programmers, I expect that building a C-library with
a supplied makefile will not be too challenging :-)

In addition, Vimside can be configured so that it can use the Vim
Forms and Self libraries. The latest version of these can be gotten
from github or you can get released versions from vim.org:

For most of the Vimside commands there are associated Options that configure
how the command can be used. Many such Options allow the user to run one
of multiple possible implementations.  In particular, there might be a
"native" Vim, non-Forms-based solution and also a Forms-based solution. The
Forms-based solution is built upon "native" Vim but requires the downloading
of the above two libraries: Self and Forms. Each such command with multiple
implementations can be configure individually to use or not use Forms.

What's more, the Forms library allows one to used a popup menu
(useful if you do not know all of the Vimside key-mappings yet).
And, it is expected that the package-inspector and the type-inspector
will only have Forms implementations - how to do a type-inspector
otherwise might be a challenge.

==Githup and Package Manager Install Plugin:

If, as a developer, one wants fixes as they appear, one can clone the
github {Vimside} repository and, as updates appear, copy the files
over to you Vim home location or you can use a plugin manager.

Vim has a number of third-party plugin managers. If you are using one
you can configure it to automatically download and install {Vimside}.

Intalling with vim-addon-manager (VAM)

For more information about vim-addon-manager, see [vim-addon-manager](https://github.com/MarcWeber/vim-addon-manager) and [Vim-addon-manager getting started](https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-getting-started.txt)

In your .vimrc, add self as shown below:

    fun SetupVAM()


      let g:vim_addon_manager = {}
      let g:vim_addon_manager.plugin_sources = {}


      let g:vim_addon_manager.plugin_sources['self'] = {'type': 'git', 'url': 'git://github.com/megaannum/self'}
      let g:vim_addon_manager.plugin_sources['forms'] = {'type': 'git', 'url': 'git://github.com/megaannum/forms'}
      let g:vim_addon_manager.plugin_sources['vimproc'] = {'type': 'git', 'url': 'git://github.com/Shougo/vimproc'}
      let g:vim_addon_manager.plugin_sources['vimshell'] = {'type': 'git', 'url': 'git://github.com/Shougo/vimshell'}
      let g:vim_addon_manager.plugin_sources['ensime'] = {"type": "git", "url": "git://github.com/aemoncannon/ensime";, "branch" : "scala-2.9"}
      let g:vim_addon_manager.plugin_sources['vimside'] = {'type': 'git', 'url': 'git://github.com/megaannum/vimside'}

      let plugins = [
        \ 'self',
        \ 'forms',
        \ 'vimproc',
        \ 'vimshell',
        \ 'ensime',
        \ 'vimside'
        \ ]

      call vam#ActivateAddons(plugins,{'auto_install' : 0})


    call SetupVAM()

Note that to use Vimside, the 'self' and 'forms' libraries above are optional.
With the 'forms' library, Vimside supports additional features such as a
popup-menu of commands and the type and package inspectors (not yet

Also, when one downloads Vimproc, you MUST go into the vimproc directory
and build the C-language file 'proc.c' using one of the supplied make files.

Now start Vim. You will be asked by vim-addon-manager if you would like
to download and install the plugins.

Installing with Pathogen:
With pathogen, you just have to clone all required plugins into your ~/.vim/bundle directory. Running the following lines as a bash script will do exactly that.


    declare -a repos=(
      "-b scala-2.9 git://github.com/aemoncannon/ensime.git";

    cd ~/.vim/bundle

    for repo in "${repos[@]}"; do
        git clone $repo

Note that you also with pathogen have to run *make* on the appropriate make file inside the vimproc plugin directory.

== Ensime Install

Ensime can be downloaded from https://github.com/aemoncannon/ensime
and its on-line manual is at: aemoncannon.github.com/ensime/index.html/.

In addition, for ENSIME, there are pre-built releases available at:
I highly recommend getting these (Scala 2.9.2 and/or 2.10.0)
rather than trying to build the Ensime Scala code yourself.

Ensime is not a Vim plugin. It is a Scale program. It has to be installed
and built or a pre-build version has to be used. It can be downloaded


One can the follow the instructions there and build it.

I have never done this. Rather, I have downloaded a pre-build bundle.
One for Scala 2.9 and another for Scala 10.0. These can be found at:


The Ensime build directory has the following layout using
ensime_2.9.2- as an example:


or ensime_2.10.0-


It is important that the value of the 'vimside-scala-version'
Option agrees with the Ensime build version. For
ensime_2.9.2- (the default value):

   call owner.Set("vimside-scala-version", "2.9.2")


and for ensime_2.10.0-

   call owner.Set("vimside-scala-version", "2.10.0")



These values can be set in 'data/vimside/options_user.vim'.

In addition, the version of Java ($JAVA_HOME/bin/java -version)
in the window  that runs Vim (or launched GVim) must agree with
the value of the Option 'vimside-java-version'. This Option
has the default value of '1.7' and can be set, again, in

  call owner.Set("vimside-java-version", "1.8")



Having built Ensime or downloaded a pre-built package, you must
set an Option in Vimside so that Vimside can locate the script
used to start the Ensime server. To set a Vimside Option, you
must copy the 'example_options_user.vim' or, when using
properties, 'example_vimside.properties' located in 'data/vimside'
to a file called 'options_user.vim' or 'vimside.properties' and edit it.

There is two different ways to do this.

The first is to set the Option 'ensime-install-path' or
as a Property 'ensime.install.path' to the
location of downloaded Ensime source. If you use the VAM plugin manager,
then Ensime will be in the directory:


so you would set the Option according

  call owner.Set("ensime-install-path", $HOME . "/.vim/vim-addons/ensime")
  call owner.Set("ensime-install-path", $HOME . "/vimfiles/vim-addons/ensime")

or, as a Property,


If installed with pathogen, those paths are

Then depending upon the name of the build directory, which is under the
'ensime-install-path' Option value directory location, you would
set the value of the Option 'ensime-dist-dir' or Property
'ensime.dist.dir' to that directory name.  For example:

    call owner.Set("ensime-dist-dir", "ensime_2.9.2-")
    call owner.Set("ensime-dist-dir", "ensime_2.10.0-")

or, as a Property,


Alternatively, you can specify the full path to the ensime distribution
using the Option 'ensime-dist-path' or Property 'ensime.dist.path'.
As an example, if you installed an Ensime build package in some Scala
directory, you might set the Option as:

    call owner.Set("ensime-dist-path", $HOME . "/scala/ensime/ensime_2.9.2-")

or, as a Property,


If you set the 'ensime-dist-path' ('ensime-dist.path'), it is checked first
and, if it exists, it is used rather than the 'ensime-install-path'
and 'ensime-dist-dir' ('ensime.install.path' and 'ensime.dist.dir')

Vimside supports the Ensime SBT commands. With such, there is an additional
library, an SBT Plugin that supports integration with the ENSIME IDE:

== Vimside Testing

RECOMMENDED for initial testing:
To run against test Scala/Java project, first in data/vimside directory
copy example_options_user.vim to options_user.vim.

  > cd $HOME/.vim/data/vimside
  > /bin/cp example_options_user.vim options_user.vim
  > /bin/cp example_vimside.properties vimside.properties

Then, in options_user.vim (or vimside.properties) uncomment the
following two lines:

   call a:option.Set("ensime-config-file-name", "ensime_config.vim")

or, as a Property,


This tells Vimside to use the test project code and to use the
ensime_config.vim as the source for Ensime Configuration.

One can also run Emacs and enter the command to start Ensime.
I sometimes do this just to check-out how Emacs-Ensime does something
that I am trying to implement in VimL for Vimside.

Lastly, read the doc/vimside.txt for more complete information.

Acknowledgements and thanks:
Aemon Cannon for writing Ensime.
Daniel Spiewak has a JEdit binding to Ensime and a simply great video
explaining why a true editor with Ensime is better than an Eclipse
Ide (https://www.youtube.com/watch?v=cd2LV0xy9G8 MUST SEE)
and usage examples (http://vimeo.com/28597033),
Sven Eigenbrodt provided the Pathogen installation information.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vimside.zip 0.4.0 2013-08-25 7.0 richard emberson Big change was the addition of the ActWin (Action Window) which
is now the default window for both compiler errors (via Ensime or
SBT) and the uses-of-symbol-at-point command. Very configurable.
The quickfix window can still be use if desired via configuration.
Now Vimside supports either initialization with the Option files
'options_user.vim' and a project specific options file (and/) or
with Properties file 'vimside.properties' and a project specific
properties file. See the 'data/vimside/PROPERTIES' file for
available Properties (or, changing '.' to '-', Options).
Also, bumped (after a long time, the version number.
vimside.zip 0.2.23 2013-03-24 7.3 richard emberson With this release, variable at bottom of the plugin/vimside.vim file
have been added which allows one to turn on logging during Vimside Option
loading. For the Vimside logger, Options must first be loaded
in order to configure it. Thus, no logging when loading Options.
So, I added a non-configurable logger that only logs in the
vimside#options#manager.vim file. Hopefully, this will help
users figure out whats happening during option loading.
Also, two Options have been removed, test-ensime-file-use and
test-ensime-file-dir; they might have been useful when there was only
one "test" project under data/vimside not not now.
I knew that the SExp parser was a "quick and dirty" implementation, what
I had not realized was that it was really "slow and dirty"; with the
type inspector feature, getting the symbol-at-point info for String
took 65 seconds to parse. So, the SExp parse was re-written so that now
it takes a little over 8 seconds - still long but much better.
Modified the ensime/scheduler.vim Job adding code so that while processing
the current Jobs list, any add is saved in a separate list (like any remove)
and only at the end of processing are the adds, if any, are done. This
fixed a bug in the hover code. Also in scheduler.vim, because the result for
symbol-at-point for String was so large (a String of length 110K), all of
it was not read from the socket during a single read. This was fixed so
that partial reads resulted in a second (and third) read to get the
rest of the protocol message.
In the type-inspector window, a ":q" now does what "q" does, it closes
the window. Also, changed current page name from "s:page" to "s:current_page"
to mirror the current inspector's name. Also, the current_page is now
only generated if it does not exist (speeding up history previous/next
For certain symbols, symbol-at-point requests to the Ensime server backend
would cause it to generate scala-notes event messages and the reception of
these events would cause the between server polling times to be increase -
which was bad since one is still waiting for the rpc response. This was
fixed by check if there are any outstanding rpc's prior to adjusting
polling time.
Added a couple of newly implemented features to the Forms popup menu.
Added a couple of newly implemented features to the Forms popup menu.
Updated where one could download the pre-build images of Ensime.
Fixed example to use the latest pre-build Ensime version numbers:
ensime_2.9.2- and ensime_2.10.0-
Communications with the server is now both asynchronous and synchronous.
Generally, asynchronous will still be used for standard communication
while synchronous is used for unit tests. Maybe, in time, some of the
commands will be synchronous - maybe configurable via Options.
Added unit tests.
Tests require runVimTests-1.22.zip and vimtap-0.4.0.zip.
vimside.zip 0.2.21 2013-03-14 7.3 richard emberson Type and Package Inspector
vimside.zip 0.2.17 2013-02-16 7.0 richard emberson Added support for SBT (Simple Build Tool) projects.
vimside.zip 0.2.14 2013-01-01 7.0 richard emberson Implemented method vimside#ensime#swank#handle_no_response() which is call
by vimside#ensime#io#ping(timeout) when the response from the Ensime server
is empty which uses the previous checkin's Options
    scheduler-many-max-count-no-events (default 50)
    scheduler-events-max-count-no-events (default 50)
to ultimately restore the schedule to a "not expecting anything/steady" state
(a long time between pings). This simply assures that if there is some
bug in handling responses from the server, a fast ping rate will
ultimately stop and the system returned to steady-state.
vimside.zip 0.2.13 2012-12-31 7.0 richard emberson Added Build and Rebuild project commands.
Re-wrote how the swank dispatch and scheduling code handle events.
Replaced the scheduling Options with a new set of Options.
vimside.zip 0.2.12 2012-12-09 7.0 richard emberson Added Imports (add/suggest) Refactoring command.
Fixed Search command interaction with Time-base scheduler.
Fixed Search display of entered text prior to calling Ensime.
Fixed Search command result sorting.
Search now non-incremental by default.
Add Search Option allowing the setting for number of results:
Fixed Ensime config so that indexing is allowed on startup by default.
Upgraded doc and example configs for Ensime Scala 2.10-RC3 build.
vimside.zip 0.2.11 2012-12-04 7.0 richard emberson Add Refactor Options to validate allowed/disallow identifier names.
vimside.zip 0.2.10 2012-12-03 7.0 richard emberson Add pathogen install instructions.
vimside.zip 0.2.9 2012-12-02 7.0 richard emberson Added refactoring commands.
Changed key mapping for vimside#command#SymbolAtPoint() and vimside#command#PreviousPosition().
Made the test source code so that there are no compile errors.
vimside.zip 0.2.8 2012-11-29 7.0 richard emberson First pre-alpha code release.
vimside.zip 0.2 2012-10-28 7.0 richard emberson Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.