Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

ENhanced Scala Interaction Mode for Emacs

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 etc
Octocat-spinner-32 lib
Octocat-spinner-32 project
Octocat-spinner-32 src
Octocat-spinner-32 .gitignore
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
README.md

ENSIME

the ENhanced Scala Interaction Mode for Emacs

Features

  • Highlight errors and warnings in your code buffers.
  • Inspect the type of any expression.
  • Browse packages
  • Completion-on-demand for variable, methods, constructores, etc.
  • Jump to symbol definitions.
  • sbt support
  • Check out this video
  • or this one showcasing the debugger

System Requirements

  • Emacs 22 or later.
  • Unix-like OS or Windows. Note that you'll need to use bin/server.bat on windows.
  • Java Runtime
  • Scala 2.8 compatible source and libraries. ENSIME is built against the 2.8 nightly Scala releases.

Installation from Distribution Zip

scala-mode

ENSIME is designed to compliment scala-mode. scala-mode can be found in the Scala distribution under ./misc/scala-tool-support/emacs/

ensime-mode

Download the latest ENSIME distribution from the github downloads page. Unpack the ENSIME distribution into a directory of your choosing.

Add the following lines to your .emacs file: (require 'scala-mode) (add-to-list 'auto-mode-alist '("\.scala$" . scala-mode)) (add-to-list 'load-path "ENSIME_ROOT/elisp/") (require 'ensime) (add-hook 'scala-mode-hook 'ensime-scala-mode-hook) ;; MINI HOWTO: open .scala file. Ensure bin/server.sh is executable. M-x ensime

Permissions

Verify that the startup script (usually bin/server.sh) has executable permissions.

Project Configuration

ENSIME has built-in support for generating configuration files. In Emacs, execute M-x ensime-config-gen. Follow directions in the mini-buffer to create a .ensime file for your project..

ENSIME will try to guess the type(sbt, mvn, etc) of your project, based on the files and directory structure. If the config generator does a poor job for your project, please let us know so we can improve it. And of course you can still create the .ensime file for your project manually. See the section on the .ensime format below.

Note for sbt Users

Add ':sbt-compile-on-save t' to your config file if you'd like sbt to recompile your project whenever you save. This is disabled by default as it consumes a lot of CPU.

Note for Scala Standard Library (or other giant project) hackers

You may want to increase the jvm heap size to give ENSIME some more breathing room. We've had some reports of ENSIME hanging when retrieving type information in huge projects. You can add the necessary flags in bin/server.sh.

Installation from Git Repository (for ENSIME hackers)

ENSIME is an sbt project and we have a custom sbt task, 'dist', that generates the distributable directory structure. When hacking ENSIME, you don't want to run the ensime server directly from the git clone. First, run 'sbt dist'. Then, follow the install instructions above, using CLONE_DIR/dist as your server-root.

Usage

To enable ensime type M-x ensime. Follow the minibuffer instructions to specify the location of your .ensime project file.

TAB - Start completing a method/variable.

C-c t / Double-Click - Inspect the type of the expression under the cursor.

M-. / Control-Click - Jump to definition of symbol under cursor.

M-, - Pop back to previously visited position.

Double-Click(on an import statement) - Inspect the package under cursor.

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

C-c p - Inspect the package of the current source file.

C-c o - Inspect the package specified in .ensime as :project-package.

. - Forward one page in the inspector history.

, - Backward one page in the inspector history.

M-n / TAB - Forward one link in the inspector.

M-p - Backward one link in the inspector.

C-c C-a - Switch to the sbt command-line (works for sbt projects only)

C-c C-z - Switch to the scala interpreter, with project classes in the classpath.

C-c c - Type-check the current file.

C-c a - Type-check all files in the project.

M-x ensime-reload-config - Reload the .ensime file and recompile the project. Useful if you hit a server bug.

M-x ensime-config-get - Start the automatic configuration file generator.

Troubleshooting

You may want to examine the contents of the *inferior-ensime-server* buffer. This buffer collects the stdout and stderr of the server process, which is useful for debugging.

Configuration Format

The .ensime file must be placed in the root directory of your project(or sub-project if you have a multi-module sbt build). The contents of the file must be a valid Emacs-Lisp S-Expression.



Here's a quick primer on ELisp values:

"..." - A String

t - True

nil - False or opposite of t.

(...) - A literal list.

:abcd123 - A keyword

(:key1 val1 :key2 val2) - A 'property list'. Acts like a literal dictionary, indexed by keyword.



And now a description of all the available configuration options:

:server-root "...."

  • Required. The absolute path to the root of your ENSIME distribution. Note, this is not your project directory.

:server-cmd "...."

  • The command with which to invoke the ENSIME server. By default, this will be set to "bin/server.sh" on Unix systems and "bin/server.bat" on Windows.

:server-host "...."

  • The host to connect to. Connecting to remote ENSIME servers is not currently supported (though it may work...)

:use-sbt [t|nil]

  • Assume a standard sbt directory structure. Look in default sbt locations for dependencies, sources, target, etc.

:sbt-compile-on-save [t|nil]

  • Should ENSIME issue a 'compile' command to sbt whenever you save a file? This is disabled by default as it consumes a lot of CPU.

:use-maven t

  • Use an existing pom.xml to determine the dependencies for the project. A Maven-style directory structure is assumed.

:use-ivy t

  • Use an existing ivy.xml to determine the dependencies for the project. A Maven-style directory structure is assumed.

:ivy-compile-conf "...."
:ivy-runtime-conf "...." :ivy-test-conf "...."

  • Specify the names of dependency profiles to be used for compilation, runtime, and testing scenarios. Only necessary if you have custom configurations!

:project-package "...."

  • The main scala package for your project. Used by ENSIME to populate the project outline view.

:sources ([dir | file]*)

  • Manually include source files by directory(recursively) or by filename. If directory is given, only .scala and .java files will be considered.

:dependency-jars ([dir | file]*)

  • Manually include jars by directory(recursively) or by filename.

:compile-dependency-jars ([dir | file]*)

  • Manually include jars by directory(recursively) or by filename, to be included only at compile time.

:runtime-dependency-jars ([dir | file]*)

  • Manually include jars by directory(recursively) or by filename, to be included only at run time.

:dependency-dirs ([dir | file]*)

  • Manually include directories of .class files.

:target dir

  • Manually specify the target of the project build process. Should be the directory where .class files are written. The target is used to populate the classpath when launching the inferior scala repl and the debugger.
Something went wrong with that request. Please try again.