A wiki for Spacemacs

Spacemacs with Alchemist is an extremely popular set-up to use for Elixir development. Give it a try by following our guide here and let us know what you think!

http://spacemacs.org - Official SpaceMacs site
http://www.alchemist-elixir.org - Alchemist Elixir site

Installation

We need to install Emacs first, then Spacemacs, then add the Elixir layer to SpaceMacs:

1) Emacs installation

Here are the instructions for OS X (from their wiki). For other platforms look here.

Usual Emacs installation:

brew update
brew install emacs --with-cocoa
brew linkapps emacs

Or, SpaceMacs recommended installation (includes SpaceMacs icon etc):

$ brew tap d12frosted/emacs-plus
$ brew install emacs-plus
$ brew linkapps emacs-plus

2) Spacemacs installation

Then simply backup your original emacs.d folder and install Spacemacs with:

mv ~/.emacs.d ~/.emacs.backup
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d

Once that is done, start Emacs and let it install everything, then restart and Spacemacs config will kick in. Select VIM mode when it asks you.

3) Adding the Elixir layer

Open up your ~/.spacemacs file, and under dotspacemacs-configuration-layers simply add elixir. It should look something like this:

   dotspacemacs-configuration-layers
   '(
     ruby
     ;; ----------------------------------------------------------------
     ;; Example of useful layers you may want to use right away.
     ;; Uncomment some layer names and press <SPC f e R> (Vim style) or
     ;; <M-m f e R> (Emacs style) to install them.
     ;; ----------------------------------------------------------------
     helm
     ;; auto-completion
     ;; better-defaults
     emacs-lisp
     ;; git
     ;; markdown
     ;; org
     ;; (shell :variables
     ;;        shell-default-height 30
     ;;        shell-default-position 'bottom)
     ;; spell-checking
     ;; syntax-checking
     ;; version-control
     elixir
     )

Then simply restart SpaceMacs and it will install everything. That’s it, you now have SpaceMacs installed!!

4) Install Ack or Ag

This will speed up search significantly.

Ack is a tool like grep, optimized for programmers.
Ag is like Ack, but claims to be 5-10x faster.

I’ve opted for Ag, install it in OS X with brew install the_silver_searcher

5) Optional - enable smooth scrolling, NeoTree to right and session restore

Smooth scrolling (source)

Simply add the last 5 lines below to your user-config to defun dotspacemacs/user-config () to end up with something like:

(defun dotspacemacs/user-config ()
  "Configuration function for user code.
This function is called at the very end of Spacemacs initialization after
layers configuration.
This is the place where most of your configurations should be done. Unless it is
explicitly specified that a variable should be set before a package is loaded,
you should place your code here."
  ;; scroll one line at a time (less "jumpy" than defaults)
  (setq mouse-wheel-scroll-amount '(1 ((shift) . 1))) ;; one line at a time
  (setq mouse-wheel-progressive-speed nil) ;; don't accelerate scrolling
  (setq mouse-wheel-follow-mouse 't) ;; scroll window under mouse
  (setq scroll-step 1) ;; keyboard scroll one line at a time
  )

NeoTree on right hand side

If you would like your NeoTree SPC f t to open on the right hand side simple add '(neo-window-position (quote right)) to you custom-set-variables in your .spacemacs file (then restart or reload).

Session restore

Set dotspacemacs-auto-resume-layouts to t in your .spacemacs - this will restore your session when you open SpaceMacs. (You may or may not like this - might be an idea to try it without for a while first.)

6) For Mac users

Adding a font

The default font does not seem to be one shipped with OS X, so open your .spacemacs file (which can also be opened from within SpaceMacs with SPC f e d and under dotspacemacs-default-font swap the font to “Menlo” and change the size to 12.

Adding the OSX layer

In layers, add osx as this will add some common Mac keybindings (such as command and w to close a window, command and + or - to increase/decrease font size etc.

For those with British Keyboards

Add the following to your user-config so that you can use ALT+3 for the hash key:

  ;; Allow hash to be entered
  (define-key window-numbering-keymap (kbd "M-3") nil) 
  (global-set-key (kbd "M-3") (lambda () (interactive) (insert "#")))

Making the Emacs shell respect your .bash_profile

Install exec-path-from-shell by SPC SPC package-install (then start typing exec-path-from-shell)
Then open or create a .bashrc file and at the bottom add . ~/.bash_profile

Getting started with Spacemacs and documentation

• Migrating from Vim - This document is intended to supplement the Spacemacs documentation by bridging the gap between vim and Spacemacs.
• SpaceMacs Documentation - The full SpaceMacs documentation

Installing packages

Find the package you want to install on Melpa (the Emacs Package Manager) and then check it is not already installed by SPC h SPC followed by the package name. If it’s not…

• If it’s a layer add it to the layers list in your .spacemacs file and restart
• Otherwise hit SPC SPC <package name> RET and it will install it

Most packages are on Melpa and included by SpaceMacs, but if not, you can add the package name to dotspacemacs-additional-packages and restart to see if it installs, if not then additionally add any downloadable associated files to a directory in your load path.

Spacemacs quick tips

See the thread for more, here are a few worth pointing out:

Opening and reloading config

• You can open your .spacemacs file from within SpaceMacs with SPC f e d
• After making changes with the above, you can use SPC f e R to reload your config (saves having to restart it - but if you want to restart it, you can do SPC q r)

Lookup, viewing docs and misc

• SPC h SPC to open documentation
• Need to lookup up an Emacs function? If you are curious as to what a function is bound to, you can do SPC h d f name-of-function RETURN, e.g. SPC h d f what-cursor-position RETURN
• When you see things that ask you to do something like M-x customise-face that means you have to press SPC SPC and then type in customise-face .
• , is the mode leader, so when something is referenced as SPC m <something> you can simply use , <something>

Searching

• SPC p p - Show projects you have opened previously
• SPC p f - Find file in project
• SPC s s - Swoop search (search in file) (you can also do the usual vim /)
• SPC f f - Find file (fuzzy search)
• SPC f r - Find/show recent files
• SPC / - Find pattern (text) in open file (shortcut for SPC s p)
• SPC * - Same as SPC / but searches what’s under the cursor
• If you ned to search a term exactly, escape the space, e.g.: SPC / see\ the\ posts
• SPC s a p find pattern (text) in project

Windows

• SPC w s to split window SPC w v to split vertically
• SPC w d to delete/close window (or Command W in OS X)

Buffers

• SPC b b to list buffers
• SPC TAB to go to last buffer

NeoTree

• SPC f t open NeoTree
• SPC 0 to select NeoTree window
• SPC 1 to select first (other) window

Shells

• SPC ' open shell (opens in the directory of the file you’re in)
• SPC p ' open shell in root of project

Commenting/uncommenting

• gcc or SPC cl comment/uncomment line
• gc3j to comment an additional 3 lines down (end with k for up)
• v highlight code then gc

Spacemacs Tutorials

• Spacemacs ABC (YouTube) - by Eivind Fonn
• Development Workflow with Spacemacs (YouTube) by Jon Canada (Elixir user)

Spacemacs Blog Posts

• Spacemacs and Alchemist to make Elixir of immortality by Zohaib
• An Absolute Beginners Guide to Spacemacs for Academic Writing
• SpaceMAcs tips by Bebbu - Some getting started tips

Spacemacs Themes

• Check out the Elixify theme (also see the Elixify thread here on the forum).
• Also rake a look at the Code School theme ported from TextMate.

SpaceMacs Gitter Chat

https://gitter.im/syl20bnr/spacemacs - they are very active and helpful in their channel so definitely pay them a visit if you need help

Troubleshooting

If you get any warnings on startup, try SPC b b for buffers and look in ‘messages’.

Alchemist Elixir basic usage

• Alchemist basic usage

Alchemist docs

• Alchemist official docs (for emacs)