Introduction

emacs-up is a bare-bones, quick-start Emacs configuration. It is meant to get newcomers started and productive with Emacs and contains the minimal configuration required to satisfy employee asks inside Helpshift. emacs-up is currently configured for Clojure & Frontend programming only, but I’m hoping that it will soon be expanded to include other programming languages used within Helpshift.

Installation

• The minimum supported Emacs version for this configuration is Emacs 27. You can install the latest Emacs through Homebrew as follows:

  $ brew cask install emacs
      

• Please install the following packages (prerequisites) using your system package manager:
  • git
  • aspell
  • automake
  • texinfo
  • makedoc
  • ripgrep
• Out of the box, emacs-up supports development on Clojure versions 1.8 and Java 8 (and above). If you are someone who has to program against Clojure 1.7 , 1.6 or older versions, refer to the section below this one on instructions to do that.
• Clone emacs-up to your machine as your .emacs.d folder.

  $ git clone https://github.com/helpshift/emacs-up.git ~/.emacs.d
      

• Create a .lein/profiles.clj file in your home directory. Note: You need a minimum lein version of 2.8.3. I recommend installing the latest current lein (2.9.6 as of this point in time)
  • The contents of the file should be as follows:

    {:user {:plugins [[cider/cider-nrepl "0.26.0"]
                      [refactor-nrepl "2.5.0"]]}}
            

  • You don’t need the cider-nrepl or refactor-nrepl plugin section if you use cider-jack-in to start your REPL and connect to it. We don’t use cider-jack-in at Helpshift, for reasons outside the scope of this document.
  • Changes will not apply to REPLs that are already running. After creating the profiles.clj file, you need to stop and restart running REPLs.
• For Javascript auto formatting, do, npm install -g prettier.
• Fire up Emacs and wait for it to download packages (This is a one-time thing).
• Review the next section in this README. It has details of external tools and dependencies that you need to install for working with certain packages. Install these dependencies for the best experience. They are:
  • clj-kondo
  • clj-style
• (For beginners) Go through the tutorial in the docs/ folder to get started.

Packages that Emacs-Up configures out-of-the-box

• avy: Jump to things in Emacs tree-style.
• cider: Clojure IDE and REPL. This package is pinned to a stable version.
• clj-refactor: A collection of commands for refactoring Clojure code. This package is pinned to a stable version.
• company-mode: Modular in-buffer completion framework for Emacs.
• dumb-jump: an Emacs jump to definition package for 40+ languages.
• flycheck: On-the-fly syntax checking extension
• flycheck-clj-kondo: Emacs Integration with clj-kondo, a linter for Clojure code providing on-the-fly syntax checking.
  • Note: Needs Install: This package needs clj-kondo to provide linting information for Clojure files. Install clj-kondo by following installation instructions at https://github.com/borkdude/clj-kondo/blob/master/doc/install.md
• cljstyle-mode: Emacs Integration with cljstyle, an automatic formatting tool which ensures that Clojure code is well-formatted.
  • Note: Needs Install: This package needs cljstyle to format your Clojure files when you save the buffer. Install cljstyle by following installation instructions at https://github.com/greglook/cljstyle#installation
• helm: Emacs incremental completion and narrowing framework.
  • Note: Needs Install: We recommend installing Ripgrep to search across files on disk. Installing rg will allow you to leverage super fast searches on files and data from within Emacs.
• helm-cider: helm integration for cider.
• helm-projectile: helm integration for projectile.
• magit: An Emacs mode for Git.
• paredit: Minor mode for editing parentheses.
• plantuml-mode: Major mode for PlantUML
• projectile: Project navigation and management library for Emacs.
• prettier-js: Auto formatting for JSX and JS files
• rjsx-mode: Major mode for JSX and JS files
• smex: M-x interface with Ido-style fuzzy matching.
• yasnippet: a template system for Emacs.

Developing against Clojure 1.7

If you are developing against Clojure 1.7, you need to install older packages of CIDER, Clj-Refactor and Clojure mode. Don’t worry, I have you covered here.

• Open the file hs-clj-packages.el - at the top level in this repository - and modify the value against clj-version from clj18+ to clj17. (This is the first line of code in the file, so it’s at the very top).
• Create a .lein/profiles.clj file in your home directory.
  • The contents of the file should be as follows:

    {:user {:plugins [[cider/cider-nrepl "0.17.0"]
                      [refactor-nrepl "2.3.1"]]
            :dependencies [[nrepl "0.3.1"]]}}
            

  • Changes will not apply to REPLs that are already running. After creating the profiles.clj file, you need to stop and restart running REPLs.
• Fire up / Restart your Emacs and wait for it to download packages (This is a one-time thing).

Developing against Clojure 1.6 and older versions

If you are developing against Clojure 1.6 or earlier, you need to install older packages of CIDER, Clj-Refactor and Clojure mode. Don’t worry, I have you covered here.

• Open the file hs-clj-packages.el - at the top level in this repository - and modify the value against clj-version from clj18+ to clj16-. (This is the first line of code in the file, so it’s at the very top).
• Create a .lein/profiles.clj file in your home directory.
  • The contents of the file should be as follows:

    {:repl {:plugins [[cider/cider-nrepl "0.10.2"]
                      [refactor-nrepl "1.1.0"]]
            :dependencies [^:replace [org.clojure/tools.nrepl "0.2.12"]]}}
            

  • Changes will not apply to REPLs that are already running. After creating the profiles.clj file, you need to stop and restart running REPLs.
• Fire up / Restart your Emacs and wait for it to download packages (This is a one-time thing).

Updating Emacs Up

The current version of emacs-up is v3.5.0. If you are updating an existing installation of emacs-up, the NEWS.org file lists major changes and update instructions.

Happy Programming! May the force be with you.