dotfiles/README.org

8.2 KiB

RekahSoft Dotfiles

Cuirass Status

These are the dotfiles of the author, managed using guix-home.

Repository Structure

channels.scm
Guix Channel File
.gitignore
Files ignored by git
.guix/
Guix channel directory
.guix-authorizations
Guix authorizations file1
.guix-channel
Guix channel file2
README.org
Org-mode3 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 channels4 allow for Guix to be customized and extended. They are also critical for replicating a Guix system5. 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.

  guix time-machine -- describe -f channels > channels.scm

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.ca6. 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 guix/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.

  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

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

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

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.

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

Working with Local Sources

Clone this repository, if you haven't already.

  git clone <repo> ~/.dotfiles
  cd ~/.dotfiles

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

  guix time-machine -C channels.scm -- home reconfigure -L .guix -e '(@ (rekahsoft guix-config home) %home)'

Build

  guix time-machine -C channels.scm -- home build -L .guix -e '(@ (rekahsoft guix-config home) %home)'

Test in a container

  guix time-machine -C channels.scm -- home container -L .guix -e '(@ (rekahsoft guix-config home) %home)'

View Guix Extension Graph

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

View Shepherd Graph

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

Development

This section details some useful tips regarding development.

Guix

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

  # 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

Updates that modify zsh site-functions (completions)

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

  # 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

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).

  startx

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

  guix shell ratpoison -- startx.sh ratpoison new

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.

  guix shell xfce xfce4-session xfconf -- startx.sh startxfce4 new

Footnotes