rde Manual

Table of Contents

Next:   [Contents][Index]


This document describes rde version 0.1, the GNU/Linux distribution, a set of tools for managing development environments, home environments, and operating systems, a set of predefined configurations, practices and workflows.

Next: , Previous: , Up: Top   [Contents][Index]

1 rde

First of all rde is a developer and power user friendly GNU/Linux operating system, ready for use with a few to zero tweaks. Let’s call this part rde GNU/Linux. Currently, it’s targeted for single-user setups, to some extent it can be used by multiple people on the same machine, but with restrictions (see FAQ).

Sometimes, it can be treated as an Emacs distribution, but while GNU Emacs is an important part, in reality rde manages not only Emacs, its packages and configurations, but other software too (which often integrates with Emacs), mostly it’s user space programs and their configurations, let’s call this part rde home. In addition to that, it can be used to manage home environments (see (guix)Home Configuration) on the operating system other than rde GNU/Linux or Guix System.

Note: The project is in an active development stage, API is a subject to change, watch rde-devel mailing list to be up to date with the latest news.

While rde is ultimately hackable and can be completely changed and customized according to someone’s needs, features, programs and configurations provided out of the box has a strong opinionated flavor and follows a number of principles (see Principles). It’s not possible to cover all existing free software, provide sane configurations and integrate it in rde, so we picked a tool for each area based on its technical capabilities, interoperability with the other programs and our own taste. Focusing on only one tool for each job, we can provide good defaults, integrate it deeply with the rest of the system and make it pleasant and effortless to use, but due to flexible design it is always possible to substitute it with other alternative, however it can require some or a lot of work and additional knowledge on the user side.

Take a brief look on the list of some tools we picked:

Window ManagerSway
Login ShellGNU Bash
Interactive Unix ShellZsh
Service Manager/Init SystemGNU Shepherd
Package ManagerGNU Guix
Multimedia FrameworkPipeWire
Video Playermpv
Everything Else (:GNU Emacs

Read the next section to get some ideas behind our choice.

Up: Introduction   [Contents][Index]

1.1 Principles

There is a list of principles we try to follow to simplify decision making process and provide a better understanding of our previous choices for newcommers. If you see some part of rde hardly violating them please let us know.

1.1.1 Primary


Sane keybindings, good contrast, and readable fonts. The environment should be safe and comfortable for long-lasting working sessions


Setup can be easily replicated. It not only helps with sharing and replicating setups, but also provides an ability to rollback to working state in case of missconfiguration or other problems.


Easy to explore, throw out or modify any part of setup. We have strong opinions on various aspects of working environments, but we don’t enforce them.


All state must be explicit and syncable or temporary, that means all the important data is backed up by default. In combination with reproducibility it gives a sense of security and confidence that both your configurations and data are safe.

1.1.2 Secondary

This is a list of additional principles, which we find reasonable and often refer to them.


Not only because of undepowered hardware, but also cause of simplicity. Slim solutions easier to understand, debug and fix.

Energy and battery efficient

Wayland, fast native applications.


Most of workflows and programs should work without network.


Attention-friendly, minimal use of notification and other distractive things.

Next: , Previous: , Up: Top   [Contents][Index]

2 Community

2.1 Approaching The Project

rde is a free/libre software (free as in a freedom), brought by passioned volunteers. It’s not easy to explain the culture of the project, we also don’t have a formal code of conduct, but it seems rde people, who forms the community and its culture are nice, kind, smart, polite and well-minded. We encourage you to join our communication channels, learn how everything usually happens here and try to make this cozy place only better, enjoy.

There are a plenty of useful resources: documentation, manuals, and other learning materials, mailing lists and IRC channels, and of course the source code. Use any or all of them. Some information will be outdated, features will be missing and issues will be appearing, it’s in a nature of software, please share the ideas, concerns, reports, suggestions and ask questions (see Communication), don’t hesitate to provide fixes, features, modifications or even experimental prototypes (see Contributing).

2.2 Communication

The primary way of communication is mailing lists. The development, support, announcements happens here, and there are a few reasons why (see Mailing Lists). For casual discussions, more interactive support or just pleasant pastime we use IRC and Matrix. Don’t be shy, jump in and let us know that you use rde, it will help you make new friends, and will help the project to grow the community and awareness.

2.2.1 Mailing Lists

Mailing lists are persistent and offline-friendly — archives are available and can be explored or even downloaded much later than discussion took place, federated — email is federated, anyone can participate with already existing account from any email server, accessible — archives are additionally available over web-interface, and almost everyone have an email address and can easily join.

There are a few mailing lists you can subscribe and/or post with your existing email account:

2.2.2 Chat

We use IRC as our primary chatting platform for a number of reasons, but the primary one is: it’s hugely accessible — IRC clients available for almost each hardware and software platform, there are of course web and mobile clients as well, no registration or other additional steps are required.

Just join #tropin channel at libera.chat.

IRC is a great tool for a real-time text-based communication. You join the channel when you need or want to and leave any time you desire.

It’s also possible to connect to IRC channel via Matrix bridge using #tropin:libera.chat room handle, learn more here: https://libera.chat/guides/faq#can-i-connect-with-matrix

Next: , Previous: , Up: Top   [Contents][Index]

3 Getting Started

3.1 Trying it

There are several ways to get the taste of rde.

3.1.1 rde Live Image

The primary one is to get the latest ISO image, write it to DVD or USB stick, boot from it and try it.

The image is available here:


To write it to usb stick you can use any software, we provide you with dd example:

# /dev/sdX is your USB stick device, which can be found in sudo dmesg
sudo dd if=rde-live-0.3-x86_64.iso of=/dev/sdX status=progress

After boot in live system, you can want to adjust a few settings.

By default qwerty and dvorak layouts are available. Ctrl is bound to Caps in adition to usual position. Layout can be changed by pressing both shifts simultaneosly. s means a key with a logo, usually placed between Alt and Ctrl. C is for Ctrl, M is for Alt, S is for Shift.

To set other keyboard layouts switch to the fourth workspace (s-4) open Emacs (s-RET), open eshell (s-e), adjust to your preference and type the following commands:

swaymsg 'input type:keyboard xkb_layout "us,ru"'
swaymsg 'input type:keyboard xkb_variant "dvorak,"'

To jump back and forth between workspaces type s-TAB, to launch application use s-S-d.

To get more information about sway settings and keybinding visit ~/.config/sway/config by typing C-x C-f ~/.c/s/c RET.

There are a bunch of useful keybindings for Emacs: s-o for jumping between Emacs windows (usually called panes in other programs), C-g for aborting/cancel actions, M-x for executing Emacs commands (interactive functions), s-r for recompile, C-c C-k for interrupting compilation, C-x C-f for openning file, M-n/p for next/previous thing in minibuffer/eshell history, M-s g for searching a text in files, M-g l for searching text in current file. C-h m to see keybindings and other information about enabled modes.

There are a few keys, which can be useful for navigating info: C-h i to open info, m for menu, i or I for working with indecies, ^ or u go up in the document structure, l go back to previous place.

To change timezone use eshell and the following commands:

# Find appropriate timezone, Etc/UTC for example
sudo cp $TZDIR/Etc/UTC /etc/localtime
# Waring: this command can reset some settings, like keyboard layout
swaymsg reload

To start interacting with the community you can join IRC by calling M-x rde-erc-connect or erc-tls. Say hi, ask for help or just hangout around.

After all or some of the corners of live operating system are explored, you can proceed with installation (see Installation). Alternatively, you can use a current Guix System installation and just use rde on top of it, the steps will be similiar.

3.1.2 rde home on Foreign Distro

The secondary option is to use rde on already existing non-Guix operating system with guix command available. On Debian GNU/Linux and derivatives Guix can be installed and started in two commands:

sudo apt update && sudo apt install guix
sudo systemctl start guix-daemon

After that you can use rde home as usual or even proceed with full operating system installation (see Installation).

3.1.3 rde as a Channel

Some advanced users may prefer to use only parts of rde they are interested: features, services, or just packages.

In that case you can add the following channel to channels.scm.

  (name 'rde)
  (url "https://git.sr.ht/~abcdw/rde")
     "2841 9AC6 5038 7440 C7E9  2FFA 2208 D209 58C1 DEB0"))))

3.2 Installation

For now this section will be just a bare minimum to get started, later more details will be added.

3.2.1 Writing Config

The simpliest way is to take example configuration, explore it and edit according to your needs. Live image contains ~/rde-configs, which is a real-world full-blown rde configuration.

The other option is to craft the configuration from scratch, take rde-config record declaration from example configuration and remove all the features and start adding them one by one, expanding the scope covered by the configuration.

3.2.2 Applying Config

There is a Makefile in example configuration, it contains various targets for reconfiguration, building and initialization of home environment, operating system and guix profiles, use them directly or just as an example to create your own targets. To navigate through the list of targets can use imenu (M-g i). To actually run the target use compile emacs command, just type M-x compile RET and type the name of the target, after you started typing part of the target name, corfu (see Corfu) will show a tooltip with a list of available options.

