#Introduction

This mini cookbook accompanies the official builds.sr.ht docs. 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:

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:

;; manifest.scm

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

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

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:

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

;; manifest.scm

(specifications->manifest
 '("twelve-tone"))

image: guix
tasks:
  - guix: |
      guix pull -C project/path/to/channels.scm
      guix package -v0 -m project/path/to/manifest.scm
  - generate: |
      twelve-tone

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

#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. 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:

;; manifest.scm

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

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