dotfiles/README.org

#+TITLE: Dotfiles
#+AUTHOR: Christopher James Hayward
#+EMAIL: chris@chrishayward.xyz

#+EXPORT_FILE_NAME: dotfiles
#+ROAM_KEY: https://chrishayward.xyz/dotfiles

#+HUGO_BASE_DIR: docs
#+HUGO_AUTO_SET_LASTMOD: t
#+HUGO_SECTION:
#+HUGO_DRAFT: false

#+NAME: description
#+BEGIN_SRC text
Immutable NixOS dotfiles.
#+END_SRC

#+ATTR_ORG: :width 420px
#+ATTR_HTML: :width 420px
#+ATTR_LATEX: :width 420px
[[./docs/images/desktop-example.png]]

Built for Life, Liberty, and the Open Road.

+ 100% Immutable
+ 100% Declarative
+ 100% Reproducible

* Introduction

This is my personal configuration(s) for GNU/Linux[fn:1] systems. It enables a consistent experience and computing environment across all of my machines. This project is written with GNU/Emacs[fn:2], leveraging its capabilities for Literate Programming[fn:3], a technique where programs are written in a natural language, such as English, interspersed with snippets of code to describe a software project.

#+NAME: file-warning
#+BEGIN_SRC text
This file is controlled by /etc/dotfiles/README.org
#+END_SRC

** Getting Started

1) Download the latest version of NixOS https://nixos.org/download.html
2) Partition drives and mount the file system https://nixos.org/manual/nixos/stable/#sec-installation-partitioning
3) Clone the project to =/mnt/etc/dotfiles= ~git clone git@git.chrishayward.xyz:chris/dotfiles /mnt/etc/dotfiles~
4) Load the default shell environment ~nix-shell /mnt/etc/dotfiles~
5) Install the default system ~sudo nixos-install --flake /mnt/etc/dotfiles#nixos~
6) Reboot and login, start a graphical system with ~startx~

** Making Changes

The ~nixos-rebuild~ command updates the system so that it corresponds to the configuration specified in the module. It builds the new system in =/nix/store/=, runs the activation scripts, and restarts and system services (if needed). The command has one required argument, which specifies the desired operation:

+ boot :: Build the new configuration and make it the boot default, without activation
+ test :: Build and activate the new configuration, without adding it to the boot menu
+ switch :: Build and activate the new configuration, making it the new boot default
+ build :: Build the new configuration, without activation, nor adding it to the boot menu
+ build-vm :: Build a script that starts a virtual machine with the desired configuration

#+BEGIN_SRC shell
# Build and activate a new configuration.
sudo nixos-rebuild switch --flake $FLAKE#$HOSTNAME
#+END_SRC

Instead of building a new configuration, it's possible to rollback to a previous generation using the ~nixos-rebuild~ command, by supplying the ~--rollback~ argument.

#+BEGIN_SRC shell
# Rollback to the previous generation.
sudo nixos-rebuild switch --rollback
#+END_SRC

** Docker Container

It's possible to use parts of this configuration using the container. By default, sandboxing is turned /off/ inside of the container, even though it's enabled in new installations. This can lead to differences between derivations built inside containers, versus those built without any containerization. This is especially true if a derivation relies on sandboxing to block sideloading of dependencies.

#+BEGIN_SRC conf :tangle Dockerfile
# Derive from the official image.
FROM nixos/nix

# Add the unstable channel.
RUN nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs
RUN nix-channel --update

# Setup the default environment.
WORKDIR /etc/dotfiles
COPY . .

# Load the default system shell.
RUN nix-shell /etc/dotfiles
#+END_SRC

* Operating System

NixOS[fn:4] is a purely functional Linux distribution built on top of the Nix[fn:5] package manager. It uses a declarative configuration language to define entire computer systems, and allows reliable system upgrades and rollbacks. NixOS[fn:4] also has tool dedicated to DevOps and deployment tasks, and makes it trivial to share development environments.

#+BEGIN_SRC nix :noweb yes :tangle flake.nix
# <<file-warning>>
{
  description = "<<description>>";

  inputs = {
    <<os-nixpkgs>> 
    <<os-home-manager>>
    <<os-emacs-overlay>>
    <<os-nixos-hardware>>
    <<os-nix-on-droid>>
  };

  outputs = inputs @ { self, nixpkgs, nixpkgs-unstable, ... }: {
    nixosConfigurations = {
      <<host-default>>
      <<host-acernitro>>
      <<host-raspberry>>
      <<host-homecloud>>
      <<host-zero-one>>
      <<host-zero-two>>
      <<host-android>>
    };
  };
}
#+END_SRC

** Nixpkgs

Nixpkgs[fn:6] is a collection of over 60,000 software packages that can be installed with the Nix[fn:5] package manager. Two main branches are offered:

1) The current stable release
2) The Unstable branch following the latest development

#+NAME: os-nixpkgs
#+BEGIN_SRC nix
nixpkgs.url = "nixpkgs/nixos-unstable";
nixpkgs-unstable.url = "nixpkgs/master";
#+END_SRC

** Home Manager

Home Manager[fn:7] provides a basic system for managing user environments using the Nix[fn:5] package manager together with the Nix libraries found in Nixpkgs[fn:6]. It allows declarative configuration of user specific (non-global) packages and files.

#+NAME: os-home-manager
#+BEGIN_SRC nix
home-manager.url = "github:nix-community/home-manager";
home-manager.inputs.nixpkgs.follows = "nixpkgs";
#+END_SRC

** Emacs Overlay

Adding the Emacs Overlay[fn:8] extends the GNU/Emacs[fn:2] package set to contain the latest versions, and daily generations from popular package sources, including the needed dependencies to run GNU/Emacs[fn:2] as a Window Manager.

#+NAME: os-emacs-overlay
#+BEGIN_SRC nix
emacs-overlay.url = "github:nix-community/emacs-overlay";
#+END_SRC

** NixOS Hardware

NixOS Hardware[fn:9] is a collection of NixOS[fn:4] modules covering specific hardware quirks. Unlike the channel, this will update the git repository on a rebuild. However, it's easy to pin particular revisions for more stability.

#+NAME: os-nixos-hardware
#+BEGIN_SRC nix
nixos-hardware.url = "github:nixos/nixos-hardware";
#+END_SRC

** Nix On Droid

Nix On Droid[fn:10] is a deployment of the Nix[fn:5] Package Manager on Android, in a single-click installable package. It does not require =root=, user namespace support, or disabling SELinux, but relies on =proot=. It has no relation to the Termux distribution.

#+NAME: os-nix-on-droid
#+BEGIN_SRC nix
nix-on-droid.url = "github:t184256/nix-on-droid/master";
nix-on-droid.inputs.nixpkgs.follows = "nixpkgs";
#+END_SRC

* Development Shells

The command ~nix-shell~[fn:11] will build the dependencies of the specified derivation, but not the derivation itself. It will then start an interactive shell in which all environment variables defined by the derivation /path/ have been set to their corresponding values.

Import this shell with ~nix-shell /etc/dotfiles/shell.nix~.

#+BEGIN_SRC nix :noweb yes :tangle shell.nix
# <<file-warning>>
{ pkgs ? import <nixpkgs> { } }:

with pkgs;

let
  nixBin = writeShellScriptBin "nix" ''
    ${nixFlakes}/bin/nix --option experimental-features "nix-command flakes" "$@"
  '';

in mkShell {
  buildInputs = [
    git
  ];
  shellHook = ''
    export FLAKE="$(pwd)"
    export PATH="$FLAKE/bin:${nixBin}/bin:$PATH"
  '';
}
#+END_SRC

** Go

Go[fn:12] is an open-source programming language that makes it easy to build simple, reliable, and efficient software. It's statically typed and compiled programming language. It's syntactically similar to C, but with memory safety, garbage collection, structural typing, and CSP-style concurrency.

Import this shell with ~nix-shell /etc/dotfiles/shells/go.nix~

#+BEGIN_SRC nix :noweb yes :tangle shells/go.nix
# <<file-warning>>
{ pkgs ? import <nixpkgs> { } }:

with pkgs;
mkShell {
  buildInputs = [
    go
    gopls
  ];
  shellHook = ''
    export GO111MODULE=on
    export GOPATH=$XDG_DATA_HOME/go
    export PATH=$GOPATH/bin:$PATH
  '';
}
#+END_SRC

** Rust

Rust[fn:13] is a multi-paradigm programming language designed for performance and safety, especially safe concurrency. It is syntactically similar to C++, but can garantee memory safety by using a borrow checker to validate references. Rust[fn:13] achieves memory safety /without/ garbage collection, and reference counting is optional.

Import this shell with ~nix-shell /etc/dotfiles/shells/rust.nix~.

#+BEGIN_SRC nix :noweb yes :tangle shells/rust.nix
# <<file-warning>>
{ pkgs ? import <nixpkgs> { } }:

with pkgs;
mkShell {
  buildInputs = [
    rustup
  ];
  shellHook = ''
    export RUSTUP_HOME="$XDG_DATA_HOME/rustup"
    export CARGO_HOME="$XDG_DATA_HOME/cargo"
    export PATH="$CARGO_HOME/bin:$PATH"
  '';
}
#+END_SRC

** Node

Node.js[fn:14] is an open-source, cross-platform, back-end JavaScript runtime environment that runs on the V8 engine, and executes JavaScript code outside of a web browser. Node.js[fn:14] lets developers user JavaScript to write command line tools, and for server-side scripting to produce dynamic web page content.

Import this shell with ~nix-shell /etc/dotfiles/shells/node.nix~.

#+BEGIN_SRC nix :noweb yes :tangle shells/node.nix
# <<file-warning>>
{ pkgs ? import <nixpkgs> { } }:

with pkgs;
mkShell {
  buildInputs = [
    nodejs
    yarn
  ];
  shellHook = ''
    export NPM_CONFIG_TMP="$XDG_RUNTIME_DIR/npm"
    export NPM_CONFIG_CACHE="$XDG_CACHE_HOME/npm"
    export NPM_CACHE_PREFIX="$XDG_CACHE_HOME/npm"
    export PATH="$(yarn global bin):$PATH"
  '';
}
#+END_SRC

** gRPC

gRPC[fn:15] is a modern open-source, high-performance Remote Procedure Call (RPC) framework that can run in any environment. It can efficiently connect services in and across data centres with pluggable support for load balancing, tracing, health checking, and authentication.

Import this shell with ~nix-shell /etc/dotfiles/shells/grpc.nix~.

#+BEGIN_SRC nix :noweb yes :tangle shells/grpc.nix
# <<file-warning>>
{ pkgs ? import <nixpkgs> { } }:

with pkgs;
mkShell {
  buildInputs = [
    grpc
    grpc-tools
    grpcui
    grpcurl
  ];
  shellHook = ''
  '';
}
#+END_SRC

** C/C++

C[fn:16] is a general-purpose, procedural computer programming language support structured programming, lexical variable scope, and recursion. It has a static type system, and by design provides constructs that map efficiently to typical machine instructions. C++[fn:17] is a general-purpose programming language created as an extension of the C[fn:16] programming language.

Import this shell with ~nix-shell /etc/dotfiles/shells/cc.nix~.

#+BEGIN_SRC nix :noweb yes :tangle shells/cc.nix
# <<file-warning>>
{ pkgs ? import <nixpkgs> { } }:

with pkgs;
mkShell {
  buildInputs = [
    gdb
    ccls
    cmake
    gnumake
    libstdcxx5
    gcc-unwrapped
    llvmPackages.libcxx
  ];
  shellHook = ''
  '';
}
#+END_SRC

** Python

Python[fn:18] is an interpreted high-level, general-purpose programming language. Its design philosophy emphasizes code readability, with its notable use of significant indentation. Its language constructs, as well as its object-oriented approach aim to help programmers write clear, logical, code for small and large projects.

Import this shell with ~nix-shell /etc/dotfiles/shells/python.nix~

