(λmacs)
Emacs for Clojure development on macOS X.

For a number of years I've been using Emacs as my primary/only IDE. I used a number of "distributions" readily available on internet such as emacs-live and Prelude of which I made my own extension Preludex, and I watched the birth of Spacemacs and the new challenger doom-emacs.

Over time each of these distributions grew larger and larger and it became hard to keep the configuration up-to-date but still minimal (just what you need).

So I decided to build my own out of the best pieces of all of them.

If you are new to Emacs, it is probably best if you start with one of the more popular distributions so that you get enough community support. If only you need is to develop Clojure, and have enough tooling support feel free to use my configuration.

• Download and install Emacs For Mac OS X if you don't have it yet!

Alternatively you can install it via:

sudo mkdir /usr/local/Frameworks
sudo chown $(whoami):admin /usr/local/Frameworks
brew tap d12frosted/emacs-plus
brew install emacs-plus@29 --with-no-frame-refocus --with-xwidgets --with-imagemagick --with-native-comp --with-elrumo2-icon

You can check github://d12frosted/homebrew-emacs-plus what each option does.

NOTE: you can choose your icon here and replace the last argument with the one you want

• Backup your previous installation:

mv ~/.emacs.d ~/.emacs.d-backup

• Clone (λmacs)

git clone https://github.com/BrunoBonacci/lambdamacs.git ~/.emacs.d

• Install platform tools

Some platform tools are used to enhance the user experience and to support some features.

brew install the_silver_searcher aspell fd

• That's all, start hacking!

If you want you can customize your configuration (see next section).

There are a number of configurable options to setup (λmacs) just right for your environment.

To change the configuration file edit config/user-config.el.

• First configure your name and email:

;; add your name and email address
(setq user-full-name    "Firstname Lastname"
      user-mail-address "your-email@email.org")

• Install a nice looking font and pick a size:

Here some suggestions:

• Roboto Mono
• Fira Code
• Victor Mono

(setq lambdamacs/default-font "Roboto Mono Thin for Powerline")
(setq lambdamacs/default-font-size 150)

• Select your favorite theme

There are a number a themes already installed see the full list and see theme screenshots. I'd recommend to pick your favorite as default and use a light theme as alternative. It can be useful sometimes to switch to the alternative for example if you make a presentation. Light themes work better with projectors.

