Skip to content

Latest commit

 

History

History
167 lines (126 loc) · 7.57 KB

emacs.md

File metadata and controls

167 lines (126 loc) · 7.57 KB

Emacs

Emacs can be set up in infinitely many ways, depending on your needs and skills.

Emacs consists of a bare-metal core and many many addons written in Emacs Lisp. Some of the packages are built-in, others are in the official repo, and even more are fetched from external repos. Packages provide features and can modify each other.

Because plugging them together takes a lot of effort and basically behaves like your Linux distro just within Emacs, there's Emacs distributions. To name a few:

Spacemacs

The best editor is neither Emacs nor Vim, it's Emacs and Vim!

Spacemacs is cloned to ~/.emacs.d and provides the building blocks for a very well integrated Emacs IDE.

It supports three editing styles (and all available at once): Vim, Emacs and Spacemacs.

Probably best to start with the quickstart guide.

Below is my rough introduction on how you can do things.

JJ's setup

I'll try to present my setup in order to inspire your Emacs experience.

I use Spacemacs with my custom ~/.spacemacs configuration. It's an all-in-one config file which configures and customizes Spacemacs.

The config enables and sets up several features, among them are:

  • C++ and Python semantic autocompletion (with lsp-mode, clangd)
    • Symbol (function, class, variable, ...) reference and definition tracking
  • Git project navigation and tracking (projectile, magit)
    • Project compilation
    • Error highlighting
  • Code snippet template expansion (yasnippet)
  • Perfect codestyle indentation and formatting
  • More custom keybindings
  • ...

In order for C++ semantic indexing to work with openage, symlink the bin/compile_commands.json to the project git root! clangd needs to find this file in a parent dir of the source files so it knows the compiler invocations.

Spacemacs Installation

  • Distribution packages:
    • Install emacs, which is the GNU Emacs system package
    • Install clangd for semantic c++ parsing, usually part of clang distro package
    • Install python-lsp-server for semantic Python parsing
  • Home directory configuration setup:
    • Clone Spacemacs: git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
    • Clone JJ's configs: git clone https://github.com/TheJJ/conffiles ~/.jjconfigs
    • Symlink the Spacemacs config: ln -s .jjconfigs/.spacemacs ~/.spacemacs
  • Launch emacs
    • Wait until initial package setup is complete
    • Press Space to begin

Spacemacs Updates

You need to update 4 things regularly:

  • Emacs (your distro updates do this)
  • Spacemacs (go to .emacs.d and do git pull)
  • .spacemacs-config (go to .jjconfigs and do git pull, or whatever you use to track the .spacemacs)
  • Emacs packages (click on Update Packages or press SPC f e U or run M-x configuration-layer/update-packages)

Spacemacs Basics

You have three input methods active at once: Vim, Emacs and Spacemacs.

  • If you're used to vim, most commands you're used to will probably just work.
  • Most Emacs keybindings work too after you pressed i for the insert mode.
  • Spacemacs bindings start by, who'd have thought it, pressing Space
  • Press ESC to leave the current mode.
  • Press C-g (control-g) to abort whatever input/action you're currently in.

But how can you do anything?

  • I recommend you treat Emacs like Firefox - leave it open all the time
    • you can have many open tabs ("buffers") (centaur for real tabs)
    • you can have many open windows ("frames")
    • you can split the views ("windows")
    • open a new file in running Emacs from the commandline with: emacsclient -n
  • Key combination syntax:
    • C = Control key
    • M = Meta = Alt key
    • S = Super = The key between C and M
    • M-g f = First press Meta and then g, let go of both, then press f
  • Every key (and combination) is bound to a function invocation
    • You can invoke functions directly with M-x
      • What does a keypress do? M-x describe-key
      • Find definitions and documentation of a function: M-x describe-function
  • Quit and Exit:
    • Spacemacs-style: SPC q q
    • Emacs-style: C-x C-c
    • Vim-style: ESC :q
  • Buffer = opened real file (or for any other IO, like logs, ...)
    • Switch to buffer: SPC b b (C-x b)
    • Close buffer: SPC b d (C-x k)
  • File Operations:
    • Open file browser: SPC f f (C-x C-f)
      • Open project: SPC p p
      • Open/switch to project file: SPC p h
    • Save: SPC f s (C-x C-s)
    • Close: SPC b d (C-x k)
    • Browse projects: SPC p p
  • Window and views:
    • Split the view horizontally: SPC w / (C-x 3)
    • Close current view SPC w d (C-x 0)
    • Open a new Emacs window: SPC F n (C-x 5 2)
    • Close current Emacs window SPC F d (C-x 5 0)
    • Open the file browser tree: SPC f t
  • Code naviation:
    • Go to line: M-g g
    • Find definition: , g d (M-g d)
    • Find references: , g r (M-g f)
    • Refactor variable name: , r r
    • Search the whole project code for something M-x projectile-ag
  • Git status, commits, ...:
    • Launch Magit: SPC g s
    • View git-blame: M-x vc-annotate

An open buffer has several active modes:

  • It's major-mode (e.g. c++-mode) and
  • Minor modes (e.g. line-number-mode, auto-completion, ...; see them with M-x describe-mode).
  • Each mode contributes to some behavior of the buffer (basically by providing/registering functions and setting variables).

This design allows you to fully customize and extend Emacs with whatever new feature and behavior you desire.

Some features to start with

You can start these things with M-x, or hack them into .spacemacs once you get going with elisp.

  • Classical menu bars: menu-bar-mode, tool-bar-mode
  • Markdown live editing preview: vmd-mode
  • Git: magit-status
  • Remote over-ssh editing: tramp (just open file with name /ssh:host:path/to/file)
  • Text Search: ag
  • Debugging: realgud
  • File tree: treemacs, speedbar
  • Programming Symbol tree: lsp-treemacs-symbols
  • Syntax check: lsp-treemacs-error-list, flycheck-mode
  • Easy config customization: customize
  • ...

Remember M-x describe-$thing to start digging into $thing!

Your journey

Once you start missing features and wanting to customize the configuration further, please:

  • either branch off my config repo to have your own .spacemacs and you can still merge my changes
  • or start your own .spacemacs config!

Please contact us if you need help or are overwhelmed by the awesomeness!