#+BEGIN_SRC nix :noweb yes :tangle shells/python.nix
# <<file-warning>>
{ pkgs ? import <nixpkgs> { } }:

with pkgs;
mkShell {
  buildInputs = [
    python38Packages.pip
    python38Packages.pip-tools
    python38Packages.pyls-mypy
    python38Packages.pyls-isort
    python38Packages.pyls-black
  ];
  shellHook = ''
  '';
}
#+END_SRC

* Host Configurations

NixOS[fn:4] typically stores the current machine configuration in =/etc/nixos/configuration.nix=. In this project, this file is stored in =/etc/dotfiles/hosts/$HOSTNAME/...=, and imported, along with the generated hardware configurations. This ensures that multiple host machines can share the same modules, and generating new host definitions is trivial. It also makes it easier to share common configurations amongst all of the hosts, such as with pre-configured wireless networking:

#+NAME: host-config-wifi
#+BEGIN_SRC nix
networking.wireless.networks.MyWiFi_5C1870.pskRaw =
  "409b3c85fef1c5737f284d2f82f20dc6023e41804e862d4fa26265ef8193b326";
#+END_SRC

It's helpful to add the machine hostnames to the networking configuration, so I can refer to another host across the network by name. Some devices that can have more than one IP (WIFI / Ethernet) will have the wireless hostname suffixed:

#+NAME: host-config-home
#+BEGIN_SRC nix
networking.hosts = {
  "192.168.3.105" = [ "gamingpc" ];
  # "" = [ "acernitro" ];
  "192.168.3.163" = [ "acernitro_" ];
  "192.168.3.182" = [ "raspberry" ];
  "192.168.3.123" = [ "raspberry_" ];
  # "" = [ "homecloud" ];
  # "" = [ "homecloud_" ];
  # "" = [ "zero-one" ];
  # "" = [ "zero-two" ];
  # "" = [ "android" ];
};
#+END_SRC

** Default

The default host, built using QEMU[fn:19], a free and open-source emulator that can perform hardware virtualization. It features a lightweight system optimized for development, running GNU/Emacs[fn:2] + EXWM[fn:20] as the graphical environment.

#+NAME: host-default
#+BEGIN_SRC nix :noweb yes
nixos = nixpkgs.lib.nixosSystem {
  system = "x86_64-linux";
  specialArgs = { inherit inputs; };
  modules = [
    ./hosts/nixos
    <<module-x11>>
    <<module-ssh>>
    <<module-flakes>>
    <<module-cachix>>
    <<module-home-manager>>
  ];
};
#+END_SRC

Deploy this configuration with ~nixos-rebuild switch --flake /etc/dotfiles/#nixos~.

#+BEGIN_SRC nix :noweb yes :tangle hosts/nixos/default.nix
# <<file-warning>>
{ ... }:

{
  imports = [
    ./configuration.nix
    ./hardware.nix
  ];
}
#+END_SRC

*** Configuration

This is a basic default configuration that specified the indended default configuration of the system. Because NixOS[fn:4] has a declarative configuration model, you can create or edit a description of the desired configuration, and update it from one file.

#+BEGIN_SRC nix :noweb yes :tangle hosts/nixos/configuration.nix
# <<file-warning>>
{ config, pkgs, inputs, ... }:

{
  time.timeZone = "America/Toronto";

  networking.hostName = "nixos";
  networking.useDHCP = false;
  networking.firewall.enable = false;
  networking.interfaces.ens3.useDHCP = true;

  <<host-config-home>>

  programs.mtr.enable = true;
  programs.fish.enable = true;
  programs.gnupg.agent.enable = true;

  users.users.chris = {
    shell = pkgs.fish;
    isNormalUser = true;
    extraGroups = [ "wheel" ];
  };
}
#+END_SRC

*** Hardware

The file system for this host is a single 24GB QCOW file, a format for disk images used by QEMU[fn:19]. The file can be recreated easily by following the steps listed in the NixOS[fn:4] installation manual, specifically the section on disk formatting.

#+BEGIN_SRC nix :noweb yes :tangle hosts/nixos/hardware.nix
# <<file-warning>>
{ config, lib, pkgs, modulesPath, ... }:

{
  imports =
    [ (modulesPath + "/profiles/qemu-guest.nix")
    ];

  boot.initrd.availableKernelModules = [ "ata_piix" "floppy" "sd_mod" "sr_mod" ];
  boot.initrd.kernelModules = [ ];
  boot.kernelModules = [ ];
  boot.extraModulePackages = [ ];

  boot.loader.grub.enable = true;
  boot.loader.grub.version = 2;
  boot.loader.grub.device = "/dev/sda";

  fileSystems."/" =
    { device = "/dev/disk/by-uuid/fddc37ff-a442-41fa-afc4-abf878be7c5a";
      fsType = "ext4";
    };

  swapDevices =
    [ { device = "/dev/disk/by-uuid/5fc0e3df-e796-4fe2-8482-c6acaed9d36f"; }
    ];
}
#+END_SRC

** Acernitro

My gaming laptop, the model is an Acer Nitro AN-515-53[fn:21]. The Nitro 5 has more in common with the mid-range notebooks rather than the gaming models due to its cooling design, chassis, and overall construction.

Here are the specs:

| Slot    | Component                             |
|---------+---------------------------------------|
| CPU     | Intel Core i5-8300H                   |
| GPU     | NVIDIA GeForce GTX 1050Ti (4GB GDDR5) |
| RAM     | 16GB DDR4                             |
| Display | 15.6" Full HD (1920 x 1080), IPS      |
| Storage | 1000GB HDD                            |
| Weight  | 2.48kg (5.5 lbs)                      |

#+NAME: host-acernitro
#+BEGIN_SRC nix :noweb yes
acernitro = nixpkgs.lib.nixosSystem {
  system = "x86_64-linux";
  specialArgs = { inherit inputs; };
  modules = [
    ./hosts/acernitro
    <<module-x11>>
    <<module-ssh>>
    <<module-flakes>>
    <<module-cachix>>
    <<module-nvidia>>
    <<module-firefox>>
    <<module-moonlight>>
    <<module-teamviewer>>
    <<module-home-manager>>
  ];
};
#+END_SRC

Deploy this configuration with ~nixos-rebuild switch --flake /etc/dotfiles/#acernitro~.

#+BEGIN_SRC nix :noweb yes :tangle hosts/acernitro/default.nix
# <<file-warning>>
{ ... }:

{
  imports = [
    ./configuration.nix
    ./hardware.nix
  ];
}
#+END_SRC

*** Configuration

This configuration is nearly identical to the default, except for a few key differences:

+ Enables sound
+ Applies the desired hostname
+ It adds support for =UEFI= systems
+ Enables support for wireless networking

#+BEGIN_SRC nix :noweb yes :tangle hosts/acernitro/configuration.nix
# <<file-warning>>
{ config, pkgs, inputs, ... }:

{
  time.timeZone = "America/Toronto";

  networking.hostName = "acernitro";
  networking.firewall.enable = false;
  networking.wireless.enable = true;
  networking.wireless.userControlled.enable = true;
  networking.useDHCP = false;
  networking.interfaces.enp6s0f1.useDHCP = true;
  networking.interfaces.wlp0s20f3.useDHCP = true;

  <<host-config-wifi>>
  <<host-config-home>>

  services.xserver.dpi = 96;
  services.openssh.enable = true;
  services.printing.enable = true;

  programs.mtr.enable = true;
  programs.fish.enable = true;
  programs.gnupg.agent.enable = true;

  users.users.chris = {
    shell = pkgs.fish;
    isNormalUser = true;
    extraGroups = [ "wheel" ];
  };
}
#+END_SRC

*** Hardware

+ Enables sound via PulseAudio
+ Adds support for the NVIDIA Hybrid GPU

#+BEGIN_SRC nix :noweb yes :tangle hosts/acernitro/hardware.nix
# <<file-warning>>
{ config, lib, pkgs, modulesPath, ... }:

{
  imports =
    [ (modulesPath + "/installer/scan/not-detected.nix")
    ];

  boot.initrd.availableKernelModules = [ "xhci_pci" "ahci" "usb_storage" "sd_mod" "rtsx_pci_sdmmc" ];
  boot.initrd.kernelModules = [ ];
  boot.kernelModules = [ "kvm-intel" ];
  boot.extraModulePackages = [ ];

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  sound.enable = true;
  hardware.pulseaudio.enable = true;
  hardware.pulseaudio.support32Bit = true;

  fileSystems."/" =
    { device = "/dev/disk/by-uuid/2f548eb9-47ce-4280-950f-9c6d1d162852";
      fsType = "ext4"; 
    };

  fileSystems."/boot" =
    { device = "/dev/disk/by-uuid/5BC3-73F3";
      fsType = "vfat";
    };

  swapDevices =
    [ { device = "/dev/disk/by-uuid/bef7bf62-d26f-45b1-a1f8-1227c2f8b26a"; }
    ];

  powerManagement.cpuFreqGovernor = lib.mkDefault "powersave";
}
#+END_SRC

** Raspberry

The Raspberry Pi 400[fn:22] is your complete personal computer, built into a compact keyboard. It features a quad-core, 64-bit processor, 4GB of RAM, wireless networking, dual-display output, 4k video playback, as well as a 40-pin GPIO header. It's the most powerful Raspberry Pi computer yet.

#+NAME: host-raspberry
#+BEGIN_SRC nix :noweb yes
raspberry = nixpkgs.lib.nixosSystem {
  system = "aarch64-linux";
  specialArgs = { inherit inputs; };
  modules = [
    ./hosts/raspberry
    <<module-x11>>
    <<module-ssh>>
    <<module-flakes>>
    <<module-cachix>>
    <<module-home-manager>>
  ];
};
#+END_SRC

Deploy this configuration with ~sudo nixos-rebuild switch --flake /etc/dotfiles/#raspberry~.

#+BEGIN_SRC nix :noweb yes :tangle hosts/raspberry/default.nix
# <<file-warning>>
{ ... }:

{
  imports = [
    ./configuration.nix
    ./hardware.nix
  ];
}
#+END_SRC

*** Configuration

#+BEGIN_SRC nix :noweb yes :tangle hosts/raspberry/configuration.nix
# <<file-warning>>
{ config, pkgs, ... }:

{
  networking.hostName = "raspberry";
  networking.firewall.enable = false;
  networking.networkmanager.enable = true;
  networking.interfaces.eth0.useDHCP = true;
  networking.interfaces.wlan0.useDHCP = true;

  <<host-config-home>>

  environment.systemPackages = [
    pkgs.libraspberrypi
    pkgs.raspberrypi-eeprom
  ];

  programs.fish.enable = true;
  programs.gnupg.agent.enable = true;

  users.users.chris = {
    shell = pkgs.fish;
    isNormalUser = true;
    extraGroups = [ "wheel" ];
  };
}
#+END_SRC

*** Hardware

This section is very much a work in progress. I have struggled to get this device to boot according to the NixOS documentation / wiki on the subject. It seems that when running with the vendored kernel there's an issue booting from the SD card. Nevertheless, the issue is avoided by using the standard kernel.

#+BEGIN_SRC nix :noweb yes :tangle hosts/raspberry/hardware.nix
# <<file-warning>>
{ config, pkgs, lib, inputs, ... }:

{
  # imports = [
  #   inputs.nixos-hardware.nixosModules.raspberry-pi-4
  # ];

  # boot.kernelPackages = pkgs.linuxPackages_rpi4;
  boot.tmpOnTmpfs = true;
  boot.initrd.availableKernelModules = [ "usbhid" "usb_storage" ];
  boot.kernelParams = [
    "8250.nr_uarts=1"
    "console=ttyAMA0,115200"
    "console=tty1"
    "cma=128M"
  ];

  boot.loader.grub.enable = false;
  boot.loader.generic-extlinux-compatible.enable = true;
  boot.loader.raspberryPi = {
    enable = true;
    version = 4;
    firmwareConfig = ''
      dtparam=sd_poll_once=on
      dtparam=audio=on
    '';
  };

  sound.enable = true;
  hardware.pulseaudio.enable = true;
  hardware.enableRedistributableFirmware = true;
  # hardware.raspberry-pi."4".fkms-3d.enable = true;

  fileSystems = {
    "/" = {
      device = "/dev/disk/by-uuid/44444444-4444-4444-8888-888888888888";
      fsType = "ext4";
      options = [ "noatime" ];
    };
  };

  powerManagement.cpuFreqGovernor = "ondemand";
}
#+END_SRC