(setq lambdamacs/default-theme 'doom-moonlight)
(setq lambdamacs/alternative-theme 'doom-one-light)

You can switch between themes by typing M-x lambdamacs/switch-theme-to-alternative and switch back to the default theme with M-x lambdamacs/switch-theme-to-default

(λmacs) has the following project structure:

.emacs.d
├── init.el    - main emacs init file
├── config/    - user configuration and other settings
├── modules/   - packages which are not available in MELPA
├── src/       - packages installation and configuration
├── assets/    - Assets for this project (images, css, etc)
├── yas/       - Custom Yasnippets
└── .save/     - Locally saved items (history, items etc.)

• TODO:
• [ ] wsd
• [ ] workgroups / persp-mode / toggle-zoom ??
• [ ] code rtf pygments
• [ ] repl image hack

Here is the list of keybindings which are added by this configuration. All standard keybindings are valid, plus the default keybindings of the pacakge installed.

Here is how to read the keybindings:

• C-x - means Ctrl + x
• C-x 1 - means Ctrl + x followed by 1
• M-x - means Meta + x or Alt + x or Option + x
• s-x - means Super + x or Command ⌘ + x
• SPC - is space bar
• RET - is reutrn key

Here the keybindings added/defined by (λmacs):

(λmacs) focus is on Clojure development. Clojure is a JVM hosted language. JVM release process has been traditionally quite slow, but in the recent years Oracle and OpenJDK have speed up the release process to roughly every 6 months.

For this reason it is common to having the need to use/try different version of the underlying JVM while working on a Clojure project.

Emacs doesn't have a facility to do this and, to my knowledge, there is package that handles this. For this reason I wrote a module that offers this possibility and described the solution in this blog post: Switching between multiple Java JDK versions in Emacs.

You can read more about the solution in the blog post but here I will only describe how it works.

Firstly you need to tell (λmacs) where your JDKs are installed. Typically on a macOS the default location is: /Library/Java/JavaVirtualMachines.

If this is the location where are your JDK versions are installed then you don't need to change the configuration, otherwise select the appropriate folder in the config/user-config.el file.

;; base directory where all the JDK versions are installed
;; use `M-x switch-java' to select the JVM to use
(setq JAVA_BASE "/Library/Java/JavaVirtualMachines")

Once you set the base directory where all your JDKs are installed and evaluated the form, to select a JVM to use you can just run: M-x switch-java which will show the list of available JVMs. Once you select one JDK, it will update the $JVM_HOME environment variable and use it whenever you start a new REPL or java application.

Here other commands you can run:

• M-x switch-java select a JDK from a list of available ones
• M-x switch-java-default will select the system default JDK (the one in use prior any selection)
• M-x switch-java-which-version? displays the JDK currently in use.

You can see a usage demo here:

yasnippets is a templating minor-mode with allows to define code templates and complete them with a few keystrokes. Think about the repetitve structures in your code. Check out this demo on Youtube. It works across languages and there are plenty of predefine templates Here the is a list of all most of the boundled snippets.

However if you want to define your own snippets you can drop them in ~/.emacs.d/yas folder divided by major-mode. If you are unfamiliar with the templating language used by yasnippet you can check the official online documentation.

If you do RESTful services development restclient is going to be your best companion.

restclient turns normal text buffers into executable HTTP requests ideal to tests your webservices.

For example, create an empty buffer, activate the move via M-x restclient-mode then write your HTTP requests like:

#
# retrieve your current IP address
#
GET http://ifconfig.co/ip


#
# retrieve the geolocation city info
#
GET http://ifconfig.co/city
Accept: text/plain


#
# retrieve all as json
#
GET http://ifconfig.co/json
Content-Type: application/json

After each request try to press C-c C-v to execute the request and see the response.

All *.rest files are in restclient-mode by default.

Here a list of all the keybindings for this mode:

• C-c C-c : runs the query under the cursor, tries to pretty-print the response (if possible)
• C-c C-r : same, but doesn't do anything with the response, just shows the buffer
• C-c C-v : same as C-c C-c, but doesn't switch focus to other window
• C-c C-p : jump to the previous query
• C-c C-n : jump to the next query
• C-c C-. : mark the query under the cursor
• C-c C-u : copy query under the cursor as a curl command
• C-c C-g : start a [helm](https://emacs-helm.github.io/helm/) session with sources for variables and requests (if helm is available, of course)
• C-c n n : narrow to region of current request (including headers)
• TAB : hide/show current request body, only if
• C-c C-a : show all collapsed regions
• C-c C-i : show information on resclient variables at point

The way Cider formats the code isn't particularly nice. To format the code properly you need to have a repl running and the code needs to be loaded. Because of this the formatting changes depending on which state your IDE is. I think it is a bad idea. I rather have a less appealing formatting, but which can be done without having to load/compile the code.

(λmacs) performs a reformatting of the code on save with a definition which doesn't take into account which particular form you are in. However, there are times this is not convenient, like when working on someone else code. To disable the code-reformat set the variable lambdamacs/cljfmt-reformat-on-save to nil in the configuration.

(setq lambdamacs/cljfmt-reformat-on-save nil)

You can toggle the value with M-x cljfmt-toggle-reformat.

This is my personal setup, I don't mind you using it and I'd appreciate feedbacks and suggestions on how to improve it! Issue a PR, and if it works for me, I'll merge it!

The code in this repo has is the sum of my personal experience and the following references:

• Emacs Prelude - A great Emacs distribution.
• @bbastov .emacs.d - Bozhidar's Emacs config.
• emacs-live - Another Emacs distribution.
• @daviwil dotfiles - David Wilson's Emacs config.
• Easily, the most elegant Emacs out there!
• Get Things Done with Emacs - From which I took the beautiful CSS for org-mode (thanks).

Thank you to all of you!

Copyright © 2020 Bruno Bonacci and contributors. Distributed under the GNU General Public License, version 3.