Note: this article is part of my Emacs For Writers series. It’s a complete tutorial on Emacs for non-programmers.
When you start up Emacs, the question is, “What’s your setup?” Your personal Emacs setup file is read at startup every time Emacs loads. This is where you can load your customization, packages, and preferences. But how does Emacs know which file to check? We’re going to learn about all of this below.
Table of Contents
Emacs Lisp is your customization language
Emacs Lisp is a variant of the Common Lisp programming language used as the backbone of the Emacs ecosystem. Lisp is a very old language that does things its own way, using a lot of parentheses, and a wacky syntax. But don’t worry, you don’t need to be an Emacs Lisp expert to customize Emacs to your liking.
However, you’ll find that learning a little Emacs Lisp will greatly benefit you down the road, even though it’s outside the scope of this tutorial. If you’ve ever searched for a certain Emacs functionality online, you may have landed in an Emacs forum in which someone has suggested a workaround using—you guessed it—Emacs Lisp. There’s no getting around it. At just about every turn in your Emacs journey, you will need to employ some Emacs Lisp here and there in order to get some work done. But that’s OK.
That’s enough background information for now. Let’s move to getting this configuration installed.
How to install your Emacs configuration
To make your onboarding process a little easier, I have gone ahead and set up a starter config for you and hosted it publicly at github.com.
You’ll probably notice some funny things about this configuration. First of all, it’s in an Org Mode file. That’s right. Org Mode lets you store code inside of the source block snippet that can be run in other contexts.
It’s good for you to see this, because many Emacs users manage and document their configuration inside Org Mode files and then compile, or “tangle,” the code to different places.
In this case, you can tangle the code from this config file by downloading it, opening it, and running C-c C-v t. But before you do that, be aware that this will overwrite your existing .emacs file with the code from the config.org file.
As an alternative, you can copy and paste sections of the Org file into your own personal configuration to see what they do. It’s your choice. Watch the video above for a live demonstration of how the tangling process works.
If you’re curious about what’s inside the config, you will notice that the paragraphs surrounding the code snippets, as well as comments inside the snippets explain what each section does. I also talk more about it in the video above.
Common errors you might see on startup
GNU Emacs is a richly documented program with a lot of built-in complexity. When something fails, the program tries to give you as much information as possible to help you debug it. Here are a few common errors you might see if your Emacs fails on startup.
No such file or directory
This means you are trying to load or access a file that Emacs does not recognize or does not exist.
For example, I might have something like this in my config:
(load-file "~/Desktop/hp1.txt")
Everything about this function is correct. The load-file declaration loads the contents of a file into Emacs. The problem here is the file I tried to load does not exist in my system, so I get an error:
Cannot open load file: No such file or directory, /home/user/Desktop/hp1.txt
Void function: “Symbol’s function definition is void”
If you are trying to run a function that has not been declared or is incorrect, void, formless, and useless, you might get an error like this:
Symbol’s function definition is void: evil-mode
This error was generated because my configuration tried to load up Evil mode, but I don’t have Evil mode installed (and nor should you). 😉
End of file during parsing
You will usually see this error if you have missing parentheses somewhere in your config. You might have typed something wrong, or accidentally deleted a paren somewhere. (Believe me, I’ve done it all.)
Invalid read syntax
Like the above “End of file during parsing” error, you’ll get an “Invalid read syntax” if you have an extra parentheses somewhere.
Don’t overdo it with your config
Once you get into a config mindset, it’s very easy to go overboard and start trying to configure every little detail of your interface. Believe me, I know from experience. Just look back through my YouTube videos and you’ll see how radically my interface changed over the years.
But no matter how much I tweaked my setup, I threw most of it away and settled back into a minimalist config. It’s your choice, it’s your canvas. I’ll just say this: don’t let your obsessive tweaking get in the way of doing meaningful work.
If you find you’ve gone too far, just throw it all away and start over. Your next setup will be a lot simpler and more organized.
Going deep with Emacs Lisp
If you want to go deeper into Emacs Lisp, there’s a great tutorial that ships with your Emacs installation. Just press C-h i to enter the Help system. Then press “M” and start “Emacs Lisp…” Let your wonderful Vertico expansion do some work for you. From there, select the Emacs Lisp Intro. You may enjoy this.