_____     _ _              _       ____
  |  ___|_ _| | | _____  _ __( )___  / ___| _ __   __ _  ___ ___ _ __ ___   __ _  ___ ___
  | |_ / _` | | |/ / _ \| '__|// __| \___ \| '_ \ / _` |/ __/ _ \ '_ ` _ \ / _` |/ __/ __|
  |  _| (_| | |   < (_) | |    \__ \  ___) | |_) | (_| | (_|  __/ | | | | | (_| | (__\__ \
  |_|  \__,_|_|_|\_\___/|_|    |___/ |____/| .__/ \__,_|\___\___|_| |_| |_|\__,_|\___|___/
                                           |_|
             ____             __ _                       _   _
            / ___|___  _ __  / _(_) __ _ _   _ _ __ __ _| |_(_) ___  _ __
           | |   / _ \| '_ \| |_| |/ _` | | | | '__/ _` | __| |/ _ \| '_ \
           | |__| (_) | | | |  _| | (_| | |_| | | | (_| | |_| | (_) | | | |
            \____\___/|_| |_|_| |_|\__, |\__,_|_|  \__,_|\__|_|\___/|_| |_|
                                   |___/
             Copyright (c) 2022 S. Varrette <[email protected]>

Personal settings and customization for Spacemacs, the Emacs distribution I'm now using.

The best editor is neither Emacs nor Vim, it's Emacs and Vim! Spacemacs is a new way of experiencing Emacs -- it's a sophisticated and polished set-up, focused on ergonomics, mnemonics and consistency.

It superseeds my previous emacs settings made for Emacs 24 which is now obsoblete.

Installation | Configuration Overview | Usage | Screenshots

Installation

The below installation notes are made for a setup on Mac OS. You will have to adapt them for the other environments. See also Spacemacs Practicalli for general information.

1. (if not done yet) Install Emacs (See emacs-plus for more information.) with Homebrew
   • emacs-plus used to demonstrate some flickering issues that may be annoying, consider emacs-mac port in that case.
   • You may want to run directly make install-emacs-{plus|mac} from this repository depending on the chosen option to run the below commands

# Option 1 (emacs-plus) - 'make install-emacs-plus'
brew tap d12frosted/emacs-plus
brew install emacs-plus --with-spacemacs-icon
brew linkapps emacs-plus
# Option 2 (emacs-mac) - 'make install-emacs-mac'
brew tap railwaycat/emacsmacport
brew install --cask emacs-mac-spacemacs-icon

2. You MUST clone the current repository into ~/.spacemacs.d

git clone https://github.com/Falkor/spacemacs-config.git ~/.spacemacs.d
# Alternative setup (my preferred way to keep things organised):
#     clone into ~/git/github.com/Falkor/spacemacs-config and symlink where appropriate
mkdir -p ~/git/github.com/Falkor/
cd ~/git/github.com/Falkor/
git clone https://github.com/Falkor/spacemacs-config.git
ln -s ~/git/github.com/Falkor/spacemacs-config ~/.spacemacs.d

3. Install Spacemacs into your XDG emacs directory i.e ~/.config/spacemacs and ensure ``~/.config/emacs` points to that directory.
   • use symbolic links for ~/.config/emacs to quickly switch between spacemacs and any other setup (Ex: Doom Emacs, My previous Falkor/emacs-config2 ... )
   • we'll use the develop branch of spacemacs
   • alternatively, you can clone it into the default emacs configuration directory ~/.emacs.d
   • You may want to run directly: make install-spacemacs

cd ~/.spacemacs.d
make install-spacemacs
### In details, default XDG-compliant installation
mkdir .config
git clone https://github.com/syl20bnr/spacemacs ~/.config/spacemacs
ln -s ~/.config/spacemacs  ~/.config/emacs   # emacs config expected in ~/.config/emacs
cd ~/.config/spacemacs
git checkout develop

4. Install some nice fonts (required for the Spacelines-all-the-icons mode-line)
   • You may want to run directly: make install-fonts-darwin

brew tap homebrew/cask-fonts
brew install --cask font-source-code-pro font-meslo-lg-nerd-font

5. You will also need to disable a keybord shortcut set by default on Mac OS for the CTRL-SPC sequence.

   • Go into System Preferences / Keybord / Shortcuts / Input Source and uncheck the settings.

6. Finally, you will have to install a few system packages required for the different layers to work properly. Just run:

make bootstrap

This will install the following packages:

Spacemacs Layer	Required dependency	Installation (if different)
[Ma]git	Delta	brew install git-delta
python	black, flake8, ipython,
ruby	prettier, solargraph
C-C++	rtags
CMake	cmake
shell	shellcheck
solidity	solc	brew install solidity
dash	Dash, sqlite3	brew install dash5 sqlite3

In addition, a few NPM dependencies will be installed to satisfy the LSP layer``

Configuration Overview

A working congiration will be organized within two main directories

Emacs Variable	Value	Description
dotspacemacs-directory	~/.spacemacs.d/	Local [Falkor's] customizations repository
user-emacs-directory	.config/emacs/	User [Spac]Emacs directory

The general layout will be as follows:

~ # HOME
├── .spacemacs.d/      # Clone of THIS repository (dotspacemacs-directory)
│    ├── init.el -> .spacemacs
│    ├── .spacemacs        # Main Spacemacs configuration
│    ├── layers/           # Local layers completing Spacemacs's default ones
│    │   ├── falkor/          # Custom layer 'falkor', holding some of my customizations
│    │   └── savegeometry/    # Custom layer 'savegeometry', saving and restoring window position and size
│    ├── settings/         # Local Spacemacs settings, used to split the global configuration in meaningfull manner
│    │   ├── layers.el        # Definitions of layers to configure and associated packages
│    │   ├── private.el       # private (not tracked) settings (name, email, API etc.)
│    │   └── user-config.el   # functions used to aggregate local settings per topic
│    ├── snippets/
│    └── templates
│        ├── auto-insert
│        └── yatemplates
├── .config/           # XDG configuration diretorie
│   ├── emacs -> spacemacs    # Convenient symlink for reference emacs configuration (user-emacs-directory)
│   └── spacemacs/            # Clone of official Spacemacs repository
[...]

In details:

• The main Spacemacs configuration file (dotfile) .spacemacs holds the global configuration -- see also dotfile content
  • the configuration layers (dotspacemacs-configuration-layers) are defined in settings/layers.el
  • The current list of themes is defined in .spacemacs under the dotspacemacs-themes variable
  • the configuration for user code (part of the function dotspacemacs/user-config in .spacemacs) relies when possible on code defined as functions local-settings/<topic>-config under settings/user-config.el

This repository hosts also local spacemacs layers (see also explaination on layers):

• savegeometry: save and restore window position and sie between Emacs launches
• falkor: my own customizations, to be placed at the last position.

For several reasons, it was not possible to outsource all customization into the falkor which explains why a lot of settings are still set into .spacemacs.

Usage

See spacemacs cheatsheet for a review of the default settings.

In addition, I have imported from my historical emacs configuration my favorite key bindings made compliant with the hybrid editing style. The below tables review the most noticable changes you may want to be aware before using my configuration.

	Normal state	Insert State
Leader key	SPC	CTRL+SPC
META+X	SPC SPC	CTRL+SPC SPC

From that stage, you have access to all Spacemacs key bindings. Indeed, a help buffer (which-key) is displayed each time the SPC key is pressed in normal mode. It lists the available key bindings and their associated commands.

Custom key bindings for the common modes will be documented here.

Magit

To interact with github or gitlab forges, you will have to store the tokens - see official instructions or practicallu forge configs

git config --global github.user USERNAME
git config --global gitlab.user USERNAME

To create a token, use the web interface of the forge/host you want to connect to. Here is a list of pages to do this for certain popular hosts:

• GitHub personal access tokens - 3 scopes are required:
  • repo: grants full read/write access to private and public repositories.
  • user: grants access to profile information.
  • read:org: grants read-only access to organization membership.
• GitLab personal access tokens
  • api is the only required scope.

Once you have your token, you will have to store it in GPG encrypted form under ~/.spacemacs.d/.authinfo.gpg

• Create a file ~/.spacemacs.d/.authinfo with the following content (adapt USERNAME and TOKEN accordingly) -- no comment!

machine api.github.com login USERNAME^forge password YOURTOKEN

• Use SPC SPC epa-encrypt-file to encrypt the file with gpg
  • kill the buffer and check that Emacs is able to open and read the file
  • if yes: delete the file ~/.spacemacs.d/.authinfo

You can check your correct settings by restarting Emacs, enter magit status (SPC g s) and press '@' to enter forge mode, 'a' to add the current repository.

Screenshots

Theme and Modeline

This configuration relies on the doom-tomorrow-day theme (part of the Doom theme megapack for GNU Emacs).

The modeline is based on Spacelines-all-the-icons

Example of a modified buffer in insert state (press 'i' as in Vim):

Idem but un normal state (ESC)

▲ back to top