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.
|• Introduction||What rde is?|
|• Community||The best rde part.|
|• Getting Started||Try, customize and install.|
|• Features||All the parts of rde.|
|• Contributing||Tips and guidelines.|
|• Tips and Tricks|
|• FAQ||Frequently asked questions.|
|• Concept Index||Concepts.|
— The Detailed Node Listing — 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:
|Login Shell||GNU Bash|
|Interactive Unix Shell||Zsh|
|Service Manager/Init System||GNU Shepherd|
|Package Manager||GNU Guix|
|Everything Else (:||GNU Emacs|
Read the next section to get some ideas behind our choice.
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.
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.
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.
Wayland, fast native applications.
Most of workflows and programs should work without network.
Attention-friendly, minimal use of notification and other distractive things.
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).
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.
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:
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
There are several ways to use rde.
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:
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.
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
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).
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)
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.
TODO: Write a paragraph about importance of Emacs in rde setup. Deep integrations, consistent and uniform interface.
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
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.
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
TODO: Mention about tab-always-indent ’complete
TODO: Add a note about future history
The first 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.
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.
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
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.
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.
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.
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.
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
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
[[:space:]] +? non-hungry version (see (Elisp)Regular Expressions) (see (Emacs)Regexps)
(ledger3) and (ledger-mode).
There are 3 primary utilities for creating and modifying screenshots:
shot-output, which captures the current sway output and saves it to clipboard.
shot-window-or-selection, which can capture either window under cursor (if clicked), or region (if region is selected with mouse).
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.
Building a package from the local sources.
GUILE_LOAD_PATH=path/to/src guix build -e '(@ (your module name) package-name)'
TODO: Write about multi-user usage.
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.