** TODO Homecloud

The Raspberry Pi Model B-8GB[fn:23] is the latest product in the popular Raspberry Pi range of computers. It offers groundbreaking increases in processor speed, multimedia performance, memory, and connectivity compared to the prior generation. On NixOS[fn:4], the Raspberry Pi family is /only/ supported on the =AArch64= platform, although there is community support for =armv6l= and =armv7l=.

#+NAME: host-homecloud
#+BEGIN_SRC nix :noweb yes
homecloud = nixpkgs.lib.nixosSystem {
  system = "aarch64-linux";
  specialArgs = { inherit inputs; };
  modules = [
    ./hosts/homecloud
    <<module-ssh>>
    <<module-flakes>>
    <<module-cachix>>
    <<module-docker>>
    <<module-jellyfin>>
  ];
};
#+END_SRC

Deploy this configuration with ~sudo nixos-rebuild switch --flake /etc/dotfiles/#homecloud~.

#+BEGIN_SRC nix :noweb yes :tangle hosts/homecloud/default.nix
# <<file-warning>
{ ... }:

{
  imports = [
    ./configuration.nix
    ./hardware.nix
  ];
}
#+END_SRC

*** TODO Configuration

#+BEGIN_SRC nix :noweb yes :tangle hosts/homecloud/configuration.nix
# <<file-warning>>
{ # TODO
}
#+END_SRC

*** TODO Hardware

#+BEGIN_SRC nix :noweb yes :tangle hosts/homecloud/hardware.nix
# <<file-warning>>
{ # TODO
}
#+END_SRC

** TODO Zero-One

TODO: Raspberry Pi Zero/Zero WH

#+NAME: host-zero-one
#+BEGIN_SRC nix
zero-one = nixpkgs.lib.nixosSystem {
  system = "armv7l-linux";
  specialArgs = { inherit inputs; };
  modules = [
    ./hosts/zero-one
    ./modules/ssh.nix
    ./modules/flakes.nix
    ./modules/cachix.nix
  ];
};
#+END_SRC

** TODO Zero-Two

#+NAME: host-zero-two
#+BEGIN_SRC nix
zero-two = nixpkgs.lib.nixosSystem {
  system = "armv7l-linux";
  specialArgs = { inherit inputs; };
  modules = [
    ./hosts/zero-two
    ./modules/ssh.nix
    ./modules/flakes.nix
    ./modules/cachix.nix
  ];
};
#+END_SRC

** TODO Android

This is my Samsung Galaxy S10+[fn:24] running Nix On Droid[fn:10] with the experimental support for Flakes being used to manage the configuration.

#+NAME: host-android
#+BEGIN_SRC nix
android = (inputs.nix-on-droid.lib.aarch64-linux.nix-on-droid {
  config = ./hosts/android/nix-on-droid.nix;
}).activationPackage;
#+END_SRC

Build the activation package with ~nix build .#android --impure~, and activate it with =result/activate=.

#+BEGIN_SRC nix :noweb yes :tangle hosts/android/nix-on-droid.nix
# <<file-warning>>
{ pkgs, ... }:

{
  environment.packages = [
    pkgs.git
    pkgs.vim
    pkgs.pass
    pkgs.gnupg
    pkgs.openssh
  ];
}
#+END_SRC

* Module Definitions

Modules are files combined by NixOS[fn:4] to produce the full system configuration. Modules wre introduced to allow extending NixOS[fn:4] without modifying its source code. They also allow splitting up =configuration.nix=, making the system configuration easier to maintain and use.

** X11

#+NAME: module-x11
#+BEGIN_SRC nix
./modules/x11.nix
#+END_SRC

X11, or X[fn:25] is the generic name for the X Window System Display Server. All graphical GNU/Linux[fn:1] applications connect to an X-Window[fn:25] (or Wayland[fn:26]) to display graphical data on the monitor of a computer. Its a program that acts as the interface between graphical applications and the graphics subsystem of the computer.

#+BEGIN_SRC nix :noweb yes :tangle modules/x11.nix
# <<file-warning>>
{ config, pkgs, ... }:

{
  services.xserver.enable = true;
  services.xserver.layout = "us";
  services.xserver.libinput.enable = true;
  services.xserver.displayManager.startx.enable = true;

  environment = {
    systemPackages = with pkgs; [
      pkgs.sqlite
      pkgs.pfetch
      pkgs.cmatrix
      pkgs.asciiquarium
    ];
    extraInit = ''
      export XAUTHORITY=/tmp/Xauthority
      export xserverauthfile=/tmp/xserverauth
      [ -e ~/.Xauthority ] && mv -f ~/.Xauthority "$XAUTHORITY"
      [ -e ~/.serverauth.* ] && mv -f ~/.serverauth.* "$xserverauthfile"
    '';
  };

  services.picom.enable = true;
  services.printing.enable = true;

  fonts.fonts = with pkgs; [
    iosevka-bin
    emacs-all-the-icons-fonts
  ];
}
#+END_SRC

** SSH

#+NAME: module-ssh
#+BEGIN_SRC nix
./modules/ssh.nix
#+END_SRC

OpenSSH[fn:27] is a suite of secure networking utilities based on the Secure Shell Protocol, which provides a secure channel over an unsecured network in a client-server architecture. OpenSSH[fn:27] started as a fork of the free SSH program; later versions were proprietary software.

Apply some configuration to the default settings:

+ Disable logging in as =root=
+ Disable password authentication

#+BEGIN_SRC nix :noweb yes :tangle modules/ssh.nix
# <<file-warning>>
{ config, pkgs, ... }:

{
  services.openssh = {
    enable = true;
    permitRootLogin = false;
    passwordAuthentication = false;
  };
}
#+END_SRC

** Flakes

#+NAME: module-flakes
#+BEGIN_SRC nix
./modules/flakes.nix
#+END_SRC

Nix Flakes[fn:28] are an upcoming feature of the Nix package manager[fn:5]. They allow you to specify your codes dependencies in a declarative way, simply by listing them inside of a ~flake.nix~ file. Each dependency is then pinned to a specific git-hash. Flakes[fn:28] replace the =nix-channels= command and things like ~builtins.fetchGit~, keeping dependencies at the top of the tree, and channels always in sync. Currently, Flakes[fn:28] are not available unless explicitly enabled.

#+BEGIN_SRC nix :noweb yes :tangle modules/flakes.nix
# <<file-warning>>
{ config, pkgs, inputs, ... }:

{
  nix = {
    package = pkgs.nixUnstable;
    extraOptions = ''
      experimental-features = nix-command flakes
    '';
  };

  nixpkgs = {
    config = { allowUnfree = true; };
    overlays = [ inputs.emacs-overlay.overlay ];
  };
}
#+END_SRC

** Cachix

#+NAME: module-cachix
#+BEGIN_SRC nix
./modules/cachix.nix
#+END_SRC

Cachix[fn:29] is a Command line client for Nix[fn:5] binary cache hosting. This allows downloading and usage of pre-compiled binaries for applications on /nearly/ every available system architecture. This speeds up the time it takes to rebuild configurations.

#+BEGIN_SRC nix :noweb yes :tangle modules/cachix.nix
# <<file-warning>>
{ config, ... }:

{
  nix = {
    binaryCaches = [
      "https://nix-community.cachix.org"
    ];
    binaryCachePublicKeys = [
      "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
    ];
  };
}
#+END_SRC

** Docker

#+NAME: module-docker
#+BEGIN_SRC nix
./modules/docker.nix
#+END_SRC

Docker [fn:30] is a set of platform as a service that uses OS level virtualization to deliver software in packages called containers. Containers are isolated from one another and bundle their own software, libraries, and configuration files; they can communicate with each other through well-defined channels.

#+BEGIN_SRC nix :noweb yes :tangle modules/docker.nix
{ config, pkgs, ... }:

{
  virtualisation.docker = {
    enable = true;
    enableOnBoot = true;
    autoPrune.enable = true;
  };
}
#+END_SRC

** NVIDIA

#+NAME: module-nvidia
#+BEGIN_SRC nix
./modules/nvidia.nix
#+END_SRC

#+BEGIN_SRC nix :noweb yes :tangle modules/nvidia.nix
{ config, pkgs, ... }:

let
  myIntelBusId = "PCI:0:2:0";
  myNvidiaBusId = "PCI:1:0:0";
  myNvidiaOffload = pkgs.writeShellScriptBin "nvidia-offload" ''
    export __NV_PRIME_RENDER_OFFLOAD=1
    export __NV_PRIME_RENDER_OFFLOAD_PROVIDER=NVIDIA-G0
    export __GLX_VENDOR_LIBRARY_NAME=nvidia
    export __VK_LAYER_NV_optimus=NVIDIA_only
    exec -a "$0" "$@"
  '';

in {
  # Add the offload script to the $PATH.
  environment.systemPackages = [ myNvidiaOffload ];

  # Enable the NVIDIA drivers.
  # NOTE: You may need to use either of the commands below:
  services.xserver.videoDrivers = [ "nvidia" ];
  # services.xserver.videoDrivers = [ "modesetting" "nvidia" ];

  # Configure `offload-mode'.
  hardware.nvidia.prime = {
    offload.enable = true;
    intelBusId = myIntelBusId;
    nvidiaBusId = myNvidiaBusId;
  };
}
#+END_SRC

** Firefox

#+NAME: module-firefox
#+BEGIN_SRC nix
./modules/firefox.nix
#+END_SRC

Firefox Browser[fn:31], also known as Mozilla Firefox or simply Firefox, is a free and open-source web browser developed by the Mozilla Foundation and its subsidiary, the Mozilla Corporation. Firefox uses the Gecko layout engine to render web pages, which implements current and anticipated web standards. In 2017, Firefox began incorporating new technology under the code name Quantum to promote parallelism and a more intuitive user interface.

#+BEGIN_SRC nix :noweb yes :tangle modules/firefox.nix
# <<file-warning>>
{ pkgs, ... }:

{
  # NOTE: Use the binary until module is developed.
  environment.systemPackages = [
    pkgs.firefox-bin 
  ];
}
#+END_SRC

** Jellyfin

#+NAME: module-jellyfin
#+BEGIN_SRC nix
./modules/jellyfin.nix
#+END_SRC

Jellyfin[fn:32] is a suite of multimedia applications designed to organize, manage, and share digital media files to networked devices. It consists of a server application installed on a machine, and another application running as a client on devices such as Smartphones, Tablets, SmartTVs, Streaming Media Players, Game Consoles, or in a Web Browser. It can also serve media to DLNA and Chromecast enabled devices. It's free and open-source software fork of Emby.

#+BEGIN_SRC nix :noweb yes :tangle modules/jellyfin.nix
# <<file-warning>>
{ config, pkgs, ... }:

{
  services.jellyfin = {
    enable = true;
  };
}
#+END_SRC

** Moonlight

#+NAME: module-moonlight
#+BEGIN_SRC nix
./modules/moonlight.nix
#+END_SRC

Moonlight[fn:33] is an open-source implementation of NVIDIA's GameStream Protocol. You can stream your collection of PC games from your GameStream-compatible PC to any supported device and play them remotely. Moonlight[fn:33] is perfect for gaming on the go (or on GNU/Linux[fn:1]) without sacrificing the graphics and game selection available for the PC.

#+BEGIN_SRC nix :noweb yes :tangle modules/moonlight.nix
# <<file-warning>>
{ pkgs, ... }:

{
  environment.systemPackages = [
    pkgs.moonlight-qt
  ];
}
#+END_SRC

** Teamviewer

