#+TITLE: RekahSoft Dotfiles
#+AUTHOR: Collin J. Doering

#+BEGIN_EXPORT html
<p><a href="https://guix-ci.home.rekahsoft.ca/jobset/rekahsoft-dotfiles"><img src="https://guix-ci.home.rekahsoft.ca/jobset/rekahsoft-dotfiles/badge.svg?type=0" alt="Cuirass Status"></a></p>
#+END_EXPORT

#+begin_abstract
These are the dotfiles of the author, managed using guix-home, in combination with gnu stow
(until the gnu stow deployment mechanism has been deprecated in preference of guix-home).
#+end_abstract

* Repository Structure

- ~channels.scm~         :: [[*Guix Channel File][Guix Channel File]]
- ~.gitignore~           :: Files ignored by git
- ~.guix/~               :: Guix channel directory
- ~.guix-authorizations~ :: Guix authorizations file[fn:1]
- ~.guix-channel~        :: Guix channel file[fn:2]
- ~README.org~           :: Org-mode[fn:3] documentation
- ~TODO.org~             :: Org-mode todo's, known issues and future aspirations
- ~home-manifest.scm~    :: Guix manifest used for cuirass builds (and as needed via the cli)
- ~user-config~          :: Configuration for various programs managed using a combination of gnu stow and guix-home

** Guix Channel File

Guix channels[fn:4] allow for Guix to be customized and extended. They are also critical for
replicating a Guix system[fn:5]. To ensure reproducibility, a ~channels.scm~ file is provided
in this repository that is expected to be used during deployment. It pins external guix
channels to specific versions.

*** TODO Updating guix channels used for deployment

**This doesn't work right unless your channels match what is expected by this repository.**

#+begin_src shell
  guix time-machine -- describe -f channels > channels.scm
#+end_src

** ~dotfiles~ the Guix Channel

