Rational Emacs

A sensible starting point for hacking your own Emacs configuration.

Please note: rational-emacs is under active development. While the intent of this project is to provide a stable Emacs configuration for use by anyone, it is not yet stable enough for everyday or production use. The rapid pace of changes could cause your configuration to break on your next pull of the repository. If you are not expecting or prepared to encounter such issues, we would recommend you wait for things to stabilize a bit before using.

Quick Start

Install emacs >= 27.2 from your distribution’s repositories.

Clone this repository to ~/.emacs.d or ~/.config/emacs:

git clone https://github.com/SystemCrafters/rational-emacs ~/.config/emacs

This will set up the minimal configuration. If you’d like a more fully-configured experience, copy the example-config.el to ~/.rational-emacs/config.el and restart Emacs.

Principles

This configuration and all associated modules intend to follow the below priniciples.

NOTE: Some of these may change over time as we learn from this process.

Minimal, modular configuration

The core configuration only sets up Emacs to have a cleaner presentation with sensible defaults. It is up to the user to decide which of the various rational-* modules to load and when to load them.

Configuration modules should depend on other modules and the base configuration as little as possible. When a configuration module needs to integrate with other functionality in Emacs, the standard extensibility points of each package should be used (instead of expecting our own configuration module).

The implication is that someone should be able to install or copy code from a rational-* module into their own configuration without using Rational Emacs.

Prioritize built-in Emacs functionality

Where possible, we will leverage built-in Emacs functionality instead of external packages, for example:

• project.el instead of Projectile
• tab-bar-mode instead of Perspective.el, persp-mode, eyebrowse, etc
• eglot instead of lsp-mode (because eglot prioritizes built-in functionality)
• Possibly vc-mode by default

Works well in the terminal

Some people prefer to use Emacs in the terminal instead of as a graphical program. This configuration should work well in this case too! This also enables the use of Emacs in Termux on Android.

Can be integrated with a Guix configuration

It should be possible to customize aspects of the Rational Emacs configuration inside of a Guix Home configuration so that things like font sizes, themes, etc can be system-specific.

It can also use packages installed via the Guix package manager instead of package.el.

Works well with Chemacs2

Chemacs2 is an excellent tool for enabling the use of multiple Emacs configurations simultaneously. This configuration will behave well when used with Chemacs2 so that users can try and use different Emacs configurations as needed.

Helps you learn Emacs Lisp

Instead of providing a higher-level configuration system out of the box like other Emacs configurations, we follow standard Emacs Lisp patterns so that you can learn by reading the configuration.

Why use it?

Why choose this configuration over Doom Emacs, Spacemacs, Prelude, or others?

The goal of this configuration is to make it easier to write your own Emacs configuration while using pre-made configuration parts maintained by the community. Instead of using a monolithic, all-encompassing approach, we strive to ensure that all parts of this configuration are optional or interchangeable.

You should even be able to use the configuration modules we provide with your own init.el file without using this base configuration repo!

Modules

Here is a list of the built-in modules that you may load. They are located in directory $RATIONAL_EMACS_HOME/modules, which are in the directory your git clone from listing li#git_clone. Follow the links to each to get more information about how they can be configured!

rational-defaults

Sensible default settings for Emacs

rational-ui

Extra UI configuration for a better experience (mode line, etc)

rational-completion

A better selection framework configuration based on Vertico

rational-evil

An evil-mode configuration

rational-windows

Window management configuration

rational-use-package

Configuration for use-package

Modules that we will be adding in the future:

rational-desktop

A desktop environment centered around EXWM

rational-present

Tools for giving presentations

rational-screencast

Tools for doing screencasts

rational-workspace

An improved workspace experience based on tab-bar-mode

rational-shell

A starter configuration for eshell and vterm

Customization

To add your own customization to this configuration, create a configuraton file in one of the following places:

• ~/.rational-emacs/config.el
• ~/.config/rational-emacs/config.el

In your configuration you can set any Emacs configuration variable, face attributes, themes, etc as you normally would.

If you prefer to explicitly control where your config.el and early-config.el are found for Rational Emacs, you may provide a value for the RATIONAL_EMACS_HOME environment variable, either on the command line or in your shell configuration. This variable should only contain the path to the config.el files, for example:

RATIONAL_EMACS_HOME=~/my-rational-emacs-config

How the rational config file is found

The rational config files (config.el and early-config.el) are found in the rational-config-path. That path will match exactly one of the following scenarios, in the order specified:

• Using Chemacs2 (See below for more on this)
  • The environment variable RATIONAL_EMACS_HOME is used if provided in the profile definition.
  • The rational-emacs subdirectory of the profile is used when no environment variable is provided in the profile definition.
• Use the value found in the RATIONAL_EMACS_HOME environment variable.
• The environment variable XDG_CONFIG_HOME is present or the path $HOME/.config/rational-emacs exists.
  • These normally resolve to the same file, so build the path from the XDG_CONFIG_HOME environment variable or the explicit path ~/.config/rational-emacs
• Use the HOME environment variable to make the path, which expands to $HOME/.rational-emacs.