#+NAME: module-teamviewer
#+BEGIN_SRC nix
./modules/teamviewer.nix
#+END_SRC

The Teamviewer[fn:34] remote connectivity cloud platform enables secure remote access to any device, across platforms, from anywhere, anytime. Teamviewer[fn:34] connects computers, smartphones, servers, IoT devices, robots -- anything -- with fast, high performance connections through their global access network. It has been used in outer-space low-bandwidth environments.

#+BEGIN_SRC nix :noweb yes :tangle modules/teamviewer.nix
# <<file-warning>>
{ pkgs, ... }:

{
  # NOTE: Neither of these are working!
  # services.teamviewer.enable = true;

  # environment.systemPackages = [
  #   pkgs.teamviewer
  # ];
}
#+END_SRC

** Home Manager

Home Manager[fn:7] includes a =flake.nix= file for compatibility with Nix Flakes, a feature utilized heavily in this project. When using flakes, switching to a new configuration is done /only/ for the entire system, using the command ~nixos-rebuild switch --flake <path>~, instead of ~nixos-rebuild~, and ~home-manager~ seperately.

#+NAME: module-home-manager
#+BEGIN_SRC nix :noweb yes
inputs.home-manager.nixosModules.home-manager {
  home-manager.useGlobalPkgs = true;
  home-manager.useUserPackages = true;
  home-manager.users.chris = {
    imports = [
      <<module-git>>
      <<module-gpg>>
      <<module-vim>>
      <<module-gtk>>
      <<module-emacs>>
    ];
  };
}
#+END_SRC

*** Git

#+NAME: module-git
#+BEGIN_SRC nix
./modules/git.nix
#+END_SRC

Git[fn:35] is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn, has a tiny footprint, and lighting fast performance. It outclasses every other version control tool such as: SCM, Subversion, CVS, ClearCase, with features like cheap local branching, convinient staging areas, and multiple workflows.

#+BEGIN_SRC nix :noweb yes :tangle modules/git.nix
# <<file-warning>>
{ pkgs, ... }:

{
  programs.git = {
    enable = true;
    userName = "Christopher James Hayward";
    userEmail = "chris@chrishayward.xyz";

    signing = {
      key = "37AB1CB72B741E478CA026D43025DCBD46F81C0F";
      signByDefault = true;
    };
  };
}
#+END_SRC

*** Gpg

#+NAME: module-gpg
#+BEGIN_SRC nix
./modules/gpg.nix
#+END_SRC

GNU Privacy Guard[fn:36] is a free-software replacement for Symantec's PGP cryptographic software suite. It is compliant with RFC 4880, the IETF standards-track specification of OpenPGP. Modern versions of PGP are interoperable with GnuPG and other OpenPGP-compliant systems.

#+BEGIN_SRC nix :noweb yes :tangle modules/gpg.nix
# <<file-warning>>
{ pkgs, ... }:

{
  services.gpg-agent = {
    enable = true;
    defaultCacheTtl = 1800;
    enableSshSupport = true;
    pinentryFlavor = "gtk2";
  };
}
#+END_SRC

*** Vim

#+NAME: module-vim
#+BEGIN_SRC nix
./modules/vim.nix
#+END_SRC

Neovim[fn:37] is a project that seeks to aggressively refactor Vim in order to:

+ Simplify maintenance and encourage contributions
+ Split the work between multiple developers
+ Enable advanced UIs without core modification
+ Maximize extensibility

#+BEGIN_SRC nix :noweb yes :tangle modules/vim.nix
# <<file-warning>>
{ pkgs, ... }:

{
  programs.neovim = {
    enable = true;
    viAlias = true;
    vimAlias = true;
    vimdiffAlias = true;
    extraConfig = ''
      set number relativenumber
      set nobackup
    '';
    extraPackages = [
      pkgs.nixfmt
    ];
    plugins = with pkgs.vimPlugins; [
      vim-nix
      vim-airline
      vim-polyglot
    ];
  };
}
#+END_SRC

*** GTK

#+NAME: module-gtk
#+BEGIN_SRC nix
./modules/gtk.nix
#+END_SRC

GTK[fn:38] is a free and open-source, cross-platform widget toolkit for graphical user interfaces. It's one of the most popular toolkits for the Wayland[fn:26] and X11[fn:25] windowing systems.

#+BEGIN_SRC nix :noweb yes :tangle modules/gtk.nix
# <<file-warning>>
{ pkgs, ... }:

{
  home.packages = [
    pkgs.arc-theme
    pkgs.arc-icon-theme
    pkgs.lxappearance
  ];

  home.file.".gtkrc-2.0" = {
    text = ''
      gtk-theme-name="Arc-Dark"
      gtk-icon-theme-name="Arc"
      gtk-font-name="Sans 10"
      gtk-cursor-theme-size=0
      gtk-toolbar-style=GTK_TOOLBAR_BOTH_HORIZ
      gtk-toolbar-icon-size=GTK_ICON_SIZE_LARGE_TOOLBAR
      gtk-button-images=0
      gtk-menu-images=0
      gtk-enable-event-sounds=1
      gtk-enable-input-feedback-sounds=1
      gtk-xft-antialias=1
      gtk-xft-hinting=1
      gtk-xft-hintstyle="hintmedium"
    '';
  };
}
#+END_SRC

* Emacs Configuration

#+NAME: module-emacs
#+BEGIN_SRC nix
./modules/emacs.nix
#+END_SRC

GNU/Emacs[fn:2] is an extensible, customizable, free/libre text editor -- and more. At its core is an interpreter for Emacs Lisp[fn:36], a dialect of the Lisp programming language with extensions to support text editing. Other features include:

+ Highly customizable
+ Full Unicopde support
+ Content-aware editing modes
+ Complete built-in documentation
+ Wide range of functionality beyond text editing

#+BEGIN_SRC nix :noweb yes :tangle modules/emacs.nix
# <<file-warning>>
{ pkgs, ... }:

let
  myEmacs = pkgs.emacsWithPackagesFromUsePackage {
    config = ../README.org;
    package = <<emacs-native-comp-package>>
    alwaysEnsure = true;
    alwaysTangle = true;
    extraEmacsPackages = epkgs: [
      # Required packages...
      <<emacs-exwm-package>>
      <<emacs-evil-package>>
      <<emacs-general-package>>
      <<emacs-which-key-package>>

      # Optional packages.
      <<emacs-org-package>>
      <<emacs-org-roam-package>>
      <<emacs-org-drill-package>>
      <<emacs-pomodoro-package>>
      <<emacs-writegood-package>>
      <<emacs-hugo-package>>
      <<emacs-reveal-package>>
      <<emacs-pass-package>>
      <<emacs-mu4e-package>>
      <<emacs-dired-package>>
      <<emacs-icons-package>>
      <<emacs-emoji-package>>
      <<emacs-eshell-package>>
      <<emacs-vterm-package>>
      <<emacs-magit-package>>
      <<emacs-fonts-package>>
      <<emacs-elfeed-package>>
      <<emacs-nix-mode-package>>
      <<emacs-projectile-package>>
      <<emacs-lsp-package>>
      <<emacs-company-package>>
      <<emacs-golang-package>>
      <<emacs-python-package>>
      <<emacs-rustic-package>>
      <<emacs-plantuml-package>>
      <<emacs-swiper-package>>
      <<emacs-desktop-package>>
      <<emacs-doom-themes-package>>
      <<emacs-doom-modeline-package>>
    ];
  };

in {
  home.packages = [
    <<emacs-exwm-extras>>
    <<emacs-hugo-extras>>
    <<emacs-pass-extras>>
    <<emacs-mu4e-extras>>
    <<emacs-aspell-extras>>
    <<emacs-desktop-extras>>
    <<emacs-plantuml-extras>>
    <<emacs-nix-mode-extras>>
  ];

  programs.emacs = {
    enable = true;
    package = myEmacs;
  };

  <<emacs-exwm-config>>
  <<emacs-exwm-xinitrc>>
  <<emacs-mu4e-config>>
}
#+END_SRC

When Emacs is started, it normally tries to load a Lisp program from an ititialization file, or /init/ file. This file, if it exists, specifies how to initialize and configure Emacs. 

#+BEGIN_SRC emacs-lisp :noweb yes :tangle ~/.emacs.d/init.el
;; <<file-warning>>

;; Required inputs.
<<emacs-exwm-elisp>>
<<emacs-evil-elisp>>
<<emacs-general-elisp>>
<<emacs-which-key-elisp>>

;; Optional inputs.
<<emacs-org-elisp>>
<<emacs-org-roam-elisp>>
<<emacs-org-drill-elisp>>
<<emacs-org-agenda-elisp>>
<<emacs-pomodoro-elisp>>
<<emacs-writegood-elisp>>
<<emacs-aspell-elisp>>
<<emacs-eww-elisp>>
<<emacs-hugo-elisp>>
<<emacs-reveal-elisp>>
<<emacs-pass-elisp>>
<<emacs-erc-elisp>>
<<emacs-mu4e-elisp>>
<<emacs-dired-elisp>>
<<emacs-icons-elisp>>
<<emacs-emoji-elisp>>
<<emacs-eshell-elisp>>
<<emacs-vterm-elisp>>
<<emacs-magit-elisp>>
<<emacs-fonts-elisp>>
<<emacs-elfeed-elisp>>
<<emacs-projectile-elisp>>
<<emacs-lsp-elisp>>
<<emacs-company-elisp>>
<<emacs-golang-elisp>>
<<emacs-python-elisp>>
<<emacs-rustic-elisp>>
<<emacs-plantuml-elisp>>
<<emacs-desktop-elisp>>

;; User interface.
<<emacs-swiper-elisp>>
<<emacs-transparency-elisp>>
<<emacs-doom-themes-elisp>>
<<emacs-doom-modeline-elisp>>
#+END_SRC

It's somtimes desirable to have customization that takes effect during Emacs startup earlier than the normal init file. Place these configurations in =~/.emacs.d/early-init.el=. Most customizations should be put in the normal init file =~/.emacs.d/init.el=.

#+BEGIN_SRC emacs-lisp :noweb yes :tangle ~/.emacs.d/early-init.el
;; <<file-warning>>
<<emacs-disable-ui-elisp>>
<<emacs-native-comp-elisp>>
<<emacs-backup-files-elisp>>
<<emacs-shell-commands-elisp>>
#+END_SRC

** Disable UI

Emacs[fn:2] has been around since the 1980s, and it's painfully obvious when you're greeted with the default user interface. Disable some unwanted features to clean it up, and bring the appearance to something closer to a modern editor.

#+NAME: emacs-disable-ui-elisp
#+BEGIN_SRC emacs-lisp
;; Disable unwanted UI elements.
(tooltip-mode -1)
(menu-bar-mode -1)
(tool-bar-mode -1)
(scroll-bar-mode -1)

;; Fix the scrolling behaviour.
(setq scroll-conservatively 101)

;; Fix mouse-wheel scrolling behaviour.
(setq mouse-wheel-follow-mouse t
      mouse-wheel-progressive-speed t
      mouse-wheel-scroll-amount '(3 ((shift) . 3)))
#+END_SRC

** Native Comp

#+NAME: emacs-native-comp-package
#+BEGIN_SRC nix
pkgs.emacsGcc;
#+END_SRC

Native Comp, also known as GccEmacs, refers to the ~--with-native-compilation~ configuration option when building GNU/Emacs[fn:2]. It adds support for compiling Emacs Lisp to native code using ~libgccjit~. All of the Emacs Lisp packages shipped with Emacs are native-compiled, providing a noticable performance iomprovement out-of-the-box.

#+NAME: emacs-native-comp-elisp
#+BEGIN_SRC emacs-lisp
;; Silence warnings from packages that don't support `native-comp'.
(setq comp-async-report-warnings-errors nil         ;; Emacs 27.2 ...
      native-comp-async-report-warnings-errors nil) ;; Emacs 28+  ...
#+END_SRC

** Backup Files

Emacs[fn:2] makes a backup for a file only the first time the file is saved from a buffer. No matter how many times the file is subsequently written to, the backup remains unchanged. For files managed by a version control system, backup files are redundant since the previous versions are already stored.

#+NAME: emacs-backup-files-elisp
#+BEGIN_SRC emacs-lisp
;; Disable unwanted features.
(setq make-backup-files nil
      create-lockfiles nil)
#+END_SRC

** Shell Commands

Define some methods for interaction between GNU/Emacs[fn:2], and the systems underyling shell:

1) Method to run an external process, launching any application on a new process without interferring with Emacs[fn:2]
2) Method to apply commands to the curren call process, effecting the running instance of Emacs[fn:2]