This repository is itself a Guix channel, which allows home configurations to come directly
from the channel, and the version of this configuration be managed just like any other guix
channel. It also facilitates CI, allowing for changes this channel be evaluated by Cuirass at
[[https://guix-ci.home.rekahsoft.ca]][fn:6]. This channel does not define any packages, only
home configurations.

* Quickstart

Home configuration, including startup services (via userland shepherd), configuration files
and installed packages are all managed using [[https://guix.gnu.org][guix]]/[[https://guix.gnu.org/en/manual/devel/en/html_node/Home-Configuration.html][guix-home]] and can be installed with the
following.

#+begin_src shell
  guix pull -C ~/.dotfiles/channels.scm
  guix home reconfigure -e '(@ (rekahsoft guix-config home) %home)'
#+end_src

* TODO Legacy Configuration

Configurations for a variety of programs are available to be 'installed' by symbolically
linking them into ~$HOME~ using stow. This process is simplified by the provided ~Makefile~,
however is expected to be deprecated by the switch to Guix home, which is not yet fully
completed. Currently guix home only manages bash configuration, and all other configuration
is still managed using the 'legacy' stow method described here.

#+begin_src shell
  # See what will be installed/linked by stow
  make DRY=true

  # Install/link all configurations
  make
#+end_src

** TODO Makefile Usage

~Makefile~ is expected to be become unnecessary after this configuration is managed by Guix home instead of using stow.

#+begin_verse
make [packages] [DRY=true] [RESTOW=true] [DELETE=true]

Where:
  <DRY>     must be undfined or 'true'
  <RESTOW>  must be undfined or 'true'
  <DELETE>  must be undfined or 'true'

Notes:
  If no [packages] are listed, all packages are actioned upon via the all target
#+end_verse

*** Examples

#+begin_src shell
  # Install a subset of the entire configuration
  make zsh xorg

  # Relink configuration
  make RESTOW=true

  # Relink configuration for a subset of packages
  make RESTOW=true bash zsh

  # Uninstall/unlink configuration
  make DELETE=true

  # Uninstall/unlink configuration for a subset of packages
  make DELETE=true bash
#+end_src

* Working with Local Sources

Clone this repository.

#+begin_src shell
  git clone <repo> ~/.dotfiles
  cd ~/.dotfiles
#+end_src

This home configuration is presented as a guix channel, and because of this, changes normally
need to be committed in order to be tested. However, the ~-L|--load-path~ option to guix can
be used to explicitly reference this repositories' uncommitted channel sources in ~.guix~
(using ~-L .guix~).

Additionally, to test with a different set of channels (for example, to check if this home
configuration works following updates to the guix, nonguix or some other dependent channel),
~guix time-machine~ can be used, explicitly referencing a channel file with ~-C|--channel~.
When ones local guix channels match ~channels.scm~, ~guix time-machine ...~ does not need to
be used because it has no effect and just adds overhead.

** TODO Issues when using ~-L|--load-path~ along with ~guix time-machine~

I have found that source changes are not detected when using ~guix time-machine -C
channels.scm -- <CMD>~ when ~<CMD>~ uses the ~-L|--load-path~ option. However, ~guix <CMD>~
on its own does detect source changes.

It's worth noting that I've missed this before because *I think* that when using ~guix
time-machine~ with ~-L~ the source is still parsed/evaluated, so syntax errors are detected.

This needs to be further investigated and is likely a guix bug.

Another note: It appears that if ~-L~ is provided on both sides of the guix time-machine
command, it works as expected and detects source changes. This does not appear to be
consistent though, and sometimes using ~-L~ only on the rhs works as expected.

** Deploy

#+begin_src shell
  guix time-machine -C channels.scm -- home reconfigure -L .guix -e '(@ (rekahsoft guix-config home) %home)'
#+end_src

** Build

#+begin_src shell
  guix time-machine -C channels.scm -- home build -L .guix -e '(@ (rekahsoft guix-config home) %home)'
#+end_src

** Test in a container

#+begin_src shell
  guix time-machine -C channels.scm -- home container -L .guix -e '(@ (rekahsoft guix-config home) %home)'
#+end_src

** View Guix Extension Graph

#+begin_src shell
  guix home extension-graph -e '(@ (rekahsoft guix-config home) %home)' | guix shell gnome-icon-theme xdot -- xdot -
#+end_src

** View Shepherd Graph

#+begin_src shell
  guix home shepherd-graph -e '(@ (rekahsoft guix-config home) %home)' | guix shell gnome-icon-theme xdot -- xdot -
#+end_src

* Development

This section details some useful tips regarding development.

** Guix

Here are some useful commands for working with package upgrades on guix.

#+begin_src shell
  # Check for binary substitute availability on the tip of master
  guix time-machine -- weather -m ~/.dotfiles/home-manifest.scm

  # Build a environment using the provided home-manifest.scm off the tip of master (useful to test the new environment)
  guix time-machine -- environment -m ~/.dotfiles/home-manifest.scm -- exit
#+end_src

*** Updates that modify zsh site-functions (completions)

These updates require additional manual effort, otherwise completions don't show up.

#+begin_src shell
  # Set fpath in ~/.zprofile (this is already done in the zsh configuration)
  #fpath=(~/.guix-home/profile/share/zsh/site-functions $fpath)

  rm -r ~/.zcompdump && compinit
#+end_src

*** Try out any packaged window manager

The included ~xorg~ configuration provides a script that is used to ~startx~, located in
~~/.bin/startx.sh~ after installing/linking the ~xorg~ configuration. This script is required
as the ~startx~ that comes with the ~xinit~ package on guix does not work when Xorg is
installed in a user profile. Like the original ~startx~ command, this script passes through
arguments to ~~/.xinitrc~. The included ~~/.xinitrc~ takes two optional arguments,
~SESSION_WM~ and ~SESSION_TYPE~, the window manager to run and the session type to use. The
session type can be one of ~full~ (default), ~min~, or ~new~.

Start the default window manager (~exwm~) with the default session type (~full~).

#+begin_src shell
  startx
#+end_src

**Note:** if using the configuration ~zsh~ or ~bash~, all ~*.sh~
scripts linked into ~~/.bin~ are aliased to exclude the ~.sh~ suffix.

#+begin_src shell
  guix shell ratpoison -- startx.sh ratpoison new
#+end_src

**Note:** The script ~startx.sh~ must be used directly here, and not
by the ~startx~ alias mentioned above.

This works very well for simple window managers, however for more
complicated environments, many times there are numerous packages that
will be required. Here is an example of starting xfce using this
mechanism.

#+begin_src shell
  guix shell xfce xfce4-session xfconf -- startx.sh startxfce4 new
#+end_src

* Footnotes

[fn:1] https://guix.gnu.org/manual/en/html_node/Channel-Authentication.html

[fn:2] https://guix.gnu.org/manual/en/html_node/Package-Modules-in-a-Sub_002ddirectory.html

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

[fn:4] https://guix.gnu.org/manual/en/html_node/Channels.html

[fn:5] https://guix.gnu.org/manual/en/html_node/Replicating-Guix.html

[fn:6] Only available in my internal home-network