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

Cuirass Status

#+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 ~/.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 -- ~ when ~~ uses the ~-L|--load-path~ option. However, ~guix ~ 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