#+NAME: emacs-shell-commands-elisp
#+BEGIN_SRC emacs-lisp
;; Define a method to run an external process.
(defun dotfiles/run (cmd)
  "Run an external process."
  (interactive (list (read-shell-command "λ ")))
  (start-process-shell-command cmd nil cmd))

;; Define a method to run a background process.
(defun dotfiles/run-in-background (cmd)
  (let ((command-parts (split-string cmd "[ ]+")))
    (apply #'call-process `(,(car command-parts) nil 0 nil ,@(cdr command-parts)))))
#+END_SRC

** Nix Mode

#+NAME: emacs-nix-mode-extras
#+BEGIN_SRC nix
pkgs.nixfmt
#+END_SRC

Nix-mode[fn:39] is an Emacs[fn:2] major mode for editing Nix[fn:5] expressions. This provides basic handling of =.nix= files. Syntax highlighting and indentation support using =SMIE= are provided.

#+NAME: emacs-nix-mode-package
#+BEGIN_SRC nix
epkgs.nix-mode
#+END_SRC

** Evil Mode

Evil[fn:21] is an extensible VI layer for GNU/Emacs[fn:2]. It emulates the main features of Vim[fn:37], turning GNU/Emacs[fn:2] into a modal editor.

#+NAME: emacs-evil-package
#+BEGIN_SRC nix
epkgs.evil
epkgs.evil-collection
epkgs.evil-surround
epkgs.evil-nerd-commenter
#+END_SRC

The next time Emacs[fn:2] is started, it will come up in /normal state/, denoted by =<N>= in the modeline. This is where the main ~vi~ bindings are defined. Like Emacs[fn:2] in general, Evil[fn:21] is extensible in Emacs Lisp[fn:36].

#+NAME: emacs-evil-elisp
#+BEGIN_SRC emacs-lisp
;; Enable the Extensible VI Layer for Emacs.
(setq evil-want-integration t   ;; Required for `evil-collection.'
      evil-want-keybinding nil) ;; Same as above.
(evil-mode +1)

;; Configure `evil-collection'.
(evil-collection-init)

;; Configure `evil-surround'.
(global-evil-surround-mode +1)

;; Configure `evil-nerd-commenter'.
(global-set-key (kbd "M-;") 'evilnc-comment-or-uncomment-lines)
#+END_SRC

** EXWM

#+NAME: emacs-exwm-package
#+BEGIN_SRC nix
epkgs.exwm
#+END_SRC

EXWM (Emacs X Window Manager)[fn:20] is a full-featured tiling X window manager for GNU/Emacs[fn:2] built on-top of XELB. It features:

+ Fully keyboard-driven operations
+ Hybrid layout modes (tiling & stacking)
+ Dynamic workspace support
+ ICCM/EWMH compliance

#+NAME: emacs-exwm-extras
#+BEGIN_SRC nix
pkgs.nitrogen
pkgs.autorandr
#+END_SRC
  
I wanted to leave ~(exwm-enable)~ out of my Emacs configuration (which does no harm anyways). This can be called when using the daemon to start EXWM[fn:20].

#+NAME: emacs-exwm-config
#+BEGIN_SRC nix
xsession = {
  enable = true;
  windowManager.command = ''
    ${pkgs.nitrogen}/bin/nitrogen --restore
    ${myEmacs}/bin/emacs --daemon -f exwm-enable
    ${myEmacs}/bin/emacsclient -c
  '';
};
#+END_SRC

EXWM[fn:20] cannot make an X window manager by itself, this is by design; You must tell X to do it. Override the =~/.xinitrc= file to start the =xsession=.

#+NAME: emacs-exwm-xinitrc
#+BEGIN_SRC nix
home.file.".xinitrc" = {
  text = ''
    exec ./.xsession
  '';
};
#+END_SRC

#+NAME: emacs-exwm-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `exwm'.
(setq exwm-worspace-show-all-buffers t)
(setq exwm-input-prefix-keys
  '(?\M-x
  ?\C-g
  ?\C-\ ))
(setq exwm-input-global-keys
  `(([?\s-r] . exwm-reset)
    ,@(mapcar (lambda (i)
                `(,(kbd (format "s-%d" i)) .
                (lambda ()
                (interactive)
                (exwm-workspace-switch-create ,i))))
                (number-sequence 1 9))))

;; Configure `exwm-randr'.
(require 'exwm-randr)
(exwm-randr-enable)

;; Configure custom hooks.
(setq display-time-and-date t)
(add-hook 'exwm-init-hook
  (lambda ()
    (display-battery-mode +1) ;; Display battery info (if available).
    (display-time-mode +1)))  ;; Display the time in the modeline.

;; Setup buffer display names.
(add-hook 'exwm-update-class-hook
  (lambda ()
    (exwm-workspace-rename-buffer exwm-class-name))) ;; Use the system class name.

;; Configure monitor hot-swapping.
(add-hook 'exwm-randr-screen-change-hook
  (lambda ()
    (dotfiles/run-in-background "autorandr --change --force"))) ;; Swap to the next screen config.
#+END_SRC

** General

#+NAME: emacs-general-package
#+BEGIN_SRC nix
epkgs.general
#+END_SRC

General[fn:40] provides a more convenient method for binding keys in Emacs[fn:2], providing a unified interface for key definitions. Its primary purpose is to build on /existing/ functionality to make key definitions more clear and concise.

#+NAME: emacs-general-elisp
#+BEGIN_SRC emacs-lisp
;; Use <SPC> as a leader key via `general.el'.
(general-create-definer dotfiles/leader
  :states '(normal motion)
  :keymaps 'override
  :prefix "SPC"
  :global-prefix "C-SPC")

;; Find files with <SPC> <period> ...
;; Switch buffers with <SPC> <comma> ...
(dotfiles/leader
  "." '(find-file :which-key "File")
  "," '(switch-to-buffer :which-key "Buffer")
  "k" '(kill-buffer :which-key "Kill")
  "c" '(kill-buffer-and-window :which-key "Close"))

;; Add keybindings for executing shell commands.
(dotfiles/leader
  "r" '(:ignore t :which-key "Run")
  "rr" '(dotfiles/run :which-key "Run")
  "ra" '(async-shell-command :which-key "Async"))

;; Add keybindings for quitting Emacs.
(dotfiles/leader
  "q" '(:ignore t :which-key "Quit")
  "qq" '(save-buffers-kill-emacs :which-key "Save")
  "qw" '(kill-emacs :which-key "Now")
  "qf" '(delete-frame :which-key "Frame"))

;; Add keybindings for toggles / tweaks.
(dotfiles/leader
  "t" '(:ignore t :which-key "Toggle / Tweak"))

;; Add keybindings for working with frames to replace
;; the C-x <num> <num> method of bindings, which is awful.
(dotfiles/leader
  "w" '(:ignore t :which-key "Windows")
  "ww" '(window-swap-states :which-key "Swap")
  "wc" '(delete-window :which-key "Close")
  "wh" '(windmove-left :which-key "Left")
  "wj" '(windmove-down :which-key "Down")
  "wk" '(windmove-up :which-key "Up")
  "wl" '(windmove-right :which-key "Right")
  "ws" '(:ignore t :which-key "Split")
  "wsj" '(split-window-below :which-key "Below")
  "wsl" '(split-window-right :which-key "Right"))
#+END_SRC

** Which Key

Which-key[fn:41] is a minor mode for Emacs[fn:2] that displays the key bindings following your currently entered incomplete command (prefix) in a popup or mini-buffer.

#+NAME: emacs-which-key-package
#+BEGIN_SRC nix
epkgs.which-key
#+END_SRC

#+NAME: emacs-which-key-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `which-key' to see keyboard bindings in the
;; mini-buffer and when using M-x.
(setq which-key-idle-delay 0.0)
(which-key-mode +1)
#+END_SRC

** EWW

The Emacs Web Wowser[fn:42] is a Web browser written in Emacs Lisp[fn:36] based on the ~shr.el~ library. It's my primary browser when it comes to text-based browsing.

+ Use ~eww~ as the default browser
+ Don't use any special fonts or colours

#+NAME: emacs-eww-elisp
#+BEGIN_SRC emacs-lisp
;; Set `eww' as the default browser.
(setq browse-url-browser-function 'eww-browse-url)

;; Configure the `shr' rendering engine.
(setq shr-use-fonts nil
      shr-use-colors nil)
#+END_SRC

** ERC

ERC[fn:43] is a powerful, modular, and extensible IRC client for GNU/Emacs[fn:2]. It's part of the GNU project, and included in Emacs.

#+NAME: emacs-erc-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `erc'.
(setq erc-autojoin-channels-alist '(("irc.libera.chat" "#emacs" "#nixos" "#systemcrafters"))
      erc-track-exclude-types '("JOIN" "NICK" "QUIT" "MODE")
      erc-lurker-hide-list '("JOIN" "PART" "QUIT"))

;; Connect to IRC via `erc'.
(defun dotfiles/erc-connect ()
  "Connected to IRC via `erc'."
  (interactive)
  (erc-tls :server "irc.libera.chat"
           :port 6697
           :nick "megaphone"
           :password (password-store-get "megaphone@libera.chat")
           :full-name "Chris Hayward"))

;; Configure keybindings.
(dotfiles/leader
  "i" '(dotfiles/erc-connect :which-key "Chat"))
#+END_SRC

** Dired

#+NAME: emacs-dired-package
#+BEGIN_SRC nix
epkgs.dired-single
#+END_SRC

Dired[fn:44] shows a directory listing inside of an Emacs[fn:2] buffer that can be used to perform various file operations on files and subdirectories. THe operations you can perform are numerous, from creating subdirectories, byte-compiling files, searching, and editing files. Dired-Extra[fn:45] provides extra functionality for Dired[fn:44].

#+NAME: emacs-dired-elisp
#+BEGIN_SRC emacs-lisp
;; Include `dired-x' for the `jump' method.
(require 'dired-x)

;; Configure `dired-single' to support `evil' keys.
(evil-collection-define-key 'normal 'dired-mode-map
  "h" 'dired-single-up-directory
  "l" 'dired-single-buffer)

;; Setup `all-the-icons' and the `dired' extension.

;; Configure keybindings for `dired'.
(dotfiles/leader
  "d" '(dired-jump :which-key "Dired"))
#+END_SRC

** Icons

#+NAME: emacs-icons-package
#+BEGIN_SRC nix
epkgs.all-the-icons
epkgs.all-the-icons-dired
#+END_SRC

All The Icons[fn:46] is a utility package to collect various Icon Fonts and prioritize them within GNU/Emacs[fn:2].

#+NAME: emacs-icons-elisp
#+BEGIN_SRC emacs-lisp
;; Setup `all-the-icons-dired'.
(add-hook 'dired-mode-hook 'all-the-icons-dired-mode)

;; Display default font ligatures.
(global-prettify-symbols-mode +1)
#+END_SRC

** Emojis

#+NAME: emacs-emoji-package
#+BEGIN_SRC nix
epkgs.emojify
#+END_SRC

Emojify[fn:47] is an Emacs[fn:2] extension to display Emojis. It can display GitHub style Emojis like :smile: or plain ascii ones such as :). It tries to be as efficient as possible, while also providing flexibility.

#+NAME: emacs-emoji-elisp
#+BEGIN_SRC emacs-lisp
;; Setup `emojify'.
(add-hook 'after-init-hook 'global-emojify-mode)
#+END_SRC

** EShell

#+NAME: emacs-eshell-package
#+BEGIN_SRC nix
epkgs.eshell-prompt-extras
#+END_SRC

EShell [fn:48] is a shell-like command interpreter for GNU/Emacs[fn:2] implemented in Emacs Lisp[fn:36]. It invokes no external processes except for those requested by the user. It's intended to be an alternative for IELM, and a full REPL envionment for Emacs[fn:2].

#+NAME: emacs-eshell-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `eshell'.
(setq eshell-highlight-prompt nil
      eshell-prefer-lisp-functions nil)

;; Configure the lambda prompt.
(autoload 'epe-theme-lambda "eshell-prompt-extras")
(setq eshell-prompt-function 'epe-theme-lambda)

;; Configure keybindings for `eshell'.
(dotfiles/leader
  "e" '(eshell :which-key "EShell"))
#+END_SRC

** VTerm

Emacs Libvterm (VTerm)[fn:49] is a fully-fledged terminal emulator inside GNU/Emacs[fn:2] based on Libvterm[fn:50], a blazing fast C library used in Neovim[fn:37]. As a result of using compiled code (instead of Emacs Lisp[fn:36]), VTerm[fn:49] is capable, fast, and it can seamlessly handle large outputs.

#+NAME: emacs-vterm-package
#+BEGIN_SRC nix
epkgs.vterm
#+END_SRC

#+NAME: emacs-vterm-elisp
#+BEGIN_SRC emacs-lisp
;; Add keybindings for interacting with the shell(s).
(dotfiles/leader
  "v" '(vterm :which-key "VTerm"))
#+END_SRC

** Magit

Magit[fn:51] is an interface to the Git[fn:35] version control system, implemented as a GNU/Emacs[fn:2] package written in Elisp[fn:36]. It fills the glaring gap between the Git[fn:35] command line interface and various GUIs, letting you perform trivial as well as elaborate version control tasks within a few mnemonic key presses.

#+NAME: emacs-magit-package
#+BEGIN_SRC nix
epkgs.magit
#+END_SRC

| Key | Description                          |
|-----+--------------------------------------|
| gg  | Check the status of a repository     |
| gc  | Clone a remote repository            |
| gf  | Fetch the contents of the repository |
| gp  | Pull the remotes of the repository   |

#+NAME: emacs-magit-elisp
#+BEGIN_SRC emacs-lisp
;; Add keybindings for working with `magit'.
(dotfiles/leader
  "g" '(:ignore t :which-key "Git")
  "gg" '(magit-status :which-key "Status")
  "gc" '(magit-clone :which-key "Clone")
  "gf" '(magit-fetch :which-key "Fetch")
  "gp" '(magit-pull :which-key "Pull"))
#+END_SRC

** Fonts

#+NAME: emacs-fonts-package
#+BEGIN_SRC nix
epkgs.hydra
#+END_SRC

#+NAME: emacs-fonts-elisp
#+BEGIN_SRC emacs-lisp
;; Configure the font when running as `emacs-server'.
(custom-set-faces
  '(default ((t (:inherit nil :height 96 :family "Iosevka")))))

;; Set all three of Emacs' font faces.
;; NOTE: This only works without `emacs-server'.
;; (set-face-attribute 'default nil :font "Iosevka" :height 96)
;; (set-face-attribute 'fixed-pitch nil :font "Iosevka" :height 96)
;; (set-face-attribute 'variable-pitch nil :font "Iosevka" :height 96)

;; Define a `hydra' function for scaling the text interactively.
(defhydra hydra-text-scale (:timeout 4)
  "Scale text"
  ("j" text-scale-decrease "Decrease")
  ("k" text-scale-increase "Increase")
  ("f" nil "Finished" :exit t))

;; Create keybinding for calling the function.
(dotfiles/leader
  "tf" '(hydra-text-scale/body :which-key "Font"))
#+END_SRC

** Elfeed

#+NAME: emacs-elfeed-package
#+BEGIN_SRC nix
epkgs.elfeed
#+END_SRC

Elfeed[fn:52] is an extensible web feed reader for GNU/Emacs[fn:2], support both =Atom= and =RSS=. It requires =Emacs 24.3+= and is available for download from the standard repositories.

| Key | Command |
|-----+---------|
| l   | Open    |
| u   | Update  |

#+NAME: emacs-elfeed-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `elfeed'.
(setq elfeed-db-directory (expand-file-name "~/.cache/elfeed"))

;; Add custom feeds for `elfeed' to fetch.
(setq elfeed-feeds (quote
                     (("https://hexdsl.co.uk/rss.xml")
                      ("https://lukesmith.xyz/rss.xml")
                      ("https://friendo.monster/rss.xml")
                      ("https://chrishayward.xyz/index.xml")
                      ("https://protesilaos.com/codelog.xml"))))

;; Add custom keybindings for `elfeed'.
(dotfiles/leader
  "l" '(:ignore t :which-key "Elfeed")
  "ll" '(elfeed :which-key "Open")
  "lu" '(elfeed-update :which-key "Update"))
#+END_SRC

** Org Mode

#+NAME: emacs-org-package
#+BEGIN_SRC nix
epkgs.org
#+END_SRC

Org-mode[fn:53] is a document editing and organizing mode, designed for notes, planning, and authoring within the free software text editor GNU/Emacs[fn:2]. The name is used to encompass plain text files (such as this one) that include simple marks to indicate levels of a hierarchy, and an editor with functions that can read the markup and manipulate the hierarchy elements.

#+NAME: emacs-org-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `org-mode' source blocks.
(setq org-src-fontify-natively t      ;; Make source blocks prettier.
      org-src-tab-acts-natively t     ;; Use TAB indents within source blocks.
      org-src-preserve-indentation t) ;; Stop `org-mode' from formatting blocks.

;; Add an `org-mode-hook'.
(add-hook 'org-mode-hook
  (lambda ()
    (org-indent-mode)
    (visual-line-mode)))

;; Remove the `Validate XHTML 1.0' message from HTML export.
(setq org-export-html-validation-link nil
      org-html-validation-link nil)

;; TODO: Configure default structure templates.
;; (require 'org-tempo)

;; Apply custom keybindings.
(dotfiles/leader
  "o" '(:ignore t :which-key "Org")
  "oe" '(org-export-dispatch :which-key "Export")
  "ot" '(org-babel-tangle :which-key "Tangle")
  "oi" '(org-toggle-inline-images :which-key "Images")
  "of" '(:ignore t :which-key "Footnotes")
  "ofn" '(org-footnote-normalize :which-key "Normalize"))
#+END_SRC

** Org Roam

#+NAME: emacs-org-roam-package
#+BEGIN_SRC nix
epkgs.org-roam
epkgs.org-roam-server
#+END_SRC

Org Roam[fn:54] is a plain-text knowledge management system. It borrows principles from the Zettelkasten method[fn:55], providing a solution for non-hierarchical note-taking. It should also work as a plug-and-play solution for anyone already using Org Mode[fn:53] for their personal wiki (me). Org Roam Server[fn:56] is a Web application to visualize the Org Roam[fn:54] database. Although it should automatically reload if there's a change in the database, it can be done so manually by clicking the =reload= button on the Web interface.

#+NAME: emacs-org-roam-elisp
#+BEGIN_SRC emacs-lisp
;; Setup `org-roam' hooks.
(add-hook 'after-init-hook
  (lambda ()
    (org-roam-mode)
    (org-roam-server-mode)))

;; Configure `org-roam'.
(setq org-roam-encrypt-files t
      org-roam-directory (expand-file-name "/etc/dotfiles")
      org-roam-capture-templates '()
      org-roam-dailies-capture-templates '())

;; Encrypt files with the public key.
(setq epa-file-select-keys 2
      epa-file-encrypt-to "37AB1CB72B741E478CA026D43025DCBD46F81C0F"
      epa-cache-passphrase-for-symmetric-encryption t)

;; Define a new `title-to-slug' function to override the default `org-roam-title-to-slug' function.
;; This is done to change the replacement character from "_" to "-".
(require 'cl-lib)
(defun dotfiles/title-to-slug (title)
  "Convert TITLE to a filename-suitable slug."
  (cl-flet* ((nonspacing-mark-p (char)
                                (eq 'Mn (get-char-code-property char 'general-category)))
             (strip-nonspacing-marks (s)
                                     (apply #'string (seq-remove #'nonspacing-mark-p
                                                                 (ucs-normalize-NFD-string s))))
             (cl-replace (title pair)
                         (replace-regexp-in-string (car pair) (cdr pair) title)))
    (let* ((pairs `(("[^[:alnum:][:digit:]]" . "-") ;; Convert anything not alphanumeric.
                    ("--*" . "-")                   ;; Remove sequential dashes.
                    ("^-" . "")                     ;; Remove starting dashes.
                    ("-$" . "")))                   ;; Remove ending dashes.
           (slug (-reduce-from #'cl-replace (strip-nonspacing-marks title) pairs)))
      (downcase slug))))
(setq org-roam-title-to-slug-function #'dotfiles/title-to-slug)

;; Configure capture templates.
;; Standard document.
(add-to-list 'org-roam-capture-templates
  '("d" "Default" entry (function org-roam-capture--get-point)
        "%?"
        :file-name "docs/${slug}"
        :unnarrowed t
        :head 
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward
,#+EMAIL: chris@chrishayward.xyz
"))

;; Course document.
(add-to-list 'org-roam-capture-templates
  '("c" "Course" plain (function org-roam-capture--get-point)
        "%?"
        :file-name "docs/courses/${slug}"
        :unnarrowed t
        :head
"
,#+TITLE: ${title}
,#+SUBTITLE:
,#+AUTHOR: Christopher James Hayward
,#+EMAIL: chris@chrishayward.xyz

,#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
,#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil
"))

;; Daily notes.
(add-to-list 'org-roam-dailies-capture-templates
  '("d" "Default" entry (function org-roam-capture--get-point)
           "* %?"
           :file-name "docs/daily/%<%Y-%m-%d>"
           :head
"
,#+TITLE: %<%Y-%m-%d>
,#+AUTHOR: Christopher James Hayward

,#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
,#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil
"))

;; Apply custom keybindings.
(dotfiles/leader
  "or"  '(:ignore t :which-key "Roam")
  "ori" '(org-roam-insert :which-key "Insert")
  "orf" '(org-roam-find-file :which-key "Find")
  "orc" '(org-roam-capture :which-key "Capture")
  "orb" '(org-roam-buffer-toggle-display :which-key "Buffer"))

;; Apply custom keybindings for dailies.
(dotfiles/leader
  "ord" '(:ignore t :which-key "Dailies")
  "ordd" '(org-roam-dailies-find-date :which-key "Date")
  "ordt" '(org-roam-dailies-find-today :which-key "Today")
  "ordm" '(org-roam-dailies-find-tomorrow :which-key "Tomorrow")
  "ordy" '(org-roam-dailies-find-yesterday :which-key "Yesterday"))
#+END_SRC

** Org Drill

#+NAME: emacs-org-drill-package
#+BEGIN_SRC nix
epkgs.org-drill
#+END_SRC

Org Drill[fn:57] is an extension for Org Mode[fn:53] that uses a spaced repition algorithm to conduct interactive /Drill Sessions/ using Org files as sources of facts to be memorized.

#+NAME: emacs-org-drill-elisp
#+BEGIN_SRC emacs-lisp
;; Configure keybindings for `org-drill'.
(dotfiles/leader
  "od" '(:ignore t :which-key "Drill")
  "odd" '(org-drill :which-key "Drill")
  "odc" '(org-drill-cram :which-key "Cram")
  "odr" '(org-drill-resume :which-key "Resume"))
#+END_SRC

** Org Agenda

The way Org Mode[fn:53] works, TODO items, time-stamped items, and tagged headlines can be scattered throughout a file, or even a number of files. To get an overview of open action items, or of events that are important for a particular date, this information must be collected, sorted, and displayed in an organized way.

#+NAME: emacs-org-agenda-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `org-agenda' to use the project files.
(setq org-agenda-files '("/etc/dotfiles/"
                         "/etc/dotfiles/docs/"
                         "/etc/dotfiles/docs/courses/"
                         "/etc/dotfiles/docs/daily/"
                         "/etc/dotfiles/docs/notes/"
                         "/etc/dotfiles/docs/posts/"
                         "/etc/dotfiles/docs/slides/"))

;; Include files encrypted with `gpg'.
(require 'org)
(unless (string-match-p "\\.gpg" org-agenda-file-regexp)
  (setq org-agenda-file-regexp
    (replace-regexp-in-string "\\\\\\.org" "\\\\.org\\\\(\\\\.gpg\\\\)?"
                              org-agenda-file-regexp)))

;; Open an agenda buffer with SPC o a.
(dotfiles/leader
  "oa" '(org-agenda :which-key "Agenda"))
#+END_SRC

** Org Pomodoro

#+NAME: emacs-pomodoro-package
#+BEGIN_SRC nix
epkgs.org-pomodoro
#+END_SRC

Org Pomodoro[fn:58] adds basic support for the Pomodoro Technique[fn:59] in GNU/Emacs[fn:2]. It can be started for the task at point, or the last task time was clocked for. Each session starts a timer of 25 minutes, finishing with a break of 5 minutes. After 4 sessions, ther will be a break of 20 minutes. All values are customizable.

#+NAME: emacs-pomodoro-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `org-pomodor' with the overtime workflow.
(setq org-pomodoro-manual-break t
      org-pomodoro-keep-killed-time t)

;; Configure keybindings.
(dotfiles/leader
  "op" '(org-pomodoro :which-key "Pomodoro"))
#+END_SRC

** Writegood Mode

#+NAME: emacs-writegood-package
#+BEGIN_SRC nix
epkgs.writegood-mode
#+END_SRC

Writegood Mode[fn:60] is an Emacs[fn:2] minor mode to aid in finding common writing problems. It highlights the text based on the following criteria:

+ Weasel Words
+ Passive Voice
+ Duplicate Words

#+NAME: emacs-writegood-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `writegood-mode'.
(dotfiles/leader
  "tg" '(writegood-mode :which-key "Grammar"))
#+END_SRC

** Aspell

#+NAME: emacs-aspell-extras
#+BEGIN_SRC nix
pkgs.aspell
pkgs.aspellDicts.en
pkgs.aspellDicts.en-science
pkgs.aspellDicts.en-computers
#+END_SRC

GNU Aspell[fn:61] is a Free and Open Source spell checker designed to replace ISpell. It can be used as a library, or an independent spell checker. Its main feature is that it does a superior job of suggesting possible replacements for mis-spelled words than any other spell checker for the English language.

#+NAME: emacs-aspell-elisp
#+BEGIN_SRC emacs-lisp
;; Use `aspell' as a drop-in replacement for `ispell'.
(setq ispell-program-name "aspell"
      ispell-eextra-args '("--sug-mode=fast"))

;; Configure the built-in `flyspell-mode'.
(dotfiles/leader
  "ts" '(flyspell-mode :which-key "Spelling"))
#+END_SRC

** Hugo

#+NAME: emacs-hugo-extras
#+BEGIN_SRC nix
pkgs.hugo
#+END_SRC

Hugo[fn:62] is one of the most popular open-source static site generators.

#+NAME: emacs-hugo-package
#+BEGIN_SRC nix
epkgs.ox-hugo
#+END_SRC

Ox-Hugo[fn:63] is an Org-Mode[fn:53] exporter for Hugo[fn:62] compabile markdown. I post nonsense on my Personal Blog[fn:64], and share my notes on various textbooks, articles, and software Here[fn:65].

#+NAME: emacs-hugo-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `ox-hugo' as an `org-mode-export' backend.
(require 'ox-hugo)

;; Capture templates.
;; Personal blog post.
(add-to-list 'org-roam-capture-templates
             '("p" "Post" plain (function org-roam-capture--get-point)
               "%?"
               :file-name "docs/posts/${slug}"
               :unnarrowed t
               :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward
,#+DATE: %<%Y-%m-%d>

,#+OPTIONS: num:nil todo:nil tasks:nil

,#+EXPORT_FILE_NAME: ${slug}
,#+ROAM_KEY: https://chrishayward.xyz/posts/${slug}/

,#+HUGO_BASE_DIR: ../
,#+HUGO_AUTO_SET_LASTMOD: t
,#+HUGO_SECTION: posts
,#+HUGO_DRAFT: true
"))

;; Shared notes.
(add-to-list 'org-roam-capture-templates
             '("n" "Notes" plain (function org-roam-capture--get-point)
                "%?"
                :file-name "docs/notes/${slug}"
                :unnarrowed t
                :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward

,#+OPTIONS: num:nil todo:nil tasks:nil
,#+EXPORT_FILE_NAME: ${slug}
,#+ROAM_KEY: https://chrishayward.xyz/notes/${slug}/

,#+HUGO_BASE_DIR: ../
,#+HUGO_AUTO_SET_LASTMOD: t
,#+HUGO_SECTION: notes
,#+HUGO_DRAFT: true
"))
#+END_SRC

** Reveal

#+NAME: emacs-reveal-package
#+BEGIN_SRC nix
epkgs.ox-reveal
#+END_SRC

Reveal.js[fn:66] is an open source HTML presentation framework. It enables anyone with a web browser to create fully-featured and beautiful presentations for free. Presentations with Reveal.js[fn:66] are built on open web technologies. That means anything you can do on the web, you can do in your presentation. Ox Reveal[fn:67] is an Org Mode[fn:53] export backend.

#+NAME: emacs-reveal-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `ox-reveal' as an `org-mode-export' backend.
(require 'ox-reveal)

;; Don't rely on any local software.
(setq org-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js")

;; Create a capture template.
(add-to-list 'org-roam-capture-templates
             '("s" "Slides" plain (function org-roam-capture--get-point)
               "%?"
               :file-name "docs/slides/${slug}"
               :unnarrowed t
               :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward
,#+EMAIL: chris@chrishayward.xyz

,#+REVEAL_ROOT: https://cdn.jsdelivr.net/npm/reveal.js
,#+REVEAL_THEME: serif

,#+EXPORT_FILE_NAME: ${slug}

,#+OPTIONS: reveal_title_slide:nil
,#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
,#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil
"))
#+END_SRC

** Passwords

#+NAME: emacs-pass-extras
#+BEGIN_SRC nix
pkgs.pass
#+END_SRC

With Pass[fn:68], each password lives inside of an encrypted =gpg= file, whose name is the title of the website or resource that requires the password. These encrypted files may be organized into meaningful folder hierarchies, compies from computer to computer, and in general, manipulated using standard command line tools.

#+NAME: emacs-pass-package
#+BEGIN_SRC nix
epkgs.password-store
#+END_SRC

Configure keybindings for passwords behind =SPC p=:

| Key | Description         |
|-----+---------------------|
| p   | Copy a password     |
| r   | Rename a password   |
| g   | Generate a password |

#+NAME: emacs-pass-elisp
#+BEGIN_SRC emacs-lisp
;; Set the path to the password store.
(setq password-store-dir (expand-file-name "~/.password-store"))

;; Apply custom keybindings.
(dotfiles/leader
  "p" '(:ignore t :which-key "Passwords")
  "pp" '(password-store-copy :which-key "Copy")
  "pr" '(password-store-rename :which-key "Rename")
  "pg" '(password-store-generate :which-key "Generate"))
#+END_SRC

** MU4E

#+NAME: emacs-mu4e-extras
#+BEGIN_SRC nix
pkgs.mu
pkgs.isync
#+END_SRC

#+NAME: emacs-mu4e-package
#+BEGIN_SRC nix
epkgs.mu4e-alert
#+END_SRC

#+NAME: emacs-mu4e-config
#+BEGIN_SRC nix
home.file.".mbsyncrc" = {
  text = ''
    IMAPStore xyz-remote
    Host mail.chrishayward.xyz
    User chris@chrishayward.xyz
    PassCmd "pass chrishayward.xyz/chris"
    SSLType IMAPS
    
    MaildirStore xyz-local
    Path ~/.cache/mail/
    Inbox ~/.cache/mail/inbox
    SubFolders Verbatim
    
    Channel xyz
    Far :xyz-remote:
    Near :xyz-local:
    Patterns * !Archives
    Create Both
    Expunge Both
    SyncState *
  '';
};
#+END_SRC

#+BEGIN_SRC sh
mbsync -a
mu init --maildir="~/.cache/mail" --my-address="chris@chrishayward.xyz"
mu index
#+END_SRC

#+NAME: emacs-mu4e-elisp
#+BEGIN_SRC emacs-lisp
;; Add the `mu4e' shipped with `mu' to the load path.
(add-to-list 'load-path "/etc/profiles/per-user/chris/share/emacs/site-lisp/mu4e/")
(require 'mu4e)

;; Confiugure `mu4e'.
(setq mu4e-maildir "~/.cache/mail"
      mu4e-update-interval (* 5 60)
      mu4e-get-mail-command "mbsync -a"
      mu4e-compose-format-flowed t
      mu4e-change-filenames-when-moving t
      mu4e-compose-signature (concat "Chris Hayward\n"
                                     "chris@chrishayward.xyz"))

;; Sign all outbound email with GPG.
(add-hook 'message-send-hook 'mml-secure-message-sign-pgpmime)
(setq message-send-mail-function 'smtpmail-send-it
      mml-secure-openpgp-signers '("37AB1CB72B741E478CA026D43025DCBD46F81C0F"))

;; Setup `mu4e' accounts.
(setq mu4e-contexts
  (list
    ;; Main
    ;; chris@chrishayward.xyz
    (make-mu4e-context
      :name "Main"
      :match-func
        (lambda (msg)
          (when msg
            (string-prefix-p "/Main" (mu4e-message-field msg :maildir))))
      :vars
        '((user-full-name . "Christopher James Hayward")
          (user-mail-address . "chris@chrishayward.xyz")
          (smtpmail-smtp-server . "mail.chrishayward.xyz")
          (smtpmail-smtp-service . 587)
          (smtpmail-stream-type . starttls)))))

;; Setup `mu4e-alert'.
(setq mu4e-alert-set-default-style 'libnotify)
(mu4e-alert-enable-notifications)
(mu4e-alert-enable-mode-line-display)

;; Open the `mu4e' dashboard.
(dotfiles/leader
  "m" '(mu4e :which-key "Mail"))
#+END_SRC

** Projectile

#+NAME: emacs-projectile-package
#+BEGIN_SRC nix
epkgs.projectile
#+END_SRC

Projectile[fn:69] is a project interaction library for GNU/Emacs[fn:2]. Its goal is to provide a nice set of features operating on a project level, without introducing external dependencies.

#+NAME: emacs-projectile-elisp
#+BEGIN_SRC emacs-lisp
;; Configure the `projectile-project-search-path'.
(setq projectile-project-search-path '("~/.local/source"))
(projectile-mode +1)
#+END_SRC

** LSP Mode

#+NAME: emacs-lsp-package
#+BEGIN_SRC nix
epkgs.lsp-mode
epkgs.lsp-ui
#+END_SRC

The Language Server Protocol (LSP)[fn:70] defines the protocol used between an Editor or IDE, and a language server that provides features like:

+ Auto Complete
+ Go To Defintion
+ Find All References

#+NAME: emacs-lsp-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `lsp-mode'.
(setq lsp-idle-delay 0.5
      lsp-prefer-flymake t)

;; Configure `lsp-ui'.
(setq lsp-ui-doc-position 'at-point
      lsp-ui-doc-delay 0.5)
#+END_SRC

** CCLS

#+NAME: emacs-ccls-package
#+BEGIN_SRC nix
epkgs.ccls
#+END_SRC

Emacs CCLS[fn:71] is a client for CCLS, a C/C++/Objective-C language server supporting multi-million line C++ code bases, powered by libclang.

#+NAME: emacs-ccls-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `ccls' to work with `lsp-mode'.
(defun dotfiles/ccls-hook ()
  (require 'ccls)
  (lsp))

;; Configure `ccls' mode hooks.
(add-hook 'c-mode-hook 'dotfiles/ccls-hook)
(add-hook 'c++-mode-hook 'dotfiles/ccls-hook)
(add-hook 'objc-mode-hook 'dotfiles/ccls-hook)
(add-hook 'cuda-mode-hook 'dotfiles/ccls-hook)
#+END_SRC

** Company Mode

#+NAME: emacs-company-package
#+BEGIN_SRC nix
epkgs.company
#+END_SRC

Company[fn:72] is a text completion framework for GNU/Emacs[fn:2]. The name stands for =Complete Anything=. It uses pluggable back-ends and front-ends to retieve and display completion candidates.

#+NAME: emacs-company-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `company-mode'.
(setq company-backend 'company-capf
      lsp-completion-provider :capf)

;; Enable it globally.
(global-company-mode +1)
#+END_SRC

** Go Mode

#+NAME: emacs-golang-package
#+BEGIN_SRC nix
epkgs.go-mode
#+END_SRC

Go Mode[fn:73] is a major mode for editing Golang[fn:12] source code in GNU/Emacs[fn:2].

#+NAME: emacs-golang-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `go-mode' to work with `lsp-mode'.
(defun dotfiles/go-hook ()
  (add-hook 'before-save-hook #'lsp-format-buffer t t)
  (add-hook 'before-save-hook #'lsp-organize-imports t t))

;; Configure a custom `before-save-hook'.
(add-hook 'go-mode-hook #'dotfiles/go-hook)
#+END_SRC

** Rustic

#+NAME: emacs-rustic-package
#+BEGIN_SRC nix
epkgs.rustic
#+END_SRC

Rustic[fn:72] is a fork of rust-mode that integrates well with the Language Server Protocol[fn:68]. Include the rust shell before launching GNU/Emacs[fn:2] to use this!

#+NAME: emacs-rustic-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `rustic' with `lsp-mode'.
(setq rustic-format-on-save t
      rustic-lsp-server 'rls)
#+END_SRC

** Python Mode

#+NAME: emacs-python-package
#+BEGIN_SRC nix
epkgs.pretty-mode
#+END_SRC

The built in Python Mode[fn:74] has a nice feature set for working with Python[fn:18] code in GNU/Emacs[fn:2]. It is complimented with the addition of an LSP[fn:70] server. These tools are included in the Development Shell[fn:11] for Python[fn:18].

#+NAME: emacs-python-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `pretty-mode' to work with `python-mode'.
(add-hook 'python-mode-hook
  (lambda ()
    (turn-on-pretty-mode)))
#+END_SRC

** PlantUML

#+NAME: emacs-plantuml-extras
#+BEGIN_SRC nix
pkgs.plantuml
#+END_SRC

PlantUML[fn:75] is an open-source tool allowing users to create diagrams from a plain-text language. Besides various UML diagrams, PlantUML[fn:75] has support for various other software developmented related formats, as well as visualizations of =JSON= and =YAML= files.

#+NAME: emacs-plantuml-package
#+BEGIN_SRC nix
epkgs.plantuml-mode
#+END_SRC

PlantUML Mode[fn:76] is a major mode for editing PlantUML[fn:75] sources in GNU/Emacs[fn:2].

#+NAME: emacs-plantuml-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `plantuml-mode'.
(add-to-list 'org-src-lang-modes '("plantuml" . plantuml))
(org-babel-do-load-languages 'org-babel-load-languages '((plantuml . t)))
(setq plantuml-default-exec-mode 'executable
      org-plantuml-exec-mode 'plantuml)
#+END_SRC

** Swiper

#+NAME: emacs-swiper-package
#+BEGIN_SRC nix
epkgs.ivy
epkgs.counsel
epkgs.ivy-rich
epkgs.ivy-posframe
epkgs.ivy-prescient
#+END_SRC

Ivy (Swiper)[fn:77] is a generic completion mechanism for GNU/Emacs[fn:2]. While operating similarily to other completion schemes like =icomplete-mode=, it aims to be more efficient, smaller, simpler, and smoother to use, while remaining highly customizable.

#+NAME: emacs-swiper-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `ivy'.
(setq counsel-linux-app-format-function
  #'counsel-linux-app-format-function-name-only)
(ivy-mode +1)
(counsel-mode +1)

;; Configure `ivy-rich'.
(ivy-rich-mode +1)

;; Configure `ivy-posframe'.
(setq ivy-posframe-parameters '((parent-frame nil))
      ivy-posframe-display-functions-alist '((t . ivy-posframe-display)))
(ivy-posframe-mode +1)

;; Configure `ivy-prescient'.
(setq ivy-prescient-enable-filtering nil)
(ivy-prescient-mode +1)
#+END_SRC

** Transparency

It's possible to control the frame opacity in GNU/Emacs[fn:2]. Unlike other transparency hacks, it's not merely showing the desktop background image, but is true transparency -- you can se other windows behind the Emacs[fn:2] window.

#+NAME: emacs-transparency-elisp
#+BEGIN_SRC emacs-lisp
;; Configure the default frame transparency.
(set-frame-parameter (selected-frame) 'alpha '(95 . 95))
(add-to-list 'default-frame-alist '(alpha . (95 . 95)))
#+END_SRC

** Desktop Environment

#+NAME: emacs-desktop-extras
#+BEGIN_SRC nix
pkgs.brightnessctl
#+END_SRC

The Desktop Environment[fn:78] package provides commands and a global minor mode for controlling your GNU/Linux[fn:1] desktop from within GNU/Emacs[fn:2].

#+NAME: emacs-desktop-package
#+BEGIN_SRC nix
epkgs.desktop-environment
#+END_SRC

You can control the brightness, volume, take screenshots, and lock / unlock the screen. The package depends on the availability of shell commands to do the heavy lifting. They can be changed by customizing the appropriate variables.

#+NAME: emacs-desktop-elisp
#+BEGIN_SRC emacs-lisp
;; Configure `desktop-environment'.
(require 'desktop-environment)
(desktop-environment-mode +1)
#+END_SRC

** Doom Themes

#+NAME: emacs-doom-themes-package
#+BEGIN_SRC nix
epkgs.doom-themes
#+END_SRC

Doom Themes[fn:79] is a theme megapack for GNU/Emacs[fn:2], inspired by community favourites.

#+NAME: emacs-doom-themes-elisp
#+BEGIN_SRC emacs-lisp
;; Include modern themes from `doom-themes'.
(setq doom-themes-enable-bold t
      doom-themes-enable-italic t)

;; Load the `doom-moonlight' theme.
(load-theme 'doom-moonlight t)
(doom-modeline-mode +1)

;; Load a new theme with <SPC> t t.
(dotfiles/leader
  "tt" '(counsel-load-theme :which-key "Theme"))
#+END_SRC

** Doom Modeline

#+NAME: emacs-doom-modeline-package
#+BEGIN_SRC nix
epkgs.doom-modeline
#+END_SRC

Doom Modeline[fn:80] is a fancy and fast modeline inspired by minimalism design. It's integrated into Centaur Emacs, Doom Emacs, and Spacemacs.

#+NAME: emacs-doom-modeline-elisp
#+BEGIN_SRC emacs-lisp
;; Add the `doom-modeline' after initialization.
(add-hook 'after-init-hook 'doom-modeline-mode)
(setq doom-modeline-height 16
      doom-modeline-icon t)
#+END_SRC

* Footnotes

[fn:1] https://gnu.org

[fn:2] https://gnu.org/software/emacs/

[fn:3] https://literateprogramming.com/knuthweb.pdf

[fn:4] https://nixos.org/manual/nixos/stable

[fn:5] https://nixos.org/manual/nix/stable

[fn:6] https://nixos.org/manual/nixpkgs/stable

[fn:7] https://github.com/nix-community/home-manager

[fn:8] https://github.com/nix-community/emacs-overlay

[fn:9] https://github.com/nixos/nixos-hardware

[fn:10] https://github.com/t184256/nix-on-droid

[fn:11] https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html

[fn:12] https://golang.org

[fn:13] https://rust-lang.org

[fn:14] https://nodejs.org

[fn:15] https://grpc.io

[fn:16] https://iso.org/standard/74528.html

[fn:17] https://en.wikipedia.org/wiki/C++/

[fn:18] https://python.org

[fn:19] https://qemu.org

[fn:20] https://github.com/ch11ng/exwm

[fn:21] https://evil.readthedocs.io/en/latest/overview.html

[fn:22] https://raspberrypi.org/products/raspberry-pi-400/

[fn:23] https://www.raspberrypi.org/products/raspberry-pi-4-model-b/

[fn:24] https://samsung.com/us/mobile/galaxy-s10/buy/

[fn:25] https://x.org/wiki/

[fn:26] https://wayland.freedesktop.org

[fn:27] https://openssh.com

[fn:28] https://nixos.wiki/wiki/Flakes

[fn:29] https://nix-community.cachix.org

[fn:30] https://docker.org

[fn:31] https://en.wikipedia.org/wiki/Firefox

[fn:32] https://jellyfin.org

[fn:33] https://moonlight-stream.org

[fn:34] https://teamviewer.com

[fn:35] https://git-scm.com

[fn:36] https://emacswiki.org/emacs/LearnEmacsLisp

[fn:37] https://neovim.io

[fn:38] https://gtk.org

[fn:39] https://github.com/nixos/nix-mode

[fn:40] https://github.com/noctuid/general.el

[fn:41] https://github.com/justbur/emacs-which-key

[fn:42] https://emacswiki.org/emacs/eww

[fn:43] https://gnu.org/software/emacs/erc.html

[fn:44] https://emacswiki.org/emacs/DiredMode

[fn:45] https://emacswiki.org/emacs/DiredExtra#Dired_X

[fn:46] https://github.com/domtronn/all-the-icons.el

[fn:47] https://github.com/iqbalansari/emacs-emojify

[fn:48] https://gnu.org/software/emacs/manual/html_mono/eshell.html

[fn:49] https://github.com/akermu/emacs-libvterm

[fn:50] https://github.com/neovim/libvterm

[fn:51] https://magit.vc

[fn:52] https://github.com/skeeto/elfeed

[fn:53] https://orgmode.org

[fn:54] https://github.com/org-roam/org-roam

[fn:55] https://zettelkasten.de

[fn:56] https://github.com/org-roam/org-roam-server

[fn:57] https://orgmode.org/worg/org-contrib/org-drill.html

[fn:58] https://github.com/marcinkoziej/org-pomodoro

[fn:59] https://en.wikipedia.org/wiki/Pomodoro_Technique

[fn:60] https://github.com/bnbeckwith/writegood-mode

[fn:61] https://aspell.net

[fn:62] https://gohugo.io

[fn:63] https://oxhugo.scripter.co

[fn:64] https://chrishayward.xyz/posts/

[fn:65] https://chrishayward.xyz/notes/

[fn:66] https://revealjs.com

[fn:67] https://github.com/hexmode/ox-reveal

[fn:68] https://password-store.org

[fn:69] https://projectile.mx

[fn:70] https://microsoft.github.io/language-server-protocol

[fn:71] https://github.com/MaskRay/emacs-ccls

[fn:72] https://company-mode.github.io

[fn:73] https://emacswiki.org/emacs/GoMode

[fn:74] https://plantuml.com

[fn:75] https://github.com/skuro/plantuml-mode

[fn:76] https://github.com/abo-abo/swiper

[fn:77] https://github.com/DamienCassou/desktop-environment

[fn:78] https://github.com/hlissner/emacs-doom-themes

[fn:79] https://github.com/seagle0128/doom-modeline

[fn:80] https://laptopmedia.com/laptop-specs/acer-nitro-5-an515-53-2

[fn:81] https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html