rde

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.

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:

• ~abcdw/rde-announce@lists.sr.ht for news and updates.
• ~abcdw/rde-discuss@lists.sr.ht for questions, discussions and support.
• ~abcdw/rde-devel@lists.sr.ht for patches, development related discussions and bug reports.

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

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:

http://files.trop.in/rde/

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.5-x86_64.iso of=/dev/sdX bs=32M status=progress oflag=sync

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:

ls $TZDIR
# 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.

(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)

3.2.1 Writing Config

The simpliest way is to take example configuration, explore it and edit according to your needs. Live image contains ~/example-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 target/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.

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
• Dynamic Abbreviations
• Completion at Point
• TempEL snippets

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.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.1 vterm

4.9.1 Slack

There is a Slack feature which allows you to access Slack workspaces via the emacs-slack client.

For authentication to work, you need to ensure you have set an Auth source back-end (see (Auth)) in Emacs. If you use password-store (see (Auth)The Unix password store), you should have an entry of the form ‘nick@workspace‘ for your Slack token and, if you need a cookie (consult https://github.com/yuya373/emacs-slack#how-to-get-token-and-cookie for details), an entry of the form ‘nick^cookie@workspace‘.

4.10.1 Clojure

4.10.2 Common Lisp

4.10.3 Go

4.10.4 JavaScript

4.10.5 OCaml

4.10.6 Python

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