dotfiles/README.org

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

#+begin_abstract
These are the dotfiles of Collin Doering.
#+end_abstract

* Quickstart

Clone this repository.

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

Dependencies are managed using [[https://guix.gnu.org][guix]] and can be installed with the following.

#+begin_src shell
  guix pull -C ~/.dotfiles/channels.scm
  guix package -m ~/.dotfiles/home-manifest.scm
#+end_src

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

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

  # Install/link all configurations
  make
#+end_src

* Makefile Usage

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

* 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-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 environment --ad-hoc 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 environment --ad-hoc xfce xfce4-session xfconf -- startx.sh startxfce4 new
#+end_src