OO Emacs

This is my personal emacs configuration.

Principles and Goals

• performant (WIP) Startup should be as fast as possible (ideally less than a second) and consequently my startup time should be as low as possible. Furthermore, the experience while using emacs should be responsive fast and snappy. As of this version, (emacs-init-time) is “3.882691 seconds” without compilation.
• introspectable I want to know what is happening and when it is happening. I want my configuration to be such that I keep track of any changes I make where a “change” could be adding a hook or adding an advice or even binding a key. To this end I use lgr to create an extensive log buffer.
• expressive I want expressive and powerful functions and macros at my disposal that help me do what I want sanely, concisely and with precision.
• stable (WIP) I should be able to count on things working properly. To this end I created tests.
• correct (WIP) My configuration should follow standards determined by the compiler whenever they are reasonable and make sense. Compiling my configuration should result in no warnings.
• reproducable (WIP) I should be able to recreate my exact configuration–with all my external packages and their exact committs. Right now I use package.el but I will eventually migrate to either elpaca or borg.
• well-documented (WIP) Every function and macro should have a thorough docstring explaining what it does. Moreover, each file should have its own commentary explaining its purpose as well as any other tidbits I deem useful.
• tested (WIP) Every function and macro should have evidence that it does what it claims to do in the form of a test. This helps me not only ensure that any refactoring preserves the expected behavior of a function or macro but also it provides me with sanity checks in case something goes wrong.
• easy and predictable to extend It should be easy to add some new functionality to my configuration. All I should have to do is create a file and load it from the right place. I should not have to think about it as there should be a standard procedure.

Features

• Optimized for speed by evaluating macros during compilation (WIP)
• Extensive abbrev configuration with over 1000 abbrevs
• Spacemacs-like keybinding scheme
• Advanced macros such as block! and lef!
• Avoids the use of macros such as use-package, leaf and setup.el
• Gracefully handle errors raised in hooks with custom hook functions
• Extensively log events using lgr
• Custom modeline created with powerline
• Ensures using no-littering
• Automatically kill unused buffers with buffer-terminator

File Structure

• init.el Initialize my emacs configuration.

This means adding the lisp directory to the load-path, loading all of the init-FEATURE.el files, and setting up necessary initial variables.

• lisp/base-SOMETHING.el - Provide configuration functions and macros.

Usually these files will set some initial variables or provide me with macros and functions for helping me configure emacs. These are loaded before.

• lisp/init-FEATURE.el - Initialize FEATURE.

Typically that means adding hooks or advices, setting variables, binding keys and autoloading functions. Crucially, refrain from loading FEATURE or any other features unless absolutely necessary.

• lisp/config-FEATURE.el - Configure FEATURE.

This should not be Loaded immediately because it will require FEATURE. it contains funtionality that is only needed after FEATURE is already loaded. This is meant to be used with eval-after-load: (eval-after-load FEATURE)

• lisp/oo-keybindings.el - Store all of my keybindings.

  This is an exception to the rule of keeping everything involving FEATURE to config-FEATURE.el and init-FEATURE.el in exchange for better modularity and easier profiling of keybindings.

• lisp/oo-SOMENAME - Some file I use but do not know what to do with yet.

These are files that do not fit into the category of the other lisp files I have mentioned. This is an unfleshed out part of my design which needs further consideration and improvement.

• test/BASEFILE-test.el - Test functions and macos provided in BASEFILE.

  Use ert to thoroughly test functions and macros in BASEFILE. These test are designed to be run with eldev but of course can also be run.

• .local/var/ - Store Persistent data.

  This directory is for storing cache data which is inappropriate to version control. The recentf-save-file is an example.

• .local/etc/ - Store autogenerated configuration.
• .local/share - Store things I want stored but do not want seen.

  For now this just contains screenshots.

Naming Convention (WIP)

I chose the prefix “oo” that I use because it is short and something that I thought would not likely to be the prefix for an emacs package. Also, I thought that the characters oo were smooth an easy to read as opposed to something like xx which I had tried prior. I do not know why I did not do just a single o though I remember having thought about it.

Sometimes if I feel a function is an extension for another feature then I make the extension +FEATURE. I took this idea from doom and my reasoning is that this name is concise and it connotes that it is an extension for said feature.

How to Install

Simply clone the repo. You may also want to install nerd-fonts. Note that my emacs config is not a distribution like doom, spacemacs or prelude. I did not write it with the specific intention of it being used by others.

git clone https://github.com/Luis-Henriquez-Perez/.emacs.d ~/.config/emacs/

Acknowledgements

There are too many to list and thank. I should be thanking all those who have contributed to emacs as well as all the authors and contributors to the packages I use. Additionally, I should thank the writers of countless blog posts, reddit posts and youtube videos I have learned from. Because of my limited memory I will only name a few of these that I remember well.

• d12frosted’s environment

  This configuration inspired me to organize my emacs-lisp files into init and config files, to use eldev and to compile my lisp files. In turn, this lead me to discover standard conventions such as using a copyright header, ending each file with a provide form.

• Doom Emacs

  Doom inspired my naming conventions as well as some macros such as quietly!.

• Spacemacs

  Spacemacs was actually the first framework that I used when starting emacs. It inspired how I organize my keybindings and it also introduced me to evil and gave me the idea to have varying cursor colors.

• Xah Lee

  Xah Lee has created a great repository of information for emacs usage in his website. It is an excellent supplement to the manual.