How to configure spacemacs so that it executes code when you start it?

Question

Foreword

I know the title looks subjective, but I want this question to be a smooth introduction to spacemacs for newcomers not coming from emacs at all (which is my case).

You might wonder why I decided to use spacemacs, which is a highly custom hack over emacs, without taking the time to get used to vanilla emacs first. Well, in fact, I've been trying to use emacs and vim for a long time because I could understand why those software were able to boost productivity and make you feel more "at home" when coding/hacking.
Unfortunately, while I was starting to get used to vim a bit, the time you need to spend in learning, and most of all, the time you need to spend in configuring those software, was way too high for me.
Then I discovered spacemacs, which takes a bit of what is great in vim, what is great in emacs, and put them together into a nice mostly preconfigured package.

The issue is that most of the configuration is done through emacs-lisp, and expects the user to understand how the code is loaded and executed when you start the software, which I completely don't (as I started to realize the more and more I digged into the code).

What I want to achieve

I want to be able to start emacs, and see it execute some custom code I would write so that:

• the line numbers are showing in any buffer I open
• git live changes are shown in the left side
• symbols are highlighted when the cursor is over
• my "home page" show a list of projects and I can load the most recent one, which remembers the buffer configuration from last time

I want to be able to actually code those features (and maybe a bunch of others) when necessary, or install them when they are already available.

What I tried