Once the rational-config-path is determined, if it does not exist in the filesystem, it is created. However, just the path is created, the files config.el and early-config.el must be created by you.

Example Configuration:

(require 'rational-defaults)
(require 'rational-screencast)
(require 'rational-ui)
(require 'rational-editing)
(require 'rational-evil)
(require 'rational-completion)
(require 'rational-windows)

;; Set further font and theme customizations
(custom-set-variables
 '(rational-ui-default-font
   '(:font "JetBrains Mono" :weight light :height 185)))

(load-theme 'doom-snazzy t)

;; To not load `custom.el' after `config.el', uncomment this line.
;; (setq rational-load-custom-file nil)

The custom.el file

The custom.el file will hold the auto-generated code from the Emacs Customization UI, and other packages that similarly add code to the variables and faces form in the init.el file.

Simplified overview of how Emacs Customization works

Customizable values are defined with the defcustom form, and can be customized using the Easy Customization UI. A complete discussion is out of scope for this document, instead see the Emacs Manual for more information.

There are several states a value can be in, for our purposes, we will only consider two of them: the default state and the changed state. These are not the “official” names but easily convey the concepts of the variable. If a value is in the default state, looking in the Customization UI, the state will be listed as STANDARD. Rational Emacs takes the approach of using the customize-set-variable to update the values defined with defcustom. This will show the values as SET for current session only in the Customization UI. This is normal since the values are set each time emacs starts. They are technically “SAVED” since they exist as emacs-lisp code, but since they are not in a custom-set-variables form the Customization UI only sees them as “SET for the current session only”.

A SAVED and set value means the Customization code has written the configuration to disk to be loaded again the next time Emacs starts. When Emacs saves the configuration from the Customization UI, it simply adds a couple of forms to the end of your initialization file (typically init.el), with comments warning about having more than one form with the same name:

(custom-set-variables
 ;; custom-set-variables was added by Custom.
 ;; If you edit it by hand, you could mess it up, so be careful.
 ;; Your init file should contain only one such instance.
 ;; If there is more than one, they won't work right.
 '(rational-ui-default-font '(:font "JetBrains Mono" :weight light :height 185))
 '(rational-ui-display-line-numbers t))
(custom-set-faces
 ;; custom-set-faces was added by Custom.
 ;; If you edit it by hand, you could mess it up, so be careful.
 ;; Your init file should contain only one such instance.
 ;; If there is more than one, they won't work right.
 )

Loading the custom.el file

When rational-load-custom-file is non-nil (the default), the custom.el file is loaded after the initialization process, including after the user config.el is loaded.

The customization variable values (as set in init.el with customize-set-variables) are in the SET for current session only state, unless altered by a saved customization loaded from custom.el. Any values set through the Customization UI or other work flows, for example by using the org-agenda-to-front or org-remove-file functions, which write to the custom-set-variables form, are preserved in the custom.el file if they are saved for future sessions (as by the Customization UI widget, or by code).

Not loading the custom.el file

To not load the custom file, change the value for the rational-load-custom-file to nil in your config.el.

Using customize-set-variable in Emacs Lisp has the same effect as using the Customization UI, except the customization is not saved to custom.el as if you had used the Customization UI and used the widget to save the customizations for future sessions.

If you choose to follow this pattern, customizing variables in your config.el only (not using the UI) then you may never need to load custom.el. However, there are some caveats: using certain work flows with Org Agenda files or risky variables in .dir-locals.el which write to the custom.el file will never be applied, even though they are saved in the custom file.

Using it with Chemacs2

If you have the Chemacs2 configuration cloned to ~/.emacs.d or ~/.config/emacs, you can clone rational-emacs anywhere you like and add an entry to it in your ~/.emacs-profiles.el file:

You can then put your early-config.el and config.el files in the subfolder ~/path/to/rational-emacs/rational-emacs. So, for example if you installed Rational Emacs to ~/.rational-emacs, then your early-config.el and config.el files would be in the path ~/.rational-emacs/rational-emacs. This is the default path, but you can change the name to something else, see below for examples.

(("rational" . ((user-emacs-directory . "~/path/to/rational-emacs"))))

If you prefer to put your Rational Emacs customizations elsewhere (for example in a folder called `config` or maybe `personal`), you can specify the RATIONAL_EMACS_HOME environment variable, for example like this:

(("rational" . ((user-emacs-directory . "~/path/to/rational-emacs")
                (env . (("RATIONAL_EMACS_HOME" . "~/path/to/rational-emacs/personal"))))))

Or some place completely different:

(("rational" . ((user-emacs-directory . "~/path/to/rational-emacs")
                (env . (("RATIONAL_EMACS_HOME" . "~/rational-config/personal"))))))

Then launch it with emacs --with-profile rational!

Contributing

This is a community-run modular Emacs configuration, for which we appreciate feedback in the form of issues and pull requests. Feel free to open an issue prior to opening a pull request if you’re not certain your idea is in the spirit of the Principles.

If you enjoy crafting your computing experience, join the SystemCrafters community!

License

This code is licensed under the MIT License. Why? So you can copy the code from this configuration!

---