236 lines
8.5 KiB
Org Mode
236 lines
8.5 KiB
Org Mode
#+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:2]
|
|
- ~.guix-channel~ :: Guix channel file[fn:3]
|
|
- ~README.org~ :: Org-mode[fn:4] 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:5] allow for Guix to be customized and extended. They are also critical for
|
|
replicating a Guix system[fn:6]. 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:7]. 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
|