Most of the targets uses ${GUIX}, which points to the guix binary, it helps to make sure builds are reproducible, but you need to create this binary by calling make rde/profiles/guix, it will generate a guix binary based on the content of rde/channels-lock.scm. After that feel free to experiment with other targets.

On foreign system you are mostly interested in */home/* targets, but if you manage your whole operating system with GNU Guix pay attention to */system/reconfigure or if installing a fresh OS take a look at cow-store and */system/init targets.

To get more information about installation process read See (guix)Manual Installation, skip unrelated sections like keyboard configuration and keep in mind that we already have cow-store and */system/init targets in Makefile for you.

Happy hacking, see you in a bit in the next section.

Next: , Previous: , Up: Top   [Contents][Index]

4 Features

rde feature is a building block of rde configuration.

TODO: Write here information about rde values, feature fields and basic conventions. Integration between features based on rde values.

4.1 rde Emacs

TODO: Write a paragraph about importance of Emacs in rde setup. Deep integrations, consistent and uniform interface.

4.2 Getting Help

4.3 Key Bindings

The most frequent actions are usually binded to combinations using s- modifier, where s is super key (see (Emacs)Modifier Keys). s-RET to launch emacsclient, s-TAB switch back and forth between workspaces, inside Emacs s-e for toggle eshell, s-b for switch buffer, s-b for recompile.

Note: As you can see we use Emacs notation for keybindings. We expect reader to be familiar with basic terminology, if you are not yet See (Emacs)User Input, and See (Emacs)Keys.

All of the key bindings are organized in keymaps (see (Emacs)Keymaps), and usually keymaps are binded to prefix keys. For example goto-map is binded to M-g prefix, M-g g will invoke goto-line or similiar command. Keymaps can overlap, for example you can bind M-g s in global-map and o in goto-map, the both M-g s and M-g o will coexist. Also, one keymap can shadow binding of another, more information is available in Emacs manual.

There are two important tricks, which used often in key bindings: continous modifiers and double tap. If you want to make it easier to type a key sequence, use the same modifier: M-g M-l is much easier to press than M-g C-l, because in the first option you press modifier once and hold it, after that you type gl and in the second you press and hold Meta, press g, release Meta, press and hold Control, press l.

Note: Some actions are bound to RET, TAB, etc and on regular keyboards it can be inconvinient to reach for such keys, especially in long key sequences. In such cases C-m, C-i (see (Emacs)Named ASCII Chars) can be used. For example C-x C-f C-n C-n C-m will open the second file in find-file dialog.

If the command is frequently used bind it to the same key as well: M-g M-g for goto-line or similiar action, C-c C-c for finishing org capture operation, git commit message or other action depending on the context, s-b s-b switching back and forth between current and previous buffer.

The last example is a little special, because it’s not a key sequence, but two actions bound to the same key, first one is switch-to-buffer defined in the global-map, bound to s-b and the second one is exit-minibuffer defined in minibuffer-local-map, bound to the same key, after the first press, when the minibuffer spawned for picking a candidate, minibuffer-local-map is activated and s-b shadowed with exit-minibuffer. While implementation is a little special the idea is still the same.

4.4 Navigation

4.5 Completion

There are a lot of places, where completion happens, but most of the heavy work is usually done in Emacs, and this section is focused on it. Other applications can try to mimic a fraction of its power and work in a similiar way to some degree, and we try to configure them to do so, but there are no guarantees.

The primary completion mechanism is tightly related to minibuffer (see (Emacs)Minibuffer) and internally utilize completing-read function (see (Elisp)Minibuffer Completion). Minibuffer usually used for reading values and dynamically adjust the behavior of command. To simplify this process prompt, default value, possible options and predicates checking the value can be provided, based on it the completion facilities help to input correct value(s) or narrow the list of options and pick apropriate candidates.

The way completion candidates are presented, updated, sorted, selected, the way hotkeys work and other aspects depend heavily on minibuffer completion UI. At the moment of writing rde preferred UI is Vertico, the reasons for this choice are described in the corresponding section (see Vertico). The way they get filtered depends on completion styles (see (Emacs)Completion Styles) for particular completion category (see (Elisp)Programmed Completion), in addition to built-in styles, rde uses Orderless package and respective completion styles (see Orderless).

The second completion mechanism is In-buffer Completion

4.5.1 Completing Files

