dotfiles/README.org

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

#+PROPERTY: header-args:emacs-lisp :tangle init.el :comments org
#+PROPERTY: header-args            :results silent :eval no-export

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

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

Portable [[https://gnu.org/software/emacs][GNU/Emacs]][fn:1] dotfiles. Built for Life, Liberty, and the Open Road.

+ 100% Literate
+ 100% Immutable
+ 100% Reproducible

* Init

This project makes heavy use of modern features and libraries. Since [[https://orgmode.org/worg/org-contrib/babel/intro.html][Org-babel]][fn:2]'s used during the initialization, [[https://orgmode.org][Org-mode]][fn:3] must load prior to importing any custom modules. My solution includes the introduction of some early intitialization code written in [[https://gnu.org/software/emacs/manual/html_node/elisp/index.html][Emacs Lisp]][fn:4].

#+begin_src emacs-lisp
(load-file "~/.emacs.d/bin/options.el")
(load-file "~/.emacs.d/bin/cleanup.el")
(load-file "~/.emacs.d/bin/packages.el")
#+end_src

** Load host definition

Begin the process by loading any host specific option overrides. The host configuration tangles, and loads (if it exist) using the systems name. If a host definition doesn't exist the default values remain. 

#+begin_src emacs-lisp
(let ((host-file (concat dotfiles/home "/hosts/" system-name ".org")))
  (when (file-exists-p host-file)
    (org-babel-load-file host-file)))
#+end_src

** Load enabled modules

All of the modules in ~dotfiles/modules~ load after the host overrides. By default, all of the packages defined in ~dotfiles/modules-p~ load. Override this behaviour in a host configuration file.

#+begin_src emacs-lisp
(dolist (m dotfiles/modules)
  (let ((mod-file (concat dotfiles/home "/modules/" (symbol-name m) ".org")))
    (when (file-exists-p mod-file)
      (org-babel-load-file mod-file))))
#+end_src

* Hosts

Each host machines configuration loaded immediately after declaring the options, before applying any configuration. This allows system to system control while remaining immutable. Override any of the available options configurations in a host file. Here's some examples to get started:

+ [[file:hosts/acernitro.org][Acernitro]]
+ [[file:hosts/gamingpc.org][GamingPC]]
+ [[file:hosts/localhost.org][Termux]]
+ [[file:hosts/raspberry.org][Raspberry]]
+ [[file:hosts/virtualbox.org][VirtualBox]] 

* Modules

Breaking down the project into logical units or chapters to keep the code more maintainable and organized. This is also a fundamental requirement to achieve the goal of modularity. Below are details of the modules, and their respective dependencies.

#+begin_src plantuml :file docs/images/modules.png :exports none
left to right direction
allowmixing

package Core
package Editor
package Shell
package Email
package Terminal
package Encryption
package Desktop
package Writing
package Presentations
package Website
package Capture
package Projects
package Development
package Interface
package Dashboard

Editor --> Core

Shell --> Editor
Email --> Editor
Projects --> Editor
Terminal --> Editor
Interface --> Editor
Encryption --> Editor

Desktop --> Shell

Writing --> Encryption

Capture --> Writing
Website --> Writing
Presentations --> Writing

Development --> Projects

Dashboard --> Interface
#+end_src

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

+ [[file:modules/capture.org][Capture]]
+ [[file:modules/core.org][Core]] 
+ [[file:modules/dashboard.org][Dashboard]] 
+ [[file:modules/desktop.org][Desktop]] 
+ [[file:modules/development.org][Development]] 
+ [[file:modules/editor.org][Editor]] 
+ [[file:modules/email.org][Email]] 
+ [[file:modules/encryption.org][Encryption]] 
+ [[file:modules/interface.org][Interface]] 
+ [[file:modules/presentations.org][Presentations]] 
+ [[file:modules/projects.org][Projects]] 
+ [[file:modules/shell.org][Shell]] 
+ [[file:modules/terminal.org][Terminal]]
+ [[file:modules/website.org][Website]] 
+ [[file:modules/writing.org][Writing]] 

* Options

Here's a complete list of all of the options configurable for each host, and their default values. 

+ All variables prefixed with ~dotfiles/~
+ Initialized prior to loading of packages or hosts

** Constants

| Symbol               | Default          | Description                                 |
|----------------------+------------------+---------------------------------------------|
| ~dotfiles/home~      | =~/.emacs.d=     | Origininal value of ~user-emacs-directory~. |
| ~dotfiles/cache~     | =~/.cache/emacs= | Redirection target of ~user-emacs-dictory~. |
| ~dotfiles/modules-p~ | [[file:modules/][Modules]]          | All of the available system modules.        |

** Variables
  
| Symbol                       | Default                 | Description                       |
|------------------------------+-------------------------+-----------------------------------|
| ~dotfiles/browser~           | =$BROWSER=              | Default system web browser.       |
| ~dotfiles/language~          | =$LANG=                 | Default system language.          |
|------------------------------+-------------------------+-----------------------------------|
| ~dotfiles/modules~           | ~dotfiles/modules-p~    | All of the enabled modules.       |
|------------------------------+-------------------------+-----------------------------------|
| ~dotfiles/font~              | Fira Code               | Unified system font family.       |
| ~dotfiles/font-size~         | 96                      | Unified system font size.         |
|------------------------------+-------------------------+-----------------------------------|
| ~dotfiles/idle~              | 0.0                     | Completion delay time.            |
|------------------------------+-------------------------+-----------------------------------|
| ~dotfiles/leader-key~        | SPC                     | All powerful leader key.          |
| ~dotfiles/leader-key-global~ | C-(dotfiles/leader-key) | Global prefix for the leader key. |
|------------------------------+-------------------------+-----------------------------------|
| ~dotfiles/projects~          | =~/.local/source=       | Location of source code projects. |
| ~dotfiles/passwords~         | =~/.password-store=     | Location of local password store. |
|------------------------------+-------------------------+-----------------------------------|
| ~dotfiles/public-key~        | =5EAG356GFAE...=        | GPG key to encrypt org files for. |

* Resources

[fn:1] https://gnu.org/software/emacs
[fn:2] https://orgmode.org/worg/org-contrib/babel/intro.html
[fn:3] https://orgmode.org
[fn:4] https://gnu.org/software/emacs/manual/html_node/elisp/index.html
[fn:5] https://en.wikipedia.org/wiki/Chicken_or_the_egg