dotfiles/README.org

#+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.
#+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
- ~home-manifest.scm~    :: Guix manifest used for cuirass builds (and as needed via the cli)
- ~user-config~          :: Configuration for various programs managed using 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.

First, obtain the projects guix channel file. There are two ways to do this; with http
fetching only the channel file, or with git, fetching the entire dotfiles project; the later
is necessary if you plan on [[*Working with Local Sources][Working with Local Sources]].

#+begin_src shell
  mkdir ~/.dotfiles && curl --output-dir ~/.dotfiles -O https://git.rekahsoft.ca/rekahsoft/dotfiles/raw/branch/master/channels.scm
  # OR
  git clone https://git.rekahsoft.ca:rekahsoft/dotfiles.git ~/.dotfiles
#+end_src

Then, use guix to pull the provided channel file and reconfigure guix-home.

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

** Try it out in a container!

Thanks to the power of Guix, these dotfiles can be tried out in a container, with the only
prerequisite being guix itself.

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

* Working with Local Sources

Clone this repository, if you haven't already.

#+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