You can use future history M-n to insert file under the point into minibuffer prompt. Place a point on file, type C-x C-f M-n C-m, boom, you are viewing/editing a file! If there is no file under the cursor or you type M-n twice, current file will be inserted to the prompt by future history. (see (Emacs)Minibuffer History)

4.5.2 Sources of Completion Consult Cape

4.5.3 In-buffer Completion

There are a few different completion mechanisms, which can be used for completing text in buffer. Abbreviations, Dynamic Abbreviations, Snippets and Completion At Point. Abbreviations

The first and one of the simplest completions in buffer can be done. Define abbreviations (see (Emacs)Defining Abbrevs) either interactively or programmatically. Expand abbreviation with expand-abbrev, which usually bound to C-x '. Alternatively abbrev-mode can be enabled and typing space or punctuation characters will automatically expand abbreviation. Dynamic Abbreviations

The second and one of the most versatile completion can be done with dabbrev-completion, which is bound to C-M-/, it will present a list of words, which were used before in current buffer and have the same prefix as text before point. While the list of candidates can be not preciese or sometimes even meaningless for current position, it works in almost any buffer in almost any mode.

The list of candidates can be expanded by the prefix argument C-u C-M-/ will also provide candidates from friendly buffers, C-u C-u C-M-/ will use all buffers for searching candidates.

dabbrev-expand expands current text instead of giving a list of candidates, it’s bound to M-/ and can used multiple times in a row to go further in the list of expansion candidates.

For more information See (Emacs)Dynamic Abbrevs. Completion at Point

CAP is a very generic in-buffer completion mechanism, it tries functions from completion-at-point-functions and when one of them succeed, shows a list of candidates in buffer, minibuffer or overlay depending on completion UI (see Completion). It can be used for almost everything: completing emails, programming constructs provided by REPL or LSP, words, snippets, emojis, anything else.

CAPFs usually added automatically by lsp package, major-mode, but can be added manually by user as well, also a few CAPFs can be combined in a superCAPF in case you need candidates from different CAPFs be in the same list all at once. For generally useful CAPFs take a look at Cape package (see Cape).

Usually CAP triggered by completion-at-point function, often bound to C-M-i in many modes. If tab-always-indent has value 'complete, TAB can trigger completion-at-point as well. UIs like Corfu can trigger CAP automatically after timeout and when enough number of charactors is present (see Corfu). TempEL snippets

Tempel is a simple template package, it uses tempo syntax and integrates well with CAPF and abbrev. More information about templates syntax read See (TempEL). Various rde features can extend a list of available templates using home-emacs-tempel-service-type.

For expanding templates you have several options: Type the full template name and use expand-abbrev, which is usually bound to C-x ', type <PART_OF_THE_TEMPLATE_NAME_MATCHING_COMPLETION_STYLE and use compeltion-at-point (alternatively if you use corfu (see feature-corfu), the list will be shown automatically), by default feature-emacs-tempel automatically adds its capf by hooks specified in tempel-capf-hooks, this capf prepended to the list of capfs, but triggered only when the string start with tempel-trigger-prefix (< by default) or call tempel-insert, which bound to M-+ by default.

4.5.4 Completion Styles Orderless

4.5.5 Annotations Marginalia

4.5.6 Vertico

It’s a well-implemented, hackless and simple, well-integrated with built-in Emacs mechanisms, performant, but still quite flexible and powerful minibuffer completion UI. MCT, built-in completion buffers, icomplete and other similiar packages can work well, but some more sophisticated solutions like helm, ivy won’t be a good fit for rde due to custom implementation of functionality (alternatives for which later appeared in Emacs itself like completion annotations) and thus they will have a lower integration quality and user experience consistency.

Having a buffer based completion, like builtin one or mct allows for more sophisticated actions, for example to search through annotations and not only candidates themselves using isearch. It can be treated as a downside of minibuffer-based completion UIs, however, in most cases it’s possible to export a list of candidates using embark (see Embark) and perform the same operations on it.

Vertico configuration in rde is quite minimalistic and intuitive, some commands/categories will be presented differently (in other window or in one line/ido-like), it’s done to provide more room for commands, which works better, when there are more candidates visible at the same time and provide less distraction, when it’s enough to show only a few items in one line without annotations.

4.5.7 Corfu

Corfu provides a UI for Completion At Point functions, similiar to the one you usually see in IDEs (a small tooltip near the point). Corfu sets completion-in-region-function and after that completion-at-point starts showing this little overlay completion UI, completion candidates a generated using completion-at-point-functions, which provided by many major modes and separate packages like cape (see Cape), usually other features sets them automatically, but nothing stops anyone to adjust it to his liking.