(and what doesn't work)

I (naively) configured my spacemacs like any lisp/emacs newcomer would do:

(defun dotspacemacs/user-config ()
  "Configuration function for user code.
 This function is called at the very end of Spacemacs initialization after
layers configuration. You are free to put any user code."

  ;; TODO
  ;; - Display whitespaces
  ;; - Install workgroups2

  ;; interface  ;; this works
  (setq powerline-default-separator 'arrow)

  ;; mouse scroll  ;; this works? maybe
  (setq mouse-wheel-scroll-amount '(1 ((shift) . 1))) ;; one line at a time
  (setq mouse-wheel-progressive-speed nil) ;; don't accelerate scrolling

  ;; middle click copy-paste  ;; this works
  (setq x-select-enable-primary t)

  ;; diff-hl  ;; this used to work but now does not
  (diff-hl-flydiff-mode)
  (setq diff-hl-side 'left)

  ;; rust  ;; this works (and seems the right way to do it)
  (add-hook 'rust-mode-hook #'racer-mode)
  (add-hook 'racer-mode-hook #'eldoc-mode)

  ;; neotree  ;; this works? maybe
  (setq neo-show-hidden-files nil)

  ;; toggle preferences  ;; this does not work
  (spacemacs/toggle-automatic-symbol-highlight-on)
  (spacemacs/toggle-line-numbers-on)

  ;; COrrect DOuble CAps  ;; this does not works either (should be a hook)
  (doublecaps-mode 1)
)

The question

I am conscious that there is a concept called "major-modes" and "minor-modes" which apply respectively to all buffers or only specific buffer instances, but I am also very confused about the fact that emacs has its own global and local variables (which seems to be customizable through (setq)), that spacemacs also has variables or methods to customize (spacemacs/toggle-something-on) but also (custom-set-variables), and that most of what I want to do is achievable using "hooks".

The spacemacs documentation leaves me completely clueless because it mostly asumes you know how things work, and the emacs one is like a nuclear plant maintenance guide.

Could somebody at ease with spacemacs give me an "entry point" to understanding those concepts?

I want to be able to answer the questions: "Oh, I want to customize that behavior, where do I need to code? What are the methods I should call? What are the methods I should NOT call? What variable can I change/create? What is actually executed when I put my code here?...etc"

Answer 1

Here is what you need to know to get started:

• The only file you should touch to customize Spacemacs is ~/.spacemacs (or ~/.spacemacs.d/init.el if you prefer having a directory). You shouldn't touch anything within ~/.emacs.d. You shouldn't have any ~/.emacs file neither.

• You should read once through the ~/.spacemacs file in order to see all possible configuration options, they are well documented.

• The ~/.spacemacs file is structured with the following functions:

  • dotspacemacs/layers: This is the place to configure the functionalities of Spacemacs you want, such as the activated layers, the additional packages you need, the excluded packages you don't want, etc… You shouldn't add/remove any variable or code there, just modify existing values.

  • dotspacemacs/init: This is where you can enable/disable the customization offered by Spacemacs, such as changing the leader key, using https for update, turning on line numbers, etc… You shouldn't add/remove any variable or code there, just modify existing values.

  • dotspacemacs/user-init: This is where you will customize Spacemacs before packages are loaded. There are only a few case when this is needed, only when variables should be set before packages are loaded. For instance setting ranger-override-dired to t so that when ranger will load, it will do what is needed to override dired functionalities with its own. Doing this after the package are loaded would not work as it will be to late. If you are unsure about placing customization there or within dotspacemacs/user-config, you are more likely to want customizations in dotspacemacs/user-config. Try there first, and if it doesn't work you can try to set the variable here.

  • dotspacemacs/user-config: This is the place where you'll most likely put all your personal configuration. This will be executed after all packages have been loaded and configured, so it will override any other configuration.

• Emacs configuration is done in Emacs lisp, so you'll need a basic knowledge of it to configure Spacemacs, there is no other way. The really basics:

  • (<function>): function call.
  • (<function> <arg_1> <arg_2> …): function call with arguments.
  • (setq <variable> <value>): set the value of a variable.

Concerning your questions:

Note: I've seen that you said some of these configuration don't work, but they work as expected for me. Please try to request some help on gitter to help you debugging that.

• «the line numbers are showing in any buffer I open»: There exists already a configuration option you can enable for this in the ~/.spacemacs (which one is let as an exercise for the reader :-) ).

• «git live changes are shown in the left side»: I put (setq diff-hl-side 'left) in my user-config and this is working. IIRC this is not possible to customize in Terminal (non-GUI) mode of Emacs.

• «symbols are highlighted when the cursor is over»: This can be toggled on with SPC t h a. You can enable it at start time by calling (spacemacs/toggle-automatic-symbol-highlight-on) from user-config. Be aware that the package providing this functionality have some problems and is incompatible with a few other packages (https://github.com/syl20bnr/spacemacs/issues/2706, https://github.com/syl20bnr/spacemacs/issues/3475).

• «my "home page" show a list of projects and I can load the most recent one, which remembers the buffer configuration from last time»: The list of recent projects should be visible if you have projects within the dotspacemacs-startup-lists variable. Remembering the windows layouts from last time can be done by setting dotspacemacs-auto-resume-layouts to t. You'll have to learn about layouts if you want to be able to use per-project layouts. For instance:

  • SPC p l to open a project in a new perspective
  • Change your window configuration for this project
  • SPC p l allow you to open a new perspective on a project
  • Change window configuration for this project
  • Use SPC l n to switch between projects
  • Quit Spacemacs
  • Start Spacemacs, and get back to your projects with their perspective with SPC l n (only works with dotspacemacs-auto-resume-layouts set to t).

• «TODO Display whitespaces»: Can be toggled with SPC t w for a buffer, or SPC t C-w for all buffers. You can use (spacemacs/toggle-whitespace-globally-on) in user-config to enable it at startup.

• «;; rust»: On develop this is not needed as long as you use the rust layer. It's maybe not on master for now though.

 Some supplementary information

• There are major-mode and minor-mode. These are not related to the fact they apply to only one or all buffers. Instead, each buffer has one, and only one, major-mode (like python-mode, ruby-mode, etc…). Each buffer can have several minor-mode (like linum-mode). Some minor-mode are global in the sense they will affect all buffers, like global-centered-cursor-mode.

• Emacs lisp variables can be global or buffer-local. Changing a global variable will affect all buffers. Changing a buffer-local variable with (setq … will affect only the current buffer. It is possible to change the default value of a buffer-local variable with (setq-default …. This will change the value for all newly created buffers.

  buffer-local variables have default values, but they may be overridden by hooks when entering some given mode. The modify such values for some kind of buffers a function should be added to the hook, for instance:

  (setq-default fill-column 80)
  (add-hook 'mail-mode-hook (lambda () (setq fill-column 72)))
  (add-hook 'python-mode-hook (lambda () (setq fill-column 79)))
  

• Spacemacs indeed provide some toggle functions for some functionalities. They are called (spacemacs/toggle-…) and adding -on or -off at the end enable or disable them.

• (custom-set-variables) is part of the customize part of Emacs, and this should be avoided with Spacemacs for now as their behavior is not well defined (https://github.com/syl20bnr/spacemacs/pull/5168 may solve this).

• «I want to be able to answer the questions: "Oh, I want to customize that behavior, where do I need to code? What are the methods I should call? What are the methods I should NOT call? What variable can I change/create? What is actually executed when I put my code here?...etc"»:

  Spacemacs, like Emacs or vim, is a powerful tool. Like every powerful tool, it requires some time to get used to it, to be comfortable with. If you want to start piloting a plane, you'll not intuitively know what button to press to do this or that. If you want to achieve something, you have to go through a really long manual, or get an instructor. It's the same for Spacemacs. There is a documentation, a quick-start and a migrating from vim documents. They are quite long, but it's because the range of possibilities are as-long as the documents. The other way is to get help from some "instructor", i.e. Spacemacs regular contributors. I would recommend you to come to the gitter room which is quite active and hopefully helpful.