Noob Guix' Checklist

Computing

AIMED AT: users who have gone through the basics and installed the system, but are still confused about things

Guix has not much in the way of end-user tutorials that tell you how to operate in day-to-day life. So you easily miss obvious things. We can't learn everything all at once nor see the best way to work even if we know roughly what commands exist. What follows would have prevented problems I had for far too long. Give it a gander in case you are suffering like I did.

I'd like to grow this list. If you have suggestions, email me!

Root vs user profile ??? I'm confus!

No, you don't need to run guix pull both as root and as your main user. Here's a full system upgrade: 

guix pull
guix upgrade
sudo -E guix system reconfigure ~/config.scm

Using sudo with the -E flag means you'll be using the user's copy of Guix, thus root does not need to do a guix pull. Do remember that root's copy is outdated if you ever log in to root on a tty (just don't do that).

(<2022-Jan-23> OK, pretty sure the -E flag is not even needed)

Loading

How best to load your own package definitions? In short:

  1. Don't set the shell variable GUIX_PACKAGE_PATH – forget about it altogether – instead, set up a private channel (see the manual).
  2. In addition, be familiar with the -L (--load-path) flag.

That's because you are solving two separate problems:

  1. Always having access to your privately defined packages
  2. Quickly iterating on new definitions

Quick iteration from a private channel is slow, because as of <2020-Mar-22>, guix pull does not have a setting to only pull the local channels, so you have to wait for it to update all your channels, pulling things over the network and calculating a new package graph, and god forbid there's actually an update to Guix.

In principle, GUIX_PACKAGE_PATH solves both problems, but it introduces its own problems: Guix gets no ability to version-control your packages (as it does with a channel), it's a bigger hurdle to publish your packages, and as of <2020-Mar-22>, it causes every Guix command to complain a lot about "source file newer than compiled".

Ok, show me

So, let's assume you have this directory structure for files containing your package definitions: 

~/my-channel/me/emacs-xyz.scm
~/my-channel/me/machine-learning.scm
~/my-channel/me/various.scm
~/my-channel/.git

Those *.scm files contain the top-level expressions (define-module (me emacs-xyz)) and (define-module (me machine-learning)) et cetera – the module names have to match the file and directory names.

Next up, the following content of ~/.config/guix/channels.scm will give you access to your packages. Plug and play. 

(cons*

  (channel
    (name 'me)
    (url "file:///home/me/my-channel/.git"))

  %default-channels)

That's all good when your package definitions work. But when I am writing a new package, I run into errors maybe twenty times before I get it right. So during this process of iteration, instead of repeatedly git-committing and guix-pulling, load the directory directly, sidestepping the whole channel concept: 

guix package -L ~/my-channel -i MY-EXPERIMENTAL-PACKAGE

Or, for example 

guix build -KM 5 -L ~/my-channel MY-EXPERIMENTAL-PACKAGE

That's it. The additional flags are a bit off topic here, but -M 5 (--max-jobs=5) simply lets there be 5 concurrent build jobs so it'll build faster. The -K (--keep-failed) means that on a failed build, it'll tell you the path to the build directory, so you can see what got built and what didn't, what the configure variables are etc. An use case is when you're trying to modify a Makefile procedurally in the package definition (e.g. delete a few lines) and want to visit the actual Makefile to check that the modification had the intended effect.

I recommend shortening all that to a quick command, let's call it "test": 

alias test="guix package -KM 5 -L ~/my-channel -i "

Then you can just run test PACKAGE every time you edit the definition for PACKAGE.

How to get help

You often find no help by Googling? Here are two places to get info, far more reliable than a generic web search:

  1. The #guix IRC channel logs
  2. The mailing list archives, particularly help-guix but also bug-guix lists.gnu.org/archive/html/

Download the entire chat log of the #guix IRC channel. Many, many times I've got answers by ripgrepping that directory.

Manpages

Especially when you keep separate package profiles/manifests, you might find Man pages and info documentation absent. To fix, every manifest (in addition to the main user profile & the system-wide profile) should contain at least the following packages:

  • man-db
  • info-reader
  • pkg-config

I'm not sure if there's a better way to do this.

Created (4 years ago)