Corfu supports completion styles, including orderless, use M-SPC to insert space without closing completion UI.

Use M-h/M-g to quickly review documentation/source code for selected candidate and C-M-v/C-M-V to scroll other window.

Use M-m to move candidates to minibuffer, it maybe helpful if you want to apply embark (see Embark) actions or just get more room.

4.5.8 Embark

4.6 Shells

4.6.1 Bash

rde uses GNU Bash (see (Bash)) with minimum customizations as a login shell (see (Bash)login shell), it’s available on many foreign distributions and usually used as a login shell for user, so it won’t require any additional setup or admin privileges to change some system settings while using rde home.

4.6.2 Zsh

However, the default shell is zsh (see (zsh)), in contrast to login shell, setting the default shell doesn’t require admin privileges. The configuration is quite customized to provide a good out of the box experience.

4.6.3 Eshell

Due to Emacs-centric approach of rde, eshell (see (Eshell)) is intended to be the primary shell for everyday use. It’s not a POSIX-complaint, and is not a shell you can use in usual terminal emulator. It feels somehow similar to bash and zsh, but has a deep integration with Emacs and Emacs Lisp.

4.7 Terminals

There is a notion of default and backup terminals in rde, the former is a terminal emulator intended for everyday use, the latter is one, which can be used for recovery work or during migration from usual CLI-based to Emacs-based workflows.

rde uses emacsclient (see (Emacs)Emacs Server) as a default terminal, while emacsclient itself isn’t a terminal emulator, it can launch term, ansi-term or vterm. The latter is a full-fledged terminal emulator, which works inside Emacs and recommended as an alternative to a separate terminal applications, also, when feature-vterm is enabled vterm is bound to s-t and due to key binding approach (see Key Bindings) can be easily invoked with s-RET s-t. In addition to that in many cases the terminal emulator isn’t needed and you can just spawn eshell directly with s-RET s-e.

4.7.1 vterm

4.8 Emacs Regular Expressions Cheatsheet

[[:space:]] +? non-hungry version (see (Elisp)Regular Expressions) (see (Emacs)Regexps)

4.9 Programming Languages

4.9.1 Clojure

4.10 Finances

(ledger3) and (ledger-mode).

4.11 Graphical Environment

4.11.1 Screen Capture

There are 3 primary utilities for creating and modifying screenshots:

  1. shot-output, which captures the current sway output and saves it to clipboard.
  2. shot-window-or-selection, which can capture either window under cursor (if clicked), or region (if region is selected with mouse).
  3. swappy-clipboard, which allows to edit the current content of the clipboard and save it back to it or file.

The usual workflow is following: capture something (output with s-print, window or region with s-S-print), insert the content of clipboard to any application you want (browser, instant messanger, etc). If you need to modify the content of clipboard (add a label, highlight something or make an arrow pointing to important object, etc) or save it to the file use s-M-print.

Next: , Previous: , Up: Top   [Contents][Index]

5 Contributing

5.1 Sharing Feedback

The easiest way to contribute is to let us know you use rde. Explaining how you use it and sharing constructive feedback will help the project even more.

5.2 Sending Patches

The process is similiar to many FLOSS projects, just send patch or series of patches on rde-devel mailing list.

5.3 Commit Messages

There are a few subsystem system: for system services, home: for home services, packages: for packages, rde: for rde features, use them and module/object you modify without prefix. Use present simple, add period at the end of the subject line. Elaborate on the reason behind change in the message body. For example:

rde: emacs: Update %default-emacs-package to emacs-next-stable.

This prevent clipboard issue from happening.

TODO: Add contribution checklist

Next: , Previous: , Up: Top   [Contents][Index]

6 Tips and Tricks

6.1 guix build

Building a package from the local sources.

GUILE_LOAD_PATH=path/to/src guix build -e '(@ (your module name) package-name)'

Next: , Previous: , Up: Top   [Contents][Index]


TODO: Write about multi-user usage.

Next: , Previous: , Up: Top   [Contents][Index]

8 Acknowledgments

The project is inspired by Nix and GNU Guix, technically it heavily relies on Guix Home, Guix System and GNU Emacs, but it also take inspiration in Nix’s home-manager, NixOS and Nix itself. Some parts of rde become a part of Guix, different packages or services, additions to build system and some bigger parts like guix home, sometimes ideas drift from GNU Guix and its community to rde and we are very greatful for insights, collaboration and all the help.

rde won’t be possible without GNU, Emacs and many other Free/Libre and Open Source projects, much kudos to all of them.

Previous: , Up: Top   [Contents][Index]

Concept Index