rde Manual

Table of Contents

Next:   [Contents][Index]

rde

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 user space software too (which often integrates with Emacs), 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:

PurposeTool
Window ManagerSway
TerminalAlacritty
Login ShellGNU Bash
Interactive Unix ShellZsh
Service Manager/Init SystemGNU Shepherd
Package ManagerGNU Guix
FilesystemBtrfs
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

Ergonomic

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

Reproducible

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.

Hackable

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.

Stateless

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.

Lightweight

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.

Offline

Most of workflows and programs should work without network.

Peaceful

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.

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 use 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:

https://trop.in/rde/current-live/amd64/rde-live-latest-amd64.iso

TODO: Actually make a live ISO and upload it.

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.

(cons*
 (channel
  (name 'rde)
  (url "https://git.sr.ht/~abcdw/rde")
  (introduction
   (make-channel-introduction
    "257cebd587b66e4d865b3537a9a88cccd7107c95"
    (openpgp-fingerprint
     "2841 9AC6 5038 7440 C7E9  2FFA 2208 D209 58C1 DEB0"))))
 %default-channels)

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.

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, we try to configure them to do so, but there are no guarantees.

4.5.1 Dynamic Abbreviations

The first and 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.

4.5.2 Completion At Point

C-M-i completion-at-point

4.5.3 Consult

4.5.4 Vertico

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 Programming Languages

4.8.1 Clojure

4.9 Finances

(ledger3) and (ledger-mode).

4.10 Graphical Environment

4.10.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 the content of clipboard to file use s-M-print.


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

5 Installation


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

6 Contributing


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

7 Tips and Tricks

7.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]

8 FAQ

TODO: Write about multi-user usage.


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

9 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