---
title: Sourcehut Builder Cookbook for Guix System
---

# Introduction

This *mini* cookbook accompanies the official [builds.sr.ht
docs](https://man.sr.ht/builds.sr.ht).  The official documentation
covers various topics regarding all build images.

# Packages

## Install packages using sourcehut build manifest

A list of packages can be specified in `packages` field of sourcehut
build manifest. Packages are installed before running any task. Only
packages from the `%default-guix-channels` can be specified this way.

Example:

```yaml
image: guix
packages:
  - hello
tasks:
  - greet: |
      hello
```

To specify the output of package, `:` can be used in between the
package name and its output.  For example, `git:send-email` can be
specified in `packages` field to install `send-email` output of `git`
package.

## Install packages using guix manifest

This is the recommended way of installing packages, since a guix
manifest allows specifying packages, outputs, commits, versions,
transformations, etc.  Projects should have a guix manifest in the
source.

Example:

```scheme
;; manifest.scm

(specifications->manifest
 '("hello"))
```

First task of your build manifest can be set up to prepare your build
environment using guix.

```yaml
image: guix
tasks:
  - guix: |
      guix package -v0 -m project/path/to/manifest.scm
  - greet: |
      hello
```

# Channels

This is the recommended way, and currently the only way to specify and
use channels.  Current implementation of build executor prevents us
from specifying guix channels, and using them efficiently using the
sourcehut build manifest.  Projects should have a `channels.scm` file
in the source.

Example:

```scheme
;; channels.scm

(append
 (list
  (channel
   (name 'guixrus)
   (url "https://git.sr.ht/~whereiseveryone/guixrus")
   (introduction
    (make-channel-introduction
     "7c67c3a9f299517bfc4ce8235628657898dd26b2"
     (openpgp-fingerprint
      "CD2D 5EAA A98C CB37 DA91  D6B0 5F58 1664 7F8B E551")))))
 %default-channels)
```

Packages from custom/additional channels cannot be specified in
`packages` field of build manifest. A guix manifest should be used
instead.

```scheme
;; manifest.scm

(specifications->manifest
 '("hello"))
```

```yaml
image: guix
tasks:
  - guix: |
      guix pull -C project/path/to/channels.scm
      guix package -v0 -m project/path/to/manifest.scm
  - greet: |
      hello
```

# Profiles and Environments

Since the builder creates a new build environment for every job, build
user's default guix profile, i.e. `~/.guix-profile`, always starts
empty.  Using guix environment becomes unnecessary for trivial builds.

For non-trivial builds, that require more than one build environment
in a single build job, multiple guix profiles or guix environments can
be created.  The profiles can be sourced into `~/.buildenv` or in the
task itself, when needed.  See [Build
Environment](https://man.sr.ht/builds.sr.ht/#build-environment).

# Substitute Servers

Downloading from substitute servers other than the official guix
servers is done in two steps.  If the substitute servers are trusted,
they should be authorized first.  This is done by providing the public
keys of trusted servers to `guix archive --authorize`.  URLs to
substitute servers can then be given to various guix commands, like
`guix package`, via `--substitute-urls` flag to enable downloading
binaries directly instead.  See [Substitute
Authentication](https://guix.gnu.org/manual/en/html_node/Substitute-Authentication.html).
Projects should have public keys of substitute servers in the source.

Guix System will trust the keys only until the next boot. This is
important only if you are inspecting failed builds using shell access.

Example:

```scheme
;; manifest.scm

(specifications->manifest
 '("hello"))
```

```yaml
image: guix
tasks:
  - guix: |
      guix archive --authorize < project/path/to/key.pub
      servers="https://example.com https://ci.guix.gnu.org https://bordeaux.guix.gnu.org"
      guix package -v0 --substitute-urls=$servers -m project/path/to/manifest.scm
  - greet: |
      hello
```