Руководство GNU Guix

Table of Contents

Next: , Up: (dir)   [Contents][Index]

GNU Guix

Этот документ описывает GNU Guix версии 1.0.1, пакетный менеджер, написанный для системы GNU.

This manual is also available in Simplified Chinese (see GNU Guix参考手册), French (see Manuel de référence de GNU Guix), German (see Referenzhandbuch zu GNU Guix), Spanish (see Manual de referencia de GNU Guix), and Russian (see Руководство GNU Guix). If you would like to translate it in your native language, consider joining the Translation Project.


Next: , Previous: , Up: Top   [Contents][Index]

1 Введение

GNU Guix1 — это уитилита для управления пакетами и дистрибутив системы GNU. Guix позволяет непривилегированным пользователям устанавливать, обновлять и удалять программные пакеты, откатываться до предыдущих наборов пакетов, собирать пакеты из исходников и обеспечивает создание и поддержку программного окружения в целом.

Вы можете установить GNU Guix поверх существующей системы GNU/Linux, и она дополнит функции системы новой утилитой, не внося помехи (see Установка). Или можно использовать отдельную операционную систему — систему Guix2. See Дистрибутив GNU.


Next: , Up: Введение   [Contents][Index]

1.1 Управление программным обеспечением Guix Way

Guix предоставляет интерфейс командной строки для управления пакетами (see Управление пакетами), инструменты, которые помогают в разработке программного обеспечения (see Разработка), более сложные утилиты командной строки (see Утилиты), а также программный интерфейс Scheme (see Программный интерфейс). Его демон сборки отвечает за сборку пакетов по запросам пользователей (see Настройка демона) и за скачивание компилированных бинарников из авторизованных ресурсов (see Подстановки).

Guix включает определения пакетов для множества проектов GNU и не-GNU, каждый из которых уважает свободу пользователя в работе за компьютером. Он расширяемый: пользователи могут писать свои собственные определения пакетов (see Описание пакетов) и делать их доступными как независимые пакетные модули (see Пакетные модули). Он также настраиваемый: пользователи могут получать специальные определения пакетов из существующих, в том числе через командную строку (see Опции трансформации пакета).

Под капотом Guix работает как функциональный пакетный менеджер — принцип, впервые введённый Nix (see Благодарности). В Guix процесс сборки и установки пакета рассматривается как функция в математическом смысле. Эта функция принимает входные данные, как например, скрипты сборки, компилятор, её результат зависит только от входных данных, и он не может зависеть от программ или скриптов, которые не подаются на вход явным образом. Функция сборки всегда производит один результат, когда получает один и тот же набор входных данных. Она не может как-либо изменять окружение запущенной системы; например, она не может создавать, изменять или удалять файлы за пределами её директорий сборки и установки. Это достигается так: процесс сборки запускается в изолированном окружении (или контейнере), в котором видны только входные данные, заданные явно.

Результат работы функций сборки пакетов кешируется в файловой системе в специальной директории, называемой склад (see Склад).Каждый пакет устанавливается в собственную директорию склада, по умолчанию — под /gnu/store. Имя директории содержит хеш всех входных данных, используемых для сборки этого пакета, так что изменение входных данных порождает различные имена директорий.

Этот подход является принципиальным, на нём основаны ключевые особенностей Guix: поддержка транзакционного обновления пакета и откаты, установка для отдельного пользователя, сборка мусора от пакетов (see Особенности).


Previous: , Up: Введение   [Contents][Index]

1.2 Дистрибутив GNU

Guix comes with a distribution of the GNU system consisting entirely of free software3. The distribution can be installed on its own (see Установка системы), but it is also possible to install Guix as a package manager on top of an installed GNU/Linux system (see Установка). When we need to distinguish between the two, we refer to the standalone distribution as Guix System.

The distribution provides core GNU packages such as GNU libc, GCC, and Binutils, as well as many GNU and non-GNU applications. The complete list of available packages can be browsed on-line or by running guix package (see Вызов guix package):

guix package --list-available

Наша цель — предоставить состоящий на 100% из свободного программного обеспечения рабочий дистрибуив Linux или другие варианты GNU. Мы ориентируемся на продвижении и полноценной интеграции компонентов GNU и поддержке программ и утилит, которые помогают пользователям реализовать их свободы.

Пакеты в данные момент доступны для следующих платформ:

x86_64-linux

архитектура Intel/AMD x86_64 с ядром Linux-Libre;

i686-linux

архитектура Intel 32-bit (IA32) с ядром Linux-Libre;

armhf-linux

Архитектура ARMv7-A с hard float, Thumb-2 и NEON, используя двочиный интерфейс приложений EABI hard-float (ABI), с ядром Linux-Libre.

aarch64-linux

little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.

mips64el-linux

little-endian 64-bit MIPS processors, specifically the Loongson series, n32 ABI, and Linux-Libre kernel. This configuration is no longer fully supported; in particular, the project’s build farms no longer provide substitutes for this architecture.

Пользуясь системой Guix, вы объявляете все аспекты конфигурации системы, и Guix выполняет установку инстранции ОС транзакционным, повторяемым способом, не имеющей состояния (stateless) (see Конфигурирование системы). Система Guix использует ядро Linux-libre, систему инициализации Shepherd (see Введение in The GNU Shepherd Manual), хорошо известные утилиты и тулчейны GNU, а также графическое окружение на выбор.

Система Guix доступна для платформ, приведённых выше, кроме mips64el-linux.

Информация о портировании на другие архитектуры и ядра доступна в see Портирование.

Дистрибутив созаётся совместными усилиями, приглашаем вас! См. See Содействие, чтобы узнать о том, как вы можете помочь.


Next: , Previous: , Up: Top   [Contents][Index]

2 Установка

Заметка: Мы рекомендуем использовать этот скрипт установки для установки Guix на существующую систему GNU/Linux, называемый далее чужой дистрибутив.4 Скрипт автоматизирует скачивание, установку и начальную конфигурацию Guix. Он должен запускаться от пользователя root.

При установке на чужой дистрибутив GNU Guix дополняет доступные утилиты без внесения помех. Его данные живут только в двух директориях — обычно /gnu/store и /var/guix; другие файлы вашей системы, как /etc, остаются нетронутыми.

Установленный Guix можно обновлять командой guix pull (see Запуск guix pull).

Если вы предпочитаете выполнять шаги установки вручную или хотита подправить их, следующие параграфы будут полезны. В них описаны требования Guix к программному обеспечению, а также процесс ручной установки до запуска в работу.


Next: , Up: Установка   [Contents][Index]

2.1 Бинарная установка

Этот раздел описывает, как установить Guix на обычную систему из отдельного архива, который содержит бинарники Guix и все его зависимости. Это обычно быстрее установки из исходных кодов, которая описана в следующем разделе. Единственное требование - иметь GNU tar и Xz.

Заметка: Мы рекомендуем использовать этот установочный скрипт. Скрипт автоматизирует скачивание, установку и начальные шаги конфигурации, описанные ниже. Он должен запускаться от пользователя root.

Установка производится следующими образом:

  1. Скачайте архив с бинарником из ‘https://ftp.gnu.org/gnu/guix/guix-binary-1.0.1.system.tar.xz’, где system — это x86_64-linux для машины x86_64, на которой уже запущено ядро Linux, и так далее.

    Убедитесь в аутентичности архива, скачав файл .sig и запустив:

    $ wget https://ftp.gnu.org/gnu/guix/guix-binary-1.0.1.system.tar.xz.sig
    $ gpg --verify guix-binary-1.0.1.system.tar.xz.sig
    

    Если это завершается ошибкой, значит у вас нет необходимого публичного ключа, тогда запустите команду для импорта ключа:

    $ gpg --keyserver pool.sks-keyservers.net \
          --recv-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
    

    и запустите команду gpg --verify.

    Take note that a warning like “This key is not certified with a trusted signature!” is normal.

  2. Теперь вам необходимы привилегии пользователя root. В зависимости от вашего дистрибутива, можно запустить su - или sudo -i. Под root запустите:
    # cd /tmp
    # tar --warning=no-timestamp -xf \
         guix-binary-1.0.1.system.tar.xz
    # mv var/guix /var/ && mv gnu /
    

    Это создаёт /gnu/store (see Склад) и /var/guix. Последнее содержит готовый к использованию профиль для root (подробнее в следующем шаге).

    Не распаковывайте архив в работающую систему Guix, так как это перезапишет её основные файлы.

    Опция --warning=no-timestamp необходима, чтобы удостовериться, что GNU tar не вызывает ошибок об "устаревшей дате", подобные ошибки появлялись в GNU tar 1.26 и старше, в последних версиях всё в порядке). Они возникают из-за того, что архив имеет нулевую дату модификации (что соответствует 1 января 1970). Это сделано с той целью, чтобы удостовериться, что содержимое архива не засисит от даты его создания, что делает его воспроизводимым (повторяемым).

  3. Сделайте профиль доступным по пути ~root/.config/guix/current, куда guix pull будет устанавливать обновления (see Запуск guix pull):
    # mkdir -p ~root/.config/guix
    # ln -sf /var/guix/profiles/per-user/root/current-guix \
             ~root/.config/guix/current
    

    Добавьте etc/profile в PATH и другие соответствующие переменные окружения:

    # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
      source $GUIX_PROFILE/etc/profile
    
  4. Создайте группу и пользовательские учётные записи, как это обозначено в (see Установка окружения сборки).
  5. Запустите демон и сделайте добавьте его в автоззагрузку после старта.

    Если ваш дистрибутив использует систему инициализации systemd, этого можно добиться следующими командами:

    # cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
         /etc/systemd/system/
    # systemctl start guix-daemon && systemctl enable guix-daemon
    

    Если ваш дистрибутив использует систему инициализации Upstart:

    # initctl reload-configuration
    # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
         /etc/init/
    # start guix-daemon
    

    Или можно запускать демон вручную так:

    # ~root/.config/guix/current/bin/guix-daemon \
           --build-users-group=guixbuild
    
  6. Сделайте команду guix доступной для других пользователей машины, например, так:
    # mkdir -p /usr/local/bin
    # cd /usr/local/bin
    # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
    

    Хорошо также предоставить доступ к Info-версии руководства так:

    # mkdir -p /usr/local/share/info
    # cd /usr/local/share/info
    # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
      do ln -s $i ; done
    

    Это добавляет /usr/local/share/info в поиск, запуск info guix откроет это руководство, см. (see Other Info Directories in GNU Texinfo для подробной информации об изменении путей поиска Info).

  7. Чтобы использовать подстановки из ci.guix.gnu.org или из одного из зеркал (see Подстановки), авторизуйте их:
    # guix archive --authorize < \
         ~root/.config/guix/current/share/guix/ci.guix.gnu.org.pub
    
  8. Каждый пользователь, возможно, должен выполнить дополнительные шаги, чтобы сделать их окружение Guix готовым к использованию see Установка приложения.

Вуаля! Установка завершена!

Вы можете проверить, что Guix работает, установив тестовый пакет для профиля root:

# guix install hello

Архив для бинарной установки может быть воспроизведён (повторён) и проверен простым запуском следующей команды в дереве исходников Guix:

make guix-binary.system.tar.xz

..., что в свою очередь, выполнит:

guix pack -s system --localstatedir \
  --profile-name=current-guix guix

See Вызов guix pack для подробной информации об этом полезном инструменте.


Next: , Previous: , Up: Установка   [Contents][Index]

2.2 Требования

Этот раздел содержит требования для сборки Guix из исходников. Пожалуйста, смотрите файлы README и INSTALL в дереве исходников Guix для подробной информации.

GNU Guix доступен для скачивания на сайте https://www.gnu.org/software/guix/.

GNU Guix зависит от следующих пакетов:

Следующие зависимости опциональны:

Если строка --disable-daemon не использовалась в configure, тогда необходимы также следующие пакеты:

При конфигурировании Guix в системе, котора уже имеет установленный Guix, обязательно укажите такую же главную директорию, как в существующей установке, пользуясь опцией --localstatedir в скрипет configure (see localstatedir in GNU Coding Standards). Скрипт configure защищает от случайной ошибки в конфигурации localstatedir, так что вы не повредите случайно (see Склад).

When a working installation of the Nix package manager is available, you can instead configure Guix with --disable-daemon. In that case, Nix replaces the three dependencies above.

Guix совместим с Nix, так что возможно разделение склада между ними. Чтобы сделать так, нужно указать configure не только то же значение --with-store-dir, но и такое же значение --localstatedir. Последнее существенно важно, потому что это указывает путь базы данных, в которой хранятся метаданные о складе и другие вещи. Значения по умолчанию для Nix: --with-store-dir=/nix/store и --localstatedir=/nix/var. Отметим, что --disable-daemon не обязательно для того, чтобы разделять склад с Nix.


Next: , Previous: , Up: Установка   [Contents][Index]

2.3 Запуск набора тестов

После успешногозавершения configure и make, хорошо бы выполнить набор тестов. Это поможет выявить проблемы установки или в окружении, как и баги самого Guix (на самом деле, отчёты об ошибках тестов помогают улучшить ПО). Чтобы запустить тесты, напечатайте:

make check

Тесты можно выполнять параллельно при включении опции -j в GNU make, так быстрее. Первый запуск может длиться несколько минут на топовой машине, последующие запуски будут быстрее, так как склад, который создаётся для тестов, уже закеширует различные вещи.

Также можно запустить отдельные наборы тестов, используя переменную TESTS, как в примере:

make check TESTS="tests/store.scm tests/cpio.scm"

По умолчанию результаты тестов выводятся в файл. Чтобы просмотреть результаты каждого отдельного теста, нужно задать переменную makifile SCM_LOG_DRIVER_FLAGS, как в примере:

make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"

В случае ошибки, пожалуйста, отправьте сообщение на bug-guix@gnu.org и присоедините файл test-suite.log. Пожалуйста, обозначьте в сообщении используемую версию Guix, а также номера версий зависимостей (see Требования).

Guix также идёт с набором тестов для всей системы, который проверяет нстранцию системы Guix. Их можно запустить только в системах, где Guix уже установлен, так:

make check-system

или, опять же, задав TESTS, чтобы выбрать список тестов для запуска:

make check-system TESTS="basic mcron"

Тесты системы определены в модулях (gnu tests …). При работе они запускают операционную систему под легковесным инструментарием в виртуальной машине. Они могут выполнять тяжёлые вычисления или довольно простые в зависимости от наличия подстановок их зависимостей (see Подстановки). Некоторые из них требуют много места для работы с образами виртуальной машины.

Конечно, в случае неудачных тестов, пожалуйста, направьте детали на bug-guix@gnu.org.


Next: , Previous: , Up: Установка   [Contents][Index]

2.4 Настройка демона

Такие операции, как сборка пакета или запуск сборщика мусора, выполняются запуском специальных процесса — демона сборки — по запросам клиентов. Только демон имеет доступ к складу и его базе данных. Так что операции управления складом выполняются с помощью демона. Например, инструменты командной строки, как guix package и guix build, обычно взаимодействуют с демоном через удалённый вызов процедур (RPC) и сообщают, что необходимо сделать.

Следующие разделы поясняют как настроить окружение демона сборки. Смотрите также Подстановки для подробной инсорации о том, как разрешить демону скачивать собранные бинарники.


Next: , Up: Настройка демона   [Contents][Index]

2.4.1 Установка окружения сборки

В случае стандартной многопользовательской установки Guix и его демон (программа guix-daemon) установливаются системным администратором; /gnu/store принадлежит root, и guix-daemon запущен от root. Непривилегированные пользователи могут пользоваться инструментами Guix, чтобы собирать пакеты или получить доступ к складу с какой-либо целью, и демон выполнит это по их запросу, убедившись, что склад находится в должном состоянии, и разрешив сборку пакетов и разделение их между пользователями.

Когда guix-daemon запущен от root, возможно, из соображений безопасности вы не примете того, что процессы сборки пакетов тоже выполняются от root. Чтобы избежать этого, необходимо создать специальных пользователей для сборки. Ими будет пользоваться процесс сборки, запускаемый демоном. Эти пользователи сборки не должны иметь оболочки и домашней директории — они просто будут использоваться, когда демон сбрасывает привилегии root в процессе сборки. Наличие нескольких таких пользователей позволит демону запускать отдельные процессы сборки под отдельными UID, что гарантирует, что они не будут помехой друг другу — важная особенность, учитывая, что сборка рассматривается как чистая функция (see Введение).

В системе GNU/Linux набор пользователей для сборки может быть создан так (используя синтаксис команды Bash shadow):

# groupadd --system guixbuild
# for i in `seq -w 1 10`;
  do
    useradd -g guixbuild -G guixbuild           \
            -d /var/empty -s `which nologin`    \
            -c "Guix build user $i" --system    \
            guixbuilder$i;
  done

Число пользователей для сборки определяет, сколько задач сборки может быть запущено параллельно. Это задаётся опцией --max-jobs (see --max-jobs). Чтобы использовать guix system vm и подобные, вам потребуется добавить пользователей для сборки в группу kvm, так чтобы они имели доступ к /dev/kvm, используя -G guixbuild,kvm вместо -G guixbuild (see Вызов guix system).

Программа guix-daemon тогда может запускаться от root следующим образом5:

# guix-daemon --build-users-group=guixbuild

Так демон стартует процессы сборки в chroot под одним из пользователей группы guixbuilder. В GNU/Linux по умолчанию окружение chroot содержит только следующее:

Можно указать директорию, в которую демон сохраняет деревья сборки через переменную окружения TMPDIR. Однако дерево сборки внутри chroot всегда называется /tmp/guix-build-name.drv-0, где name - это имя деривации, то есть, например, coreutils-8.24. Так значение TMPDIR не проникает внутрь окружения сборки, что предотвращает расхождения и случаях, когда процессы сборки имеют иные имена их деревьев сборки.

Демон также уважаем переменную окружения http_proxy, когда выполняет скачивание по HTTP как для дериваций с фиксированным результатом (see Деривации), так и для подстановок (see Подстановки).

Если вы устанавливаете Guix как непривилегированный пользователь, всё ещё возможно запустить guix-daemon с указанием --disable-chroot. Однако процессы сборки не будут изолированы один от другого, а также от остальной системы. Так процессы сборки смогут внести помехи в работу друг друга, смогут получить доступ к программам, библиотекам и другим файлам, доступным в системе, что конечно, делает затруднительным рассмотрение сборки как чистой функции.


Next: , Previous: , Up: Настройка демона   [Contents][Index]

2.4.2 Использование функционала разгрузки

При необходимости, демон сборки может разгружать сборку деривации на другие машины, работающие с Guix, используя разгрузочный хук сборки7. Когда эта функция включена, тогда считывается список машин для сборки, заданный пользователем в файле /etc/guix/machines.scm; при каждом запросе сборки командой guix build демон предпринимает попытку разгрузить сборку на одну из машин, удовлетворяющих требованиям деривации, в частноси, требованиям к типу системы, т.е. x86_64-linux. Отсутствующий набор данных и пакетов, необходимы для сборки, копируется через SSH на целевую машину, на которой затем выполняется процесс сборки. После успешного завершения результат(ы) сборки копируются обратно на машину, инициировавшую сборку.

Файл /etc/guix/machines.scm обычно выглядит так:

(list (build-machine
        (name "eightysix.example.org")
        (system "x86_64-linux")
        (host-key "ssh-ed25519 AAAAC3Nza…")
        (user "bob")
        (speed 2.))     ;incredibly fast!

      (build-machine
        (name "meeps.example.org")
        (system "mips64el-linux")
        (host-key "ssh-rsa AAAAB3Nza…")
        (user "alice")
        (private-key
         (string-append (getenv "HOME")
                        "/.ssh/identity-for-guix"))))

В примере выше мы обозначили список, состоящий из двух машин: одна — для архитектуры x86_64, а другая — для архитектуры mips64el.

По факту, этот файл, что не удивительно, является файлом Scheme, и он имеет значение, когда запускается хук разгрузки. Он возвращает объекты класса build-machine. Приведённый пример показывает фиксированный список машин для сборки, но можно представить, скажем, используя DNS-SD, он может возвращать список потенциальных машин, обнаруженных в локальной сети (see Guile-Avahi in Using Avahi in Guile Scheme Programs). Тип данных build-machine описан ниже.

Тип данных: build-machine

Этот тип данных представляет машины для сборки, на которые демон может разгружать сборки. Важные поля:

name

Имя хоста удалённой машины

system

Тип системы удалённой машины, то есть x86_64-linux.

user

Аккаунт пользователя, используемый для соединения с удалённой машиной через SSH. Отметим, что ключ-пара SSH не должна быть защищена парольной фразой, чтобы разрешить не интерактивные авторизации.

host-key

Это публичный ключ хоста в формает OpenSSH. Он используется при аутентификации машины, когда мы подсоединяемс к ней. Это длинная строка, которая выглядит примерно так:

ssh-ed25519 AAAAC3NzaC…mde+UhL hint@example.org

Если на машине запущен демон OpenSSH sshd, ключ хоста может быть найден в файле под директорией /etc/ssh, например, /etc/ssh/ssh_host_ed25519_key.pub.

Если на машине запущен демон SSH GNU lsh, lshd, тогда ключ хоста расположен в /etc/lsh/host-key.pub или подобном файле. Его можно конвертировать в формат OpenSSH, используя lsh-export-key (see Converting keys in LSH Manual):

$ lsh-export-key --openssh < /etc/lsh/host-key.pub 
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV…

Список необязательных полей:

port (default: 22)

Номер порта сервера SSH на машине.

private-key (default: ~root/.ssh/id_rsa)

Файл приватного ключа в формате OpenSSH, используемого в соединении с машиной. Этот ключ не должен быть защищён парольной фразой.

Отметим, что значение по умолчанию — приватный ключ аккаунта root. Убедитесь, что он существует, если вы используете настройки по умолчанию.

compression (default: "zlib@openssh.com,zlib")
compression-level (default: 3)

Методы компрессии уровня SSH и уровень компрессии.

Отметим, что разгрузка зависит от компрессии SSH, что уменьшает использование траффика при передаче файлов на и с машин для сборки.

daemon-socket (default: "/var/guix/daemon-socket/socket")

Имя файла сокета Unix-домена, который слушает guix-daemon на удалённой машине.

parallel-builds (default: 1)

Число сборок, которые могут быть запущены на машине.

speed (default: 1.0)

Показатель скорости. Планировщик разгрузки предпримет попытку выбрать машину с наибольшим показателем скорости.

features (default: '())

Набор строк, описывающий специфические функции, которые поддерживаются на машине. Например, "kvm" для машин, которые имеют модули Linux KVM и соответствующую поддерку аппаратного обеспечения. Деривации могут запрашивать функции по имени, и тогда они будут запранированы на соответствующих машинах для сборки.

Команда guix должна быть в путях для поиска на машинах лоя сборки. Можно проверить это, выполнив:

ssh build-machine guix repl --version

Есть ещё одна вещь, которую нужно выполнить после размещения machines.scm. Выше описано, что при разгрузке файлы передаются вперёд и назад между складами на машинах. Для этого необходимо сгенерировать ключ-пару на кадой машине, чтобы позволить демону экспортировать подписанные архивы файлов из склада (see Вызов guix archive):

# guix archive --generate-key

Каждая машина для сорки должна авторизовать ключ машины-инициатора, чтобы принимать элементы из склада, которые присылает инициатор:

# guix archive --authorize < master-public-key.txt

Точно так же машина-инициатор должна авторизовать ключ каждой машины для сборки.

Всё движение с ключами, описанное здесь, создаёт надёжную двустороннюю свзь между инициатором и машинами для сборки. А именно, когда машина-инициатор принимает файлы из машины для сборки (или наборот), её демон может удостоверить их подлинность и невмешательство других, а также то, что они подписаны авторизованным ключом.

Чтобы проверить работоспособность настроек, запустите следующую команду на инициирующем узле:

# guix offload test

Это выполнит попытку соединиться с каждой из машин для сборки, обозначенных в /etc/guix/machines.scm, проверит наличие модулей Guile и Guix на каждой машине, а также сделает попытку экспортировать и импортировать, а затем выведет отчёт об этом процессе.

Если нужно тестировать другой файл с описанием машин, просто приведите его в командной строке:

# guix offload test machines-qualif.scm

И последнее, можно тестировать набор машин, чьи имена соответствуют регулярному выражению, например:

# guix offload test machines.scm '\.gnu\.org$'

Чтобы отобразить текущую загрузку всех машин для сборки, запустите команду на инициирущем узле:

# guix offload status

Previous: , Up: Настройка демона   [Contents][Index]

2.4.3 Поддержка SELinux

Guix включает файл политик SELinnux etc/guix-daemon.cil, который может устанавливаться в систему, в которой включен SELinux, тогда файлы Guix будут помечены и настроены для соответствующего поведения демона. Так как система Guix не предоставляет политику SELinux, политика демона не может использоваться в системе Guix.

2.4.3.1 Установка политики SELinux

Чтобы установить политику, запустите следующую команду от root:

semodule -i etc/guix-daemon.cil

Затем измените метку файловой системы с restorecon или другим механизмом, поставляемым вашей системой.

Когда политика установлена, изменена метка файловой системы и демон перезапущен, она должна работать в контексте guix_daemon_t. Можно проверить это следующей командой:

ps -Zax | grep guix-daemon

Наблюдайте файлы логов SELinux во время работы команды guix build hello, чтобы удостовериться, что SELinux позволяет выполнение необходимых операций.

2.4.3.2 Ограничения

Эта политика не совершенна. Тут есть ряд ограничений или причуд, который нужно учитывать при разворачивании политики SELinux для демона Guix.

  1. guix_daemon_socket_t на самом деле не используется. Никакие операции с сокетом не выполняются. Ничего плохого в том, чтобы иметь эту неиспользуемую метку, но желательно определить правила сокета для этой метки.
  2. guix gc не может получить доступ к обычным ссылкам профилей. По задумке метка файла назначения символической ссылки не зависит от метки файла самой ссылки. Хотя все профили под $localstatedir помечены, ссылки на эти профили не наследуют метку директории, в которой они находятся. Для ссылок на домашние директории пользователей это будет user_home_t. Но для ссылок из домашней директории root, а также /tmp или рабочей директории HTTP-сервера и т.п., это не работает. guix gc не будет допускаться к чтению и следованию по этим ссылкам.
  3. Функция демона прослушивать соединения TCP может более не работать. Это может потребовать дополнительных правил, потому что SELinux относится к сетевым сокетам иначе, чем к файлам.
  4. В настоящее время всем файлам с именами, соответствующими регулярному выражению /gnu/store/.+-(guix-.+|profile)/bin/guix-daemon, присвоена метка guix_daemon_exec_t; это означает, что любому файлу с таким именем в любом профиле разрешён запуск в домене guix_daemon_t. Это не идеально. Атакующий может собрать пакет, который содержит исполняемый файл и убеить пользователя установить и запустить его, и таким образом он получит доступ к домену guix_daemon_t. В этой связи SELinux мог бы не давать ему доступ к файлам, которые разрешены для процессов в этом домене.

    Мы можем создать политику с большими ограничениями во время установки, так чтобы только точное имя исполняемого файла установленного в данный момент guix-daemon было помечено меткой guix_daemon_exec_t вместо того, чтобы использовать регулярное выражение, выбирающее большой ряд файлов. Проблемой в данном случае будет то, что root потребуется устанавливать или обновлять политику во время любой установки в случае, если обновлён исполняемый файл guix-daemon.


Next: , Previous: , Up: Установка   [Contents][Index]

2.5 Вызов guix-daemon

Программа guix-daemon реализует весь функционал доступа к складу. Это включает запуск процессов сборки, запуск сборщика мусора, проверка доступности результата сборки и т.д. Он должен быть запущен от root так:

# guix-daemon --build-users-group=guixbuild

Для подробностей о том, как настроить его, смотрите see Настройка демона.

По умолчанию guix-daemon запускает процессы сборки под различными UID, от пользователей из группы, обозначенной в --build-users-group. В дополнение каждый процесс сборки запускается в окружении chroot, которое содержит только набор элементов склада, от которых зависит процесс сборки, как это обозначено в деривации (see derivation), а также набор специфичных системных директорий. По умолчанию последнее включает /dev и /dev/pts. Более того, под GNU/Linux окружение сборки — это контейнер: в дополнение к тому, что он имеет собственное дерево файловой системы, он также имеет отдельное пространство имён монтирования, своё собственное пространство имён процессов PID, пространство сетевых имён и т.д. Это позволяет получить воспроизводимые сборки (see Особенности).

Когда демон выполняет сборку по запросу пользователя, он создаёт директорию под /tmp или под директорией, заданной его переменной окружения TMPDIR. Эта директория разделяется с контейнером на время сборки, хотя внутри контейнера дерево сборки всегда называется /tmp/guix-build-name.drv-0.

Директория сборки автоматически удаляется по завершении, если конечно, сборка не завершилась с ошибкой, и клиент не обозначил --keep-failed (see --keep-failed).

Демон слушает соединения и порождает один под-процесс для каждой сессии, запускаемой клиентом (одну из подкоманд guix). Команда guix processes позволяет мониторить активность вашей системы, предоставляя обзор каждой активной сессии и клиентов. Смотрите See Вызов guix processes для подробной информации.

Поддерживаются следующие опции командной строки:

--build-users-group=group

Использовать пользователей из группы group для запуска процессов сборки (see build users).

--no-substitutes

Не использовать подстановки для сборок. Это означает — собирать элементы локально вместо того, чтобы скачивать собранные бинарники (see Подстановки).

Когда демон работает с --no-substitutes, клиенты всё ещё могут явно включить подстановку с помощью удалённого вызова процедур set-build-options (see Склад).

--substitute-urls=urls

Использовать адреса urls, разделённые пробелом по умолчанию, как список источников подстановок. Если эта опция пропущена, используется ‘https://ci.guix.gnu.org

Это означает, что подстановки могут скачиваться из адресов urls, если конечно они подписаны доверенной подписью (see Подстановки).

--no-build-hook

Не использовать хук сборки (build hook).

Хук сборки — это программа-помощник, которую может запускать демон, и которой он отправляет запросы сборки. Этот механизм используется для разгрузки сборок на другие машины (see Установка демона разгрузки).

--cache-failures

Кешировать ошибки сборки. По умолчанию кешируются только успешные сборки.

При установке этой опции можно использовать guix gc --list-failures, чтобы просматривать элементы склада, помеченные как ошибочные; guix gc --clear-failures удаляет элементы склада из кеша ошибок. See Вызов guix gc.

--cores=n
-c n

Использовать n ядер процессора для сборки каждой деривации; 0 означает использовать все доступные.

Значение по умолчанию - 0, но оно может быть изменено клиентами, в частности, опцией --cores команды guix build (see Вызов guix build).

В результате устанавливается переменная окружения NIX_BUILD_CORES для процесса сборки, который затем может использовать её для применения внутреннего параллелизма, например, для запуска make -j$NIX_BUILD_CORES.

--max-jobs=n
-M n

Разрешить максимум n параллельных задач сборки. Значение по умолчанию - 1. Установка в 0 означает, чтоб сборки не будут выполняться локально, вместо этого, демон будет разгружать сборки (see Установка демона разгрузки) или просто отчитается об ошибке.

--max-silent-time=seconds

Когда процесс сборки или подстановки молчит более seconds секунд, завершить его и отчитаться об ошибке сборки.

Значение по умолчанию - 0, что значит отключить таймаут.

Значение, заданное здесь, может быть переопределено клиентами (see --max-silent-time).

--timeout=seconds

Точно так же, когда процесс сборки или подстановки длится более seconds, завершить его и отчитаться об ошибке сборки.

Значение по умолчанию - 0, что значит отключить таймаут.

Значение, заданное здесь, может быть переопределено клиентами (see --timeout).

--rounds=N

Собирать каждую деривацию n раз подряд и вызывать ошибку, если результаты последовательных сборок не идентичны бит-к-биту. Отметим, что эта настройка может быть переопределена клиентами в команде, например, guix build (see Вызов guix build).

При использовании вместе с --keep-failed различные результаты сохраняются на складе под /gnu/store/…-check. Это делает возможным просмотр различий между двумя результатами.

--debug

Выводить отладочную информацию.

Это полезно для отладки проблем запуска демона, но затем это может быть переопределено клиентами, например, опцией --verbosity команды guix build (see Вызов guix build).

--chroot-directory=dir

Добавить директорию dir в chroot сборки.

Это может изменить результаты процессов сборки, например, если они используют необязательные (опциональные) зависимости, найденные в dir, если они доступны, но только так, а не иначе. Поэтому не рекомендуется делать так. Вместо этого, убедитесь, что каждая деривация объявляет все необходимые входные данные.

--disable-chroot

Отключить chroot для сборки.

Использование этой опции не рекомендуется, так как опять же это позволит процессам сборки получить доступ к не объявленным зависимостям. Это важно, даже если guix-daemon запущен под аккаунтом непривилегированного пользователя.

--log-compression=type

Архивировать логи сборки методом type. Это один из: gzip, bzip2 или none.

Если не используется --lose-logs, все логи сборки сохраняются в localstatedir. Для экономии места демон автоматически сжимает их с помощью bzip2 по умолчанию.

--disable-deduplication

Отключить автоматическую "дедупликацию" файлов на складе.

По умолчанию файлы, добавленные на склад, автоматически "дедуплицируются": если вновь добавленный файл идентичен другому, найденному на складе, демон делает новый файл жесткой ссылкой на другой файл. Это существенно сокращает использование места на диске за счёт небольшого увеличения запросов ввода/вывода в конце процесса сборки. Эта опция отключает такую оптимизацию.

--gc-keep-outputs[=yes|no]

Сообщить, должен ли сборщик мусора (GC) сохранять выходные данные живой деривации.

При установке в "yes" (да), сборщик мусора (GC) будет сохранять результаты любой живой деривации, доступной на складе, — файлы .drv. Значение по умолчанию - "no" (нет) - означает, что результаты дериваций хранятся только, если они доступны из корней сборщика мусора (GC roots). Смотрите See Вызов guix gc для информации о корнях сборщика мусора.

--gc-keep-derivations[=yes|no]

Сообщить, должен ли сборщик мусора (GC) сохранять деривации, соответствующие живым результатам.

При указании "yes" (да), что является значением по умолчанию, сборщик мусора сохраняет деривации, то есть файлы .drv, до тех пор, пока любой из их выходов остаётся живым. Это позволяет пользователям отслеживать исходники элементов на складе. Установка в "no" (нет) немного экономит место на диске.

Таким образом, установка --gc-keep-derivations в "yes" (да) даётт возможность пройти от результатов до дериваций, а установка --gc-keep-outputs в "yes" (да), делает возможным пройти от дериваций до результатов. Если оба установлены в "yes", тогда это сохранит всё используемое для сборки (исходники, компилятор, библиотеки и другие инструменты сборки) живых объектов на складе, без учёта, доступны эти инструменты сборки из корней сборщика мусора или нет. Это удобно для разработчиков, так как это сокращает пересборки или скачивания.

--impersonate-linux-2.6

На системах, основанных на Linux, выдавать себя за Linux 2.6. Это означает, что системный вызов ядра uname будет выдавать 2.6 номером релиза.

Это полезно для сборки программ, которые (обычно по ошибке) зависят от версии ядра.

--lose-logs

Не сохранять логи сборки. По умолчанию они сохраняются под localstatedir/guix/log.

--system=system

Считать system текущим типом системы. По умолчанию это пара архитектура/ядро, обнаруженная во время конфигурации, например, x86_64-linux.

--listen=endpoint

Слушать соединения с endpoint. endpoint интерпретируется как имя файла сокета Unix-домена, если начинается с / (знак слеша). В противном случае endpoint интерпретируется как имя хоста или им хоста и порт для прослушивания. Вот несколько примеров:

--listen=/gnu/var/daemon

Слушать соединения с сокетом Unix-домена /gnu/var/daemon, который создаётся при необходимости.

--listen=localhost

Слушать соединения TCP сетевого интерфейса, относящиеся к localhost, на порту 44146.

--listen=128.0.0.42:1234

Слушать соединения TCP сетевого интерфейса, относящиеся к 128.0.0.42, на порту 1234.

Эта опция может повторяться много раз, в таком случае guix-daemon принимает соединения на всех обозначенных точках. Пользователи могут через клиентские команды сообщать, через какие точки соединяться, для этого нужно устанавливать переменную окружения GUIX_DAEMON_SOCKET (see GUIX_DAEMON_SOCKET).

Заметка: Протокол демона неаутентичный и нешифрованный. Использование --listen=host подходит локальным сетям, как например, кластерам, где только доверенные узлы могут соединяться с демоном сборки. В других случаях, когда необходим удалённый доступ к демону рекомендуется использовать сокеты Unix-домена вместе с SSH.

Когда --listen пропущена, guix-daemon слушает соединения с сокетом Unix-домена, расположенным в localstatedir/guix/daemon-socket/socket.


Previous: , Up: Установка   [Contents][Index]

2.6 Установка приложения

При использовании дистрибутива GNU/Linux, отличного от системы, называемого также чужой дистрибутив, необходимо несколько дополнительных шагов, чтобы всё работало. Вот некоторые из них.

2.6.1 Локали

Пакеты, установленные с помощью Guix, не будут использовать данные локали хост-системы. Вместо этого вы должны вначале установить один из пакетов локали, доступных в Guix, а затем определить переменную окружения GUIX_LOCPATH:

$ guix install glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale

Отметим, что пакет glibc-locales содержит данные для всех локалей, поддерживаемых GNU libc, и весит околоа 110 Миб. В альтернативу glibc-utf8-locales меньше, но ограничен несколькими локалями UTF-8.

Переменная GUIX_LOCPATH играет ту же роль, что и LOCPATH (see LOCPATH in The GNU C Library Reference Manual). Но есть два существенных различия.

  1. GUIX_LOCPATH учитывается только libc в Guix, но не учитывается libc, предоставляемым чужим дистрибутивом. Так что использование GUIX_LOCPATH позволяет вам убедиться, что программы чужого дистрибутива не будут производить загрузку несовместимых данных локали.
  2. libc добавляет суффиксы /X.Y к каждому компоненту GUIX_LOCPATH, где X.Y - это версия libc, например, 2.22. Это значит, что если ваш профиль Guix будет содержать смесь программ, связанных с дугой версией libc, каждая версия libc будет пытаться загружать только данные локали в правильном формате.

Это важно, потому что использование данных локали другой версией libc может быть неприемлемо.

2.6.2 Служба выбора имён

При использовании Guix на чужом дистрибутиве мы настойчиво рекомендуем, чтобы система запускала демон кеша имён сервисов библиотеки GNU C, nscd, который должен слушать сокет /var/run/nscd/socket. Если это не сделано, приложения, установленные Guix, могут некорректно адресовать имена хостов или аккаунты пользователей и даже падать. Ниже объясняется почему.

Библиотека GNU C реализует выбор имён сервисов (NSS), который представляет собой расширяемый механизм для резолвинга имён в целом: резолвинг имён хостов, аккаунтов пользователей и другое (see Служба выбора имён in The GNU C Library Reference Manual).

Будучи расширяемым, NSS поддерживает плагины, которые предоставляют реализации разрешения новых имён: плагин nss-mdns резолвит имена хостов .local, плагин nis адресует пользовательские аккаунты, используя сервис сетевой информации (NIS) и т.д. Эти дополнительные сервисы адресации настраиваются для всей системы в /etc/nsswitch.conf, и все запущенные в системе программы учитывают эти настройки (see NSS Configuration File in The GNU C Reference Manual).

Когда выполняется разрешение имён, например, вызовом функции C getaddrinfo, приложения вначале делают попытку соединиться с nscd; в случае успеха nscd выполняет разрешение имён по их запросу. Если nscd не запущен, тогда они выполняют разрешение имён самостоятельно, загружая сервисы разрешения имён в их собственные адресные пространства и запуская их. Эти сервисы разрешения имён — файлы libnss_*.so — запускаются dlopen, но они могут поставляться системной библиотекой C, а не библиотекой C, с которой залинковано приложение (библиотека C из Guix).

Вот где кроется проблема — если ваше приложение залинковано с библиотекой C Guix (скажем, glibc 2.24) и пытается загрузить плагины NSS из другой библиотеки C (скажем, libnss_mdns.so для glibc 2.22), это вероятно вызовет падение или резолвинг имени завершится с ошибкой.

Запуск nscd в системе, помимо преимуществ, также исключает эту проблему несовместимости программ, потому что файлы libnss_*.so загружены в процессе nscd, а не в самом приложении.

2.6.3 Шрифты X11

Большинство графических приложений использует Fontconfig для обнаружения и загрузки шрифтов, а также рендеринга X11 на клиенте. Пакет Guix fontconfig отвечает за шрифты в $HOME/.guix-profile по умолчанию. Так что, чтобы графические приложения, установленные с помощью Guix, отображали шрифты, необходимо установить шрифты также с помощью Guix. Основные пакеты шрифтов: gs-fonts, font-dejavu и font-gnu-freefont-ttf.

Для отображения в графических приложениях текста на китайском, японском, корейском нужно установить font-adobe-source-han-sans или font-wqy-zenhei. Первый имеет множественный выход, один для языковой семьи (see Пакеты со множественным выходом). Например, следующая команда устанавливает шрифты для китайских языков:

guix install font-adobe-source-han-sans:cn

Старые программы, например, xterm, не используют Fontconfig, а вместо этого вызывают рендеринг шрифтов на стороне сервера. Таким программам необходимо указывать полное имя шрифта, используя XLFD (X Logical Font Description), примерно так:

-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1

Чтобы иметь возможность использовать такие полные имена для шрифтов TrueType, установленных в вашем профиле Guix, вам нужно расширить пути шрифтов X-сервера:

xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))

После этого можно запустить xlsfonts (из пакета xlsfonts), чтобы убедиться, что ваши шрифты TrueType находятся там.

После установки шрифтов, возможно вам потребуется обновить кеш шрифтов, чтобы использовать их в приложениях. Это необходимо делать, когда приложения, установленные с помощью Guix, не находят шрифты. Для того чтобы пересобрать кеш шрифтов, запустите fc-cache -f. Команда fc-cache предоставляется пакетом fontconfig.

2.6.4 Сертификаты X.509

Пакет nss-certs предоставялет сертификаты X.509, которые позволяют программам аутентифицировать веб-серверы и работать через HTTPS.

При использовании Guix на чужом дистрибутиве можно установить этот пакет и определить соответствующие переменные окружения, чтобы пакеты знали, где искать сертификаты. Смотрите See Сертификаты X.509 для подробной информации.

2.6.5 Пакеты Emacs

Когда вы устанавливаете пакеты Emacs с помощью Guix, файлы elisp могут помещаться в $HOME/.guix-profile/share/emacs/site-lisp/ или поддиректориях $HOME/.guix-profile/share/emacs/site-lisp/guix.d/. Последняя директория существует, потому что потенциально могут существовать тысячи пакетов Emacs, и сохранение всех их файлов в одной директории может быть неприемлемо (из-за конфликта имён). Так что мы считаем хорошей идеей использовать отдельную директорию для каждого пакета. Это очень похоже на то, как система пакетов Emacs организует файловую структуру (see Package Files in The GNU Emacs Manual).

По умолчанию Emacs (установленный Guix) "знает", куда размещаются эти пакеты, так что вам не нужно выполнять конфигурацию. Если по каким-либо причинам вы хотите отменить автозагрузку пакетов Emacs, установленных с помощью Guix, вы можете это сделать, запустив Emacs с опцией --no-site-file (see Init File in The GNU Emacs Manual).

2.6.6 Тулчейн GCC

Guix предлагает индивидуальные пакеты компиляторов, как например, gcc. Но если вам необходим полный набор инструментов (тулчейн) для компиляции и линковки исходного кода, тогда то, что вам действительно нужно, — это пакет gcc-toolchain. Этот пакет предоставляет полный тулчейн GCC для разработки C/C++, включая сам GCC, библиотеку GNU C (заголовки и бинарники, а также отладочные символы в выходе debug), Binutils и набор линковщика.

Цель оболочки — проверять опции -L и -l, направленные линковщику, и соответствующие аргументы -rpath, и вызывать соответствующий линковщик с этим новым набором аргументов. Вы можете указать оболочке отклонять линковку с библиотеками, находящимися не на складе, установив переменную окружения GUIX_LD_WRAPPER_ALLOW_IMPURITIES в значение no.


Next: , Previous: , Up: Top   [Contents][Index]

3 Установка системы

Этот раздел объясняет, как установить систему Guix на компьютер. Guix, как пакетный менеджер, можно также установить на уже установленную систему GNU/Linux (see Установка).


Next: , Up: Установка системы   [Contents][Index]

3.1 Ограничения

Мы полагаем, система Guix будет широко применяться для офисных и серверных решений. Гарантия надёжности основана на транзакционных обновлениях, откатах и воспроизводимости. Это наше прочное основание.

Тем не менее, перед началом установки, ознакомьтесь с важной информацией об ограничениях версии 1.0.1:

Мы настойчиво призываем вас присылать отчёты о проблемах (или историиуспеха!). Присоединяйтесь к нам, если вы хотите улучшить Guix. Смотрите See Содействие, чтобы узнать больше.


Next: , Previous: , Up: Установка системы   [Contents][Index]

3.2 По поводу железа

GNU Guix особенно заботится об уважении свободы пользователя при работе за компьютером. Она построена на ядре Linux-libre, что означает, что поддерживается только аппаратное обеспечение, которое имеет свободные драйверы и прошивки. Сегодня широкий список наличествующей аппаратуры поддерживается GNU/Linux-libre — от клавиатур и графических карт до сканеров и контроллеров Ethernet. К сожалению, всё ещё остаётся ряд производителей железа, которые запрещают пользователям управлять их устройствами, и такое аппаратное обеспечение не поддерживается системой Guix.

Основной областью, в которой отсутствуют свободные драйверы и прошивки, являются устройства Wi-Fi. Работают устройства Wi-Fi, которые используют платы Atheros (AR9271 и AR7010) и взаимодействуют с драйвером Linux-libre ath9k, также использующие платы Broadcom/AirForce (BCM43xx with Wireless-Core Revision 5), которые работают с драйвером Linux-libre b43-open. Свободная прошивка существует для обоих и доступна в системе Guix из коробки как часть %base-firmware (see firmware).

Фонд свободного программного обспечения FSF ведёт Уважение вашей свободы (RYF) — программу сертификации аппаратного обеспечения, которое уважает вашу свободу и вашу безопасность и утверждает, что вы имеете контроль над вашими устройствами. Мы побуждаем вас проверить список устройств, сертифицированных RYF.

Другой полезный ресурс — сайт H-Node. Он содержит каталог устройств с информацией об их поддержке в GNU/Linux.


Next: , Previous: , Up: Установка системы   [Contents][Index]

3.3 Установочная флеш и DVD

Установочный образ ISO-9660 может быть записан на USB-флеш или DVD, скачать его можно по адресу: ‘https://alpha.gnu.org/gnu/guix/guix-system-install-1.0.1.system.iso.xz’, где system одна из следующих:

x86_64-linux

для системы GNU/Linux на 64-битных Intel/AMD-совместимых процессорах;

i686-linux

для системы GNU/Linux на 32-битных Intel-совместимых процессорах.

Обязательно скачайте связанный файл подписи .sig и проверьте аутентичность образа так:

$ wget https://ftp.gnu.org/gnu/guix/guix-system-install-1.0.1.system.iso.xz.sig
$ gpg --verify guix-system-install-1.0.1.system.iso.xz.sig

Если это завершается ошибкой, значит у вас нет необходимого публичного ключа, тогда запустите команду для импорта ключа:

$ gpg --keyserver pool.sks-keyservers.net \
      --recv-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5

и запустите команду gpg --verify.

Take note that a warning like “This key is not certified with a trusted signature!” is normal.

Этот образ содержит инструменты, необходимые для установки. Он должен копироваться как есть на большую USB-флеш или DVD.

Запись на USB-флеш

Чтобы записать образ на USB-флеш, выполните следующие шаги:

  1. Распакуйте образ, используя команду xz:
    xz -d guix-system-install-1.0.1.system.iso.xz
    
  2. Вставьте в компьютер USB-флеш объёмом 1 Гб или более и определите его имя. Учитывая имя (обычно соответствующее /dev/sdX) скопируйте образ на него:
    dd if=guix-system-install-1.0.1.system.iso of=/dev/sdX
    sync
    

    Доступ к /dev/sdX обычно требует привилегий root.

Запись на DVD

Чтобы скопировать образ на DVD, проделайте следующие шаги:

  1. Распакуйте образ, используя команду xz:
    xz -d guix-system-install-1.0.1.system.iso.xz
    
  2. Вставьте чистый DVD в компьютер и определите имя устройства. Обычно DVD определяется как /dev/srX, скопируйте образ так:
    growisofs -dvd-compat -Z /dev/srX=guix-system-install-1.0.1.system.iso
    

    Доступ к /dev/srX обычно требует привилегий root.

Загрузка

Когда это сделано, вы должны перезагрузить систему и загрузиться с USB-флеш или DVD. Последнее обычно требует доступа к меню BIOS или UEFI, где можно выбрать загрузку с USB-флеш.

Смотрите See Установка Guix на виртуальную машину, если вы хотите установить систему Guix на виртуальную машину (VM).


Next: , Previous: , Up: Установка системы   [Contents][Index]

3.4 Подготовка к установке

Когда вы загрузитесь, вы можете использовать графическую установку, которая намного проще для начала (see Графическая установка в GUI). Или если вы уже знакомы с GNU/Linux или вы хотите больший контроль, чем это предоставляет графическая установка, вы можете выбрать ручной процесс установки (see Ручная установка).

Графическа установка доступна в TTY1. Вы можете запустить оболочку root в TTY 3-6, нажимая ctrl-alt-f3, ctrl-alt-f4 и т.д. TTY2 отображает эту документацию, открыть его можно клавишами ctrl-alt-f2. Листать документацию можно командами просмотрщика Info (see Stand-alone GNU Info). Установка системы запускает демона мыши GPM, который позволяет вам выделять текст лековй кнопкой мыши и вставлять средней кнопкой.

Заметка: Установка требует доступа к Интернету, чтобы скачивать любые отсутствующие зависимости в вашей конфигурации системы. Смотрите раздел "Сеть" ниже.


Next: , Previous: , Up: Установка системы   [Contents][Index]

3.5 Графическая установка в GUI

Графический установщик представляет собой текстовый интерфейс. Он взаимодействует через диалоговые блоки, проходя шаги установки системы GNU Guix.

Первый диалоговый блок позволяет вам установить систему в таком виде, как во время установки. Вы можете выбрать язык, раскладку клавиатуры, задать настройки сети для установки. На картинке ниже — диалог настройки сети.

networking setup with the graphical
installer

Следующие шаги позволят вам разметить диск, как это показано на картинке ниже. Также можно выбрать шифрование вайловой системы (или без шифрования), ввести имя хоста и пароль root, создать дополнительную учётную запись и другие действия.

partitioning with the graphical
installer

Отметим, что в любое время установщик позволяет вам отменить текущий шаг и вернуться к предыдущему шагу установки, как это показано на картинке ниже.

resuming the installation process

Когда настройки выполнены, установщик сгенерирует конфигурацию операционной системы и отобразит её (see Использование системы конфигурации). На этом этапе нажатие "OK" запустит установку. После успешнго завершения нужно перезагрузиться и использовать новую систему. Смотрите See После установки системы, чтобы узнать ещё больше.


Next: , Previous: , Up: Установка системы   [Contents][Index]

3.6 Ручная установка

Этот раздел описывает, как можно вручную установить систему GNU Guix на вашу машину. Это потребует знаний GNU/Linux, оболочки и инструментов администрирования. Если вы считаете, это не для вас, используйте вариант графической установки (see Графическая установка в GUI).

Во время установки доступна оболочка root в TTY от 3 до 6. Нажмите ctrl-alt-f3, ctrl-alt-f4 и т.д., чтобы переключиться на них. Они имеют много стандартных инструментов для установки системы. Но это также работающая система Guix, а это значит, что вы можете установить дополнительные пакеты, которые потребуются, используя guix package (see Вызов guix package).


Next: , Up: Ручная установка   [Contents][Index]

3.6.1 Раскладка клавиатуры, Сеть, Разметка диска

Перед установкой системы вам может понадобиться смена раскладки клавиатуры, а также настройка сети и разметка целевого жёсткого диска. В этом разделе приведены соответствующие инструкции.

3.6.1.1 Раскладка клавиатуры

Установочный образ использует раскладку клавиатуры US qwerty. Если нужно поменять её, можно пользоваться командой loadkeys. Например, следующая команда выбирает раскладку клавиатуры Dvorak:

loadkeys dvorak

Смотрите файлы в /run/current-system/profile/share/keymaps, чтобы найти список доступных раскладок. Запустите man loadkeys, чтобы узнать больше.

3.6.1.2 Сеть

Запустите следующую команду, чтобы узнать имена сетевых интерфейсов:

ifconfig -a

… или используйте специальную команду GNU/Linux ip:

ip a

Проводные интерфейсы называются на букву ‘e’; например, интерфейс, соответствующий первому контроллеру Ethernet на материнской плате, называется ‘eno1’. Беспроводные интерфейсы имеют имена, начинающиеся с ‘w’, как ‘w1p2s0’.

Проводное соединение

Чтобы настроить проводную сеть, запустите следующую команду, заменив interface именем проводного интерфейса, который вы хотите использовать.

ifconfig interface up
Беспроводное соединение

Чтобы настроить беспроводную сеть, можно создать конфигурционный файл для wpa_supplicant (расположение файла неважно). Можно пользоваться любым доступным текстовым редактором, например, nano:

nano wpa_supplicant.conf

Следующий пример настроек подойдёт для большинства беспроводных сетей. Нужно предоставить фактический SSID и парольную фразу для сети, к которой вы подключаетесь:

network={
  ssid="my-ssid"
  key_mgmt=WPA-PSK
  psk="the network's secret passphrase"
}

Запустите сервис беспроводной сети в фоновом режиме следующей командой (замените interface именем сетевого интерфейса, который вы используете):

wpa_supplicant -c wpa_supplicant.conf -i interface -B

Запустите man wpa_supplicant, чтобы узнать больше.

Теперь нужно получить IP-адрес. В случае сети, где IP-адреса автоматически распределяются с помощью DHCP, можно запустить:

dhclient -v interface

Попробуйте пинговать сервер, чтобы узнать, работает ли сеть:

ping -c 3 gnu.org

Настройка доступа к сети необходима почти всегда, потому что ораз может не иметь программное обеспечение и инструменты, которые могут понадобиться.

Если желаете, вы можете продолжить установку удалённо, запустив SSH-сервер:

herd start ssh-daemon

Не забудьте задать пароль командой passwd или настроить публичный ключ OpenSSH для аутентификации, чтобы иметь возможность подключиться.

3.6.1.3 Разметка диска

Если это ещё не сделано, тогда нужно разделить диск, а затем отформатировать целевой(-ые) раздел(ы).

Установочный образ содержит несколько инструментов для разметки, включая Parted (see Overview in GNU Parted User Manual), fdisk и cfdisk. Запустите и настройте ваш диск, используя план разметки, который нужен:

cfdisk

Если ваш диск использует формат GUID Partition Table (GPT), и вы планируете использовать GRUB, работающий с BIOS (что по умолчанию), убедитесь, что раздел BIOS Boot Partition доступен (see BIOS installation in GNU GRUB manual).

Если вместо этого вы хотите использовать GRUB, работающий с EFI, тогда необходима разметка система EFI FAT32 (ESP). Такая разметка может, например, монтироваться в /boot/efi и должна иметь флаг esp. То есть в случае parted:

parted /dev/sda set 1 esp on

Заметка: Не уверенны, что выбрать: GRUB, взаимодействующий с EFI или BIOS? Если существует директория /sys/firmware/efi в установочом образе, тогда вам следует использовать установку EFI и grub-efi-bootloader. В противном случае нужно использовать GRUB, работающий с BIOS, называемый grub-bootloader. Смотрите See Настройка загрузчика для большей информации о загрузчиках.

Когда разметка целевого диска выполнена, нужно создать файловую систему на соответствующем(-их) разделе(-ах)8. В случае ESP, если у вас раздел /dev/sda1, выполните:

mkfs.fat -F32 /dev/sda1

Желательно добавить метки файловых систем, чтобы вы могли ссылаться на них по именам в объявлениях file-system (see Файловые системы). Обычно это можно сделать опцией -L в mkfs.ext4, например. Допустим, раздел root располагается в /dev/sda2, можно добавить метку my-root следующим образом:

mkfs.ext4 -L my-root /dev/sda2

Если же вы планируете шифровать раздел root, можно воспользоваться утилитами Cryptsetup/LUKS (смотрите man cryptsetup for more information.) Допустим, если раздел root размещается в /dev/sda2, необходимо выполнить следующие команды:

cryptsetup luksFormat /dev/sda2
cryptsetup open --type luks /dev/sda2 my-partition
mkfs.ext4 -L my-root /dev/mapper/my-partition

Когда это сделано, монтируйте целевую файловую систему под /mnt следующей командой (опять же полагая, что метка раздела root — my-root):

mount LABEL=my-root /mnt

Также монтируйте любые другие файловые системы внутрь целевой файловой системы. Если например, выбрана точка монтирования EFI /boot/efi, монтируйте её в /mnt/boot/efi, так, чтобы она обнаруживалась после запуска guix system init.

Наконец, если вы планируете использовать один или более разделов swap (see swap space in The GNU C Library Reference Manual), обязательно инициируйте их командой mkswap. Допустим, если ваш раздел swap размещён в /dev/sda3, нужно выполнить:

mkswap /dev/sda3
swapon /dev/sda3

Возможно, вместо этого вы используете swap-файл. Например, предположим, вы хотите использовать в новой системе swap-файл в /swapfile, тогда нужно выполнить9:

# This is 10 GiB of swap space.  Adjust "count" to change the size.
dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
# For security, make the file readable and writable only by root.
chmod 600 /mnt/swapfile
mkswap /mnt/swapfile
swapon /mnt/swapfile

Заметим, что если вы шифруете раздел root и создаёте swap-файл в его файловой системе, как это описано выше, шифрование также будет защищать swap-файл, как и любой другой файл в этой файловой системе.


Previous: , Up: Ручная установка   [Contents][Index]

3.6.2 В продолжении установки

Когда целевые разделы готовы и раздел root монтирован под /mnt, всё готово для старта. Сначала запустите:

herd start cow-store /mnt

Это сделает /gnu/store копируемым при записи (copy-on-write), что заставит систему записывать пакеты, добавляемые в систему на этапе установки, на целевой диск под /mnt, а не держать их в памяти. Это важно, потому что по команде guix system init (смотрите ниже) будут скачиваться или собираться пакеты в /gnu/store, которая изначально находится в файловой системе, загрузженной в память.

Далее нужно редактировать файл объявления операционной системы, которым будет пользоваться установщик. Для этого при установке системы можно использовать три текстовых редактора. Мы ркомендуем GNU nano (see GNU nano Manual) — он поддерживает подсветку синтаксиса и работу со скобками. Другие редакторы: GNU Zile (клон Emacs), nvi (клон исходного редактора BSD vi). Мы настойчиво рекомендуем сохранять файл конфигураций в целевой файловой системе root, например, как /mnt/etc/config.scm. Иначе есть возможность потерять конфигурационный файл, когда вы загрузитесь в новую установенную систему.

Смотрите See Использование системы конфигурации для подробностей о конфигурационном файле. Конфигурационный файл для примера доступен под /etc/configuration установочного образа. Например, чтобы получить систему с графическим сервером (т.е. десктопную систему), можно это сделать примерно так:

# mkdir /mnt/etc
# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
# nano /mnt/etc/config.scm

Нужно уделить внимание содержимому конфигурационного файла, в частности:

Когда вы подготовили конфигурационный файл, нужно инициализировать новую систему (помните, что целевой раздел root монтирован под /mnt):

guix system init /mnt/etc/config.scm /mnt

Это копирует все нужные файлы и устанавливает GRUB в /dev/sdX, если конечно, вы не задали опцию --no-bootloader. Подробнее - see Вызов guix system. Эта команда может вызывать скачивание или сборку отсутствующих пакетов, что может занять время.

Когда эта команда завершена, надеемся, успешно, можно запустить reboot и загрузиться в новую систему. Пароль root в новой системе изначально пустой; пароли других пользователей должны быть заданы командой passwd от root, если конечно, ваша конфиурация не содержит указания (see user account passwords). Смотрите See После установки системы, чтобы узнать, что дальше.


Next: , Previous: , Up: Установка системы   [Contents][Index]

3.7 После установки системы

Замечательно! Теперь вы загрузились в систему Guix! Теперь можно обновить систему, когда у вас будет на это время, запустив, например:

guix pull
sudo guix system reconfigure /etc/config.scm

Это соберёт поколение (generation) системы с последними пакетами и сервисами (see Вызов guix system). Мы рекомендуем делать это регулярно, чтобы ваша система содержала обновления безопасности (see Обновления безопасности).

Заметка: Отметим, что sudo guix запускает команду guix от вашего пользователя, но не от root, потому что sudo не меняет PATH. Чтобы вместо этого запустить guix от root, напечатайте sudo -i guix ….

Присоединяйтесь к нашему IRC-каналу #guix в сети Freenode или пишите на guix-devel@gnu.org, чтобы поделиться опытом!


Next: , Previous: , Up: Установка системы   [Contents][Index]

3.8 Установка Guix на виртуальную машину (VM)

Если вы хотите установить систему Guix на виртуальную машину (VM) или на виртуальный приватный сервер (VPS) вместо вашей любимой машины, этот раздел для вас.

To boot a QEMU VM for installing Guix System in a disk image, follow these steps:

  1. Во-первых, найдите и распакуйте установочный образ системы Guix, как описано ранее (see Установочная флеш и DVD).
  2. Создайте образ диска, который будет содержать установленную систему. Чтобы создать образ диска qcow2, используйте команду qemu-img:
    qemu-img create -f qcow2 guixsd.img 50G
    

    Результирующий файл будет намного меньше 50Гб (обычно менее 1Мб), но он будет увеличиваться с заполнение виртуального устройства.

  3. Загрузите установочный образ USB в VM:
    qemu-system-x86_64 -m 1024 -smp 1 \
      -net user -net nic,model=virtio -boot menu=on \
      -drive file=guix-system-install-1.0.1.system.iso \
      -drive file=guixsd.img
    

    Порядок следования устройств имеет значение.

    В консоли VM быстро нажмите клавишу F12, чтобы открыть меню загрузки. Затем нажмите кнопку 2 и кнопку Ввод (enter), чтобы потдвердить выбор.

  4. Теперь вы в корне VM, проделайте процесс установки See Подготовка к установке и последующие инструкции.

Когда установка завершена, можно загрузиться в систему, которая расположена в образе guixsd.img. Смотрите See Запуск Guix на виртуальной машине, чтобы узнать, как это сделать.


Previous: , Up: Установка системы   [Contents][Index]

3.9 Сборка установочного образа

Установочный образ, описанный выше, собран командой guix system, а именно:

guix system disk-image --file-system-type=iso9660 \
  gnu/system/install.scm

Нужно просмотреть gnu/system/install.scm в дереве исходников, а также Вызов guix system, чтобы получить больше информации об установочном образе.

3.10 Сбрка и установка образа для плат ARM

Many ARM boards require a specific variant of the U-Boot bootloader.

Если вы собираете образ диска, а загрузчик не доступен (на другом устройстве загрузке и т.п.), советуем собрать образ, который включает загрузчик, то есть так:

guix system disk-image --system=armhf-linux -e '((@ (gnu system install) os-with-u-boot) (@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'

A20-OLinuXino-Lime2 — это имя материнской платы. Если вы обозначите недействительную плату, будет выведен список возможных плат.


Next: , Previous: , Up: Top   [Contents][Index]

4 Управление пакетами

Целью GNU Guix является предоставление пользователям возможности легко устанавливать, обновлять и удалять пакеты программного обеспечения, без необходимости изучения процедур их сборки и без необходимости разрешения зависимостей. Также Guix имеет следующие обязательные особенности.

Этот раздел описывает основные особенности Guix и предоставляемые им инструменты управления пакетами. Кроме интерфейса командной строки, который описан ниже (see guix package), можно также использовать интерфейс Emacs-Guix (see The Emacs-" "Guix Reference Manual), если установить пакет emacs-guix (выполните команду M-x guix-help, чтобы начать работу с ним):

guix install emacs-guix

Next: , Up: Управление пакетами   [Contents][Index]

4.1 Особенности

При использовании Guix каждый пакет после установки размещается в package store, в собственной директории, например, /gnu/store/xxx-package-1.2, где xxx - это строка base32.

Вместо того, чтобы ссылаться на эти директории, пользователям нужно обращаться к их профилям, профиль указывает на пакеты, которые они хотят использовать. Эти профили хранятся в домашней директории каждого пользователя в $HOME/.guix-profile.

Например, alice устанавливает GCC 4.7.2. В результате /home/alice/.guix-profile/bin/gcc указывает на /gnu/store/…-gcc-4.7.2/bin/gcc. Допустим, на той же машине bob установил GCC 4.8.0. Профиль пользователя bob просто указывает на /gnu/store/…-gcc-4.8.0/bin/gcc. То есть обе версии GCC присутствуют в одной системе без помех.

Команда guix package — главный инструмент для управления пакетами (see Вызов guix package). Она работает с профилями пользователей, которые имеют права обычных пользователей.

Команда предоставляет обязательные операции установки, удаления и обновления. Каждый вызов представляет собой транзакцию, независимо от того, выполнены успешно заданные операции, или ничего не произошло. Так, если процесс guix package завершился во время транзакции, или произошёл сбой питания во время транзакции, тогда профиль пользователя остаётся в исходном состоянии, готовом к использованию.

В дополнение, каждую транзакцию, которая работает с пакетами, можно откатить. Так если, например, обновление устанавливает новую версию пакета, которая имеет серьёзный баг, пользователи могут откатиться до предыдущей инстанции своего профиля, который работал нормально. Точно так же, глобальные настройки системы Guix являются объектом транзакционных обновлений и откатов (see Использование системы конфигурации).

Все пакеты на складе могут быть собраны как мусор. Guix может определить, какие пакеты всё ещё используются профилями пользователей, и удалить те, которые однозначно больше не используются (see Вызов guix gc). Также пользователи могут явно удалить старые поколения (generations) их профилей, поэтому пакеты, на которые ссылались старые профили, могут быть удалены.

Guix реализует чисто функциональный подход к управлению пакетами, как описано во введении (see Введение). В /gnu/store имя директории каждого пакета содержит хеш всех входных данных, которые использовались при сборке пакета: компилятор, библиотеки, скрипты сборки и т.д. Это прямое соответствие позволяет пользователям убедиться, что данная установка пакета соответствует текущему состоянию дистрибутива. Также это помогает улучшить воспроизводимость сборки: благодаря изолированному окружению сборки, которая используется при установке пакета, результат сборки содержит точно такие же файлы на разных машинах (see container).

Эта концепция позволяет Guix поддерживать прозрачное внедрение бинарников/исходников. Когда доступен элемент /gnu/store, собранный заранее на внешнем источнике, то есть готова подстановка, Guix просто скачивает и распаковывает его. В противном случае он собирает пакет из исходников на локальной машине (see Подстановки). Так как результаты сборки обычно воспроизводимы бит-к-биту, пользователи не должны доверять серверам, которые поставляют подстановки — они могут целенаправленно запросить локальную сборку и не пользоваться серверами подстановки (see Вызов guix challenge).

Управление окружением сборки — функция, которая полезна для разработчиков. Команда guix environment позволяет разработчикам пакетов быстро установить требуемое окружение разработки без необходимости устанавливать в свой профиль зависимости пакета вручную (see Вызов guix environment).

Guix и его определения пакетов подчняются контролю версиями, и guix pull позволяет "путешествовать во времени" по истории Guix (see Запуск guix pull). Это позволяет повторять инстанцию Guix на разных машинах или по прошествию времени, что в свою очередь позволяет вам повторять полностью программное окружение из достпуных трекеров источников программного обеспечения.


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.2 Вызов guix package

Команда guix package — инструмент, который позволяет пользователям устанавливать, обновлять и удалять пакеты, а также откатываться до предыдущих конфигураций (see Особенности). Его синтаксис:

guix package options

В первую очередь, options (опции) задают операции, которые нужно выполнить в транзакции. По завершении создаётся новый профиль, а предыдущие поколения (generations) профиля остаются доступными, если пользователь решит откатиться.

Например, чтобы удалить lua и устанвоить guile и guile-cairo в одной транзакции, напечатайте:

guix package -r lua -i guile guile-cairo

Для вашего удобства мы также предоставляем следующие синонимы:

Эти синонимы не такие мощные, как guix package, и предоставляют меньше опций, так что в некоторых случаях вам скорее нужно пользоваться непосредственно guix package.

guix package также поддерживает декларативный подход, с помощью которого пользователь зааёт точный набор пакетов, которые должны быть доступны, и передаёт его в опции --manifest (see --manifest).

Для каждого пользователя автоматически создаётся символическая ссылка на профиль по умолчанию, она располагается в файле $HOME/.guix-profile. Эта ссылка всегда указывает на текущее поколение пользовательского профиля по умолчанию. Так пользователи могут добавить $HOME/.guix-profile/bin в свою переменную окружения PATH и прочее. Если вы не используете систему Guix, предполагается добавление следующих строк в ваш ~/.bash_profile (see Bash Startup Files in The GNU Bash Reference Manual), чтобы порождаемые оболочки получили все необходимые определения переменных окружения:

GUIX_PROFILE="$HOME/.guix-profile" ; \
source "$HOME/.guix-profile/etc/profile"

В случае многопользовательской установки, профили пользователей сохраняются в месте, которое зарегстрировано как garbage-collector root, которое указывет на $HOME/.guix-profile (see Вызов guix gc). Эта директория обычно ссылается на localstatedir/guix/profiles/per-user/user, где localstatedir — значение, переданное скрипту configure опцией --localstatedir, а user — имя пользователя. Директория per-user создаёся, когда запускается guix-daemon, а поддиректория user создаётся guix package.

Опции options могут быть следующими:

--install=package
-i package

Установить заданный пакет.

Каждый package может задавать простое имя пакета, как например, guile, или имя пакета с указанием номера версии, например, guile@1.8.8 или просто guile@1.8 (в последнем случае выбирается самая новая версия с префиксом 1.8.)

Если не задан номер версии, тогда будет выбрана самая новая доступная версия. Добавм, что package может содержать двоеточие и одно имя выходных данных пакета, как gcc:doc или binutils@2.22:lib (see Пакеты со множественным выходом). Пакеты с соответствующим именем (и опционально, версией) будут отыскиваться в модулях дистрибутива GNU (see Пакетные модули).

Иногда пакеты имеют распространённые входные данные (propagated inputs) — это зависимости, которые устанавливаются автоматически вместе с требуемыми пакетами (см. see propagated-inputs in package objects для подробной информации о распространяемых входных днных в определениях пакетов).

Примером является библиотека GNU MPC: его файлы заголовков C ссылаются на файлы библиотеки GNU MPFR, которые в свою очередь, ссылаются на библиотеку GMP. Так при установке MPC, также в профиль будут устанволены библиотеки MPFR и GMP; удаление MPC также удалит MPFR и GMP, если конечно, они не были явно установлены пользователем.

Кроме того, пакеты иногда зависят от переменных окружения — от их путей поиска (смотрите разъяснение --search-paths ниже). Любая отсутствующая или, возможно, некорректная переменная окружения вызывает сообщение отчета.

--install-from-expression=exp
-e exp

Устанавить пакет, соответствующий exp.

exp должно быть выражением Scheme, которое определяет объект <package>. Эта опция полезна, чтобы указать однозначно пакет, который имеет схожие варианты имён, например, выражением (@ (gnu packages base) guile-final).

Отметим, что эта опция устанавливает первое содержимое пакета, чего может быть недостаточно, если нужен специфичный выход пакета со множественным выходом.

--install-from-file=file
-f file

Устанавить пакет, который определён в файле.

Например, file может содержать содержать определение (see Описание пакетов):

(use-modules (guix)
             (guix build-system gnu)
             (guix licenses))

(package
  (name "hello")
  (version "2.10")
  (source (origin
            (method url-fetch)
            (uri (string-append "mirror://gnu/hello/hello-" version
                                ".tar.gz"))
            (sha256
             (base32
              "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  (build-system gnu-build-system)
  (synopsis "Hello, GNU world: An example GNU package")
  (description "Guess what GNU Hello prints!")
  (home-page "http://www.gnu.org/software/hello/")
  (license gpl3+))

Пользователи могут найти полезным включить подобный файл guix.scm в корень дерева своего проекта исходного кода, и он будет использоваться для тестирования разработки снепшотов и для создания воспроизводимого окружения разработки (see Вызов guix environment).

--remove=package
-r package

Удалить обозначенный пакет.

Касаемо --install, каждый пакет package может задавать номер версии и имя содержимого в добавлении к имени пакета. Например, -r glibc:debug удалит содержимое debug из glibc.

--upgrade[=regexp …]
-u [regexp …]

Обновить все устанволенные пакеты. Если задано одно или более значений regexp, обновление затронет только пакеты, которые соответствуют regexp. Также смотрите опцию --do-not-upgrade ниже.

Отметим, что это обновляет пакеты, которые установлены в системе, до последних версий, имеющихся в дистрибутиве. Чтобы обновить дистрибутив, нужно регулярно запускать guix pull (see Запуск guix pull).

--do-not-upgrade[=regexp …]

При совместном использовании с опцией --upgrade не обновляет ни один пакет, чьё имя соответствует regexp. Например, обновить все пакеты в текущем профиле , кроме тех, которые содержат подстроку "emacs":

$ guix package --upgrade . --do-not-upgrade emacs
--manifest=file
-m file

Создать новое поколение профиля из объекта манифеста, возвращаемого кодом Scheme в file.

Это позволяет вам описать содержимое профиля вместо того, чтобы собирать его последовательностью команд --install и других. Преимущество в том, что file может подчиняться контролю версиями, копироваться на другие машины, чтобы повторить такой же профиль и т.д.

file должен возвращать объект manifest, который, грубо говоря, является списком пакетов:

(use-package-modules guile emacs)

(packages->manifest
 (list emacs
       guile-2.0
       ;; Use a specific package output.
       (list guile-2.0 "debug")))

В этом примере мыдолжны знать, какие модули содержат определения переменных emacs и guile-2.0, чтобы написать правильную строку use-package-modules, что может быть затруднительно. Вместо этого мы можем обозначить обычные спецификации пакетов и сделать, чтобы specifications->manifest искал соответствующие объекты пакетов так:

(specifications->manifest
 '("emacs" "guile@2.2" "guile@2.2:debug"))
--roll-back

Откатиться до предыдущего поколения профиля, то есть отменить последнюю транзакцию.

При сочетании с опциеями как --install, откат выполняется до всех прочих действий.

При откате от первого поколения, которое по факту содержит установленные пакеты, профиль будет указывать на нулевое поколение, которое не содержит файлы, кроме собственных метаданных.

После выполнения отката, установка, удаление или обновление пакетов по факту заменяет прежние будущие поколения. То есть история поколений в профиле всегда линейная.

--switch-generation=pattern
-S pattern

Переключиться на определённое поколение, опрделённое pattern.

pattern может быть либо номером поколения или числом с префиксом "+" или "-". Последнее означает сменить вперёд/назад на обозначенное число поколений. Например, если вы хотите вернуться к последнему поколению после --roll-back, используйте --switch-generation=+1.

Разница между --roll-back и --switch-generation=-1 заключается в том, что --switch-generation не создаёт нулевое поколение, так что если заданное поколение не существует, текущее поколение не будет изменено.

--search-paths[=kind]

Вывести отчёт об определениях переменных окружения в синтаксисе Bash. Это может понадобиться для использования набора установленных пакетов. Эти переменные окружения используются некоторыми установленными пакетами для поиска файлов.

Например, для GCC должны быть определены переменные окружения CPATH и LIBRARY_PATH, чтобы он мог искать заголовки и библиотеки в профиле пользователя (see Environment Variables in Using the GNU Compiler Collection (GCC)). Если GCC и, скажем, библиотека C установлены в профиле, тогда --search-paths предложит установить эти переменные в profile/include и profile/lib соответственно.

Обычный способ определить эти переменные окружения в оболочке:

$ eval `guix package --search-paths`

Вид kind может быть либо точный адрес exact, либо префикс prefix, либо суффикс suffix, то есть возвращаемые переменные окружения могут быть либо точными, либо префиксами и суффиксами текущего значения этих переменных. При пропуске вид kind по умолчанию выбирается точный exact.

Эта опция также может использоваться для вычисления комбинированных путей поиска нескольких профилей. Рассмотрим пример:

$ guix package -p foo -i guile
$ guix package -p bar -i guile-json
$ guix package -p foo -p bar --search-paths

Последняя команда выше составляет отчёт о переменной GUILE_LOAD_PATH, даже если по отдельности ни foo, ни bar не предшествуют рекомендациям.

--profile=profile
-p profile

Использовать profile вместо пользовательского профиля по умолчанию.

--allow-collisions

Разрешить соперничающие пакеты в новом профиле. Используйте на свой собственный страх и риск!

По умолчанию guix package делает отчёт о противоречиях collisions в профиле. Противоречия происходят, когда дви или более разных версии или варианта данного пакета присутсвуют в профиле.

--bootstrap

Использовать бутстрап Guile для сборки профиля. Эта опция полезна только разработчикам дистрибутива.

В дополнение к этим действиям guix package поддерживает следующие опции при обращении к текущему состоянию профиля или для проверки доступности пакетов:

--search=regexp
-s regexp

Вывести список пакетов, чьи имена или описания содержат выражение regexp с учётом регистра, упорядоченные по соответствию. Печать всех метаданных соответствующих пакетов в формате recutils (see GNU recutils databases in GNU recutils manual).

Это позволяет извлекать заданые поля, используя команду recsel, например:

$ guix package -s malloc | recsel -p name,version,relevance
name: jemalloc
version: 4.5.0
relevance: 6

name: glibc
version: 2.25
relevance: 1

name: libgc
version: 7.6.0
relevance: 1

Также для отображения имён всех доступных пакетов под лицензией GNU LGPL версии 3:

$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
name: elfutils

name: gmp
…

Также можно уточнить поиск, используя несколько флагов -s в команде guix package или несколько аргументов в guix search. Например, следующая команда возвращает список настольных игр (используя синоним guix search на этот раз):

$ guix search '\<board\>' game | recsel -p name
name: gnubg
…

При пропуске -s game мы получим пакеты программного обеспечения, которые работают с печатными платами (boards); удалив угловые скобки рядом с board, получим пакеты, которые также работают с клавиатурами (keyboards).

А теперь более запутанный пример. Следующая команда ищет библиотеки криптографии, фильтрует библиотеки Haskel, Perl, Python и Ruby и печатает имена и краткие описания найденных пакетов:

$ guix search crypto library | \
    recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis

См. See Selection Expressions in GNU recutils manual для подробной информации о регуларяных выражениях selection expressions для recsel -e.

--show=package

Показать детали пакета package из списка доступных пакетов в формате recutils (see GNU recutils databases in GNU recutils manual).

$ guix package --show=python | recsel -p name,version
name: python
version: 2.7.6

name: python
version: 3.3.5

Можно также указать полное имя пакета, чтобы получить детали определённой версии пакета:

$ guix package --show=python@3.4 | recsel -p name,version
name: python
version: 3.4.3
--list-installed[=regexp]
-I [regexp]

Вывести текущий список установленных пакетов в заданном профиле, отобразив самый последний установленный пакет последним. Если задано regexp, будут выведены только пакеты, чьи имена содержат regexp.

Для каждого установленного пакета выводит следующие элементы, разделенные табуляцией (tab): имя пакета, строка версии, частью какого пакета является установленный пакет (например, out вывода по умолчанию включает include его заголовки т.д.), а также путь этого пакета на складе.

--list-available[=regexp]
-A [regexp]

Вывести список пакетов, доступных на текущий момент в дистрибутиве данной системы (see Дистрибутив GNU). Если задано regexp, выводит только установленные пакеты, чьё имя содержит regexp.

Для каждого пакета выводит следующие элементы, разделённые табуляцией: его имя, строка версии, часть пакета (see Пакеты со множественным выходом), а также расположение его определения в исходниках.

--list-generations[=pattern]
-l [pattern]

Вывести список поколений (generations) с датами их создания; для каждого поколения отобразить установленные пакеты, самый последний установленный пакет отобразать последним. Отметим, что нулевое поколение никогда не показывается.

Для каждого установленного пакета отображает следующие элементы, разделённые табуляцией: имя пакета, строка версии, частью какого пакета является установленный пакет (see Пакеты со множественным выходом), а также расположение пакета на складе.

Если используется pattern, команда выводит только соответствующие поколения. Правильные паттерны содержат:

--delete-generations[=pattern]
-d [pattern]

Если pattern пропущен, удалит все поголения, кроме текущего.

Эта команда принимает такие же паттерны, как --list-generations. Если pattern задан, удалит соответствующие поколения. Если паттерн pattern задаёт срок, выбираются поколения старше срока. Например, --delete-generations=1m удалит поколения, которые старше одного месяца.

Если текущее поколение попадает под условия паттерна, оно не будет удалено. А также нулевое поокление никогда не удаляется.

Отметим, что удаление поколений делает невозможным откат к ним. Следовательно эта команда должна использоваться внимательно.

Наконец, так как guix package может запускать процессы сборки, она поддерживает все привычные опции сборки (see Стандартные опции сборки). Она также поддерживает опции трансформации пакетов, как --with-source (see Опции трансформации пакета). Однако, отметим, что трансформации пакетов теряются после обновлений; чтобы сохранить трансформации при обновлениях, нужно определить собственный вариант пакета в модуле Guile и добавить его в GUIX_PACKAGE_PATH (see Описание пакетов).


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.3 Подстановки

Guix поддерживает прозрачную развёртку исходников/бинарников, это означает возможность сборки пакетов локально или скачивания собранных элементов с сервера, или и то и другое. Мы называем собранные элементы подстановками (substitutes) — это подстановки результатов локальных сборок. Часто скасивание подстановки намного быстрее, чем сборка пакетов локально.

В качестве подстановок может выступать какой угодно результат сборки деривации (see Деривации). Конечно, обычно это собранные пакеты, но также архивы исходников, например, представляя собой результаты сборок дериваций, могут быть доступны в качестве подстановок.


Next: , Up: Подстановки   [Contents][Index]

4.3.1 Официальный сервер подстановок

Сервер ci.guix.gnu.org представляет собой интерфейс официальной фермы сборки, которая последовательно собирает пакеты Guix для некоторых архитектур и делает их доступными в качестве подстановок. Это источник подстановок по умолчанию; он может быть изменён при указании опции --substitute-urls как для guix-daemon (see guix-daemon --substitute-urls) так и для клиентских инструментов, как guix package (see client --substitute-urls option).

URL подстановок могут быть либо HTTP, либо HTTPS. Рекомендуется HTTPS, так как такая связь шифруется; и наоборот, использование HTTP делает связь видимой для подслушивающих, и они могут использовать собранную информацию, чтобы определить, например, что ваша система не имеет патчей, покрывающих уязвимости безопасности.

Подстановки из официальной фермы сборки доступны по умолчанию при использовании системы Guix (see Дистрибутив GNU). Однако они отключены по умолчанию при использовании Guix на чужом дистрибутиве, если конечно вы явно не включили их на одном из рекомендуемых шагов установки (see Установка). Ниже объясняется, как включить или отключить подстановки с официальной фермы сборки; такая же процедура может также использоваться для включения подстановок с любого другого сервера подстановок.


Next: , Previous: , Up: Подстановки   [Contents][Index]

4.3.2 Авторизация сервера подстановок

Чтобы разрешить Guix скачивать подстановки из ci.guix.gnu.org или зеркала, вы должны добавить его публичный ключ в список контроля доступа (ACL) импорта архивов, используя команду guix archive (see Вызов guix archive). Это действие означает, что вы доверяете ci.guix.gnu.org, что он не скомпрометирован и может давать подлинные подстановки.

Публичный ключ для ci.guix.gnu.org устанавливается вместе с Guix в prefix/share/guix/ci.guix.gnu.org.pub, где prefix — префикс установки Guix. Если вы установили Guix из исходников, проверьте подпись GPG guix-1.0.1.tar.gz, где содержится файл публичного ключа. Затем можно выполнить примерно следующее:

# guix archive --authorize < prefix/share/guix/ci.guix.gnu.org.pub

Заметка: Аналогично файл hydra.gnu.org.pub содержит публичный ключ независимой фермы сборки, которая тоже обслуживает проект — ‘https://mirror.hydra.gnu.org’.

Когда это сделано, вывод команды guix build должен измениться с примерно такого:

$ guix build emacs --dry-run
The following derivations would be built:
   /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
   /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
   /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
   /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
…

на примерно следующий:

$ guix build emacs --dry-run
112.3 MB would be downloaded:
   /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
   /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
   /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
   /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
…

Это показывает, что подстановки из ci.guix.gnu.org готовы к использованию и будут скачиваться, если это возможно, в будущих сборках.

Механизм подстановок может быть отключен глобально путём запуска guix-daemon с --no-substitutes (see Вызов guix-daemon). Также он может отключиться временно путём указания опции --no-substitutes в guix package, guix build и других инструментах командной строки.


Next: , Previous: , Up: Подстановки   [Contents][Index]

4.3.3 Аутентификация подстановок

Guix определяет и вызывает ошибку, если происходит попытка использовать поддельную подстановку. А также он игнорирует подстановки, которые не подписаны, или те, которые не подписаны ни одним ключом из списка ACL.

Но всё же есть одно исключение: если не авторизованный сервер предоставляет подстановки, которые являются идентичными бит-к-биту с теми, которые предоставляет авторизованный сервер, тогда неавторизованный сервер становится приемлемым для скачивания. Например, положим, мы выбрали два сервера подстановок такой опцией:

--substitute-urls="https://a.example.org https://b.example.org"

Если ACL содержит только ключ для b.example.org, и если вдруг a.example.org предоставляет идентичные подстановки, тогда Guix будет скачивать подстановки из a.example.org, потому что он идёт первым в списке и может рассматриваться как зеркало b.example.org. На практике независимые машины сборки обычно производят одинаковые бинарники благодаря воспроизводимым сборкам (смотрите ниже).

При использовании HTTPS, сертификат X.509 сервера не проверяется (другими словами, сервер не проходит аутентификацию), супротив тому, что HTTPS-клиенты, как веб-браузеры, обычно делают это. Это потому, что Guix аутентифицирует саму информацию подстановки, как это описано выше, что собственно и представляет для нас интерес (в то время, как сертификаты X.509 относятся к аутентификации связок между доменными именами и публичными ключами).


Next: , Previous: , Up: Подстановки   [Contents][Index]

4.3.4 Настройки proxy

Подстановки скачиваются через HTTP или HTTPS. Можно установить переменную окружения http_proxy в окружении guix-daemon, чтобы она учитывалась при скачивании. Отметим, что значение http_proxy в окружении, в котором запускаются guix build, guix package и другие клиентские команды совершенно не даёт эффекта.


Next: , Previous: , Up: Подстановки   [Contents][Index]

4.3.5 Ошибки при подстановке

Даже когда подстановка для деривации доступна, иногда попытка подстановки завершается неудачно. Это может происходить по разным причинам: сервер подстановок может быть отключен, подстановка могла быть недавно удалена, связь может прерываться и т.д.

Когда подстановки включены, и подстановка для деривации доступна, но попытка подстановки завершается с ошибкой, Guix будет пытаться собрать деривацию локально в зависимости от того, задана или нет опция --fallback (see common build option --fallback). То есть, если --fallback пропущена, тогда локальная сборка не будет выполняться, а деривация будет рассматриваться как неудачная. Однако, если --fallback задана, тогда Guix попытается собрать деривацию локально, и успех или неудача деривации будет зависеть от успешной или неудачной процедуры локальной сборки. Отметим, что когда подстановки отключены или нет доступных подстановок для деривации, локальная сборка всегда будет исполняться, вне зависимости от установки опции --fallback.

Чтобы узнать,. сколько подстановок доступны в данный момент, можно попробовать запустить команду guix weather (see Вызов guix weather). Эта команда предоставляет статистику подстановок, предоставляемых сервером.


Previous: , Up: Подстановки   [Contents][Index]

4.3.6 Касатеьно проверенных бинарников

Сегодня индивидуальный контроль над работой за компьютером находится в заложниках у корпораций, организаций и групп, которые имеют достаточно силы и решимости разрушить инфраструктуру компьютерных сетей и внедрить уязвимости. Использование подстановок ci.guix.gnu.org может быть удобным, мы также стимулируем пользователей собирать их у себя или даже устанавливать собственные фермы сборки, чтобы уменьшить зависимость от ci.guix.gnu.org. Одним из способов помочь является публикация программного обеспечения, которое вы собираете, используя guix publish, тогда другие получат дополнительный сервер на выбор, чтобы скачивать подстановки (see Вызов guix publish).

Guix определяет цель максимизировать воспроизводимость сборок (see Особенности). В большинстве случаев независимые сборки заданного пакета или деривации должны давать результаты, идентичные до бита. То есть, благодаря ряду независимых сборок пакета мы можем улучшить чистоту наших систем. Команда guix challenge должна помочь пользователям оценить серверы подстановок, а разработчикам - помочь выявить недетерминистические сборки пакетов (see Вызов guix challenge). Подобным образом опция --check команды guix build даёт возможность пользователям проверить, яляются ли установленные ранее подстановки подлинными, выполнив их локальную сборку (see guix build --check).

Мы хотим, чтобы Guix в будущем поддерживал публикации и запросы бинарников от/для пользователей в формате равноправного обмена (peer-to-peer). Если вы желаете обсудить этот проект, присоединяйтесь к нам guix-devel@gnu.org.


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.4 Пакеты со множественным выходом

Часто пакеты, определённые в Guix, имеют один выход, это значит, что исходный пакет даёт только одну директорию на складе. При запуске guix package -i glibc это устанавливает результат по умолчанию; результат по умолчанию называется выходом, но его имя может пропускаться, как показано в этой команде. В этом частном случае результат по умолчанию для glibc содержит все файлы заголовков C, разделяемые библиотеки, статические библиотеки, документацию Info и другие поставляемые файлы.

Часто более приемлемым будет разделить различные типы файлов, поставляемых одним исходным пакетом, на отдельные выходы (результаты). Например, библиотека GLib C, используемая GTK+ и связанными с ним пакетами, устанавливает более 20Мб связанной документации в виде страниц HTML. Чтобы экономить место, пользователи, которым это не нужно, документацию можно выделить в отдельный выход, называемый doc. Чтобы установить основной выход GLib, который содерит всё, кроме документации, можно запустить:

guix install glib

Команда для установки её документации:

guix install glib:doc

Some packages install programs with different “dependency footprints”. For instance, the WordNet package installs both command-line tools and graphical user interfaces (GUIs). The former depend solely on the C library, whereas the latter depend on Tcl/Tk and the underlying X libraries. In this case, we leave the command-line tools in the default output, whereas the GUIs are in a separate output. This allows users who do not need the GUIs to save space. The guix size command can help find out about such situations (see Вызов guix size). guix graph can also be helpful (see Вызов guix graph).

Есть несколько таких пакетов со множественным выходом в дистрибутиве GNU. Другие традиционные имена выходов включают lib - для библиотек и иногда файлов заголовков, bin - для самих программ, debug - для отладочной информации (see Установка файлов отладки). Выходы пакетов представлены в третьей колонке вывода guix package --list-available (see Вызов guix package).


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.5 Вызов guix gc

Пакеты, которые установлены, но не используются, могут быть очищены как мусор (garbage-collected). Команда guix gc позволяет пользователям непосредственно запустить сборщик мусора и восстановить место в директории /gnu/store. Это единственный способ удалить файлы из /gnu/store — удаление файлов вручную может поломать её безвозвратно!

Сборщик мусора имеет набор известных корней (roots): любой файл в /gnu/store, доступный из корня, рассматривается как живой (live) и не может быть удалён; любой другой файл рассматривается как мёртвый (dead) и может быть удалён. Набор корней сборщика мусора (сокращённо "GC roots") содержит профили пользователей по умолчанию; по умолчанию символические ссылки в /var/guix/gcroots представляют эти корни сборщика мусора. Новые корни могут добавляться, например, командой guix build --root (see Вызов guix build). Команда guix gc --list-roots отображает их.

Перед запуском guix gc --collect-garbage для освобождения места часто бывает полезно удалить старые поколения из пользовательских профилей; так старые пакеты, относящиеся к этим поколениям, будут удалены. Это можно сделать, запустив guix package --delete-generations (see Вызов guix package).

Мы рекомендуем запускать сборщик мусора периодически, или когда вы хотите освободить место на диске. Например, чтобы гарантировать, что по меньшей мере 5 Гб будет доступно на вашем диске, просто запустите:

guix gc -F 5G

Хорошо бы запускать это как неинтерактивную периодическую задачу (see Запланированное исполнения задач, чтобы узнать, как добавить такую задачу). Запуск guix gc без аргументов соберёт столько мусора, сколько возможно, но это часто не удобно: можно обнаружить, что придётся заново собирать или скачивать программы, "убитые" сборщиком мусора, хотя они необходимы для сборки другого софта, например, это касается инструментов компилятора.

Команда guix gc предоставляет три способа взаимодействия: может использоваться для сборки мусора (garbage-collect) любых мёртвых файлов (по умолчанию), для удаления конкретных файлов (опция --delete), для вывода информации сборщика мусора, а также для более изощрённых запросов. Опции сборщика мусора:

--collect-garbage[=min]
-C [min]

Собрать мусор, то есть недоступные файлы в /gnu/store и поддиректориях. Это операция по умолчанию, если не заданы опции.

Если задана min, остановиться, когда min байт собрано. min может быть числом байт или может содержать единицу измерения в суффиксе, как например, MiB для мебибайт и GB гигабайт (see size specifications in GNU Coreutils).

Если min пропущено, собрать весь мусор.

--free-space=free
-F free

Собирать мусор, пока не станет доступно free места в /gnu/store, если возможно; free описывает дисковое пространство, как 500MiB, как это описанов выше.

Когда free или более места стало свободно в /gnu/store, ничего не делать и немедленно выйти.

--delete-generations[=duration]
-d [duration]

Перед запуском сборщика мусора удалить все поколения, старше duration, для всех пользовательских профилей; если запускать от root, это применяется для всех профилей всех пользователей.

Например, следующая команда удаляет все поколения всех ваших профилей, которые старше 2 месцев (кроме текущего поколения), а затем запускается процесс освобождения мместа, пока по меньшей мере 10 GiB не станет доступно:

guix gc -d 2m -F 10G
--delete
-D

Попытаться удалить все файлы и директории склада, приведённые в аргументах. Это завершается с ошибкой, если какие-либо файлы не присутствуют на складе, или если они ещё живы (live).

--list-failures

Вывести список элементов склада, которые относятся к кешированным неудачным сборкам.

Это ничего не выводит, если демон не был запущен с опцией --cache-failures (see --cache-failures).

--list-roots

Вывести список корней сборщика мусора (GC roots), которыми владеет пользователь; при запуске от root, выводит список всех корней сборщика мусора.

--clear-failures

Удалить заданные элементы склада из кеша неудачных сборок.

Опять же эта опция имеет смысл, если демон запущен с --cache-failures. В противном случае это не имеет эффекта.

--list-dead

Вывести список мёртвых файлов и директорий, которые по-прежнему присутствуют на складе, то есть файлы и директории, не доступные более из любого корня.

--list-live

Вывести список живых файлов и директорий склада.

В дополнение можно запросить связи между существующими файлами на складе:

--references
--referrers

Вывести список связанных (обязательно, ссылающихся) файлов на складе с указанными аргументами.

--requisites
-R

Вывести всё необходимое для файлов на складе, указанных в аргументах. Всё необходимое включает сами файлы на складе, их связи и связи их связей рекурсивно. Другими словами, выводимый список — это непосредственный конвейер файлов на складе.

См. See Вызов guix size для информации об инструменте профилирования конвейера для элемента. См. See Вызов guix graph для информации об инструменте визуализации графа связей.

--derivers

Вернуть деривацию(-ии), производящие данные элементы склада (see Деривации).

Например, эта команда:

guix gc --derivers `guix package -I ^emacs$ | cut -f4`

возвращает файл(ы) .drv, которые произвели пакет emacs, установленный в вашем профиле.

Отметим, что может быть не найдено ни одного файла .drv, например, потому что эти файлы были удалены сборщиком мусора. Также может быть более одного файла .drv из-за дериваций с фиксированным выходом.

Наконец, следующие опции позволяют проверить целостность склада и контролировать использование диска.

--verify[=options]

Проверить целостность склада.

По умолчанию убедиться, что все элементы склада, которые в базе данных демона помечены как действующие, на самом деле присутствуют в /gnu/store.

Опции options, если они указаны, должны представлять собой список, разделённый запятыми, содержащий одно или более значений contents и repair.

Если задано --verify=contents, демон вычисляет хеш содержимого каждого элемента склада и сравнивает с его хешем в базе данных. Несовпадения хеша отображаются в отчёте как повреждение данных. Так как она проходит все файлы склада, эта команда может занять много времени, особенно в системах с медленным диском.

Использование --verify=repair или --verify=contents,repair указывает демону предпринять попытку восстановить разрушенные элементы склада, выбирая подстановки для них (see Подстановки). Так как восстановление не атомарное, и поэтому потенциально опасно, оно доступно только системному администратору. Малозатратная альтернатива в случае, если вы знаете точно, какие элементы склада испорчены, — это guix build --repair (see Вызов guix build).

--optimize

Оптимизировать склад с помощью жёстких ссылок на идентичные файлы — это дедупликация.

Демон выполняет дедупликацию после каждой успешной сборки или импорта архива, если конечно оно не было запущено с --disable-deduplication (see --disable-deduplication). Так что эта опция особенно важна, если демон запущено с --disable-deduplication.


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.6 Вызов guix pull

Пакеты, которые были установлены или обновлены до последней версии, доступные в дистрибутиве, доступны и на вашей локальной машине. Для обновления этого дистрибутива инструментами Guix нужно запустить guix pull: команда скачивает последние исходные коды Guix, описания пакетов и разворачивает их. Исходный код скачивается из репозитория Git, репозитория GNU Guix по умолчанию, хотя это можно поменять.

После выполнения этой команды guix package будет использовать пакеты и те их версии, которые имеются в только что полученной копии Guix. Эта последняя версия будет источником также всех команд Guix, модулей Scheme. Из этого обновления станет доступен набор команд guix.

Любой пользователь может обновить свою копию Guix, используя guix pull, эффект коснётся только пользователя, который запустил guix pull. Например, если пользователь root запускает guix pull, это не имеет эффекта на версию Guix, которую видит alice sees, и наоборот.

Результат запуска guix pull — это профиль profile, доступный в ~/.config/guix/current, содержащий последний Guix. Так что обязательно добавьте этот адрес первым в пути поиска, чтобы использовать последнюю версию, а также для руководства Info (see Документация):

export PATH="$HOME/.config/guix/current/bin:$PATH"
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"

Опция --list-generations или -l выводит список последних поколений, поставленных guix pull, вместе с деталями об их происхождении:

$ guix pull -l
Generation 1	Jun 10 2018 00:18:18
  guix 65956ad
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe

Generation 2	Jun 11 2018 11:02:49
  guix e0cc7f6
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
  2 new packages: keepalived, libnfnetlink
  6 packages upgraded: emacs-nix-mode@2.0.4,
    guile2.0-guix@0.14.0-12.77a1aac, guix@0.14.0-12.77a1aac,
    heimdal@7.5.0, milkytracker@1.02.00, nix@2.0.4

Generation 3	Jun 13 2018 23:31:07	(current)
  guix 844cc1c
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: 844cc1c8f394f03b404c5bb3aee086922373490c
  28 new packages: emacs-helm-ls-git, emacs-helm-mu, …
  69 packages upgraded: borg@1.1.6, cheese@3.28.0, …

Смотрите See guix describe для информации о других способах получить информацию о текущем статусе Guix.

Этот профиль ~/.config/guix/current работает, как любой другой профиль, созданный guix package (see Вызов guix package). Так что можно вывести список поколений, откатиться до предыдущего поколения, то есть до предыдущего Guix, и так далее:

$ guix package -p ~/.config/guix/current --roll-back
switched from generation 3 to 2
$ guix package -p ~/.config/guix/current --delete-generations=1
deleting /var/guix/profiles/per-user/charlie/current-guix-1-link

Команда guix pull обычно вызывается без аргументов, но поддерживает следующие опции:

--url=url
--commit=commit
--branch=branch

Скачать код канала guix из указанного url, относящийся к обозначенному коммиту commit (корректный ID коммита Git, представленный в виде шестнадцатеричной строки), или ветке branch.

Эти опции внедрены для удобства, но также можно задать конфигурационный файл ~/.config/guix/channels.scm или использовать опцию --channels (смотрите ниже).

--channels=file
-C file

Считать список каналов из файла file вместо ~/.config/guix/channels.scm. file должен содержать код Scheme, который определяет список объектов "канал". См. See Каналы для подробной информации.

--news
-N

Вывести список пакетов, которые добавлены или обновлены после предыдущего поколения.

Это та же информация, которая отображается по завершении guix pull, но без эллипсов. Это также совпадает с выводом guix pull -l для последнего поколения (смотрите ниже).

--list-generations[=pattern]
-l [pattern]

Вывести список всех поколений ~/.config/guix/current или, если предоставлен паттерн pattern, подмножество поколений, которые соответствуют pattern. Синтаксис pattern — такой же, как у guix package --list-generations (see Вызов guix package).

См. See Вызов guix describe, чтобы узнать, как вывести информацию только о текущем поколении.

--profile=profile
-p profile

Использовать профиль profile вместо ~/.config/guix/current.

--dry-run
-n

Показать, какие коммиты будут использоваться, и что будет собрано или скачано в виде подстановок, но не выполнять эту работу.

--system=system
-s system

Предпринять попытку собрать систему system, т.е. i686-linux, вместо типа системы хоста сборки.

--verbose

Производить вывод логов, отображая логи сборки в стандартный вывод ошибок.

--bootstrap

Использовать бутстрап Guile для сорки последнего Guix. Эта опция полезна только для разработчиков.

Механизм каналов channel позволяет указать guix pull, из какого репозитория или ветки скачивать, а также какие дополнительные репозитории должны использоваться для развёртки. См. See Каналы для подробной информации.

В добавок guix pull поддерживает все стандартные опции сборки (see Стандартные опции сборки).


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.7 Каналы

Guix и его коллекция пакетов можно обновить запуском guix pull (see Запуск guix pull). По умолчанию guix pull скачивает и разворачивает Guix из официального репозитория GNU Guix. Это может быть изменено определением каналов channels в файле ~/.config/guix/channels.scm. Канал обозначает URL или ветку репозитория Git для разворачивания. Также guix pull может быть настроена для скачивания из одного или более каналов. Другими словами, каналы могут использоваться для настройки и для расширения Guix, как это будет показано ниже.

4.7.1 Использование отдельного канала Guix

Канал, названный guix, обозначает, откуда должен скачиваться сам Guix (его инструменты командной строки и коллекция пакетов). Например, предположим вы хотите обновиться из вашей собственной копии репозитория Guix на example.org, а именно из ветки super-hacks, тогда можно написать в ~/.config/guix/channels.scm следующую спецификацию:

;; Tell 'guix pull' to use my own repo.
(list (channel
        (name 'guix)
        (url "https://example.org/my-guix.git")
        (branch "super-hacks")))

При такой настройке guix pull будет скачивать код из ветки super-hacks репозитория в example.org.

4.7.2 Указание дополнительных каналов

Можно также задать дополнительные каналы для выборки оттуда. Ну, например, у вас ряд собственных вариантов пакетов или собственные пакеты, которые вы считаете не особо важным для отправки в проект Guix, но хотите, чтобы эти пакеты были доступны вам в командной строке прозрачно, без дополнительных действий. Вначале можно написать модули, содержащие определения этих пакетов (see Пакетные модули), затем разместить их в репозитории Git, и тогда вы или кто-либо ещё сможете использовать их в качестве дополнтельного канала для получения пакетов. Красиво, да?

Внимание: Прежде чем вы крикнете Ух-ты, это круто! и опубликуете собственный канал, необходимо учесть некоторые предостережения:

Вы предупреждены! Обозначив это, мы верим, что внешние каналы — это способ для вас проявлять свою свободу и вместе с тем расширять коллекцию пакетов Guix и делиться улучшениями, что является основными догматами свободного программного обеспечения. Пожалуйста, свяжитесь с нами по e-mail guix-devel@gnu.org, если вы хотите обсудить это.

Чтобы использовать канал, напишите ~/.config/guix/channels.scm, чтобы обозначить guix pull скачивать оттуда в дополнение к каналу(-ам) Guix по умолчанию:

;; Add my personal packages to those Guix provides.
(cons (channel
        (name 'my-personal-packages)
        (url "https://example.org/personal-packages.git"))
      %default-channels)

Заметим, что сниппет выше (всегда!) код Scheme; мы используем cons для добавления канала в список каналов, то есть в переменную %default-channels (see cons and lists in GNU Guile Reference Manual). Если этот файл написан, guix pull производит сборку не только Guix, но и пакетных модулей из вашего репозитория. В результате в ~/.config/guix/current содержится объединение Guix и ваших собственных пакетных модулей:

$ guix pull --list-generations
…
Generation 19	Aug 27 2018 16:20:48
  guix d894ab8
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  my-personal-packages dd3df5e
    repository URL: https://example.org/personal-packages.git
    branch: master
    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
  11 new packages: my-gimp, my-emacs-with-cool-features, …
  4 packages upgraded: emacs-racket-mode@0.0.2-2.1b78827, …

Результат guix pull выше показывает, что поколение Generation 19 включает как репозиторий Guix, так и пакеты из канала my-personal-packages. Вместе с новыми и обновлёнными пакетами, которые присутствуют в списке, что-нибудь типа my-gimp и my-emacs-with-cool-features может прийти из my-personal-packages, когда остальные идут из канала Guix по умолчанию.

Чтобы создать канал, создайте репозиторий Git, содержащий ваши собственные пакетные модули, и сделайте его доступным. Репозиторий может содержать что-либо, но полезный канал будет содержать модули Guile, экспортирующие пакеты. Когда вы начали использовать канал, Guix будет работать, как будто корневая директория репозитория Git этого канала добавлена в путь загрузки Guile (see Load Paths in GNU Guile Reference Manual). Например, если ваш канал содержит файл my-packages/my-tools.scm, который определяет модуль Guile, тогда модуль будет доступен под именем (my-packages my-tools), и вы сможете использовать его, как любой другой модуль (see Модули in GNU Guile Reference Manual).

4.7.3 Объявление зависимостей канала

Авторы канала могут решить расширить коллекцию пакетов пакетами, которые поставляются другими каналами. Они могут объявить, что их канал зависит от других каналов, в файле метаданных .guix-channel, который нужно разместить в корне репозитория канала.

Файл метаданных должен содержать простое выражение S-expression как это:

(channel
 (version 0)
 (dependencies
  (channel
   (name some-collection)
   (url "https://example.org/first-collection.git"))
  (channel
   (name some-other-collection)
   (url "https://example.org/second-collection.git")
   (branch "testing"))))

В примере выше объявлен канал, который зависит от двух других каналов, из которых оба будут скачаны автоматически. Модули, предоставляемые каналом, будут скомпилированы в окружении, в котором доступны модули всех этих каналов.

В целях воспроизводимости и сопровождения вы должны избегать зависимостей от каналов, которые вы не контролируете, и вы должны стремиться минимизировать число зависимостей.

4.7.4 Копирование Guix

Результат guix pull --list-generations выше показывает точно, какие коммиты были использованы для сборки данной инстанции Guix. Так что мы можем повторить её, скажем, на другой машине, предоставив объявление канала в ~/.config/guix/channels.scm, которое завязано на этих коммитах:

;; Deploy specific commits of my channels of interest.
(list (channel
       (name 'guix)
       (url "https://git.savannah.gnu.org/git/guix.git")
       (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
      (channel
       (name 'my-personal-packages)
       (url "https://example.org/personal-packages.git")
       (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))

Команда guix describe --format=channels даже может непосредственно воспроизвести этот список каналов (see Вызов guix describe).

И тогда две машины будут работать с полностью одинаковым Guix, имея доступ к абсолютно одинаковым пакетам. Результат guix build gimp на одной машине будет совершенно таким же, бит к биту, как результат этой команды на другой машине. Это также означает, что обе машины имеют доступ ко всем исходным кодам Guix, следовательно, ко всем исходным кодам каждого пакета, определённого в Guix.

Это даёт вам супервозможности, позволяя вам отслеживать и управлять происхождением артефактов бинарников с точной детализацией, также повторять программные окружения — это воспроизводимость высокого уровня. Смотрите See Младшие версии, чтобы узнать другие преимущества таких супервозможностей.


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.8 Младшие версии

Заметка: Функциональность, описанная здесь, — это обзор технологии версии 1.0.1. Интерфейс может меняться.

Иногда вам может понадобиться перемешивать пакеты из ревизии Guix, которая работает в настоящий момент, с пакетами, доступными в другой ревизии Guix. Основания Guix inferiors позволяют вам получить это, составляя различные ревизии Guix произвольным образом.

Технически работа с ранними версиями — это в целом отдельный процесс Guix, связанный с главным процессом Guix через REPL (see Вызов guix repl). Модуль (guix inferior) позволяет запускать ранние версии и взаимодействовать с ними. Он также предоставляет высокоуровневый интерфейс для обзора и управления пакетами, которые поставляет ранняя версия — ранние версии пакетов.

При сочетании с каналами (see Каналы) ранние версии преоставляют простой способ взаимодействовать с отдельными ревизиями Guix. Например, предположим, вы хотите установить в ваш профиль текущий пакет guile вместе с тем guile-json, который был определён в предыдущей ревизии Guix (может быть, потому что новый guile-json имеет несовместимый API, и вы хотите запустить ваш код со старым API). Чтобы это сделать, можно написать манифест для использования с guix package --manifest (see Вызов guix package). В этом манифесте вы создадите описание ранней версии той предыдущей ревизии Guix, которая вас интересует, в которой вы ищете пакет guile-json ранней версии:

(use-modules (guix inferior) (guix channels)
             (srfi srfi-1))   ;for 'first'

(define channels
  ;; This is the old revision from which we want to
  ;; extract guile-json.
  (list (channel
         (name 'guix)
         (url "https://git.savannah.gnu.org/git/guix.git")
         (commit
          "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))

(define inferior
  ;; An inferior representing the above revision.
  (inferior-for-channels channels))

;; Now create a manifest with the current "guile" package
;; and the old "guile-json" package.
(packages->manifest
 (list (first (lookup-inferior-packages inferior "guile-json"))
       (specification->package "guile")))

Далее запуск guix package --manifest может вызвать сборку канала, который вы обозначили ранее, и в результате это задействует раннюю версию. Последовательные запуски будут быстрее, потому что ревизия Guix будет кеширована.

Модуль (guix inferior) предоставляет следующие процедуры для работы с ранними версиями:

Процедура Scheme: inferior-for-channels channels [#:cache-directory] [#:ttl] Возвращает раннюю версию для списка каналов

channels. Использует кеш в cache-directory, где компоненты могут восстанавливаться через ttl секунд. Эта процедура открывает новое соединение с демоном сборки.

Как побочный эффект, эта процедура может собирать или скачивать подстановки бинарников для channels, что может занять время.

Процедура Scheme: open-inferior directory [#:command "bin/guix"] Открывает раннюю версию Guix в directory,

запустив repl directory/command или эквивалент. Возвращает #f, если ранняя версия не может быть запущена.

Процедуры, приведённые ниже, обеспечивают работу и управление ранними версиями пакетов.

Процедура Scheme: inferior-packages inferior

Возвращает список пакетов, относящихся к ранней версии inferior.

Процедура Scheme: lookup-inferior-packages inferior name [version] Возвращает сортированный список пакетов ранней версии

inferior, содержащих имя name, поздняя версия - вначале. Если версия version задана, возвращает только пакеты с номером версии, начинающейся с version.

Процедура Scheme: inferior-package? obj

Возвращает true, если объект obj — это пакет ранней версии.

Процедура Scheme: inferior-package-name package
Процедура Scheme: inferior-package-version package
Процедура Scheme: inferior-package-synopsis package
Процедура Scheme: inferior-package-description package
Процедура Scheme: inferior-package-home-page package
Процедура Scheme: inferior-package-location package
Процедура Scheme: inferior-package-inputs package
Процедура Scheme: inferior-package-native-inputs package
Процедура Scheme: inferior-package-propagated-inputs package
Процедура Scheme: inferior-package-transitive-propagated-inputs package
Процедура Scheme: inferior-package-native-search-paths package
Процедура Scheme: inferior-package-transitive-native-search-paths package
Процедура Scheme: inferior-package-search-paths package

Эти процедуры являются двойниками метода доступа к записям пакетов (see Интерфейс package). Большинство из них работают с запросами для ранней версии, из которой происходит package, так что ранняя версия должна оставаться живой, когда вы вызываете эти процедуры.

Пакеты ранних версий могут использоваться прозрачно, как любой другой пакет или объект типа файл в выражении G-expressions (see G-Expressions). Они также прозрачно используются в процедуре packages->manifest, которая обычно используется в манифестах (see the --manifest option of guix package). Так можно вставлять пакет ранней версии в принципе куда угодно, как если вставлять обычный пакет: в манифесты, в поле packages вашего объявления operating-system и т.д.


Next: , Previous: , Up: Управление пакетами   [Contents][Index]

4.9 Вызов guix describe

Часто может возникать вопрос: "Какую ревизию Guix я использую?" - Или: "Какие каналы я использую?" Это полезна информация во многих ситуациях: если вы хотите повторить окружение на другой машине или в другом пользовательском аккаунте, если вы хотите составить отчёт об ошибке, чтобы определить, какие изменения в канале, который вы используете, вызвали ошибку, или если вы хотите записать состояние вашей системы в целях воспроизводимости. Команда guix describe отвечает на эти вопросы.

В случае запуска после guix pull команда guix describe отображает канал(ы), из которых производилась сборка, включая URL и репозиториев и ID коммитов (see Каналы):

$ guix describe
Generation 10	Sep 03 2018 17:32:44	(current)
  guix e0fa68c
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: e0fa68c7718fffd33d81af415279d6ddb518f727

Если вы знакомы с системой контроля версиями Git, эта команда по сути похожа на git describe; выход тот же, что в guix pull --list-generations, но ограничен текущим поколением (see the --list-generations option). Так как ID коммита Git выше ссылается однозначно на снимок Guix, эта информация — всё, что нужно для описания используемой ревизии Guix и повторения её.

Чтобы проще повторить Guix, guix describe также может вызываться для вывода списка каналов вместо читаемого описания выше:

$ guix describe -f channels
(list (channel
        (name 'guix)
        (url "https://git.savannah.gnu.org/git/guix.git")
        (commit
          "e0fa68c7718fffd33d81af415279d6ddb518f727")))

Можно сохранить это в файл и подать на вход guix pull -C на любой другой машине или через время, чтобы инициализировать эту конкретную ревизию Guix (see the -C option). Теперь, когда можно развернуть подобную ревизию Guix, вы можете также полностью повторить программное окружение. Мы скромно полагаем, это чудесно. Надеемся, вам это тоже понравится!

Подробнее об опциях, поддерживаемых guix describe:

--format=format
-f format

Произвести вывод в указанном формате format, одном из:

human

произвести вывод для чтения человеком;

каналы

произвести список спецификаций каналов, который может использоваться в guix pull -C или вставлен в файл ~/.config/guix/channels.scm (see Запуск guix pull);

json

произвести список спецификаций каналов в формате JSON;

recutils

произвести список спецификаций каналов в формате Recutils.

--profile=profile
-p profile

Вывести информацию о профиле profile.


Previous: , Up: Управление пакетами   [Contents][Index]

4.10 Вызов guix archive

Команда guix archive даёт возможность пользователям экспортировать файлы со склада в простой архив и затем импортировать их на машину с работающим Guix. В частности, это позволяет передавать файлы склада одной машины на склад другой машины.

Заметка: Если вы ищете способ производить архивы в формате, который подходит для инструментов, отличных от Guix, смотрите see Вызов guix pack.

Чтобы экспортировать файлы склада в архив в стандартный вывод, выполните:

guix archive --export options specifications...

Спецификации specifications могут быть либо именами файлов или пакетами, как для команде guix package (see Вызов guix package). Например, следующая команда создаёт архив, содержащий выход gui пакета git и главный выход emacs:

guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar

Если указанные пакеты ещё не собраны, guix archive автоматически соберёт их. Процесс сборки может контролироваться обычными опциями сборки (see Стандартные опции сборки).

Чтобы передать пакет emacs на машину, соединённую по SSH, нужно следующее:

guix archive --export -r emacs | ssh the-machine guix archive --import

Точно также для передачи всего профиля пользователя из одной машины на другую, выполните:

guix archive --export -r $(readlink -f ~/.guix-profile) | \
  ssh the-machine guix-archive --import

Однако заметим, что в обоих примерах, передаются весь emacs и профиль вместе с их зависимости (ввиду -r), не учитывая, что доступно на складе целевой машины. Опция --missing помогает определить отсутствующие элементы на целевом складе. Команда guix copy упрощает и оптимизирует весь этот процесс, так что в данном случае она решает проблему (see Вызов guix copy).

Архивы сохраняются в нормализованном виде, или в формате nar, который по сути совместим с tar, но с отличиями, которые делают его более подходящим для наших целей. Во-первых, вместо записи всех метаданных Unix для каждого файла, формат nar упоминает только формат файла (обычный, директория, символическая ссылка); права доступа Unix и владелец/группа не учитываются. Во-вторых, порядок, в котором сохраняются компоненты директории, всегда соответствуют порядку имён файлов в соответствии с порядком сортировки локали C. Это делает производство архива полностью детерминистическим.

При экспортировании демон подписывает цифровой подписью содержимое архива, и эта цифровая подпись прикрепляется. При импорте демон проверяет подпись и отменяет импорт в случае недействительной подписи, или если ключ подписи не авторизован.

Основные опции:

--export

Экспортировать указанные файлы склада или пакеты (смотрите ниже). Писать результирующий архив в стандартный вывод.

Зависимости не включаются в выход, если не задана опция --recursive.

-r
--recursive

При сочетании с --export это указывает guix archive включать в архив зависимости обозначенных элементов. Так результирующий архив будет "сам в себе": содержит полный конвейер экспортированных элементов склада.

--import

Читать архив из стандартного ввода и импортировать файлы, поставляемые им, на склад. Отклонить, если архив имеет недействительную цифровую подпись, или если он подписан публичным ключом, который не находится в списке авторизованных ключей (смотрите --authorize ниже).

--missing

Читать список имён файлов склада из стандартного ввода, одна линия - один файл, и писать в стандартный вывод подмножество этих файлов, отсутствующих на складе.

--generate-key[=parameters]

Генерировать новую ключ-пару для демона. Это необходимо получить перед тем, как экспортировать архивы опцией --export. Отметим, что эта операция обычно занимает время, так как необходимо собрать много энтропии для ключ-пары.

Сгенерированная ключ-пара обычно сохраняется под /etc/guix, в файлы signing-key.pub (публичный ключ) и signing-key.sec (прватный ключ, который должен оставаться в секрете). Если параметры parameters пропущены, генерируется ключ ECDSA, используя кривую Ed25519, или для Libgcrypt версии ранее 1.6.0 — это 4096-битный ключ RSA. Альтернативно в параметрах parameters можно указать genkey, соответствующие Libgcrypt (see gcry_pk_genkey in The Libgcrypt Reference Manual).

--authorize

Авторизовать импорт, подписанный публичным ключом, поступивший на стандартный ввод. Публичный ключ должен быть в формате s-expression, то есть в таком же формате, как файл signing-key.pub.

The list of authorized keys is kept in the human-editable file /etc/guix/acl. The file contains “advanced-format s-expressions” and is structured as an access-control list in the Simple Public-Key Infrastructure (SPKI).

--extract=directory
-x directory

Читать архив, представляющий один элемент, в качестве поставленного серверами подстановки (see Подстановки) и извлечь его в директорию directory. Это низкоуровневая операция, необходимая только в очень редких случаях, смотрите ниже.

Например, следующая команда распаковывает подстановку Emacs, поставленную ci.guix.gnu.org в /tmp/emacs:

$ wget -O - \
  https://ci.guix.gnu.org/nar/…-emacs-24.5 \
  | bunzip2 | guix archive -x /tmp/emacs

Архивы, представляющие один элемент, отличаются от архивов, содержащих множество элементов, производимых guix archive --export. Они содержат один элемент склада, но они не включают подпись. Так что эта операция не использует верификацию, и его выход должен рассматриваться как небезопасный.

Основная цель этой операции — упростить просмотр содержимого архива, происходящего, возможно, из недоверенных серверов подстановок.


Next: , Previous: , Up: Top   [Contents][Index]

5 Разработка

Если вы являетесь разработчиком программного обеспечения, Guix предоставляет инструменты, которые вы можете найти полезными, независимо от языка разработки. Об этом данный раздел.

Команда guix environment предоставляет удобный способ установить окружение разработки на ваш выбор, содержащее все зависимости и инструменты, необходимые для работы с пакетом программы. Команда guix pack позволяет создавать наборы приложений, которые могут легко распространяться для пользователей, которые не используют Guix.


Next: , Up: Разработка   [Contents][Index]

5.1 Вызов guix environment

Цель guix environment — помощь программистам в создании окружения разработки, которое можно повторять, без влияния на профили пакетов. Инструмент guix environment принимает один или более пакетов, собирает все входные данные для них и создаёт окружение оболочки для их использования.

Основной синтаксис:

guix environment options package

Следующий пример порождает новую оболочку, установленную для разработки GNU Guile:

guix environment guile

Если необходимые зависимости ещё не собраны, guix environment автоматически собирает их. Окружение новой оболочки является приращённой версией окружения, которое создаётся командой guix environment. Оно создаёт необходимые пути поиска для сборки данного пакета и добавляет их к существующим переменным окружения. Чтобы создать "чистое" окружение, в котором исходные переменные окружения не установлены, используйте опцию --pure option10.

guix environment определяет переменную GUIX_ENVIRONMENT в оболочке, которую создаёт; её значением является имя файла профиля этого окружения. Это позволяет пользователям, скажем, определить специфичные значения окружений разработки в .bashrc (see Bash Startup Files in The GNU Bash Reference Manual):

if [ -n "$GUIX_ENVIRONMENT" ]
then
    export PS1="\u@\h \w [dev]\$ "
fi

... или просмотеть профиль:

$ ls "$GUIX_ENVIRONMENT/bin"

Дополним, что может быть указано более одного пакета, в таком случае используется объединённые входные данные для указанных пакетов. Например, команда ниже порождает оболочку, в котором доступны все зависимости, как Guile, так и Emacs:

guix environment guile emacs

Иногда интерактивная сессия оболочки не нужна. Можно вызвать произвольную команду при указании токена --, который отделяет команду от остальных аргументов:

guix environment guile -- make -j4

В других ситуациях удобнее указать список паетов, необходимых для окружения. Например, следующая команда запускает python из окружения, содержащего Python 2.7 и NumPy:

guix environment --ad-hoc python2-numpy python-2.7 -- python

Более того, возможно, вам потребуются зависимости пакета, а также некоторые дополнительные пакеты, которые не являются зависимостями процесса сборки или процесса исполнения (работы), но важны при разработке. Для этого и указан флаш --ad-hoc. Пакеты, обозначенные до --ad-hoc интерпретируются как пакеты, чьи зависимости будут добавлены в окружение. Пакеты, которые обозначены после --ad-hoc, интерпретируются как пакеты, которые будут добавлены в окружение непосредственно. Например, следующая команда создаёт окружение разработки Guix, которая в дополнение включает Git и strace:

guix environment guix --ad-hoc git strace

Иногда возникает необходимость изолировать окружение настолько, насколькоо возможно, для максимальной чистоты и воспроизводимости. В частности, при использовании Guix на дистрибутиве, отличном от системы Guix, желательно предотвращать доступ из окружения разработки к /usr/bin и другим ресурсам системы. Например, следующая команда порождает Guile REPL в "контейнере", в котором монтированы только склад и текущая рабочая директория:

guix environment --ad-hoc --container guile -- guile

Заметка: Опция --container требует Linux-libre 3.19 или новее.

Доступные опции резюмированы ниже.

--root=file
-r file

Создать символическую ссылку file на профиль этого окружения и зарегистрировать её как корень сборщика мусора.

Это полезно, если вы хотите защитить своё окружение от сборщика мусора, сделать его "постоянным".

Если эта опция пропущена, окружеие защищено от сборщика мусора только на время сессии guix environment. Это означает, что в следующий раз, когда вы создадите такое же окружение, вам потребуется пересобирать и скачивать пакеты заново. See Вызов guix gc, for more on GC roots.

--expression=expr
-e expr

Создать окружение для пакета или списка пакетов, которые соответствуют выражению expr.

Например, запуск:

guix environment -e '(@ (gnu packages maths) petsc-openmpi)'

запускает оболочку с окружением для этого специфического варианта пакета PETSc.

Запуск:

guix environment --ad-hoc -e '(@ (gnu) %base-packages)'

стартует оболочку со всеми доступными базовыми пакетами.

Команды выше используют только выход по умолчанию обозначенных пакетов. Чтобы выбрать другие выходы, можно указать два элемента кортежей:

guix environment --ad-hoc -e '(list (@ (gnu packages bash) bash) "include")'
--load=file
-l file

Создать окружение для пакета или списка пакетов, код которых задан в файле file.

Например, file может содержать содержать определение (see Описание пакетов):

(use-modules (guix)
             (gnu packages gdb)
             (gnu packages autotools)
             (gnu packages texinfo))

;; Augment the package definition of GDB with the build tools
;; needed when developing GDB (and which are not needed when
;; simply installing it.)
(package (inherit gdb)
  (native-inputs `(("autoconf" ,autoconf-2.64)
                   ("automake" ,automake)
                   ("texinfo" ,texinfo)
                   ,@(package-native-inputs gdb))))
--manifest=file
-m file

Создать окружение для пакетов, содержащихся в объекте манифеста, возвращаемого кодом Scheme в файле file.

Это то же, что опция с таким же именем в guix package (see --manifest) и использует такие же файлы манифестов.

--ad-hoc

Включить все указанные пакеты в результирующее окружение, если бы целевой (лат. ad hoc) пакет имел бы их как входные данные. Эта опция полезна для быстрого создания окружения без необходимости писать выражение типа пакет, содержащее желаемые входные данные.

Например, команда:

guix environment --ad-hoc guile guile-sdl -- guile

запускает guile в окружении, в котором доступны Guile и Guile-SDL.

Отметим, что этот пример явно запрашивает выходы guile и guile-sdl по умолчанию, но возможно запросить специфичный выход, то есть glib:bin запрашивает выход bin из glib (see Пакеты со множественным выходом).

Эта опция может сочетаться с поведением по умолчанию guix environment. Пакеты, которые появляются до --ad-hoc интерпретируются как пакеты, чьи зависимости будут добавлены в окружение (поведение по умолчанию). Пакеты, которые появляются после этой опции, интерпретируются как пакеты, которые будут добавлены в окружение непосредственно.

--pure

Сброс существующих переменных окружения при сборке нового окружения, кроме обозначенных в опции --preserve (смотрите ниже). Эффект этой опции — создание окружения, в котором пути поиска содержат только входные данные пакета.

--preserve=regexp
-E regexp

При использовании вместе с --pure, оставить содержимое переменных окружения, соответствующих выражению regexp — другими словами, включить их в "белый список" переменных окружения, которые не должны обнуляться. Эту опцию можно повторять несколько раз.

guix environment --pure --preserve=^SLURM --ad-hoc openmpi … \
  -- mpirun …

Этот пример запускает mpirun в контексте, в котором определены только следующие переменные окружения: PATH, переменные окружения, чьи имена начинаются с SLURM, а также обычные "дорогие" переменные (HOME, USER, и т.д.)

--search-paths

Отобразить определения переменных окружения, которые составляют окружение.

--system=system
-s system

Попытаться собрать систему system, то есть i686-linux.

--container
-C

Запустить command в изолированном контейнере. Текущая рабочая директория за пределами контейнера отображается внутри контейнера. В дополнение, если это не переопределено опцией --user, тогда настраивается фиктивная домашняя директория, которая совпадает с домашней директорией текущего пользователя, а также соответствующий файл /etc/passwd.

Порождаемый процесс снаружи предстаёт как запущенный от текущего пользователя. Внутри контейнера он имеет такие же UID и GID, что и текущий пользователь, если не обозначена --user (смотрите ниже).

--network
-N

Разделять пространство сетевых имён контейнера с хостящей системой. Контейнеры, созданные без этого флага, могут только иметь доступ к петлевому устройству.

--link-profile
-P

Связать профиль окружения контейнера с ~/.guix-profile внутри контейнера. Это эквивалент запуска команды ln -s $GUIX_ENVIRONMENT ~/.guix-profile внутри контейнера. Связывание завершится ошибкой и отменит создание окружения, если директория уже существует, что, конечно, будет происходить, если guix environment вызвана в домашней директории пользователя.

Определённые пакеты сконфигурированы, чтобы смотреть конфигурационные файлы и данные в ~/.guix-profile;11 --link-profile позволяет этим программам вести себя ожидаемо внутри окружения.

--user=user
-u user

Использовать в контейнере имя пользователя user вместо текущего пользователя. Созданная внутри контейнера запись /etc/passwd будет содержать имя user, домашняя директория будет /home/user, но не будут копированы пользовательские данные GECOS. Более того, внутри контейнера UID и GID будут 1000. user не обязательно должен существовать в системе.

В дополнение, любой разделяемый или расширяемый путь (смотрите --share и --expose соответственно), чьи цели находятся в домашней директории пользователя, будут отображены соответственно в /home/USER; это включает автоматическое отображение текущей рабочей директории.

# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
cd $HOME/wd
guix environment --container --user=foo \
     --expose=$HOME/test \
     --expose=/tmp/target=$HOME/target

Это ограничит утечку данных идентификации пользователя через домашние пути и каждое из полей пользователя. Это один единственный компонент расширенного решения приватности/анонимности — ничто не войдёт, ничто не выйдет.

--expose=source[=target]

Расширить файловую систему контейнера источником source из хостящей системы в качестве файловой системы только для чтения с целью target внутри контейнера. Если цель target не задана, источник source используется как целевая точка монтирования в контейнере.

Пример ниже порождает Guile REPL в контейнере, в котором домашняя директория пользователя доступна только для чтения через директорию /exchange:

guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
--share=source[=target]

Разделять в контейнере файловую систему source хостящей системы как файловую систему, доступную для записи, с целью target внутри контейнера. Если цель target не задана, источник source используется в качестве целевой точки монтирования в контейнере.

Пример ниже порождает Guile REPL в контейнере, в котором домашняя директория пользователя доступна для чтения и записи через директорию /exchange:

guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile

guix environment также поддерживает все обычные опции сборки, которые поддерживает команда guix build (see Стандартные опции сборки), а также опции трансформации пакета (see Опции трансформации пакета).


Previous: , Up: Разработка   [Contents][Index]

5.2 Вызов guix pack

Иногда бывает необходимо передать программу людям, которые (ещё!) не являются счастливыми обладателями Guix. Вы могли бы им рекомендовать заустить guix package -i something, но в данном случае это не подхлдит. Тогда guix pack решает вопрос.

Заметка: Если вы ищете способ обмена бинарниками между машинами, работающими с Guix, see Вызов guix copy, Вызов guix publish и Вызов guix archive.

Команда guix pack создаёт обёрнутый набор или программный набор: она создаёт архив tarball или другой архив, содержащий исполняемые файлы программного обеспечения, которое вас интересует, а также все его зависимости. Результирующий архив может использоваться на любой машине, которая не имеет Guix, а люди могут запустить совершенно такие же бинарники, как у вас в Guix. Набор создаётся со свойством воспроизводимости до бита, так что любой может проверить, что он действительно содержит результаты сборок, которые вы поставляете.

Например, чтобы создать набор, содержащий Guile, Emacs, Geiser и все их зависимости, можно запустить:

$ guix pack guile emacs geiser
…
/gnu/store/…-pack.tar.gz

Результатом будет архив tarball, содержащий директорию /gnu/store со всеми соответствующими пакетами. Результирующий архив содержат профиль с тремя запрошенными пакетами; профиль представляет то же самое, что можно создать командой guix package -i. Это механизм, который используется, собственно, для создания автономного (standalone) бинарного архива Guix (see Бинарная установка).

Пользователи этого пакета должны запускать /gnu/store/…-profile/bin/guile для запуска Guile, что может быть не удобно. Чтобы исправить это, можно создать, например, символическую ссылку /opt/gnu/bin на профиль:

guix pack -S /opt/gnu/bin=bin guile emacs geiser

Так пользователи смогут благополучно напечатать /opt/gnu/bin/guile, и всё хорошо.

Что если получатель вашего пакета не имеет привилегий root на своей машине, и поэтому не может распаковать его в корне файловой системы? В таком случае вам стоит использовать опцию --relocatable (смотрите ниже). Эта опция производит перемещаемые бинарники, в том плане, что они могут размещаться где угодно в иерархии файловой системы: в примере выше пользователи могут распаковать ваш архив в свои домашние директории и напрямую запустить ./opt/gnu/bin/guile.

В качестве альтернативы можно производить пакет в формате образа Docker, используя следующую команду:

guix pack -f docker guile emacs geiser

Результатом будет архив, который можно передать команде docker load. Смотрите документацию Docker для подробной информации.

Ещё одна опция производит образ SquashFS следующей командой:

guix pack -f squashfs guile emacs geiser

The result is a SquashFS file system image that can either be mounted or directly be used as a file system container image with the Singularity container execution environment, using commands like singularity shell or singularity exec.

Несколько опций командной строки позволяют вам переделывать ваш пакет:

--format=format
-f format

Произвести пакет в указанном формате format.

Возможные форматы:

tarball

Это формат по умолчанию. Он производит архив tarball, содержащий все заданные бинарники и символические ссылки.

docker

Это производит архив, соответствующий спецификации образа Docker.

squashfs

This produces a SquashFS image containing all the specified binaries and symlinks, as well as empty mount points for virtual file systems like procfs.

--relocatable
-R

Produce relocatable binaries—i.e., binaries that can be placed anywhere in the file system hierarchy and run from there.

When this option is passed once, the resulting binaries require support for user namespaces in the kernel Linux; when passed twice12, relocatable binaries fall to back to PRoot if user namespaces are unavailable, and essentially work anywhere—see below for the implications.

For example, if you create a pack containing Bash with:

guix pack -RR -S /mybin=bin bash

... you can copy that pack to a machine that lacks Guix, and from your home directory as a normal user, run:

tar xf pack.tar.gz
./mybin/sh

In that shell, if you type ls /gnu/store, you’ll notice that /gnu/store shows up and contains all the dependencies of bash, even though the machine actually lacks /gnu/store altogether! That is probably the simplest way to deploy Guix-built software on a non-Guix machine.

Заметка: By default, relocatable binaries rely on the user namespace feature of the kernel Linux, which allows unprivileged users to mount or change root. Old versions of Linux did not support it, and some GNU/Linux distributions turn it off.

To produce relocatable binaries that work even in the absence of user namespaces, pass --relocatable or -R twice. In that case, binaries will try user namespace support and fall back to PRoot if user namespaces are not supported.

The PRoot program provides the necessary support for file system virtualization. It achieves that by using the ptrace system call on the running program. This approach has the advantage to work without requiring special kernel support, but it incurs run-time overhead every time a system call is made.

--expression=expr
-e expr

Consider the package expr evaluates to.

This has the same purpose as the same-named option in guix build (see --expression in guix build).

--manifest=file
-m file

Use the packages contained in the manifest object returned by the Scheme code in file.

This has a similar purpose as the same-named option in guix package (see --manifest) and uses the same manifest files. It allows you to define a collection of packages once and use it both for creating profiles and for creating archives for use on machines that do not have Guix installed. Note that you can specify either a manifest file or a list of packages, but not both.

--system=system
-s system

Предпринять попытку собрать систему system, т.е. i686-linux, вместо типа системы хоста сборки.

--target=triplet

Cross-build for triplet, which must be a valid GNU triplet, such as "mips64el-linux-gnu" (see GNU configuration triplets in Autoconf).

--compression=tool
-C tool

Compress the resulting tarball using tool—one of gzip, bzip2, xz, lzip, or none for no compression.

--symlink=spec
-S spec

Add the symlinks specified by spec to the pack. This option can appear several times.

spec has the form source=target, where source is the symlink that will be created and target is the symlink target.

For instance, -S /opt/gnu/bin=bin creates a /opt/gnu/bin symlink pointing to the bin sub-directory of the profile.

--save-provenance

Save provenance information for the packages passed on the command line. Provenance information includes the URL and commit of the channels in use (see Каналы).

Provenance information is saved in the /gnu/store/…-profile/manifest file in the pack, along with the usual package metadata—the name and version of each package, their propagated inputs, and so on. It is useful information to the recipient of the pack, who then knows how the pack was (supposedly) obtained.

This option is not enabled by default because, like timestamps, provenance information contributes nothing to the build process. In other words, there is an infinity of channel URLs and commit IDs that can lead to the same pack. Recording such “silent” metadata in the output thus potentially breaks the source-to-binary bitwise reproducibility property.

--localstatedir
--profile-name=name

Include the “local state directory”, /var/guix, in the resulting pack, and notably the /var/guix/profiles/per-user/root/name profile—by default name is guix-profile, which corresponds to ~root/.guix-profile.

/var/guix contains the store database (see Склад) as well as garbage-collector roots (see Вызов guix gc). Providing it in the pack means that the store is “complete” and manageable by Guix; not providing it pack means that the store is “dead”: items cannot be added to it or removed from it after extraction of the pack.

One use case for this is the Guix self-contained binary tarball (see Бинарная установка).

--bootstrap

Use the bootstrap binaries to build the pack. This option is only useful to Guix developers.

In addition, guix pack supports all the common build options (see Стандартные опции сборки) and all the package transformation options (see Опции трансформации пакета).


Next: , Previous: , Up: Top   [Contents][Index]

6 Программный интерфейс

GNU Guix provides several Scheme programming interfaces (APIs) to define, build, and query packages. The first interface allows users to write high-level package definitions. These definitions refer to familiar packaging concepts, such as the name and version of a package, its build system, and its dependencies. These definitions can then be turned into concrete build actions.

Build actions are performed by the Guix daemon, on behalf of users. In a standard setup, the daemon has write access to the store—the /gnu/store directory—whereas users do not. The recommended setup also has the daemon perform builds in chroots, under a specific build users, to minimize interference with the rest of the system.

Lower-level APIs are available to interact with the daemon and the store. To instruct the daemon to perform a build action, users actually provide it with a derivation. A derivation is a low-level representation of the build actions to be taken, and the environment in which they should occur—derivations are to package definitions what assembly is to C programs. The term “derivation” comes from the fact that build results derive from them.

This chapter describes all these APIs in turn, starting from high-level package definitions.


Next: , Up: Программный интерфейс   [Contents][Index]

6.1 Пакетные модули

From a programming viewpoint, the package definitions of the GNU distribution are provided by Guile modules in the (gnu packages …) name space13 (see Guile modules in GNU Guile Reference Manual). For instance, the (gnu packages emacs) module exports a variable named emacs, which is bound to a <package> object (see Описание пакетов).

The (gnu packages …) module name space is automatically scanned for packages by the command-line tools. For instance, when running guix install emacs, all the (gnu packages …) modules are scanned until one that exports a package object whose name is emacs is found. This package search facility is implemented in the (gnu packages) module.

Users can store package definitions in modules with different names—e.g., (my-packages emacs)14. There are two ways to make these package definitions visible to the user interfaces:

  1. By adding the directory containing your package modules to the search path with the -L flag of guix package and other commands (see Стандартные опции сборки), or by setting the GUIX_PACKAGE_PATH environment variable described below.
  2. By defining a channel and configuring guix pull so that it pulls from it. A channel is essentially a Git repository containing package modules. See Каналы, for more information on how to define and use channels.

GUIX_PACKAGE_PATH works similarly to other search path variables:

Environment Variable: GUIX_PACKAGE_PATH

This is a colon-separated list of directories to search for additional package modules. Directories listed in this variable take precedence over the own modules of the distribution.

The distribution is fully bootstrapped and self-contained: each package is built based solely on other packages in the distribution. The root of this dependency graph is a small set of bootstrap binaries, provided by the (gnu packages bootstrap) module. For more information on bootstrapping, see Начальная загрузка.


Next: , Previous: , Up: Программный интерфейс   [Contents][Index]

6.2 Описание пакетов

The high-level interface to package definitions is implemented in the (guix packages) and (guix build-system) modules. As an example, the package definition, or recipe, for the GNU Hello package looks like this:

(define-module (gnu packages hello)
  #:use-module (guix packages)
  #:use-module (guix download)
  #:use-module (guix build-system gnu)
  #:use-module (guix licenses)
  #:use-module (gnu packages gawk))

(define-public hello
  (package
    (name "hello")
    (version "2.10")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
    (build-system gnu-build-system)
    (arguments '(#:configure-flags '("--enable-silent-rules")))
    (inputs `(("gawk" ,gawk)))
    (synopsis "Hello, GNU world: An example GNU package")
    (description "Guess what GNU Hello prints!")
    (home-page "https://www.gnu.org/software/hello/")
    (license gpl3+)))

Without being a Scheme expert, the reader may have guessed the meaning of the various fields here. This expression binds the variable hello to a <package> object, which is essentially a record (see Scheme records in GNU Guile Reference Manual). This package object can be inspected using procedures found in the (guix packages) module; for instance, (package-name hello) returns—surprise!—"hello".

With luck, you may be able to import part or all of the definition of the package you are interested in from another repository, using the guix import command (see Вызов guix import).

In the example above, hello is defined in a module of its own, (gnu packages hello). Technically, this is not strictly necessary, but it is convenient to do so: all the packages defined in modules under (gnu packages …) are automatically known to the command-line tools (see Пакетные модули).

There are a few points worth noting in the above package definition:

See Интерфейс package, for a full description of possible fields.

Once a package definition is in place, the package may actually be built using the guix build command-line tool (see Вызов guix build), troubleshooting any build failures you encounter (see Отладка ошибок сборки). You can easily jump back to the package definition using the guix edit command (see Вызов guix edit). See Принципы опакечивания, for more information on how to test package definitions, and Вызов guix lint, for information on how to check a definition for style conformance. Lastly, see Каналы, for information on how to extend the distribution by adding your own package definitions in a “channel”.

Finally, updating the package definition to a new upstream version can be partly automated by the guix refresh command (see Вызов guix refresh).

Behind the scenes, a derivation corresponding to the <package> object is first computed by the package-derivation procedure. That derivation is stored in a .drv file under /gnu/store. The build actions it prescribes may then be realized by using the build-derivations procedure (see Склад).

Scheme Procedure: package-derivation store package [system]

Return the <derivation> object of package for system (see Деривации).

package must be a valid <package> object, and system must be a string denoting the target system type—e.g., "x86_64-linux" for an x86_64 Linux-based GNU system. store must be a connection to the daemon, which operates on the store (see Склад).

Similarly, it is possible to compute a derivation that cross-builds a package for some other system:

Scheme Procedure: package-cross-derivation store package target [system] Return the <derivation>

object of package cross-built from system to target.

target must be a valid GNU triplet denoting the target hardware and operating system, such as "mips64el-linux-gnu" (see Specifying Target Triplets in Autoconf).

Packages can be manipulated in arbitrary ways. An example of a useful transformation is input rewriting, whereby the dependency tree of a package is rewritten by replacing specific inputs by others:

Scheme Procedure: package-input-rewriting replacements [rewrite-name] Return a procedure that, when passed a package,

replaces its direct and indirect dependencies (but not its implicit inputs) according to replacements. replacements is a list of package pairs; the first element of each pair is the package to replace, and the second one is the replacement.

Optionally, rewrite-name is a one-argument procedure that takes the name of a package and returns its new name after rewrite.

Consider this example:

(define libressl-instead-of-openssl
  ;; This is a procedure to replace OPENSSL by LIBRESSL,
  ;; recursively.
  (package-input-rewriting `((,openssl . ,libressl))))

(define git-with-libressl
  (libressl-instead-of-openssl git))

Here we first define a rewriting procedure that replaces openssl with libressl. Then we use it to define a variant of the git package that uses libressl instead of openssl. This is exactly what the --with-input command-line option does (see --with-input).

The following variant of package-input-rewriting can match packages to be replaced by name rather than by identity.

Scheme Procedure: package-input-rewriting/spec replacements

Return a procedure that, given a package, applies the given replacements to all the package graph (excluding implicit inputs). replacements is a list of spec/procedures pair; each spec is a package specification such as "gcc" or "guile@2", and each procedure takes a matching package and returns a replacement for that package.

The example above could be rewritten this way:

(define libressl-instead-of-openssl
  ;; Replace all the packages called "openssl" with LibreSSL.
  (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))

The key difference here is that, this time, packages are matched by spec and not by identity. In other words, any package in the graph that is called openssl will be replaced.

A more generic procedure to rewrite a package dependency graph is package-mapping: it supports arbitrary changes to nodes in the graph.

Scheme Procedure: package-mapping proc [cut?]

Return a procedure that, given a package, applies proc to all the packages depended on and returns the resulting package. The procedure stops recursion when cut? returns true for a given package.


Next: , Up: Описание пакетов   [Contents][Index]

6.2.1 package Reference

This section summarizes all the options available in package declarations (see Описание пакетов).

Data Type: package

This is the data type representing a package recipe.

name

The name of the package, as a string.

version

The version of the package, as a string.

source

An object telling how the source code for the package should be acquired. Most of the time, this is an origin object, which denotes a file fetched from the Internet (see интерфейс origin). It can also be any other “file-like” object such as a local-file, which denotes a file from the local file system (see local-file).

build-system

The build system that should be used to build the package (see Системы сборки).

arguments (default: '())

The arguments that should be passed to the build system. This is a list, typically containing sequential keyword-value pairs.

inputs (default: '())
native-inputs (default: '())
propagated-inputs (default: '())

These fields list dependencies of the package. Each one is a list of tuples, where each tuple has a label for the input (a string) as its first element, a package, origin, or derivation as its second element, and optionally the name of the output thereof that should be used, which defaults to "out" (see Пакеты со множественным выходом, for more on package outputs). For example, the list below specifies three inputs:

`(("libffi" ,libffi)
  ("libunistring" ,libunistring)
  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib

The distinction between native-inputs and inputs is necessary when considering cross-compilation. When cross-compiling, dependencies listed in inputs are built for the target architecture; conversely, dependencies listed in native-inputs are built for the architecture of the build machine.

native-inputs is typically used to list tools needed at build time, but not at run time, such as Autoconf, Automake, pkg-config, Gettext, or Bison. guix lint can report likely mistakes in this area (see Вызов guix lint).

Lastly, propagated-inputs is similar to inputs, but the specified packages will be automatically installed alongside the package they belong to (see guix package, for information on how guix package deals with propagated inputs.)

For example this is necessary when a C/C++ library needs headers of another library to compile, or when a pkg-config file refers to another one via its Requires field.

Another example where propagated-inputs is useful is for languages that lack a facility to record the run-time search path akin to the RUNPATH of ELF files; this includes Guile, Python, Perl, and more. To ensure that libraries written in those languages can find library code they depend on at run time, run-time dependencies must be listed in propagated-inputs rather than inputs.

outputs (default: '("out"))

The list of output names of the package. See Пакеты со множественным выходом, for typical uses of additional outputs.

native-search-paths (default: '())
search-paths (default: '())

A list of search-path-specification objects describing search-path environment variables honored by the package.

replacement (default: #f)

This must be either #f or a package object that will be used as a replacement for this package. See grafts, for details.

synopsis

A one-line description of the package.

description

A more elaborate description of the package.

license

The license of the package; a value from (guix licenses), or a list of such values.

home-page

The URL to the home-page of the package, as a string.

supported-systems (default: %supported-systems)

The list of systems supported by the package, as strings of the form architecture-kernel, for example "x86_64-linux".

maintainers (default: '())

The list of maintainers of the package, as maintainer objects.

location (default: source location of the package form)

The source location of the package. It is useful to override this when inheriting from another package, in which case this field is not automatically corrected.

Scheme Syntax: this-package

When used in the lexical scope of a package field definition, this identifier resolves to the package being defined.

The example below shows how to add a package as a native input of itself when cross-compiling:

(package
  (name "guile")
  ;; ...

  ;; When cross-compiled, Guile, for example, depends on
  ;; a native version of itself.  Add it here.
  (native-inputs (if (%current-target-system)
                     `(("self" ,this-package))
                     '())))

It is an error to refer to this-package outside a package definition.


Previous: , Up: Описание пакетов   [Contents][Index]

6.2.2 origin Reference

This section summarizes all the options available in origin declarations (see Описание пакетов).

Data Type: origin

This is the data type representing a source code origin.

uri

An object containing the URI of the source. The object type depends on the method (see below). For example, when using the url-fetch method of (guix download), the valid uri values are: a URL represented as a string, or a list thereof.

method

A procedure that handles the URI.

Examples include:

url-fetch from (guix download)

download a file from the HTTP, HTTPS, or FTP URL specified in the uri field;

git-fetch from (guix git-download)

clone the Git version control repository, and check out the revision specified in the uri field as a git-reference object; a git-reference looks like this:

(git-reference
  (url "git://git.debian.org/git/pkg-shadow/shadow")
  (commit "v4.1.5.1"))
sha256

A bytevector containing the SHA-256 hash of the source. Typically the base32 form is used here to generate the bytevector from a base-32 string.

You can obtain this information using guix download (see Вызов guix download) or guix hash (see Вызов guix hash).

file-name (default: #f)

The file name under which the source code should be saved. When this is #f, a sensible default value will be used in most cases. In case the source is fetched from a URL, the file name from the URL will be used. For version control checkouts, it is recommended to provide the file name explicitly because the default is not very descriptive.

patches (default: '())

A list of file names, origins, or file-like objects (see file-like objects) pointing to patches to be applied to the source.

This list of patches must be unconditional. In particular, it cannot depend on the value of %current-system or %current-target-system.

snippet (default: #f)

A G-expression (see G-Expressions) or S-expression that will be run in the source directory. This is a convenient way to modify the source, sometimes more convenient than a patch.

patch-flags (default: '("-p1"))

A list of command-line flags that should be passed to the patch command.

patch-inputs (default: #f)

Input packages or derivations to the patching process. When this is #f, the usual set of inputs necessary for patching are provided, such as GNU Patch.

modules (default: '())

A list of Guile modules that should be loaded during the patching process and while running the code in the snippet field.

patch-guile (default: #f)

The Guile package that should be used in the patching process. When this is #f, a sensible default is used.


Next: , Previous: , Up: Программный интерфейс   [Contents][Index]

6.3 Системы сборки

Each package definition specifies a build system and arguments for that build system (see Описание пакетов). This build-system field represents the build procedure of the package, as well as implicit dependencies of that build procedure.

Build systems are <build-system> objects. The interface to create and manipulate them is provided by the (guix build-system) module, and actual build systems are exported by specific modules.

Under the hood, build systems first compile package objects to bags. A bag is like a package, but with less ornamentation—in other words, a bag is a lower-level representation of a package, which includes all the inputs of that package, including some that were implicitly added by the build system. This intermediate representation is then compiled to a derivation (see Деривации).

Build systems accept an optional list of arguments. In package definitions, these are passed via the arguments field (see Описание пакетов). They are typically keyword arguments (see keyword arguments in Guile in GNU Guile Reference Manual). The value of these arguments is usually evaluated in the build stratum—i.e., by a Guile process launched by the daemon (see Деривации).

The main build system is gnu-build-system, which implements the standard build procedure for GNU and many other packages. It is provided by the (guix build-system gnu) module.

Scheme Variable: gnu-build-system

gnu-build-system represents the GNU Build System, and variants thereof (see configuration and makefile conventions in GNU Coding Standards).

In a nutshell, packages using it are configured, built, and installed with the usual ./configure && make && make check && make install command sequence. In practice, a few additional steps are often needed. All these steps are split up in separate phases, notably15:

unpack

Unpack the source tarball, and change the current directory to the extracted source tree. If the source is actually a directory, copy it to the build tree, and enter that directory.

patch-source-shebangs

Patch shebangs encountered in source files so they refer to the right store file names. For instance, this changes #!/bin/sh to #!/gnu/store/…-bash-4.3/bin/sh.

configure

Run the configure script with a number of default options, such as --prefix=/gnu/store/…, as well as the options specified by the #:configure-flags argument.

build

Run make with the list of flags specified with #:make-flags. If the #:parallel-build? argument is true (the default), build with make -j.

check

Run make check, or some other target specified with #:test-target, unless #:tests? #f is passed. If the #:parallel-tests? argument is true (the default), run make check -j.

install

Run make install with the flags listed in #:make-flags.

patch-shebangs

Patch shebangs on the installed executable files.

strip

Strip debugging symbols from ELF files (unless #:strip-binaries? is false), copying them to the debug output when available (see Установка файлов отладки).

The build-side module (guix build gnu-build-system) defines %standard-phases as the default list of build phases. %standard-phases is a list of symbol/procedure pairs, where the procedure implements the actual phase.

The list of phases used for a particular package can be changed with the #:phases parameter. For instance, passing:

#:phases (modify-phases %standard-phases (delete 'configure))

means that all the phases described above will be used, except the configure phase.

In addition, this build system ensures that the “standard” environment for GNU packages is available. This includes tools such as GCC, libc, Coreutils, Bash, Make, Diffutils, grep, and sed (see the (guix build-system gnu) module for a complete list). We call these the implicit inputs of a package, because package definitions do not have to mention them.

Other <build-system> objects are defined to support other conventions and tools used by free software packages. They inherit most of gnu-build-system, and differ mainly in the set of inputs implicitly added to the build process, and in the list of phases executed. Some of these build systems are listed below.

Scheme Variable: ant-build-system

This variable is exported by (guix build-system ant). It implements the build procedure for Java packages that can be built with Ant build tool.

It adds both ant and the Java Development Kit (JDK) as provided by the icedtea package to the set of inputs. Different packages can be specified with the #:ant and #:jdk parameters, respectively.

When the original package does not provide a suitable Ant build file, the parameter #:jar-name can be used to generate a minimal Ant build file build.xml with tasks to build the specified jar archive. In this case the parameter #:source-dir can be used to specify the source sub-directory, defaulting to “src”.

The #:main-class parameter can be used with the minimal ant buildfile to specify the main class of the resulting jar. This makes the jar file executable. The #:test-include parameter can be used to specify the list of junit tests to run. It defaults to (list "**/*Test.java"). The #:test-exclude can be used to disable some tests. It defaults to (list "**/Abstract*.java"), because abstract classes cannot be run as tests.

The parameter #:build-target can be used to specify the Ant task that should be run during the build phase. By default the “jar” task will be run.

Scheme Variable: android-ndk-build-system

This variable is exported by (guix build-system android-ndk). It implements a build procedure for Android NDK (native development kit) packages using a Guix-specific build process.

The build system assumes that packages install their public interface (header) files to the subdirectory "include" of the "out" output and their libraries to the subdirectory "lib" of the "out" output.

It’s also assumed that the union of all the dependencies of a package has no conflicting files.

For the time being, cross-compilation is not supported - so right now the libraries and header files are assumed to be host tools.

Scheme Variable: asdf-build-system/source
Scheme Variable: asdf-build-system/sbcl
Scheme Variable: asdf-build-system/ecl

These variables, exported by (guix build-system asdf), implement build procedures for Common Lisp packages using “ASDF”. ASDF is a system definition facility for Common Lisp programs and libraries.

The asdf-build-system/source system installs the packages in source form, and can be loaded using any common lisp implementation, via ASDF. The others, such as asdf-build-system/sbcl, install binary systems in the format which a particular implementation understands. These build systems can also be used to produce executable programs, or lisp images which contain a set of packages pre-loaded.

The build system uses naming conventions. For binary packages, the package name should be prefixed with the lisp implementation, such as sbcl- for asdf-build-system/sbcl.

Additionally, the corresponding source package should be labeled using the same convention as python packages (see Модули Python), using the cl- prefix.

For binary packages, each system should be defined as a Guix package. If one package origin contains several systems, package variants can be created in order to build all the systems. Source packages, which use asdf-build-system/source, may contain several systems.

In order to create executable programs and images, the build-side procedures build-program and build-image can be used. They should be called in a build phase after the create-symlinks phase, so that the system which was just built can be used within the resulting image. build-program requires a list of Common Lisp expressions to be passed as the #:entry-program argument.

If the system is not defined within its own .asd file of the same name, then the #:asd-file parameter should be used to specify which file the system is defined in. Furthermore, if the package defines a system for its tests in a separate file, it will be loaded before the tests are run if it is specified by the #:test-asd-file parameter. If it is not set, the files <system>-tests.asd, <system>-test.asd, tests.asd, and test.asd will be tried if they exist.

If for some reason the package must be named in a different way than the naming conventions suggest, the #:asd-system-name parameter can be used to specify the name of the system.

Scheme Variable: cargo-build-system

This variable is exported by (guix build-system cargo). It supports builds of packages using Cargo, the build tool of the Rust programming language.

In its configure phase, this build system replaces dependencies specified in the Cargo.toml file with inputs to the Guix package. The install phase installs the binaries, and it also installs the source code and Cargo.toml file.

Scheme Variable: clojure-build-system

This variable is exported by (guix build-system clojure). It implements a simple build procedure for Clojure packages using plain old compile in Clojure. Cross-compilation is not supported yet.

It adds clojure, icedtea and zip to the set of inputs. Different packages can be specified with the #:clojure, #:jdk and #:zip parameters, respectively.

A list of source directories, test directories and jar names can be specified with the #:source-dirs, #:test-dirs and #:jar-names parameters, respectively. Compile directory and main class can be specified with the #:compile-dir and #:main-class parameters, respectively. Other parameters are documented below.

This build system is an extension of ant-build-system, but with the following phases changed:

build

This phase calls compile in Clojure to compile source files and runs jar to create jars from both source files and compiled files according to the include list and exclude list specified in #:aot-include and #:aot-exclude, respectively. The exclude list has priority over the include list. These lists consist of symbols representing Clojure libraries or the special keyword #:all representing all Clojure libraries found under the source directories. The parameter #:omit-source? decides if source should be included into the jars.

check

This phase runs tests according to the include list and exclude list specified in #:test-include and #:test-exclude, respectively. Their meanings are analogous to that of #:aot-include and #:aot-exclude, except that the special keyword #:all now stands for all Clojure libraries found under the test directories. The parameter #:tests? decides if tests should be run.

install

This phase installs all jars built previously.

Apart from the above, this build system also contains an additional phase:

install-doc

This phase installs all top-level files with base name matching %doc-regex. A different regex can be specified with the #:doc-regex parameter. All files (recursively) inside the documentation directories specified in #:doc-dirs are installed as well.

Scheme Variable: cmake-build-system

This variable is exported by (guix build-system cmake). It implements the build procedure for packages using the CMake build tool.

It automatically adds the cmake package to the set of inputs. Which package is used can be specified with the #:cmake parameter.

The #:configure-flags parameter is taken as a list of flags passed to the cmake command. The #:build-type parameter specifies in abstract terms the flags passed to the compiler; it defaults to "RelWithDebInfo" (short for “release mode with debugging information”), which roughly means that code is compiled with -O2 -g, as is the case for Autoconf-based packages by default.

Scheme Variable: dune-build-system

This variable is exported by (guix build-system dune). It supports builds of packages using Dune, a build tool for the OCaml programming language. It is implemented as an extension of the ocaml-build-system which is described below. As such, the #:ocaml and #:findlib parameters can be passed to this build system.

It automatically adds the dune package to the set of inputs. Which package is used can be specified with the #:dune parameter.

There is no configure phase because dune packages typically don’t need to be configured. The #:build-flags parameter is taken as a list of flags passed to the dune command during the build.

The #:jbuild? parameter can be passed to use the jbuild command instead of the more recent dune command while building a package. Its default value is #f.

The #:package parameter can be passed to specify a package name, which is useful when a package contains multiple packages and you want to build only one of them. This is equivalent to passing the -p argument to dune.

Scheme Variable: go-build-system

This variable is exported by (guix build-system go). It implements a build procedure for Go packages using the standard Go build mechanisms.

The user is expected to provide a value for the key #:import-path and, in some cases, #:unpack-path. The import path corresponds to the file system path expected by the package’s build scripts and any referring packages, and provides a unique way to refer to a Go package. It is typically based on a combination of the package source code’s remote URI and file system hierarchy structure. In some cases, you will need to unpack the package’s source code to a different directory structure than the one indicated by the import path, and #:unpack-path should be used in such cases.

Packages that provide Go libraries should install their source code into the built output. The key #:install-source?, which defaults to #t, controls whether or not the source code is installed. It can be set to #f for packages that only provide executable files.

Scheme Variable: glib-or-gtk-build-system

This variable is exported by (guix build-system glib-or-gtk). It is intended for use with packages making use of GLib or GTK+.

This build system adds the following two phases to the ones defined by gnu-build-system:

glib-or-gtk-wrap

The phase glib-or-gtk-wrap ensures that programs in bin/ are able to find GLib “schemas” and GTK+ modules. This is achieved by wrapping the programs in launch scripts that appropriately set the XDG_DATA_DIRS and GTK_PATH environment variables.

It is possible to exclude specific package outputs from that wrapping process by listing their names in the #:glib-or-gtk-wrap-excluded-outputs parameter. This is useful when an output is known not to contain any GLib or GTK+ binaries, and where wrapping would gratuitously add a dependency of that output on GLib and GTK+.

glib-or-gtk-compile-schemas

The phase glib-or-gtk-compile-schemas makes sure that all GSettings schemas of GLib are compiled. Compilation is performed by the glib-compile-schemas program. It is provided by the package glib:bin which is automatically imported by the build system. The glib package providing glib-compile-schemas can be specified with the #:glib parameter.

Both phases are executed after the install phase.

Scheme Variable: guile-build-system

This build system is for Guile packages that consist exclusively of Scheme code and that are so lean that they don’t even have a makefile, let alone a configure script. It compiles Scheme code using guild compile (see Compilation in GNU Guile Reference Manual) and installs the .scm and .go files in the right place. It also installs documentation.

This build system supports cross-compilation by using the --target option of guild compile.

Packages built with guile-build-system must provide a Guile package in their native-inputs field.

Scheme Variable: minify-build-system

This variable is exported by (guix build-system minify). It implements a minification procedure for simple JavaScript packages.

It adds uglify-js to the set of inputs and uses it to compress all JavaScript files in the src directory. A different minifier package can be specified with the #:uglify-js parameter, but it is expected that the package writes the minified code to the standard output.

When the input JavaScript files are not all located in the src directory, the parameter #:javascript-files can be used to specify a list of file names to feed to the minifier.

Scheme Variable: ocaml-build-system

This variable is exported by (guix build-system ocaml). It implements a build procedure for OCaml packages, which consists of choosing the correct set of commands to run for each package. OCaml packages can expect many different commands to be run. This build system will try some of them.

When the package has a setup.ml file present at the top-level, it will run ocaml setup.ml -configure, ocaml setup.ml -build and ocaml setup.ml -install. The build system will assume that this file was generated by OASIS and will take care of setting the prefix and enabling tests if they are not disabled. You can pass configure and build flags with the #:configure-flags and #:build-flags. The #:test-flags key can be passed to change the set of flags used to enable tests. The #:use-make? key can be used to bypass this system in the build and install phases.

When the package has a configure file, it is assumed that it is a hand-made configure script that requires a different argument format than in the gnu-build-system. You can add more flags with the #:configure-flags key.

When the package has a Makefile file (or #:use-make? is #t), it will be used and more flags can be passed to the build and install phases with the #:make-flags key.

Finally, some packages do not have these files and use a somewhat standard location for its build system. In that case, the build system will run ocaml pkg/pkg.ml or ocaml pkg/build.ml and take care of providing the path to the required findlib module. Additional flags can be passed via the #:build-flags key. Install is taken care of by opam-installer. In this case, the opam package must be added to the native-inputs field of the package definition.

Note that most OCaml packages assume they will be installed in the same directory as OCaml, which is not what we want in guix. In particular, they will install .so files in their module’s directory, which is usually fine because it is in the OCaml compiler directory. In guix though, these libraries cannot be found and we use CAML_LD_LIBRARY_PATH. This variable points to lib/ocaml/site-lib/stubslibs and this is where .so libraries should be installed.

Scheme Variable: python-build-system

This variable is exported by (guix build-system python). It implements the more or less standard build procedure used by Python packages, which consists in running python setup.py build and then python setup.py install --prefix=/gnu/store/….

For packages that install stand-alone Python programs under bin/, it takes care of wrapping these programs so that their PYTHONPATH environment variable points to all the Python libraries they depend on.

Which Python package is used to perform the build can be specified with the #:python parameter. This is a useful way to force a package to be built for a specific version of the Python interpreter, which might be necessary if the package is only compatible with a single interpreter version.

By default guix calls setup.py under control of setuptools, much like pip does. Some packages are not compatible with setuptools (and pip), thus you can disable this by setting the #:use-setuptools parameter to #f.

Scheme Variable: perl-build-system

This variable is exported by (guix build-system perl). It implements the standard build procedure for Perl packages, which either consists in running perl Build.PL --prefix=/gnu/store/…, followed by Build and Build install; or in running perl Makefile.PL PREFIX=/gnu/store/…, followed by make and make install, depending on which of Build.PL or Makefile.PL is present in the package distribution. Preference is given to the former if both Build.PL and Makefile.PL exist in the package distribution. This preference can be reversed by specifying #t for the #:make-maker? parameter.

The initial perl Makefile.PL or perl Build.PL invocation passes flags specified by the #:make-maker-flags or #:module-build-flags parameter, respectively.

Which Perl package is used can be specified with #:perl.

Scheme Variable: r-build-system

This variable is exported by (guix build-system r). It implements the build procedure used by R packages, which essentially is little more than running R CMD INSTALL --library=/gnu/store/… in an environment where R_LIBS_SITE contains the paths to all R package inputs. Tests are run after installation using the R function tools::testInstalledPackage.

Scheme Variable: rakudo-build-system

This variable is exported by (guix build-system rakudo). It implements the build procedure used by Rakudo for Perl6 packages. It installs the package to /gnu/store/…/NAME-VERSION/share/perl6 and installs the binaries, library files and the resources, as well as wrap the files under the bin/ directory. Tests can be skipped by passing #f to the tests? parameter.

Which rakudo package is used can be specified with rakudo. Which perl6-tap-harness package used for the tests can be specified with #:prove6 or removed by passing #f to the with-prove6? parameter. Which perl6-zef package used for tests and installing can be specified with #:zef or removed by passing #f to the with-zef? parameter.

Scheme Variable: texlive-build-system

This variable is exported by (guix build-system texlive). It is used to build TeX packages in batch mode with a specified engine. The build system sets the TEXINPUTS variable to find all TeX source files in the inputs.

By default it runs luatex on all files ending on ins. A different engine and format can be specified with the #:tex-format argument. Different build targets can be specified with the #:build-targets argument, which expects a list of file names. The build system adds only texlive-bin and texlive-latex-base (both from (gnu packages tex) to the inputs. Both can be overridden with the arguments #:texlive-bin and #:texlive-latex-base, respectively.

The #:tex-directory parameter tells the build system where to install the built files under the texmf tree.

Scheme Variable: ruby-build-system

This variable is exported by (guix build-system ruby). It implements the RubyGems build procedure used by Ruby packages, which involves running gem build followed by gem install.

The source field of a package that uses this build system typically references a gem archive, since this is the format that Ruby developers use when releasing their software. The build system unpacks the gem archive, potentially patches the source, runs the test suite, repackages the gem, and installs it. Additionally, directories and tarballs may be referenced to allow building unreleased gems from Git or a traditional source release tarball.

Which Ruby package is used can be specified with the #:ruby parameter. A list of additional flags to be passed to the gem command can be specified with the #:gem-flags parameter.

Scheme Variable: waf-build-system

This variable is exported by (guix build-system waf). It implements a build procedure around the waf script. The common phases—configure, build, and install—are implemented by passing their names as arguments to the waf script.

The waf script is executed by the Python interpreter. Which Python package is used to run the script can be specified with the #:python parameter.

Scheme Variable: scons-build-system

This variable is exported by (guix build-system scons). It implements the build procedure used by the SCons software construction tool. This build system runs scons to build the package, scons test to run tests, and then scons install to install the package.

Additional flags to be passed to scons can be specified with the #:scons-flags parameter. The version of Python used to run SCons can be specified by selecting the appropriate SCons package with the #:scons parameter.

Scheme Variable: haskell-build-system

This variable is exported by (guix build-system haskell). It implements the Cabal build procedure used by Haskell packages, which involves running runhaskell Setup.hs configure --prefix=/gnu/store/… and runhaskell Setup.hs build. Instead of installing the package by running runhaskell Setup.hs install, to avoid trying to register libraries in the read-only compiler store directory, the build system uses runhaskell Setup.hs copy, followed by runhaskell Setup.hs register. In addition, the build system generates the package documentation by running runhaskell Setup.hs haddock, unless #:haddock? #f is passed. Optional Haddock parameters can be passed with the help of the #:haddock-flags parameter. If the file Setup.hs is not found, the build system looks for Setup.lhs instead.

Which Haskell compiler is used can be specified with the #:haskell parameter which defaults to ghc.

Scheme Variable: dub-build-system

This variable is exported by (guix build-system dub). It implements the Dub build procedure used by D packages, which involves running dub build and dub run. Installation is done by copying the files manually.

Which D compiler is used can be specified with the #:ldc parameter which defaults to ldc.

Scheme Variable: emacs-build-system

This variable is exported by (guix build-system emacs). It implements an installation procedure similar to the packaging system of Emacs itself (see Packages in The GNU Emacs Manual).

It first creates the package-autoloads.el file, then it byte compiles all Emacs Lisp files. Differently from the Emacs packaging system, the Info documentation files are moved to the standard documentation directory and the dir file is deleted. Each package is installed in its own directory under share/emacs/site-lisp/guix.d.

Scheme Variable: font-build-system

This variable is exported by (guix build-system font). It implements an installation procedure for font packages where upstream provides pre-compiled TrueType, OpenType, etc. font files that merely need to be copied into place. It copies font files to standard locations in the output directory.

Scheme Variable: meson-build-system

This variable is exported by (guix build-system meson). It implements the build procedure for packages that use Meson as their build system.

It adds both Meson and Ninja to the set of inputs, and they can be changed with the parameters #:meson and #:ninja if needed. The default Meson is meson-for-build, which is special because it doesn’t clear the RUNPATH of binaries and libraries when they are installed.

This build system is an extension of gnu-build-system, but with the following phases changed to some specific for Meson:

configure

The phase runs meson with the flags specified in #:configure-flags. The flag --build-type is always set to plain unless something else is specified in #:build-type.

build

The phase runs ninja to build the package in parallel by default, but this can be changed with #:parallel-build?.

check

The phase runs ninja with the target specified in #:test-target, which is "test" by default.

install

The phase runs ninja install and can not be changed.

Apart from that, the build system also adds the following phases:

fix-runpath

This phase ensures that all binaries can find the libraries they need. It searches for required libraries in subdirectories of the package being built, and adds those to RUNPATH where needed. It also removes references to libraries left over from the build phase by meson-for-build, such as test dependencies, that aren’t actually required for the program to run.

glib-or-gtk-wrap

This phase is the phase provided by glib-or-gtk-build-system, and it is not enabled by default. It can be enabled with #:glib-or-gtk?.

glib-or-gtk-compile-schemas

This phase is the phase provided by glib-or-gtk-build-system, and it is not enabled by default. It can be enabled with #:glib-or-gtk?.

Scheme Variable: linux-module-build-system

linux-module-build-system allows building Linux kernel modules.

This build system is an extension of gnu-build-system, but with the following phases changed:

configure

This phase configures the environment so that the Linux kernel’s Makefile can be used to build the external kernel module.

build

This phase uses the Linux kernel’s Makefile in order to build the external kernel module.

install

This phase uses the Linux kernel’s Makefile in order to install the external kernel module.

It is possible and useful to specify the Linux kernel to use for building the module (in the "arguments" form of a package using the linux-module-build-system, use the key #:linux to specify it).

Lastly, for packages that do not need anything as sophisticated, a “trivial” build system is provided. It is trivial in the sense that it provides basically no support: it does not pull any implicit inputs, and does not have a notion of build phases.

Scheme Variable: trivial-build-system

This variable is exported by (guix build-system trivial).

This build system requires a #:builder argument. This argument must be a Scheme expression that builds the package output(s)—as with build-expression->derivation (see build-expression->derivation).


Next: , Previous: , Up: Программный интерфейс   [Contents][Index]

6.4 Склад

Conceptually, the store is the place where derivations that have been built successfully are stored—by default, /gnu/store. Sub-directories in the store are referred to as store items or sometimes store paths. The store has an associated database that contains information such as the store paths referred to by each store path, and the list of valid store items—results of successful builds. This database resides in localstatedir/guix/db, where localstatedir is the state directory specified via --localstatedir at configure time, usually /var.

The store is always accessed by the daemon on behalf of its clients (see Вызов guix-daemon). To manipulate the store, clients connect to the daemon over a Unix-domain socket, send requests to it, and read the result—these are remote procedure calls, or RPCs.

Заметка: Users must never modify files under /gnu/store directly. This would lead to inconsistencies and break the immutability assumptions of Guix’s functional model (see Введение).

See guix gc --verify, for information on how to check the integrity of the store and attempt recovery from accidental modifications.

The (guix store) module provides procedures to connect to the daemon, and to perform RPCs. These are described below. By default, open-connection, and thus all the guix commands, connect to the local daemon or to the URI specified by the GUIX_DAEMON_SOCKET environment variable.

Environment Variable: GUIX_DAEMON_SOCKET

When set, the value of this variable should be a file name or a URI designating the daemon endpoint. When it is a file name, it denotes a Unix-domain socket to connect to. In addition to file names, the supported URI schemes are:

file
unix

These are for Unix-domain sockets. file:///var/guix/daemon-socket/socket is equivalent to /var/guix/daemon-socket/socket.

guix

These URIs denote connections over TCP/IP, without encryption nor authentication of the remote host. The URI must specify the host name and optionally a port number (by default port 44146 is used):

guix://master.guix.example.org:1234

This setup is suitable on local networks, such as clusters, where only trusted nodes may connect to the build daemon at master.guix.example.org.

The --listen option of guix-daemon can be used to instruct it to listen for TCP connections (see --listen).

ssh

These URIs allow you to connect to a remote daemon over SSH16. A typical URL might look like this:

ssh://charlie@guix.example.org:22

As for guix copy, the usual OpenSSH client configuration files are honored (see Вызов guix copy).

Additional URI schemes may be supported in the future.

Заметка: The ability to connect to remote build daemons is considered experimental as of 1.0.1. Please get in touch with us to share any problems or suggestions you may have (see Содействие).

Scheme Procedure: open-connection [uri] [#:reserve-space? #t]

Connect to the daemon over the Unix-domain socket at uri (a string). When reserve-space? is true, instruct it to reserve a little bit of extra space on the file system so that the garbage collector can still operate should the disk become full. Return a server object.

file defaults to %default-socket-path, which is the normal location given the options that were passed to configure.

Scheme Procedure: close-connection server

Close the connection to server.

Scheme Variable: current-build-output-port

This variable is bound to a SRFI-39 parameter, which refers to the port where build and error logs sent by the daemon should be written.

Procedures that make RPCs all take a server object as their first argument.

Scheme Procedure: valid-path? server path

Return #t when path designates a valid store item and #f otherwise (an invalid item may exist on disk but still be invalid, for instance because it is the result of an aborted or failed build.)

A &store-protocol-error condition is raised if path is not prefixed by the store directory (/gnu/store).

Scheme Procedure: add-text-to-store server name text [references]

Add text under file name in the store, and return its store path. references is the list of store paths referred to by the resulting store path.

Scheme Procedure: build-derivations server derivations

Build derivations (a list of <derivation> objects or derivation paths), and return when the worker is done building them. Return #t on success.

Note that the (guix monads) module provides a monad as well as monadic versions of the above procedures, with the goal of making it more convenient to work with code that accesses the store (see Устройство склада).

This section is currently incomplete.


Next: , Previous: , Up: Программный интерфейс   [Contents][Index]

6.5 Деривации

Low-level build actions and the environment in which they are performed are represented by derivations. A derivation contains the following pieces of information:

Derivations allow clients of the daemon to communicate build actions to the store. They exist in two forms: as an in-memory representation, both on the client- and daemon-side, and as files in the store whose name end in .drv—these files are referred to as derivation paths. Derivations paths can be passed to the build-derivations procedure to perform the build actions they prescribe (see Склад).

Operations such as file downloads and version-control checkouts for which the expected content hash is known in advance are modeled as fixed-output derivations. Unlike regular derivations, the outputs of a fixed-output derivation are independent of its inputs—e.g., a source code download produces the same result regardless of the download method and tools being used.

The outputs of derivations—i.e., the build results—have a set of references, as reported by the references RPC or the guix gc --references command (see Вызов guix gc). References are the set of run-time dependencies of the build results. References are a subset of the inputs of the derivation; this subset is automatically computed by the build daemon by scanning all the files in the outputs.

The (guix derivations) module provides a representation of derivations as Scheme objects, along with procedures to create and otherwise manipulate derivations. The lowest-level primitive to create a derivation is the derivation procedure:

Scheme Procedure: derivation store name builder args [#:outputs '("out")] [#:hash #f] [#:hash-algo #f]  [#:recursive?

#f] [#:inputs ’()] [#:env-vars ’()]  [#:system (%current-system)] [#:references-graphs #f]  [#:allowed-references #f] [#:disallowed-references #f]  [#:leaked-env-vars #f] [#:local-build? #f]  [#:substitutable? #t] [#:properties ’()] Build a derivation with the given arguments, and return the resulting <derivation> object.

When hash and hash-algo are given, a fixed-output derivation is created—i.e., one whose result is known in advance, such as a file download. If, in addition, recursive? is true, then that fixed output may be an executable file or a directory and hash must be the hash of an archive containing this output.

When references-graphs is true, it must be a list of file name/store path pairs. In that case, the reference graph of each store path is exported in the build environment in the corresponding file, in a simple text format.

When allowed-references is true, it must be a list of store items or outputs that the derivation’s output may refer to. Likewise, disallowed-references, if true, must be a list of things the outputs may not refer to.

When leaked-env-vars is true, it must be a list of strings denoting environment variables that are allowed to “leak” from the daemon’s environment to the build environment. This is only applicable to fixed-output derivations—i.e., when hash is true. The main use is to allow variables such as http_proxy to be passed to derivations that download files.

When local-build? is true, declare that the derivation is not a good candidate for offloading and should rather be built locally (see Установка демона разгрузки). This is the case for small derivations where the costs of data transfers would outweigh the benefits.

When substitutable? is false, declare that substitutes of the derivation’s output should not be used (see Подстановки). This is useful, for instance, when building packages that capture details of the host CPU instruction set.

properties must be an association list describing “properties” of the derivation. It is kept as-is, uninterpreted, in the derivation.

Here’s an example with a shell script as its builder, assuming store is an open connection to the daemon, and bash points to a Bash executable in the store:

(use-modules (guix utils)
             (guix store)
             (guix derivations))

(let ((builder   ; add the Bash script to the store
        (add-text-to-store store "my-builder.sh"
                           "echo hello world > $out\n" '())))
  (derivation store "foo"
              bash `("-e" ,builder)
              #:inputs `((,bash) (,builder))
              #:env-vars '(("HOME" . "/homeless"))))
⇒ #<derivation /gnu/store/…-foo.drv => /gnu/store/…-foo>

As can be guessed, this primitive is cumbersome to use directly. A better approach is to write build scripts in Scheme, of course! The best course of action for that is to write the build code as a “G-expression”, and to pass it to gexp->derivation. For more information, see G-Expressions.

Once upon a time, gexp->derivation did not exist and constructing derivations with build code written in Scheme was achieved with build-expression->derivation, documented below. This procedure is now deprecated in favor of the much nicer gexp->derivation.

Scheme Procedure: build-expression->derivation store name exp  [#:system (%current-system)] [#:inputs '()] [#:outputs '("out")] [#:hash #f] [#:hash-algo #f]  [#:recursive? #f]

[#:env-vars ’()] [#:modules ’()]  [#:references-graphs #f] [#:allowed-references #f]  [#:disallowed-references #f]  [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f] Return a derivation that executes Scheme expression exp as a builder for derivation name. inputs must be a list of (name drv-path sub-drv) tuples; when sub-drv is omitted, "out" is assumed. modules is a list of names of Guile modules from the current search path to be copied in the store, compiled, and made available in the load path during the execution of exp—e.g., ((guix build utils) (guix build gnu-build-system)).

exp is evaluated in an environment where %outputs is bound to a list of output/path pairs, and where %build-inputs is bound to a list of string/output-path pairs made from inputs. Optionally, env-vars is a list of string pairs specifying the name and value of environment variables visible to the builder. The builder terminates by passing the result of exp to exit; thus, when exp returns #f, the build is considered to have failed.

exp is built using guile-for-build (a derivation). When guile-for-build is omitted or is #f, the value of the %guile-for-build fluid is used instead.

See the derivation procedure for the meaning of references-graphs, allowed-references, disallowed-references, local-build?, and substitutable?.

Here’s an example of a single-output derivation that creates a directory containing one file:

(let ((builder '(let ((out (assoc-ref %outputs "out")))
                  (mkdir out)    ; create /gnu/store/…-goo
                  (call-with-output-file (string-append out "/test")
                    (lambda (p)
                      (display '(hello guix) p))))))
  (build-expression->derivation store "goo" builder))

⇒ #<derivation /gnu/store/…-goo.drv => …>

Next: , Previous: , Up: Программный интерфейс   [Contents][Index]

6.6 Устройство склада

The procedures that operate on the store described in the previous sections all take an open connection to the build daemon as their first argument. Although the underlying model is functional, they either have side effects or depend on the current state of the store.

The former is inconvenient: the connection to the build daemon has to be carried around in all those functions, making it impossible to compose functions that do not take that parameter with functions that do. The latter can be problematic: since store operations have side effects and/or depend on external state, they have to be properly sequenced.

This is where the (guix monads) module comes in. This module provides a framework for working with monads, and a particularly useful monad for our uses, the store monad. Monads are a construct that allows two things: associating “context” with values (in our case, the context is the store), and building sequences of computations (here computations include accesses to the store). Values in a monad—values that carry this additional context—are called monadic values; procedures that return such values are called monadic procedures.

Consider this “normal” procedure:

(define (sh-symlink store)
  ;; Return a derivation that symlinks the 'bash' executable.
  (let* ((drv (package-derivation store bash))
         (out (derivation->output-path drv))
         (sh  (string-append out "/bin/bash")))
    (build-expression->derivation store "sh"
                                  `(symlink ,sh %output))))

Using (guix monads) and (guix gexp), it may be rewritten as a monadic function:

(define (sh-symlink)
  ;; Same, but return a monadic value.
  (mlet %store-monad ((drv (package->derivation bash)))
    (gexp->derivation "sh"
                      #~(symlink (string-append #$drv "/bin/bash")
                                 #$output))))

There are several things to note in the second version: the store parameter is now implicit and is “threaded” in the calls to the package->derivation and gexp->derivation monadic procedures, and the monadic value returned by package->derivation is bound using mlet instead of plain let.

As it turns out, the call to package->derivation can even be omitted since it will take place implicitly, as we will see later (see G-Expressions):

(define (sh-symlink)
  (gexp->derivation "sh"
                    #~(symlink (string-append #$bash "/bin/bash")
                               #$output)))

Calling the monadic sh-symlink has no effect. As someone once said, “you exit a monad like you exit a building on fire: by running”. So, to exit the monad and get the desired effect, one must use run-with-store:

(run-with-store (open-connection) (sh-symlink))
⇒ /gnu/store/...-sh-symlink

Note that the (guix monad-repl) module extends the Guile REPL with new “meta-commands” to make it easier to deal with monadic procedures: run-in-store, and enter-store-monad. The former is used to “run” a single monadic value through the store:

scheme@(guile-user)> ,run-in-store (package->derivation hello)
$1 = #<derivation /gnu/store/…-hello-2.9.drv => …>

The latter enters a recursive REPL, where all the return values are automatically run through the store:

scheme@(guile-user)> ,enter-store-monad
store-monad@(guile-user) [1]> (package->derivation hello)
$2 = #<derivation /gnu/store/…-hello-2.9.drv => …>
store-monad@(guile-user) [1]> (text-file "foo" "Hello!")
$3 = "/gnu/store/…-foo"
store-monad@(guile-user) [1]> ,q
scheme@(guile-user)>

Note that non-monadic values cannot be returned in the store-monad REPL.

The main syntactic forms to deal with monads in general are provided by the (guix monads) module and are described below.

Scheme Syntax: with-monad monad body ...

Evaluate any >>= or return forms in body as being in monad.

Scheme Syntax: return val

Return a monadic value that encapsulates val.

Scheme Syntax: >>= mval mproc ...

Bind monadic value mval, passing its “contents” to monadic procedures mproc17. There can be one mproc or several of them, as in this example:

(run-with-state
    (with-monad %state-monad
      (>>= (return 1)
           (lambda (x) (return (+ 1 x)))
           (lambda (x) (return (* 2 x)))))
  'some-state)

⇒ 4
⇒ some-state
Scheme Syntax: mlet monad ((var mval) ...) body ...
Scheme Syntax: mlet* monad ((var mval) ...) body ... Bind the variables var to the monadic values

mval in body, which is a sequence of expressions. As with the bind operator, this can be thought of as “unpacking” the raw, non-monadic value “contained” in mval and making var refer to that raw, non-monadic value within the scope of the body. The form (var -> val) binds var to the “normal” value val, as per let. The binding operations occur in sequence from left to right. The last expression of body must be a monadic expression, and its result will become the result of the mlet or mlet* when run in the monad.

mlet* is to mlet what let* is to let (see Local Bindings in GNU Guile Reference Manual).

Scheme System: mbegin monad mexp ...

Bind mexp and the following monadic expressions in sequence, returning the result of the last expression. Every expression in the sequence must be a monadic expression.

This is akin to mlet, except that the return values of the monadic expressions are ignored. In that sense, it is analogous to begin, but applied to monadic expressions.

Scheme System: mwhen condition mexp0 mexp* ...

When condition is true, evaluate the sequence of monadic expressions mexp0..mexp* as in an mbegin. When condition is false, return *unspecified* in the current monad. Every expression in the sequence must be a monadic expression.

Scheme System: munless condition mexp0 mexp* ...

When condition is false, evaluate the sequence of monadic expressions mexp0..mexp* as in an mbegin. When condition is true, return *unspecified* in the current monad. Every expression in the sequence must be a monadic expression.

The (guix monads) module provides the state monad, which allows an additional value—the state—to be threaded through monadic procedure calls.

Scheme Variable: %state-monad

The state monad. Procedures in the state monad can access and change the state that is threaded.

Consider the example below. The square procedure returns a value in the state monad. It returns the square of its argument, but also increments the current state value:

(define (square x)
  (mlet %state-monad ((count (current-state)))
    (mbegin %state-monad
      (set-current-state (+ 1 count))
      (return (* x x)))))

(run-with-state (sequence %state-monad (map square (iota 3))) 0)
⇒ (0 1 4)
⇒ 3

When “run” through %state-monad, we obtain that additional state value, which is the number of square calls.

Monadic Procedure: current-state

Return the current state as a monadic value.

Monadic Procedure: set-current-state value

Set the current state to value and return the previous state as a monadic value.

Monadic Procedure: state-push value

Push value to the current state, which is assumed to be a list, and return the previous state as a monadic value.

Monadic Procedure: state-pop

Pop a value from the current state and return it as a monadic value. The state is assumed to be a list.

Scheme Procedure: run-with-state mval [state]

Run monadic value mval starting with state as the initial state. Return two values: the resulting value, and the resulting state.

The main interface to the store monad, provided by the (guix store) module, is as follows.

Scheme Variable: %store-monad

The store monad—an alias for %state-monad.

Values in the store monad encapsulate accesses to the store. When its effect is needed, a value of the store monad must be “evaluated” by passing it to the run-with-store procedure (see below.)

Scheme Procedure: run-with-store store mval [#:guile-for-build] [#:system (%current-system)]

Run mval, a monadic value in the store monad, in store, an open store connection.

Monadic Procedure: text-file name text [references]

Return as a monadic value the absolute file name in the store of the file containing text, a string. references is a list of store items that the resulting text file refers to; it defaults to the empty list.

Monadic Procedure: binary-file name data [references]

Return as a monadic value the absolute file name in the store of the file containing data, a bytevector. references is a list of store items that the resulting binary file refers to; it defaults to the empty list.

Monadic Procedure: interned-file file [name] [#:recursive? #t] [#:select? (const #t)] Return the name of file once

interned in the store. Use name as its store name, or the basename of file if name is omitted.

When recursive? is true, the contents of file are added recursively; if file designates a flat file and recursive? is true, its contents are added, and its permission bits are kept.

When recursive? is true, call (select? file stat) for each directory entry, where file is the entry’s absolute file name and stat is the result of lstat; exclude entries for which select? does not return true.

The example below adds a file to the store, under two different names:

(run-with-store (open-connection)
  (mlet %store-monad ((a (interned-file "README"))
                      (b (interned-file "README" "LEGU-MIN")))
    (return (list a b))))

⇒ ("/gnu/store/rwm…-README" "/gnu/store/44i…-LEGU-MIN")

The (guix packages) module exports the following package-related monadic procedures:

Monadic Procedure: package-file package [file] [#:system (%current-system)] [#:target #f]  [#:output "out"] Return as a

monadic value in the absolute file name of file within the output directory of package. When file is omitted, return the name of the output directory of package. When target is true, use it as a cross-compilation target triplet.

Monadic Procedure: package->derivation package [system]
Monadic Procedure: package->cross-derivation package target [system] Monadic version of package-derivation and

package-cross-derivation (see Описание пакетов).


Next: , Previous: , Up: Программный интерфейс   [Contents][Index]

6.7 G-Expressions

So we have “derivations”, which represent a sequence of build actions to be performed to produce an item in the store (see Деривации). These build actions are performed when asking the daemon to actually build the derivations; they are run by the daemon in a container (see Вызов guix-daemon).

It should come as no surprise that we like to write these build actions in Scheme. When we do that, we end up with two strata of Scheme code18: the “host code”—code that defines packages, talks to the daemon, etc.—and the “build code”—code that actually performs build actions, such as making directories, invoking make, etc.

To describe a derivation and its build actions, one typically needs to embed build code inside host code. It boils down to manipulating build code as data, and the homoiconicity of Scheme—code has a direct representation as data—comes in handy for that. But we need more than the normal quasiquote mechanism in Scheme to construct build expressions.

The (guix gexp) module implements G-expressions, a form of S-expressions adapted to build expressions. G-expressions, or gexps, consist essentially of three syntactic forms: gexp, ungexp, and ungexp-splicing (or simply: #~, #$, and #$@), which are comparable to quasiquote, unquote, and unquote-splicing, respectively (see quasiquote in GNU Guile Reference Manual). However, there are major differences:

This mechanism is not limited to package and derivation objects: compilers able to “lower” other high-level objects to derivations or files in the store can be defined, such that these objects can also be inserted into gexps. For example, a useful type of high-level objects that can be inserted in a gexp is “file-like objects”, which make it easy to add files to the store and to refer to them in derivations and such (see local-file and plain-file below.)

To illustrate the idea, here is an example of a gexp:

(define build-exp
  #~(begin
      (mkdir #$output)
      (chdir #$output)
      (symlink (string-append #$coreutils "/bin/ls")
               "list-files")))

This gexp can be passed to gexp->derivation; we obtain a derivation that builds a directory containing exactly one symlink to /gnu/store/…-coreutils-8.22/bin/ls:

(gexp->derivation "the-thing" build-exp)

As one would expect, the "/gnu/store/…-coreutils-8.22" string is substituted to the reference to the coreutils package in the actual build code, and coreutils is automatically made an input to the derivation. Likewise, #$output (equivalent to (ungexp output)) is replaced by a string containing the directory name of the output of the derivation.

In a cross-compilation context, it is useful to distinguish between references to the native build of a package—that can run on the host—versus references to cross builds of a package. To that end, the #+ plays the same role as #$, but is a reference to a native package build:

(gexp->derivation "vi"
   #~(begin
       (mkdir #$output)
       (system* (string-append #+coreutils "/bin/ln")
                "-s"
                (string-append #$emacs "/bin/emacs")
                (string-append #$output "/bin/vi")))
   #:target "mips64el-linux-gnu")

In the example above, the native build of coreutils is used, so that ln can actually run on the host; but then the cross-compiled build of emacs is referenced.

Another gexp feature is imported modules: sometimes you want to be able to use certain Guile modules from the “host environment” in the gexp, so those modules should be imported in the “build environment”. The with-imported-modules form allows you to express that:

(let ((build (with-imported-modules '((guix build utils))
               #~(begin
                   (use-modules (guix build utils))
                   (mkdir-p (string-append #$output "/bin"))))))
  (gexp->derivation "empty-dir"
                    #~(begin
                        #$build
                        (display "success!\n")
                        #t)))

In this example, the (guix build utils) module is automatically pulled into the isolated build environment of our gexp, such that (use-modules (guix build utils)) works as expected.

Usually you want the closure of the module to be imported—i.e., the module itself and all the modules it depends on—rather than just the module; failing to do that, attempts to use the module will fail because of missing dependent modules. The source-module-closure procedure computes the closure of a module by looking at its source file headers, which comes in handy in this case:

(use-modules (guix modules))   ;for 'source-module-closure'

(with-imported-modules (source-module-closure
                         '((guix build utils)
                           (gnu build vm)))
  (gexp->derivation "something-with-vms"
                    #~(begin
                        (use-modules (guix build utils)
                                     (gnu build vm))
                        …)))

In the same vein, sometimes you want to import not just pure-Scheme modules, but also “extensions” such as Guile bindings to C libraries or other “full-blown” packages. Say you need the guile-json package available on the build side, here’s how you would do it:

(use-modules (gnu packages guile))  ;for 'guile-json'

(with-extensions (list guile-json)
  (gexp->derivation "something-with-json"
                    #~(begin
                        (use-modules (json))
                        …)))

The syntactic form to construct gexps is summarized below.

Scheme Syntax: #~exp
Scheme Syntax: (gexp exp)

Return a G-expression containing exp. exp may contain one or more of the following forms:

#$obj
(ungexp obj)

Introduce a reference to obj. obj may have one of the supported types, for example a package or a derivation, in which case the ungexp form is replaced by its output file name—e.g., "/gnu/store/…-coreutils-8.22.

If obj is a list, it is traversed and references to supported objects are substituted similarly.

If obj is another gexp, its contents are inserted and its dependencies are added to those of the containing gexp.

If obj is another kind of object, it is inserted as is.

#$obj:output
(ungexp obj output)

This is like the form above, but referring explicitly to the output of obj—this is useful when obj produces multiple outputs (see Пакеты со множественным выходом).

#+obj
#+obj:output
(ungexp-native obj)
(ungexp-native obj output)

Same as ungexp, but produces a reference to the native build of obj when used in a cross compilation context.

#$output[:output]
(ungexp output [output])

Insert a reference to derivation output output, or to the main output when output is omitted.

This only makes sense for gexps passed to gexp->derivation.

#$@lst
(ungexp-splicing lst)

Like the above, but splices the contents of lst inside the containing list.

#+@lst
(ungexp-native-splicing lst)

Like the above, but refers to native builds of the objects listed in lst.

G-expressions created by gexp or #~ are run-time objects of the gexp? type (see below.)

Scheme Syntax: with-imported-modules modules body

Mark the gexps defined in body… as requiring modules in their execution environment.

Each item in modules can be the name of a module, such as (guix build utils), or it can be a module name, followed by an arrow, followed by a file-like object:

`((guix build utils)
  (guix gcrypt)
  ((guix config) => ,(scheme-file "config.scm"
                                  #~(define-module …))))

In the example above, the first two modules are taken from the search path, and the last one is created from the given file-like object.

This form has lexical scope: it has an effect on the gexps directly defined in body…, but not on those defined, say, in procedures called from body….

Scheme Syntax: with-extensions extensions body

Mark the gexps defined in body… as requiring extensions in their build and execution environment. extensions is typically a list of package objects such as those defined in the (gnu packages guile) module.

Concretely, the packages listed in extensions are added to the load path while compiling imported modules in body…; they are also added to the load path of the gexp returned by body….

Scheme Procedure: gexp? obj

Return #t if obj is a G-expression.

G-expressions are meant to be written to disk, either as code building some derivation, or as plain files in the store. The monadic procedures below allow you to do that (see Устройство склада, for more information about monads.)

Monadic Procedure: gexp->derivation name exp [#:system (%current-system)] [#:target #f] [#:graft? #t]  [#:hash #f]

[#:hash-algo #f]  [#:recursive? #f] [#:env-vars ’()] [#:modules ’()]  [#:module-path %load-path]  [#:effective-version "2.2"]  [#:references-graphs #f] [#:allowed-references #f]  [#:disallowed-references #f]  [#:leaked-env-vars #f]  [#:script-name (string-append name "-builder")]  [#:deprecation-warnings #f]  [#:local-build? #f] [#:substitutable? #t]  [#:properties ’()] [#:guile-for-build #f] Return a derivation name that runs exp (a gexp) with guile-for-build (a derivation) on system; exp is stored in a file called script-name. When target is true, it is used as the cross-compilation target triplet for packages referred to by exp.

modules is deprecated in favor of with-imported-modules. Its meaning is to make modules available in the evaluation context of exp; modules is a list of names of Guile modules searched in module-path to be copied in the store, compiled, and made available in the load path during the execution of exp—e.g., ((guix build utils) (guix build gnu-build-system)).

effective-version determines the string to use when adding extensions of exp (see with-extensions) to the search path—e.g., "2.2".

graft? determines whether packages referred to by exp should be grafted when applicable.

When references-graphs is true, it must be a list of tuples of one of the following forms:

(file-name package)
(file-name package output)
(file-name derivation)
(file-name derivation output)
(file-name store-item)

The right-hand-side of each element of references-graphs is automatically made an input of the build process of exp. In the build environment, each file-name contains the reference graph of the corresponding item, in a simple text format.

allowed-references must be either #f or a list of output names and packages. In the latter case, the list denotes store items that the result is allowed to refer to. Any reference to another store item will lead to a build error. Similarly for disallowed-references, which can list items that must not be referenced by the outputs.

deprecation-warnings determines whether to show deprecation warnings while compiling modules. It can be #f, #t, or 'detailed.

The other arguments are as for derivation (see Деривации).

The local-file, plain-file, computed-file, program-file, and scheme-file procedures below return file-like objects. That is, when unquoted in a G-expression, these objects lead to a file in the store. Consider this G-expression:

#~(system* #$(file-append glibc "/sbin/nscd") "-f"
           #$(local-file "/tmp/my-nscd.conf"))

The effect here is to “intern” /tmp/my-nscd.conf by copying it to the store. Once expanded, for instance via gexp->derivation, the G-expression refers to that copy under /gnu/store; thus, modifying or removing the file in /tmp does not have any effect on what the G-expression does. plain-file can be used similarly; it differs in that the file content is directly passed as a string.

Scheme Procedure: local-file file [name] [#:recursive? #f] [#:select? (const #t)] Return an object representing local

file file to add to the store; this object can be used in a gexp. If file is a relative file name, it is looked up relative to the source file where this form appears. file will be added to the store under name–by default the base name of file.

When recursive? is true, the contents of file are added recursively; if file designates a flat file and recursive? is true, its contents are added, and its permission bits are kept.

When recursive? is true, call (select? file stat) for each directory entry, where file is the entry’s absolute file name and stat is the result of lstat; exclude entries for which select? does not return true.

This is the declarative counterpart of the interned-file monadic procedure (see interned-file).

Scheme Procedure: plain-file name content

Return an object representing a text file called name with the given content (a string or a bytevector) to be added to the store.

This is the declarative counterpart of text-file.

Scheme Procedure: computed-file name gexp [#:options '(#:local-build? #t)] Return an object representing the store

item name, a file or directory computed by gexp. options is a list of additional arguments to pass to gexp->derivation.

This is the declarative counterpart of gexp->derivation.

Monadic Procedure: gexp->script name exp [#:guile (default-guile)] [#:module-path %load-path] Return an executable

script name that runs exp using guile, with exp’s imported modules in its search path. Look up exp’s modules in module-path.

The example below builds a script that simply invokes the ls command:

(use-modules (guix gexp) (gnu packages base))

(gexp->script "list-files"
              #~(execl #$(file-append coreutils "/bin/ls")
                       "ls"))

When “running” it through the store (see run-with-store), we obtain a derivation that produces an executable file /gnu/store/…-list-files along these lines:

#!/gnu/store/…-guile-2.0.11/bin/guile -ds
!#
(execl "/gnu/store/…-coreutils-8.22"/bin/ls" "ls")
Scheme Procedure: program-file name exp [#:guile #f] [#:module-path %load-path] Return an object representing the

executable store item name that runs gexp. guile is the Guile package used to execute that script. Imported modules of gexp are looked up in module-path.

This is the declarative counterpart of gexp->script.

Monadic Procedure: gexp->file name exp [#:set-load-path? #t] [#:module-path %load-path]  [#:splice? #f]  [#:guile

(default-guile)] Return a derivation that builds a file name containing exp. When splice? is true, exp is considered to be a list of expressions that will be spliced in the resulting file.

When set-load-path? is true, emit code in the resulting file to set %load-path and %load-compiled-path to honor exp’s imported modules. Look up exp’s modules in module-path.

The resulting file holds references to all the dependencies of exp or a subset thereof.

Scheme Procedure: scheme-file name exp [#:splice? #f]

Return an object representing the Scheme file name that contains exp.

This is the declarative counterpart of gexp->file.

Monadic Procedure: text-file* name text

Return as a monadic value a derivation that builds a text file containing all of text. text may list, in addition to strings, objects of any type that can be used in a gexp: packages, derivations, local file objects, etc. The resulting store file holds references to all these.

This variant should be preferred over text-file anytime the file to create will reference items from the store. This is typically the case when building a configuration file that embeds store file names, like this:

(define (profile.sh)
  ;; Return the name of a shell script in the store that
  ;; initializes the 'PATH' environment variable.
  (text-file* "profile.sh"
              "export PATH=" coreutils "/bin:"
              grep "/bin:" sed "/bin\n"))

In this example, the resulting /gnu/store/…-profile.sh file will reference coreutils, grep, and sed, thereby preventing them from being garbage-collected during its lifetime.

Scheme Procedure: mixed-text-file name text

Return an object representing store file name containing text. text is a sequence of strings and file-like objects, as in:

(mixed-text-file "profile"
                 "export PATH=" coreutils "/bin:" grep "/bin")

This is the declarative counterpart of text-file*.

Scheme Procedure: file-union name files

Return a <computed-file> that builds a directory containing all of files. Each item in files must be a two-element list where the first element is the file name to use in the new directory, and the second element is a gexp denoting the target file. Here’s an example:

(file-union "etc"
            `(("hosts" ,(plain-file "hosts"
                                    "127.0.0.1 localhost"))
              ("bashrc" ,(plain-file "bashrc"
                                     "alias ls='ls --color=auto'"))))

This yields an etc directory containing these two files.

Scheme Procedure: directory-union name things

Return a directory that is the union of things, where things is a list of file-like objects denoting directories. For example:

(directory-union "guile+emacs" (list guile emacs))

yields a directory that is the union of the guile and emacs packages.

Scheme Procedure: file-append obj suffix

Return a file-like object that expands to the concatenation of obj and suffix, where obj is a lowerable object and each suffix is a string.

As an example, consider this gexp:

(gexp->script "run-uname"
              #~(system* #$(file-append coreutils
                                        "/bin/uname")))

The same effect could be achieved with:

(gexp->script "run-uname"
              #~(system* (string-append #$coreutils
                                        "/bin/uname")))

There is one difference though: in the file-append case, the resulting script contains the absolute file name as a string, whereas in the second case, the resulting script contains a (string-append …) expression to construct the file name at run time.

Of course, in addition to gexps embedded in “host” code, there are also modules containing build tools. To make it clear that they are meant to be used in the build stratum, these modules are kept in the (guix build …) name space.

Internally, high-level objects are lowered, using their compiler, to either derivations or store items. For instance, lowering a package yields a derivation, and lowering a plain-file yields a store item. This is achieved using the lower-object monadic procedure.

Monadic Procedure: lower-object obj [system] [#:target #f] Return as a value in %store-monad the derivation or

store item corresponding to obj for system, cross-compiling for target if target is true. obj must be an object that has an associated gexp compiler, such as a <package>.


Previous: , Up: Программный интерфейс   [Contents][Index]

6.8 Invoking guix repl

The guix repl command spawns a Guile read-eval-print loop (REPL) for interactive programming (see Using Guile Interactively in GNU Guile Reference Manual). Compared to just launching the guile command, guix repl guarantees that all the Guix modules and all its dependencies are available in the search path. You can use it this way:

$ guix repl
scheme@(guile-user)> ,use (gnu packages base)
scheme@(guile-user)> coreutils
$1 = #<package coreutils@8.29 gnu/packages/base.scm:327 3e28300>

In addition, guix repl implements a simple machine-readable REPL protocol for use by (guix inferior), a facility to interact with inferiors, separate processes running a potentially different revision of Guix.

The available options are as follows:

--type=type
-t type

Start a REPL of the given TYPE, which can be one of the following:

guile

This is default, and it spawns a standard full-featured Guile REPL.

machine

Spawn a REPL that uses the machine-readable protocol. This is the protocol that the (guix inferior) module speaks.

--listen=endpoint

By default, guix repl reads from standard input and writes to standard output. When this option is passed, it will instead listen for connections on endpoint. Here are examples of valid options:

--listen=tcp:37146

Accept connections on localhost on port 37146.

--listen=unix:/tmp/socket

Accept connections on the Unix-domain socket /tmp/socket.


Next: , Previous: , Up: Top   [Contents][Index]

7 Утилиты

This section describes Guix command-line utilities. Some of them are primarily targeted at developers and users who write new package definitions, while others are more generally useful. They complement the Scheme programming interface of Guix in a convenient way.


Next: , Up: Утилиты   [Contents][Index]

7.1 Вызов guix build

The guix build command builds packages or derivations and their dependencies, and prints the resulting store paths. Note that it does not modify the user’s profile—this is the job of the guix package command (see Вызов guix package). Thus, it is mainly useful for distribution developers.

Основной синтаксис:

guix build options package-or-derivation

As an example, the following command builds the latest versions of Emacs and of Guile, displays their build logs, and finally displays the resulting directories:

guix build emacs guile

Similarly, the following command builds all the available packages:

guix build --quiet --keep-going \
  `guix package -A | cut -f1,2 --output-delimiter=@`

package-or-derivation may be either the name of a package found in the software distribution such as coreutils or coreutils@8.20, or a derivation such as /gnu/store/…-coreutils-8.19.drv. In the former case, a package with the corresponding name (and optionally version) is searched for among the GNU distribution modules (see Пакетные модули).

Alternatively, the --expression option may be used to specify a Scheme expression that evaluates to a package; this is useful when disambiguating among several same-named packages or package variants is needed.

There may be zero or more options. The available options are described in the subsections below.


Next: , Up: Вызов guix build   [Contents][Index]

7.1.1 Стандартные опции сборки

A number of options that control the build process are common to guix build and other commands that can spawn builds, such as guix package or guix archive. These are the following:

--load-path=directory
-L directory

Add directory to the front of the package module search path (see Пакетные модули).

This allows users to define their own packages and make them visible to the command-line tools.

--keep-failed
-K

Keep the build tree of failed builds. Thus, if a build fails, its build tree is kept under /tmp, in a directory whose name is shown at the end of the build log. This is useful when debugging build issues. See Отладка ошибок сборки, for tips and tricks on how to debug build issues.

This option has no effect when connecting to a remote daemon with a guix:// URI (see the GUIX_DAEMON_SOCKET variable).

--keep-going
-k

Keep going when some of the derivations fail to build; return only once all the builds have either completed or failed.

The default behavior is to stop as soon as one of the specified derivations has failed.

--dry-run
-n

Do not build the derivations.

--fallback

When substituting a pre-built binary fails, fall back to building packages locally (see Ошибки при подстановке).

--substitute-urls=urls

Consider urls the whitespace-separated list of substitute source URLs, overriding the default list of URLs of guix-daemon (see guix-daemon URLs).

This means that substitutes may be downloaded from urls, provided they are signed by a key authorized by the system administrator (see Подстановки).

When urls is the empty string, substitutes are effectively disabled.

--no-substitutes

Не использовать подстановки для сборок. Это означает — собирать элементы локально вместо того, чтобы скачивать собранные бинарники (see Подстановки).

--no-grafts

Do not “graft” packages. In practice, this means that package updates available as grafts are not applied. See Обновления безопасности, for more information on grafts.

--rounds=n

Build each derivation n times in a row, and raise an error if consecutive build results are not bit-for-bit identical.

This is a useful way to detect non-deterministic builds processes. Non-deterministic build processes are a problem because they make it practically impossible for users to verify whether third-party binaries are genuine. See Вызов guix challenge, for more.

Note that, currently, the differing build results are not kept around, so you will have to manually investigate in case of an error—e.g., by stashing one of the build results with guix archive --export (see Вызов guix archive), then rebuilding, and finally comparing the two results.

--no-build-hook

Do not attempt to offload builds via the “build hook” of the daemon (see Установка демона разгрузки). That is, always build things locally instead of offloading builds to remote machines.

--max-silent-time=seconds

Когда процесс сборки или подстановки молчит более seconds секунд, завершить его и отчитаться об ошибке сборки.

By default, the daemon’s setting is honored (see --max-silent-time).

--timeout=seconds

Точно так же, когда процесс сборки или подстановки длится более seconds, завершить его и отчитаться об ошибке сборки.

By default, the daemon’s setting is honored (see --timeout).

-v level
--verbosity=level

Use the given verbosity level, an integer. Choosing 0 means that no output is produced, 1 is for quiet output, and 2 shows all the build log output on standard error.

--cores=n
-c n

Allow the use of up to n CPU cores for the build. The special value 0 means to use as many CPU cores as available.

--max-jobs=n
-M n

Allow at most n build jobs in parallel. See --max-jobs, for details about this option and the equivalent guix-daemon option.

--debug=level

Produce debugging output coming from the build daemon. level must be an integer between 0 and 5; higher means more verbose output. Setting a level of 4 or more may be helpful when debugging setup issues with the build daemon.

Behind the scenes, guix build is essentially an interface to the package-derivation procedure of the (guix packages) module, and to the build-derivations procedure of the (guix derivations) module.

In addition to options explicitly passed on the command line, guix build and other guix commands that support building honor the GUIX_BUILD_OPTIONS environment variable.

Environment Variable: GUIX_BUILD_OPTIONS

Users can define this variable to a list of command line options that will automatically be used by guix build and other guix commands that can perform builds, as in the example below:

$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"

These options are parsed independently, and the result is appended to the parsed command-line options.


Next: , Previous: , Up: Вызов guix build   [Contents][Index]

7.1.2 Опции трансформации пакета

Another set of command-line options supported by guix build and also guix package are package transformation options. These are options that make it possible to define package variants—for instance, packages built from different source code. This is a convenient way to create customized packages on the fly without having to type in the definitions of package variants (see Описание пакетов).

--with-source=source
--with-source=package=source
--with-source=package@version=source

Use source as the source of package, and version as its version number. source must be a file name or a URL, as for guix download (see Вызов guix download).

When package is omitted, it is taken to be the package name specified on the command line that matches the base of source—e.g., if source is /src/guile-2.0.10.tar.gz, the corresponding package is guile.

Likewise, when version is omitted, the version string is inferred from source; in the previous example, it is 2.0.10.

This option allows users to try out versions of packages other than the one provided by the distribution. The example below downloads ed-1.7.tar.gz from a GNU mirror and uses that as the source for the ed package:

guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz

As a developer, --with-source makes it easy to test release candidates:

guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz

… or to build from a checkout in a pristine environment:

$ git clone git://git.sv.gnu.org/guix.git
$ guix build guix --with-source=guix@1.0=./guix
--with-input=package=replacement

Replace dependency on package by a dependency on replacement. package must be a package name, and replacement must be a package specification such as guile or guile@1.8.

For instance, the following command builds Guix, but replaces its dependency on the current stable version of Guile with a dependency on the legacy version of Guile, guile@2.0:

guix build --with-input=guile=guile@2.0 guix

This is a recursive, deep replacement. So in this example, both guix and its dependency guile-json (which also depends on guile) get rebuilt against guile@2.0.

This is implemented using the package-input-rewriting Scheme procedure (see package-input-rewriting).

--with-graft=package=replacement

This is similar to --with-input but with an important difference: instead of rebuilding the whole dependency chain, replacement is built and then grafted onto the binaries that were initially referring to package. See Обновления безопасности, for more information on grafts.

For example, the command below grafts version 3.5.4 of GnuTLS onto Wget and all its dependencies, replacing references to the version of GnuTLS they currently refer to:

guix build --with-graft=gnutls=gnutls@3.5.4 wget

This has the advantage of being much faster than rebuilding everything. But there is a caveat: it works if and only if package and replacement are strictly compatible—for example, if they provide a library, the application binary interface (ABI) of those libraries must be compatible. If replacement is somehow incompatible with package, then the resulting package may be unusable. Use with care!

--with-git-url=package=url

Build package from the latest commit of the master branch of the Git repository at url. Git sub-modules of the repository are fetched, recursively.

For example, the following command builds the NumPy Python library against the latest commit of the master branch of Python itself:

guix build python-numpy \
  --with-git-url=python=https://github.com/python/cpython

This option can also be combined with --with-branch or --with-commit (see below).

Obviously, since it uses the latest commit of the given branch, the result of such a command varies over time. Nevertheless it is a convenient way to rebuild entire software stacks against the latest commit of one or more packages. This is particularly useful in the context of continuous integration (CI).

Checkouts are kept in a cache under ~/.cache/guix/checkouts to speed up consecutive accesses to the same repository. You may want to clean it up once in a while to save disk space.

--with-branch=package=branch

Build package from the latest commit of branch. If the source field of package is an origin with the git-fetch method (see интерфейс origin) or a git-checkout object, the repository URL is taken from that source. Otherwise you have to use --with-git-url to specify the URL of the Git repository.

For instance, the following command builds guile-sqlite3 from the latest commit of its master branch, and then builds guix (which depends on it) and cuirass (which depends on guix) against this specific guile-sqlite3 build:

guix build --with-branch=guile-sqlite3=master cuirass
--with-commit=package=commit

This is similar to --with-branch, except that it builds from commit rather than the tip of a branch. commit must be a valid Git commit SHA1 identifier.


Next: , Previous: , Up: Вызов guix build   [Contents][Index]

7.1.3 Дополительные опции сборки

The command-line options presented below are specific to guix build.

--quiet
-q

Build quietly, without displaying the build log; this is equivalent to --verbosity=0. Upon completion, the build log is kept in /var (or similar) and can always be retrieved using the --log-file option.

--file=file
-f file

Build the package, derivation, or other file-like object that the code within file evaluates to (see file-like objects).

As an example, file might contain a package definition like this (see Описание пакетов):

(use-modules (guix)
             (guix build-system gnu)
             (guix licenses))

(package
  (name "hello")
  (version "2.10")
  (source (origin
            (method url-fetch)
            (uri (string-append "mirror://gnu/hello/hello-" version
                                ".tar.gz"))
            (sha256
             (base32
              "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  (build-system gnu-build-system)
  (synopsis "Hello, GNU world: An example GNU package")
  (description "Guess what GNU Hello prints!")
  (home-page "http://www.gnu.org/software/hello/")
  (license gpl3+))
--expression=expr
-e expr

Build the package or derivation expr evaluates to.

For example, expr may be (@ (gnu packages guile) guile-1.8), which unambiguously designates this specific variant of version 1.8 of Guile.

Alternatively, expr may be a G-expression, in which case it is used as a build program passed to gexp->derivation (see G-Expressions).

Lastly, expr may refer to a zero-argument monadic procedure (see Устройство склада). The procedure must return a derivation as a monadic value, which is then passed through run-with-store.

--source
-S

Build the source derivations of the packages, rather than the packages themselves.

For instance, guix build -S gcc returns something like /gnu/store/…-gcc-4.7.2.tar.bz2, which is the GCC source tarball.

The returned source tarball is the result of applying any patches and code snippets specified in the package origin (see Описание пакетов).

--sources

Fetch and return the source of package-or-derivation and all their dependencies, recursively. This is a handy way to obtain a local copy of all the source code needed to build packages, allowing you to eventually build them even without network access. It is an extension of the --source option and can accept one of the following optional argument values:

package

This value causes the --sources option to behave in the same way as the --source option.

all

Build the source derivations of all packages, including any source that might be listed as inputs. This is the default value.

$ guix build --sources tzdata
The following derivations will be built:
   /gnu/store/…-tzdata2015b.tar.gz.drv
   /gnu/store/…-tzcode2015b.tar.gz.drv
transitive

Build the source derivations of all packages, as well of all transitive inputs to the packages. This can be used e.g. to prefetch package source for later offline building.

$ guix build --sources=transitive tzdata
The following derivations will be built:
   /gnu/store/…-tzcode2015b.tar.gz.drv
   /gnu/store/…-findutils-4.4.2.tar.xz.drv
   /gnu/store/…-grep-2.21.tar.xz.drv
   /gnu/store/…-coreutils-8.23.tar.xz.drv
   /gnu/store/…-make-4.1.tar.xz.drv
   /gnu/store/…-bash-4.3.tar.xz.drv
…
--system=system
-s system

Attempt to build for system—e.g., i686-linux—instead of the system type of the build host. The guix build command allows you to repeat this option several times, in which case it builds for all the specified systems; other commands ignore extraneous -s options.

Заметка: The --system flag is for native compilation and must not be confused with cross-compilation. See --target below for information on cross-compilation.

An example use of this is on Linux-based systems, which can emulate different personalities. For instance, passing --system=i686-linux on an x86_64-linux system or --system=armhf-linux on an aarch64-linux system allows you to build packages in a complete 32-bit environment.

Заметка: Building for an armhf-linux system is unconditionally enabled on aarch64-linux machines, although certain aarch64 chipsets do not allow for this functionality, notably the ThunderX.

Similarly, when transparent emulation with QEMU and binfmt_misc is enabled (see qemu-binfmt-service-type), you can build for any system for which a QEMU binfmt_misc handler is installed.

Builds for a system other than that of the machine you are using can also be offloaded to a remote machine of the right architecture. See Установка демона разгрузки, for more information on offloading.

--target=triplet

Cross-build for triplet, which must be a valid GNU triplet, such as "mips64el-linux-gnu" (see GNU configuration triplets in Autoconf).

--check

Rebuild package-or-derivation, which are already available in the store, and raise an error if the build results are not bit-for-bit identical.

This mechanism allows you to check whether previously installed substitutes are genuine (see Подстановки), or whether the build result of a package is deterministic. See Вызов guix challenge, for more background information and tools.

При использовании вместе с --keep-failed различные результаты сохраняются на складе под /gnu/store/…-check. Это делает возможным просмотр различий между двумя результатами.

--repair

Attempt to repair the specified store items, if they are corrupt, by re-downloading or rebuilding them.

This operation is not atomic and thus restricted to root.

--derivations
-d

Return the derivation paths, not the output paths, of the given packages.

--root=file
-r file

Make file a symlink to the result, and register it as a garbage collector root.

Consequently, the results of this guix build invocation are protected from garbage collection until file is removed. When that option is omitted, build results are eligible for garbage collection as soon as the build completes. See Вызов guix gc, for more on GC roots.

--log-file

Return the build log file names or URLs for the given package-or-derivation, or raise an error if build logs are missing.

This works regardless of how packages or derivations are specified. For instance, the following invocations are equivalent:

guix build --log-file `guix build -d guile`
guix build --log-file `guix build guile`
guix build --log-file guile
guix build --log-file -e '(@ (gnu packages guile) guile-2.0)'

If a log is unavailable locally, and unless --no-substitutes is passed, the command looks for a corresponding log on one of the substitute servers (as specified with --substitute-urls.)

So for instance, imagine you want to see the build log of GDB on MIPS, but you are actually on an x86_64 machine:

$ guix build --log-file gdb -s mips64el-linux
https://ci.guix.gnu.org/log/…-gdb-7.10

You can freely access a huge library of build logs!


Previous: , Up: Вызов guix build   [Contents][Index]

7.1.4 Отладка ошибок сборки

When defining a new package (see Описание пакетов), you will probably find yourself spending some time debugging and tweaking the build until it succeeds. To do that, you need to operate the build commands yourself in an environment as close as possible to the one the build daemon uses.

To that end, the first thing to do is to use the --keep-failed or -K option of guix build, which will keep the failed build tree in /tmp or whatever directory you specified as TMPDIR (see --keep-failed).

From there on, you can cd to the failed build tree and source the environment-variables file, which contains all the environment variable definitions that were in place when the build failed. So let’s say you’re debugging a build failure in package foo; a typical session would look like this:

$ guix build foo -K
… build fails
$ cd /tmp/guix-build-foo.drv-0
$ source ./environment-variables
$ cd foo-1.2

Now, you can invoke commands as if you were the daemon (almost) and troubleshoot your build process.

Sometimes it happens that, for example, a package’s tests pass when you run them manually but they fail when the daemon runs them. This can happen because the daemon runs builds in containers where, unlike in our environment above, network access is missing, /bin/sh does not exist, etc. (see Установка окружения сборки).

In such cases, you may need to run inspect the build process from within a container similar to the one the build daemon creates:

$ guix build -K foo
…
$ cd /tmp/guix-build-foo.drv-0
$ guix environment --no-grafts -C foo --ad-hoc strace gdb
[env]# source ./environment-variables
[env]# cd foo-1.2

Here, guix environment -C creates a container and spawns a new shell in it (see Вызов guix environment). The --ad-hoc strace gdb part adds the strace and gdb commands to the container, which would may find handy while debugging. The --no-grafts option makes sure we get the exact same environment, with ungrafted packages (see Обновления безопасности, for more info on grafts).

To get closer to a container like that used by the build daemon, we can remove /bin/sh:

[env]# rm /bin/sh

(Don’t worry, this is harmless: this is all happening in the throw-away container created by guix environment.)

The strace command is probably not in the search path, but we can run:

[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check

In this way, not only you will have reproduced the environment variables the daemon uses, you will also be running the build process in a container similar to the one the daemon uses.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.2 Invoking guix edit

So many packages, so many source files! The guix edit command facilitates the life of users and packagers by pointing their editor at the source file containing the definition of the specified packages. For instance:

guix edit gcc@4.9 vim

launches the program specified in the VISUAL or in the EDITOR environment variable to view the recipe of GCC 4.9.3 and that of Vim.

If you are using a Guix Git checkout (see Сборка из Git), or have created your own packages on GUIX_PACKAGE_PATH (see Пакетные модули), you will be able to edit the package recipes. In other cases, you will be able to examine the read-only recipes for packages currently in the store.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.3 Invoking guix download

When writing a package definition, developers typically need to download a source tarball, compute its SHA256 hash, and write that hash in the package definition (see Описание пакетов). The guix download tool helps with this task: it downloads a file from the given URI, adds it to the store, and prints both its file name in the store and its SHA256 hash.

The fact that the downloaded file is added to the store saves bandwidth: when the developer eventually tries to build the newly defined package with guix build, the source tarball will not have to be downloaded again because it is already in the store. It is also a convenient way to temporarily stash files, which may be deleted eventually (see Вызов guix gc).

The guix download command supports the same URIs as used in package definitions. In particular, it supports mirror:// URIs. https URIs (HTTP over TLS) are supported provided the Guile bindings for GnuTLS are available in the user’s environment; when they are not available, an error is raised. See how to install the GnuTLS bindings for Guile in GnuTLS-Guile, for more information.

guix download verifies HTTPS server certificates by loading the certificates of X.509 authorities from the directory pointed to by the SSL_CERT_DIR environment variable (see Сертификаты X.509), unless --no-check-certificate is used.

The following options are available:

--format=fmt
-f fmt

Write the hash in the format specified by fmt. For more information on the valid values for fmt, see Вызов guix hash.

--no-check-certificate

Do not validate the X.509 certificates of HTTPS servers.

When using this option, you have absolutely no guarantee that you are communicating with the authentic server responsible for the given URL, which makes you vulnerable to “man-in-the-middle” attacks.

--output=file
-o file

Save the downloaded file to file instead of adding it to the store.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.4 Invoking guix hash

The guix hash command computes the SHA256 hash of a file. It is primarily a convenience tool for anyone contributing to the distribution: it computes the cryptographic hash of a file, which can be used in the definition of a package (see Описание пакетов).

Основной синтаксис:

guix hash option file

When file is - (a hyphen), guix hash computes the hash of data read from standard input. guix hash has the following options:

--format=fmt
-f fmt

Write the hash in the format specified by fmt.

Supported formats: nix-base32, base32, base16 (hex and hexadecimal can be used as well).

If the --format option is not specified, guix hash will output the hash in nix-base32. This representation is used in the definitions of packages.

--recursive
-r

Compute the hash on file recursively.

In this case, the hash is computed on an archive containing file, including its children if it is a directory. Some of the metadata of file is part of the archive; for instance, when file is a regular file, the hash is different depending on whether file is executable or not. Metadata such as time stamps has no impact on the hash (see Вызов guix archive).

--exclude-vcs
-x

When combined with --recursive, exclude version control system directories (.bzr, .git, .hg, etc.)

As an example, here is how you would compute the hash of a Git checkout, which is useful when using the git-fetch method (see интерфейс origin):

$ git clone http://example.org/foo.git
$ cd foo
$ guix hash -rx .

Next: , Previous: , Up: Утилиты   [Contents][Index]

7.5 Invoking guix import

The guix import command is useful for people who would like to add a package to the distribution with as little work as possible—a legitimate demand. The command knows of a few repositories from which it can “import” package metadata. The result is a package definition, or a template thereof, in the format we know (see Описание пакетов).

Основной синтаксис:

guix import importer options

importer specifies the source from which to import package metadata, and options specifies a package identifier and other options specific to importer. Currently, the available “importers” are:

gnu

Import metadata for the given GNU package. This provides a template for the latest version of that GNU package, including the hash of its source tarball, and its canonical synopsis and description.

Additional information such as the package dependencies and its license needs to be figured out manually.

For example, the following command returns a package definition for GNU Hello:

guix import gnu hello

Specific command-line options are:

--key-download=policy

As for guix refresh, specify the policy to handle missing OpenPGP keys when verifying the package signature. See --key-download.

pypi

Import metadata from the Python Package Index. Information is taken from the JSON-formatted description available at pypi.python.org and usually includes all the relevant information, including package dependencies. For maximum efficiency, it is recommended to install the unzip utility, so that the importer can unzip Python wheels and gather data from them.

The command below imports metadata for the itsdangerous Python package:

guix import pypi itsdangerous
--recursive
-r

Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

gem

Import metadata from RubyGems. Information is taken from the JSON-formatted description available at rubygems.org and includes most relevant information, including runtime dependencies. There are some caveats, however. The metadata doesn’t distinguish between synopses and descriptions, so the same string is used for both fields. Additionally, the details of non-Ruby dependencies required to build native extensions is unavailable and left as an exercise to the packager.

The command below imports metadata for the rails Ruby package:

guix import gem rails
--recursive
-r

Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

cpan

Import metadata from MetaCPAN. Information is taken from the JSON-formatted metadata provided through MetaCPAN’s API and includes most relevant information, such as module dependencies. License information should be checked closely. If Perl is available in the store, then the corelist utility will be used to filter core modules out of the list of dependencies.

The command command below imports metadata for the Acme::Boolean Perl module:

guix import cpan Acme::Boolean
cran

Import metadata from CRAN, the central repository for the GNU R statistical and graphical environment.

Information is extracted from the DESCRIPTION file of the package.

The command command below imports metadata for the Cairo R package:

guix import cran Cairo

When --recursive is added, the importer will traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

When --archive=bioconductor is added, metadata is imported from Bioconductor, a repository of R packages for for the analysis and comprehension of high-throughput genomic data in bioinformatics.

Information is extracted from the DESCRIPTION file of a package published on the web interface of the Bioconductor SVN repository.

The command below imports metadata for the GenomicRanges R package:

guix import cran --archive=bioconductor GenomicRanges
texlive

Import metadata from CTAN, the comprehensive TeX archive network for TeX packages that are part of the TeX Live distribution.

Information about the package is obtained through the XML API provided by CTAN, while the source code is downloaded from the SVN repository of the Tex Live project. This is done because the CTAN does not keep versioned archives.

The command command below imports metadata for the fontspec TeX package:

guix import texlive fontspec

When --archive=DIRECTORY is added, the source code is downloaded not from the latex sub-directory of the texmf-dist/source tree in the TeX Live SVN repository, but from the specified sibling directory under the same root.

The command below imports metadata for the ifxetex package from CTAN while fetching the sources from the directory texmf/source/generic:

guix import texlive --archive=generic ifxetex
json

Import package metadata from a local JSON file. Consider the following example package definition in JSON format:

{
  "name": "hello",
  "version": "2.10",
  "source": "mirror://gnu/hello/hello-2.10.tar.gz",
  "build-system": "gnu",
  "home-page": "https://www.gnu.org/software/hello/",
  "synopsis": "Hello, GNU world: An example GNU package",
  "description": "GNU Hello prints a greeting.",
  "license": "GPL-3.0+",
  "native-inputs": ["gcc@6"]
}

The field names are the same as for the <package> record (See Описание пакетов). References to other packages are provided as JSON lists of quoted package specification strings such as guile or guile@2.0.

The importer also supports a more explicit source definition using the common fields for <origin> records:

{
  …
  "source": {
    "method": "url-fetch",
    "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
    "sha256": {
      "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
    }
  }
  …
}

The command below reads metadata from the JSON file hello.json and outputs a package expression:

guix import json hello.json
nix

Import metadata from a local copy of the source of the Nixpkgs distribution19. Package definitions in Nixpkgs are typically written in a mixture of Nix-language and Bash code. This command only imports the high-level package structure that is written in the Nix language. It normally includes all the basic fields of a package definition.

When importing a GNU package, the synopsis and descriptions are replaced by their canonical upstream variant.

Usually, you will first need to do:

export NIX_REMOTE=daemon

so that nix-instantiate does not try to open the Nix database.

As an example, the command below imports the package definition of LibreOffice (more precisely, it imports the definition of the package bound to the libreoffice top-level attribute):

guix import nix ~/path/to/nixpkgs libreoffice
hackage

Import metadata from the Haskell community’s central package archive Hackage. Information is taken from Cabal files and includes all the relevant information, including package dependencies.

Specific command-line options are:

--stdin
-s

Read a Cabal file from standard input.

--no-test-dependencies
-t

Do not include dependencies required only by the test suites.

--cabal-environment=alist
-e alist

alist is a Scheme alist defining the environment in which the Cabal conditionals are evaluated. The accepted keys are: os, arch, impl and a string representing the name of a flag. The value associated with a flag has to be either the symbol true or false. The value associated with other keys has to conform to the Cabal file format definition. The default value associated with the keys os, arch and impl is ‘linux’, ‘x86_64’ and ‘ghc’, respectively.

--recursive
-r

Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

The command below imports metadata for the latest version of the HTTP Haskell package without including test dependencies and specifying the value of the flag ‘network-uri’ as false:

guix import hackage -t -e "'((\"network-uri\" . false))" HTTP

A specific package version may optionally be specified by following the package name by an at-sign and a version number as in the following example:

guix import hackage mtl@2.1.3.1
stackage

The stackage importer is a wrapper around the hackage one. It takes a package name, looks up the package version included in a long-term support (LTS) Stackage release and uses the hackage importer to retrieve its metadata. Note that it is up to you to select an LTS release compatible with the GHC compiler used by Guix.

Specific command-line options are:

--no-test-dependencies
-t

Do not include dependencies required only by the test suites.

--lts-version=version
-l version

version is the desired LTS release version. If omitted the latest release is used.

--recursive
-r

Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

The command below imports metadata for the HTTP Haskell package included in the LTS Stackage release version 7.18:

guix import stackage --lts-version=7.18 HTTP
elpa

Import metadata from an Emacs Lisp Package Archive (ELPA) package repository (see Packages in The GNU Emacs Manual).

Specific command-line options are:

--archive=repo
-a repo

repo identifies the archive repository from which to retrieve the information. Currently the supported repositories and their identifiers are:

  • - GNU, selected by the gnu identifier. This is the default.

    Packages from elpa.gnu.org are signed with one of the keys contained in the GnuPG keyring at share/emacs/25.1/etc/package-keyring.gpg (or similar) in the emacs package (see ELPA package signatures in The GNU Emacs Manual).

  • - MELPA-Stable, selected by the melpa-stable identifier.
  • - MELPA, selected by the melpa identifier.
--recursive
-r

Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

crate

Import metadata from the crates.io Rust package repository crates.io.

opam

Import metadata from the OPAM package repository used by the OCaml community.

The structure of the guix import code is modular. It would be useful to have more importers for other package formats, and your help is welcome here (see Содействие).


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.6 Invoking guix refresh

The primary audience of the guix refresh command is developers of the GNU software distribution. By default, it reports any packages provided by the distribution that are outdated compared to the latest upstream version, like this:

$ guix refresh
gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0

Alternately, one can specify packages to consider, in which case a warning is emitted for packages that lack an updater:

$ guix refresh coreutils guile guile-ssh
gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13

guix refresh browses the upstream repository of each package and determines the highest version number of the releases therein. The command knows how to update specific types of packages: GNU packages, ELPA packages, etc.—see the documentation for --type below. There are many packages, though, for which it lacks a method to determine whether a new upstream release is available. However, the mechanism is extensible, so feel free to get in touch with us to add a new method!

--recursive

Consider the packages specified, and all the packages upon which they depend.

$ guix refresh --recursive coreutils
gnu/packages/acl.scm:35:2: warning: no updater for acl
gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
gnu/packages/xml.scm:68:2: warning: no updater for expat
gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp
…

Sometimes the upstream name differs from the package name used in Guix, and guix refresh needs a little help. Most updaters honor the upstream-name property in package definitions, which can be used to that effect:

(define-public network-manager
  (package
    (name "network-manager")
    ;; …
    (properties '((upstream-name . "NetworkManager")))))

When passed --update, it modifies distribution source files to update the version numbers and source tarball hashes of those package recipes (see Описание пакетов). This is achieved by downloading each package’s latest source tarball and its associated OpenPGP signature, authenticating the downloaded tarball against its signature using gpg, and finally computing its hash. When the public key used to sign the tarball is missing from the user’s keyring, an attempt is made to automatically retrieve it from a public key server; when this is successful, the key is added to the user’s keyring; otherwise, guix refresh reports an error.

The following options are supported:

--expression=expr
-e expr

Consider the package expr evaluates to.

This is useful to precisely refer to a package, as in this example:

guix refresh -l -e '(@@ (gnu packages commencement) glibc-final)'

This command lists the dependents of the “final” libc (essentially all the packages.)

--update
-u

Update distribution source files (package recipes) in place. This is usually run from a checkout of the Guix source tree (see Запуск Guix перед его устанвокой):

$ ./pre-inst-env guix refresh -s non-core -u

See Описание пакетов, for more information on package definitions.

--select=[subset]
-s subset

Select all the packages in subset, one of core or non-core.

The core subset refers to all the packages at the core of the distribution—i.e., packages that are used to build “everything else”. This includes GCC, libc, Binutils, Bash, etc. Usually, changing one of these packages in the distribution entails a rebuild of all the others. Thus, such updates are an inconvenience to users in terms of build time or bandwidth used to achieve the upgrade.

The non-core subset refers to the remaining packages. It is typically useful in cases where an update of the core packages would be inconvenient.

--manifest=file
-m file

Select all the packages from the manifest in file. This is useful to check if any packages of the user manifest can be updated.

--type=updater
-t updater

Select only packages handled by updater (may be a comma-separated list of updaters). Currently, updater may be one of:

gnu

the updater for GNU packages;

gnome

the updater for GNOME packages;

kde

the updater for KDE packages;

xorg

the updater for X.org packages;

kernel.org

the updater for packages hosted on kernel.org;

elpa

the updater for ELPA packages;

cran

the updater for CRAN packages;

bioconductor

the updater for Bioconductor R packages;

cpan

the updater for CPAN packages;

pypi

the updater for PyPI packages.

gem

the updater for RubyGems packages.

github

the updater for GitHub packages.

hackage

the updater for Hackage packages.

stackage

the updater for Stackage packages.

crate

the updater for Crates packages.

launchpad

the updater for Launchpad packages.

For instance, the following command only checks for updates of Emacs packages hosted at elpa.gnu.org and for updates of CRAN packages:

$ guix refresh --type=elpa,cran
gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9

In addition, guix refresh can be passed one or more package names, as in this example:

$ ./pre-inst-env guix refresh -u emacs idutils gcc@4.8

The command above specifically updates the emacs and idutils packages. The --select option would have no effect in this case.

When considering whether to upgrade a package, it is sometimes convenient to know which packages would be affected by the upgrade and should be checked for compatibility. For this the following option may be used when passing guix refresh one or more package names:

--list-updaters
-L

List available updaters and exit (see --type above.)

For each updater, display the fraction of packages it covers; at the end, display the fraction of packages covered by all these updaters.

--list-dependent
-l

List top-level dependent packages that would need to be rebuilt as a result of upgrading one or more packages.

See the reverse-package type of guix graph, for information on how to visualize the list of dependents of a package.

Be aware that the --list-dependent option only approximates the rebuilds that would be required as a result of an upgrade. More rebuilds might be required under some circumstances.

$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop@2.4.0 geiser@0.4 notmuch@0.18 mu@0.9.9.5 cflow@1.4 idutils@4.6 …

The command above lists a set of packages that could be built to check for compatibility with an upgraded flex package.

--list-transitive

List all the packages which one or more packages depend upon.

$ guix refresh --list-transitive flex
flex@2.6.4 depends on the following 25 packages: perl@5.28.0 help2man@1.47.6
bison@3.0.5 indent@2.2.10 tar@1.30 gzip@1.9 bzip2@1.0.6 xz@5.2.4 file@5.33 …

The command above lists a set of packages which, when changed, would cause flex to be rebuilt.

The following options can be used to customize GnuPG operation:

--gpg=command

Use command as the GnuPG 2.x command. command is searched for in $PATH.

--keyring=file

Use file as the keyring for upstream keys. file must be in the keybox format. Keybox files usually have a name ending in .kbx and the GNU Privacy Guard (GPG) can manipulate these files (see kbxutil in Using the GNU Privacy Guard, for information on a tool to manipulate keybox files).

When this option is omitted, guix refresh uses ~/.config/guix/upstream/trustedkeys.kbx as the keyring for upstream signing keys. OpenPGP signatures are checked against keys from this keyring; missing keys are downloaded to this keyring as well (see --key-download below.)

You can export keys from your default GPG keyring into a keybox file using commands like this one:

gpg --export rms@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx

Likewise, you can fetch keys to a specific keybox file like this:

gpg --no-default-keyring --keyring mykeyring.kbx \
  --recv-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5

--keyring in Using the GNU Privacy Guard, for more information on GPG’s --keyring option.

--key-download=policy

Handle missing OpenPGP keys according to policy, which may be one of:

always

Always download missing OpenPGP keys from the key server, and add them to the user’s GnuPG keyring.

never

Never try to download missing OpenPGP keys. Instead just bail out.

interactive

When a package signed with an unknown OpenPGP key is encountered, ask the user whether to download it or not. This is the default behavior.

--key-server=host

Use host as the OpenPGP key server when importing a public key.

The github updater uses the GitHub API to query for new releases. When used repeatedly e.g. when refreshing all packages, GitHub will eventually refuse to answer any further API requests. By default 60 API requests per hour are allowed, and a full refresh on all GitHub packages in Guix requires more than this. Authentication with GitHub through the use of an API token alleviates these limits. To use an API token, set the environment variable GUIX_GITHUB_TOKEN to a token procured from https://github.com/settings/tokens or otherwise.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.7 Invoking guix lint

The guix lint command is meant to help package developers avoid common errors and use a consistent style. It runs a number of checks on a given set of packages in order to find common mistakes in their definitions. Available checkers include (see --list-checkers for a complete list):

synopsis
description

Validate certain typographical and stylistic rules about package descriptions and synopses.

inputs-should-be-native

Identify inputs that should most likely be native inputs.

source
home-page
mirror-url
github-url
source-file-name

Probe home-page and source URLs and report those that are invalid. Suggest a mirror:// URL when applicable. If the source URL redirects to a GitHub URL, recommend usage of the GitHub URL. Check that the source file name is meaningful, e.g. is not just a version number or “git-checkout”, without a declared file-name (see интерфейс origin).

source-unstable-tarball

Parse the source URL to determine if a tarball from GitHub is autogenerated or if it is a release tarball. Unfortunately GitHub’s autogenerated tarballs are sometimes regenerated.

cve

Report known vulnerabilities found in the Common Vulnerabilities and Exposures (CVE) databases of the current and past year published by the US NIST.

To view information about a particular vulnerability, visit pages such as:

where CVE-YYYY-ABCD is the CVE identifier—e.g., CVE-2015-7554.

Package developers can specify in package recipes the Common Platform Enumeration (CPE) name and version of the package when they differ from the name or version that Guix uses, as in this example:

(package
  (name "grub")
  ;; …
  ;; CPE calls this package "grub2".
  (properties '((cpe-name . "grub2")
                (cpe-version . "2.3")))

Some entries in the CVE database do not specify which version of a package they apply to, and would thus “stick around” forever. Package developers who found CVE alerts and verified they can be ignored can declare them as in this example:

(package
  (name "t1lib")
  ;; …
  ;; These CVEs no longer apply and can be safely ignored.
  (properties `((lint-hidden-cve . ("CVE-2011-0433"
                                    "CVE-2011-1553"
                                    "CVE-2011-1554"
                                    "CVE-2011-5244")))))
formatting

Warn about obvious source code formatting issues: trailing white space, use of tabulations, etc.

Основной синтаксис:

guix lint options package

If no package is given on the command line, then all packages are checked. The options may be zero or more of the following:

--list-checkers
-l

List and describe all the available checkers that will be run on packages and exit.

--checkers
-c

Only enable the checkers specified in a comma-separated list using the names returned by --list-checkers.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.8 Invoking guix size

The guix size command helps package developers profile the disk usage of packages. It is easy to overlook the impact of an additional dependency added to a package, or the impact of using a single output for a package that could easily be split (see Пакеты со множественным выходом). Such are the typical issues that guix size can highlight.

The command can be passed one or more package specifications such as gcc@4.8 or guile:debug, or a file name in the store. Consider this example:

$ guix size coreutils
store item                               total    self
/gnu/store/…-gcc-5.5.0-lib           60.4    30.1  38.1%
/gnu/store/…-glibc-2.27              30.3    28.8  36.6%
/gnu/store/…-coreutils-8.28          78.9    15.0  19.0%
/gnu/store/…-gmp-6.1.2               63.1     2.7   3.4%
/gnu/store/…-bash-static-4.4.12       1.5     1.5   1.9%
/gnu/store/…-acl-2.2.52              61.1     0.4   0.5%
/gnu/store/…-attr-2.4.47             60.6     0.2   0.3%
/gnu/store/…-libcap-2.25             60.5     0.2   0.2%
total: 78.9 MiB

The store items listed here constitute the transitive closure of Coreutils—i.e., Coreutils and all its dependencies, recursively—as would be returned by:

$ guix gc -R /gnu/store/…-coreutils-8.23

Here the output shows three columns next to store items. The first column, labeled “total”, shows the size in mebibytes (MiB) of the closure of the store item—that is, its own size plus the size of all its dependencies. The next column, labeled “self”, shows the size of the item itself. The last column shows the ratio of the size of the item itself to the space occupied by all the items listed here.

In this example, we see that the closure of Coreutils weighs in at 79 MiB, most of which is taken by libc and GCC’s run-time support libraries. (That libc and GCC’s libraries represent a large fraction of the closure is not a problem per se because they are always available on the system anyway.)

When the package(s) passed to guix size are available in the store20, guix size queries the daemon to determine its dependencies, and measures its size in the store, similar to du -ms --apparent-size (see du invocation in GNU Coreutils).

When the given packages are not in the store, guix size reports information based on the available substitutes (see Подстановки). This makes it possible it to profile disk usage of store items that are not even on disk, only available remotely.

You can also specify several package names:

$ guix size coreutils grep sed bash
store item                               total    self
/gnu/store/…-coreutils-8.24          77.8    13.8  13.4%
/gnu/store/…-grep-2.22               73.1     0.8   0.8%
/gnu/store/…-bash-4.3.42             72.3     4.7   4.6%
/gnu/store/…-readline-6.3            67.6     1.2   1.2%
…
total: 102.3 MiB

In this example we see that the combination of the four packages takes 102.3 MiB in total, which is much less than the sum of each closure since they have a lot of dependencies in common.

The available options are:

--substitute-urls=urls

Use substitute information from urls. See the same option for guix build.

--sort=key

Sort lines according to key, one of the following options:

self

the size of each item (the default);

конвейер

the total size of the item’s closure.

--map-file=file

Write a graphical map of disk usage in PNG format to file.

For the example above, the map looks like this:

map of Coreutils disk usage produced
by guix size

This option requires that Guile-Charting be installed and visible in Guile’s module search path. When that is not the case, guix size fails as it tries to load it.

--system=system
-s system

Consider packages for system—e.g., x86_64-linux.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.9 Invoking guix graph

Packages and their dependencies form a graph, specifically a directed acyclic graph (DAG). It can quickly become difficult to have a mental model of the package DAG, so the guix graph command provides a visual representation of the DAG. By default, guix graph emits a DAG representation in the input format of Graphviz, so its output can be passed directly to the dot command of Graphviz. It can also emit an HTML page with embedded JavaScript code to display a “chord diagram” in a Web browser, using the d3.js library, or emit Cypher queries to construct a graph in a graph database supporting the openCypher query language. The general syntax is:

guix graph options package

For example, the following command generates a PDF file representing the package DAG for the GNU Core Utilities, showing its build-time dependencies:

guix graph coreutils | dot -Tpdf > dag.pdf

The output looks like this:

Dependency graph of the GNU Coreutils

Nice little graph, no?

But there is more than one graph! The one above is concise: it is the graph of package objects, omitting implicit inputs such as GCC, libc, grep, etc. It is often useful to have such a concise graph, but sometimes one may want to see more details. guix graph supports several types of graphs, allowing you to choose the level of detail:

package

This is the default type used in the example above. It shows the DAG of package objects, excluding implicit dependencies. It is concise, but filters out many details.

reverse-package

This shows the reverse DAG of packages. For example:

guix graph --type=reverse-package ocaml

... yields the graph of packages that explicitly depend on OCaml (if you are also interested in cases where OCaml is an implicit dependency, see reverse-bag below.)

Note that for core packages this can yield huge graphs. If all you want is to know the number of packages that depend on a given package, use guix refresh --list-dependent (see --list-dependent).

bag-emerged

This is the package DAG, including implicit inputs.

For instance, the following command:

guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf

... yields this bigger graph:

Detailed dependency graph of the GNU
Coreutils

At the bottom of the graph, we see all the implicit inputs of gnu-build-system (see gnu-build-system).

Now, note that the dependencies of these implicit inputs—that is, the bootstrap dependencies (see Начальная загрузка)—are not shown here, for conciseness.

bag

Similar to bag-emerged, but this time including all the bootstrap dependencies.

bag-with-origins

Similar to bag, but also showing origins and their dependencies.

reverse-bag

This shows the reverse DAG of packages. Unlike reverse-package, it also takes implicit dependencies into account. For example:

guix graph -t reverse-bag dune

... yields the graph of all packages that depend on Dune, directly or indirectly. Since Dune is an implicit dependency of many packages via dune-build-system, this shows a large number of packages, whereas reverse-package would show very few if any.

деривация

This is the most detailed representation: It shows the DAG of derivations (see Деривации) and plain store items. Compared to the above representation, many additional nodes are visible, including build scripts, patches, Guile modules, etc.

For this type of graph, it is also possible to pass a .drv file name instead of a package name, as in:

guix graph -t derivation `guix system build -d my-config.scm`
module

This is the graph of package modules (see Пакетные модули). For example, the following command shows the graph for the package module that defines the guile package:

guix graph -t module guile | dot -Tpdf > module-graph.pdf

All the types above correspond to build-time dependencies. The following graph type represents the run-time dependencies:

references

This is the graph of references of a package output, as returned by guix gc --references (see Вызов guix gc).

If the given package output is not available in the store, guix graph attempts to obtain dependency information from substitutes.

Here you can also pass a store file name instead of a package name. For example, the command below produces the reference graph of your profile (which can be big!):

guix graph -t references `readlink -f ~/.guix-profile`
referrers

This is the graph of the referrers of a store item, as returned by guix gc --referrers (see Вызов guix gc).

This relies exclusively on local information from your store. For instance, let us suppose that the current Inkscape is available in 10 profiles on your machine; guix graph -t referrers inkscape will show a graph rooted at Inkscape and with those 10 profiles linked to it.

It can help determine what is preventing a store item from being garbage collected.

The available options are the following:

--type=type
-t type

Produce a graph output of type, where type must be one of the values listed above.

--list-types

List the supported graph types.

--backend=backend
-b backend

Produce a graph using the selected backend.

--list-backends

List the supported graph backends.

Currently, the available backends are Graphviz and d3.js.

--expression=expr
-e expr

Consider the package expr evaluates to.

This is useful to precisely refer to a package, as in this example:

guix graph -e '(@@ (gnu packages commencement) gnu-make-final)'
--system=system
-s system

Display the graph for system—e.g., i686-linux.

The package dependency graph is largely architecture-independent, but there are some architecture-dependent bits that this option allows you to visualize.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.10 Invoking guix publish

The purpose of guix publish is to enable users to easily share their store with others, who can then use it as a substitute server (see Подстановки).

When guix publish runs, it spawns an HTTP server which allows anyone with network access to obtain substitutes from it. This means that any machine running Guix can also act as if it were a build farm, since the HTTP interface is compatible with Hydra, the software behind the ci.guix.gnu.org build farm.

For security, each substitute is signed, allowing recipients to check their authenticity and integrity (see Подстановки). Because guix publish uses the signing key of the system, which is only readable by the system administrator, it must be started as root; the --user option makes it drop root privileges early on.

The signing key pair must be generated before guix publish is launched, using guix archive --generate-key (see Вызов guix archive).

Основной синтаксис:

guix publish options

Running guix publish without any additional arguments will spawn an HTTP server on port 8080:

guix publish

Once a publishing server has been authorized (see Вызов guix archive), the daemon may download substitutes from it:

guix-daemon --substitute-urls=http://example.org:8080

By default, guix publish compresses archives on the fly as it serves them. This “on-the-fly” mode is convenient in that it requires no setup and is immediately available. However, when serving lots of clients, we recommend using the --cache option, which enables caching of the archives before they are sent to clients—see below for details. The guix weather command provides a handy way to check what a server provides (see Вызов guix weather).

As a bonus, guix publish also serves as a content-addressed mirror for source files referenced in origin records (see интерфейс origin). For instance, assuming guix publish is running on example.org, the following URL returns the raw hello-2.10.tar.gz file with the given SHA256 hash (represented in nix-base32 format, see Вызов guix hash):

http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1…ndq1i

Obviously, these URLs only work for files that are in the store; in other cases, they return 404 (“Not Found”).

Build logs are available from /log URLs like:

http://example.org/log/gwspk…-guile-2.2.3

When guix-daemon is configured to save compressed build logs, as is the case by default (see Вызов guix-daemon), /log URLs return the compressed log as-is, with an appropriate Content-Type and/or Content-Encoding header. We recommend running guix-daemon with --log-compression=gzip since Web browsers can automatically decompress it, which is not the case with bzip2 compression.

The following options are available:

--port=port
-p port

Listen for HTTP requests on port.

--listen=host

Listen on the network interface for host. The default is to accept connections from any interface.

--user=user
-u user

Change privileges to user as soon as possible—i.e., once the server socket is open and the signing key has been read.

--compression[=level]
-C [level]

Compress data using the given level. When level is zero, disable compression. The range 1 to 9 corresponds to different gzip compression levels: 1 is the fastest, and 9 is the best (CPU-intensive). The default is 3.

Unless --cache is used, compression occurs on the fly and the compressed streams are not cached. Thus, to reduce load on the machine that runs guix publish, it may be a good idea to choose a low compression level, to run guix publish behind a caching proxy, or to use --cache. Using --cache has the advantage that it allows guix publish to add Content-Length HTTP header to its responses.

--cache=directory
-c directory

Cache archives and meta-data (.narinfo URLs) to directory and only serve archives that are in cache.

When this option is omitted, archives and meta-data are created on-the-fly. This can reduce the available bandwidth, especially when compression is enabled, since this may become CPU-bound. Another drawback of the default mode is that the length of archives is not known in advance, so guix publish does not add a Content-Length HTTP header to its responses, which in turn prevents clients from knowing the amount of data being downloaded.

Conversely, when --cache is used, the first request for a store item (via a .narinfo URL) returns 404 and triggers a background process to bake the archive—computing its .narinfo and compressing the archive, if needed. Once the archive is cached in directory, subsequent requests succeed and are served directly from the cache, which guarantees that clients get the best possible bandwidth.

The “baking” process is performed by worker threads. By default, one thread per CPU core is created, but this can be customized. See --workers below.

When --ttl is used, cached entries are automatically deleted when they have expired.

--workers=N

When --cache is used, request the allocation of N worker threads to “bake” archives.

--ttl=ttl

Produce Cache-Control HTTP headers that advertise a time-to-live (TTL) of ttl. ttl must denote a duration: 5d means 5 days, 1m means 1 month, and so on.

This allows the user’s Guix to keep substitute information in cache for ttl. However, note that guix publish does not itself guarantee that the store items it provides will indeed remain available for as long as ttl.

Additionally, when --cache is used, cached entries that have not been accessed for ttl and that no longer have a corresponding item in the store, may be deleted.

--nar-path=path

Use path as the prefix for the URLs of “nar” files (see normalized archives).

By default, nars are served at a URL such as /nar/gzip/…-coreutils-8.25. This option allows you to change the /nar part to path.

--public-key=file
--private-key=file

Use the specific files as the public/private key pair used to sign the store items being published.

The files must correspond to the same key pair (the private key is used for signing and the public key is merely advertised in the signature metadata). They must contain keys in the canonical s-expression format as produced by guix archive --generate-key (see Вызов guix archive). By default, /etc/guix/signing-key.pub and /etc/guix/signing-key.sec are used.

--repl[=port]
-r [port]

Spawn a Guile REPL server (see REPL Servers in GNU Guile Reference Manual) on port (37146 by default). This is used primarily for debugging a running guix publish server.

Enabling guix publish on Guix System is a one-liner: just instantiate a guix-publish-service-type service in the services field of the operating-system declaration (see guix-publish-service-type).

If you are instead running Guix on a “foreign distro”, follow these instructions:”


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.11 Invoking guix challenge

Do the binaries provided by this server really correspond to the source code it claims to build? Is a package build process deterministic? These are the questions the guix challenge command attempts to answer.

The former is obviously an important question: Before using a substitute server (see Подстановки), one had better verify that it provides the right binaries, and thus challenge it. The latter is what enables the former: If package builds are deterministic, then independent builds of the package should yield the exact same result, bit for bit; if a server provides a binary different from the one obtained locally, it may be either corrupt or malicious.

We know that the hash that shows up in /gnu/store file names is the hash of all the inputs of the process that built the file or directory—compilers, libraries, build scripts, etc. (see Введение). Assuming deterministic build processes, one store file name should map to exactly one build output. guix challenge checks whether there is, indeed, a single mapping by comparing the build outputs of several independent builds of any given store item.

The command output looks like this:

$ guix challenge --substitute-urls="https://ci.guix.gnu.org https://guix.example.org"
updating list of substitutes from 'https://ci.guix.gnu.org'... 100.0%
updating list of substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/…-openssl-1.0.2d contents differ:
  local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://ci.guix.gnu.org/nar/…-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://guix.example.org/nar/…-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
/gnu/store/…-git-2.5.0 contents differ:
  local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
  https://ci.guix.gnu.org/nar/…-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
  https://guix.example.org/nar/…-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
/gnu/store/…-pius-2.1.1 contents differ:
  local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://ci.guix.gnu.org/nar/…-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://guix.example.org/nar/…-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs

…

6,406 store items were analyzed:
  - 4,749 (74.1%) were identical
  - 525 (8.2%) differed
  - 1,132 (17.7%) were inconclusive

In this example, guix challenge first scans the store to determine the set of locally-built derivations—as opposed to store items that were downloaded from a substitute server—and then queries all the substitute servers. It then reports those store items for which the servers obtained a result different from the local build.

As an example, guix.example.org always gets a different answer. Conversely, ci.guix.gnu.org agrees with local builds, except in the case of Git. This might indicate that the build process of Git is non-deterministic, meaning that its output varies as a function of various things that Guix does not fully control, in spite of building packages in isolated environments (see Особенности). Most common sources of non-determinism include the addition of timestamps in build results, the inclusion of random numbers, and directory listings sorted by inode number. See https://reproducible-builds.org/docs/, for more information.

To find out what is wrong with this Git binary, we can do something along these lines (see Вызов guix archive):

$ wget -q -O - https://ci.guix.gnu.org/nar/…-git-2.5.0 \
   | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/…-git.2.5.0 /tmp/git

This command shows the difference between the files resulting from the local build, and the files resulting from the build on ci.guix.gnu.org (see Comparing and Merging Files in Comparing and Merging Files). The diff command works great for text files. When binary files differ, a better option is Diffoscope, a tool that helps visualize differences for all kinds of files.

Once you have done that work, you can tell whether the differences are due to a non-deterministic build process or to a malicious server. We try hard to remove sources of non-determinism in packages to make it easier to verify substitutes, but of course, this is a process that involves not just Guix, but a large part of the free software community. In the meantime, guix challenge is one tool to help address the problem.

If you are writing packages for Guix, you are encouraged to check whether ci.guix.gnu.org and other substitute servers obtain the same build result as you did with:

$ guix challenge package

where package is a package specification such as guile@2.0 or glibc:debug.

Основной синтаксис:

guix challenge options [packages…]

When a difference is found between the hash of a locally-built item and that of a server-provided substitute, or among substitutes provided by different servers, the command displays it as in the example above and its exit code is 2 (other non-zero exit codes denote other kinds of errors.)

The one option that matters is:

--substitute-urls=urls

Consider urls the whitespace-separated list of substitute source URLs to compare to.

--verbose
-v

Show details about matches (identical contents) in addition to information about mismatches.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.12 Invoking guix copy

The guix copy command copies items from the store of one machine to that of another machine over a secure shell (SSH) connection21. For example, the following command copies the coreutils package, the user’s profile, and all their dependencies over to host, logged in as user:

guix copy --to=user@host \
          coreutils `readlink -f ~/.guix-profile`

If some of the items to be copied are already present on host, they are not actually sent.

The command below retrieves libreoffice and gimp from host, assuming they are available there:

guix copy --from=host libreoffice gimp

The SSH connection is established using the Guile-SSH client, which is compatible with OpenSSH: it honors ~/.ssh/known_hosts and ~/.ssh/config, and uses the SSH agent for authentication.

The key used to sign items that are sent must be accepted by the remote machine. Likewise, the key used by the remote machine to sign items you are retrieving must be in /etc/guix/acl so it is accepted by your own daemon. See Вызов guix archive, for more information about store item authentication.

Основной синтаксис:

guix copy [--to=spec|--from=spec] items

You must always specify one of the following options:

--to=spec
--from=spec

Specify the host to send to or receive from. spec must be an SSH spec such as example.org, charlie@example.org, or charlie@example.org:2222.

The items can be either package names, such as gimp, or store items, such as /gnu/store/…-idutils-4.6.

When specifying the name of a package to send, it is first built if needed, unless --dry-run was specified. Common build options are supported (see Стандартные опции сборки).


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.13 Invoking guix container

Заметка: As of version 1.0.1, this tool is experimental. The interface is subject to radical change in the future.

The purpose of guix container is to manipulate processes running within an isolated environment, commonly known as a “container”, typically created by the guix environment (see Вызов guix environment) and guix system container (see Вызов guix system) commands.

Основной синтаксис:

guix container action options

action specifies the operation to perform with a container, and options specifies the context-specific arguments for the action.

The following actions are available:

exec

Execute a command within the context of a running container.

The syntax is:

guix container exec pid program arguments

pid specifies the process ID of the running container. program specifies an executable file name within the root file system of the container. arguments are the additional options that will be passed to program.

The following command launches an interactive login shell inside a Guix system container, started by guix system container, and whose process ID is 9001:

guix container exec 9001 /run/current-system/profile/bin/bash --login

Note that the pid cannot be the parent process of a container. It must be PID 1 of the container or one of its child processes.


Next: , Previous: , Up: Утилиты   [Contents][Index]

7.14 Invoking guix weather

Occasionally you’re grumpy because substitutes are lacking and you end up building packages by yourself (see Подстановки). The guix weather command reports on substitute availability on the specified servers so you can have an idea of whether you’ll be grumpy today. It can sometimes be useful info as a user, but it is primarily useful to people running guix publish (see Вызов guix publish).

Here’s a sample run:

$ guix weather --substitute-urls=https://guix.example.org
computing 5,872 package derivations for x86_64-linux...
looking for 6,128 store items on https://guix.example.org..
updating list of substitutes from 'https://guix.example.org'... 100.0%
https://guix.example.org
  43.4% substitutes available (2,658 out of 6,128)
  7,032.5 MiB of nars (compressed)
  19,824.2 MiB on disk (uncompressed)
  0.030 seconds per request (182.9 seconds in total)
  33.5 requests per second

  9.8% (342 out of 3,470) of the missing items are queued
  867 queued builds
      x86_64-linux: 518 (59.7%)
      i686-linux: 221 (25.5%)
      aarch64-linux: 128 (14.8%)
  build rate: 23.41 builds per hour
      x86_64-linux: 11.16 builds per hour
      i686-linux: 6.03 builds per hour
      aarch64-linux: 6.41 builds per hour

As you can see, it reports the fraction of all the packages for which substitutes are available on the server—regardless of whether substitutes are enabled, and regardless of whether this server’s signing key is authorized. It also reports the size of the compressed archives (“nars”) provided by the server, the size the corresponding store items occupy in the store (assuming deduplication is turned off), and the server’s throughput. The second part gives continuous integration (CI) statistics, if the server supports it. In addition, using the --coverage option, guix weather can list “important” package substitutes missing on the server (see below).

To achieve that, guix weather queries over HTTP(S) meta-data (narinfos) for all the relevant store items. Like guix challenge, it ignores signatures on those substitutes, which is innocuous since the command only gathers statistics and cannot install those substitutes.

Among other things, it is possible to query specific system types and specific package sets. The available options are listed below.

--substitute-urls=urls

urls is the space-separated list of substitute server URLs to query. When this option is omitted, the default set of substitute servers is queried.

--system=system
-s system

Query substitutes for system—e.g., aarch64-linux. This option can be repeated, in which case guix weather will query substitutes for several system types.

--manifest=file

Instead of querying substitutes for all the packages, only ask for those specified in file. file must contain a manifest, as with the -m option of guix package (see Вызов guix package).

--coverage[=count]
-c [count]

Report on substitute coverage for packages: list packages with at least count dependents (zero by default) for which substitutes are unavailable. Dependent packages themselves are not listed: if b depends on a and a has no substitutes, only a is listed, even though b usually lacks substitutes as well. The result looks like this:

$ guix weather --substitute-urls=https://ci.guix.gnu.org -c 10
computing 8,983 package derivations for x86_64-linux...
looking for 9,343 store items on https://ci.guix.gnu.org...
updating substitutes from 'https://ci.guix.gnu.org'... 100.0%
https://ci.guix.gnu.org
  64.7% substitutes available (6,047 out of 9,343)
…
2502 packages are missing from 'https://ci.guix.gnu.org' for 'x86_64-linux', among which:
    58  kcoreaddons@5.49.0      /gnu/store/…-kcoreaddons-5.49.0
    46  qgpgme@1.11.1           /gnu/store/…-qgpgme-1.11.1
    37  perl-http-cookiejar@0.008  /gnu/store/…-perl-http-cookiejar-0.008
    …

What this example shows is that kcoreaddons and presumably the 58 packages that depend on it have no substitutes at ci.guix.info; likewise for qgpgme and the 46 packages that depend on it.

If you are a Guix developer, or if you are taking care of this build farm, you’ll probably want to have a closer look at these packages: they may simply fail to build.


Previous: , Up: Утилиты   [Contents][Index]

7.15 Invoking guix processes

The guix processes command can be useful to developers and system administrators, especially on multi-user machines and on build farms: it lists the current sessions (connections to the daemon), as well as information about the processes involved22. Here’s an example of the information it returns:

$ sudo guix processes
SessionPID: 19002
ClientPID: 19090
ClientCommand: guix environment --ad-hoc python

SessionPID: 19402
ClientPID: 19367
ClientCommand: guix publish -u guix-publish -p 3000 -C 9 …

SessionPID: 19444
ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass …
LockHeld: /gnu/store/…-perl-ipc-cmd-0.96.lock
LockHeld: /gnu/store/…-python-six-bootstrap-1.11.0.lock
LockHeld: /gnu/store/…-libjpeg-turbo-2.0.0.lock
ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800

In this example we see that guix-daemon has three clients: guix environment, guix publish, and the Cuirass continuous integration tool; their process identifier (PID) is given by the ClientPID field. The SessionPID field gives the PID of the guix-daemon sub-process of this particular session.

The LockHeld fields show which store items are currently locked by this session, which corresponds to store items being built or substituted (the LockHeld field is not displayed when guix processes is not running as root.) Last, by looking at the ChildProcess field, we understand that these three builds are being offloaded (see Установка демона разгрузки).

The output is in Recutils format so we can use the handy recsel command to select sessions of interest (see Selection Expressions in GNU recutils manual). As an example, the command shows the command line and PID of the client that triggered the build of a Perl package:

$ sudo guix processes | \
    recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass …

Next: , Previous: , Up: Top   [Contents][Index]

8 Конфигурирование системы

Guix System supports a consistent whole-system configuration mechanism. By that we mean that all aspects of the global system configuration—such as the available system services, timezone and locale settings, user accounts—are declared in a single place. Such a system configuration can be instantiated—i.e., effected.

One of the advantages of putting all the system configuration under the control of Guix is that it supports transactional system upgrades, and makes it possible to roll back to a previous system instantiation, should something go wrong with the new one (see Особенности). Another advantage is that it makes it easy to replicate the exact same configuration across different machines, or at different points in time, without having to resort to additional administration tools layered on top of the own tools of the system.

This section describes this mechanism. First we focus on the system administrator’s viewpoint—explaining how the system is configured and instantiated. Then we show how this mechanism can be extended, for instance to support new system services.


Next: , Up: Конфигурирование системы   [Contents][Index]

8.1 Использование системы конфигурации

The operating system is configured by providing an operating-system declaration in a file that can then be passed to the guix system command (see Вызов guix system). A simple setup, with the default system services, the default Linux-Libre kernel, initial RAM disk, and boot loader looks like this:

;; This is an operating system configuration template
;; for a "bare bones" setup, with no X11 display server.

(use-modules (gnu))
(use-service-modules networking ssh)
(use-package-modules screen)

(operating-system
  (host-name "komputilo")
  (timezone "Europe/Berlin")
  (locale "en_US.utf8")

  ;; Boot in "legacy" BIOS mode, assuming /dev/sdX is the
  ;; target hard disk, and "my-root" is the label of the target
  ;; root file system.
  (bootloader (bootloader-configuration
                (bootloader grub-bootloader)
                (target "/dev/sdX")))
  (file-systems (cons (file-system
                        (device (file-system-label "my-root"))
                        (mount-point "/")
                        (type "ext4"))
                      %base-file-systems))

  ;; This is where user accounts are specified.  The "root"
  ;; account is implicit, and is initially created with the
  ;; empty password.
  (users (cons (user-account
                (name "alice")
                (comment "Bob's sister")
                (group "users")

                ;; Adding the account to the "wheel" group
                ;; makes it a sudoer.  Adding it to "audio"
                ;; and "video" allows the user to play sound
                ;; and access the webcam.
                (supplementary-groups '("wheel"
                                        "audio" "video")))
               %base-user-accounts))

  ;; Globally-installed packages.
  (packages (cons screen %base-packages))

  ;; Add services to the baseline: a DHCP client and
  ;; an SSH server.
  (services (append (list (service dhcp-client-service-type)
                          (service openssh-service-type
                                   (openssh-configuration
                                    (port-number 2222))))
                    %base-services)))

This example should be self-describing. Some of the fields defined above, such as host-name and bootloader, are mandatory. Others, such as packages and services, can be omitted, in which case they get a default value.

Below we discuss the effect of some of the most important fields (see Интерфейс operating-system, for details about all the available fields), and how to instantiate the operating system using guix system.

Bootloader

The bootloader field describes the method that will be used to boot your system. Machines based on Intel processors can boot in “legacy” BIOS mode, as in the example above. However, more recent machines rely instead on the Unified Extensible Firmware Interface (UEFI) to boot. In that case, the bootloader field should contain something along these lines:

(bootloader-configuration
  (bootloader grub-efi-bootloader)
  (target "/boot/efi"))

See Настройка загрузчика, for more information on the available configuration options.

Globally-Visible Packages

The packages field lists packages that will be globally visible on the system, for all user accounts—i.e., in every user’s PATH environment variable—in addition to the per-user profiles (see Вызов guix package). The %base-packages variable provides all the tools one would expect for basic user and administrator tasks—including the GNU Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text editor, find, grep, etc. The example above adds GNU Screen to those, taken from the (gnu packages screen) module (see Пакетные модули). The (list package output) syntax can be used to add a specific output of a package:

(use-modules (gnu packages))
(use-modules (gnu packages dns))

(operating-system
  ;; ...
  (packages (cons (list bind "utils")
                  %base-packages)))

Referring to packages by variable name, like bind above, has the advantage of being unambiguous; it also allows typos and such to be diagnosed right away as “unbound variables”. The downside is that one needs to know which module defines which package, and to augment the use-package-modules line accordingly. To avoid that, one can use the specification->package procedure of the (gnu packages) module, which returns the best package for a given name or name and version:

(use-modules (gnu packages))

(operating-system
  ;; ...
  (packages (append (map specification->package
                         '("tcpdump" "htop" "gnupg@2.0"))
                    %base-packages)))

System Services

The services field lists system services to be made available when the system starts (see Сервисы). The operating-system declaration above specifies that, in addition to the basic services, we want the OpenSSH secure shell daemon listening on port 2222 (see openssh-service-type). Under the hood, openssh-service-type arranges so that sshd is started with the right command-line options, possibly with supporting configuration files generated as needed (see Создание сервисов).

Occasionally, instead of using the base services as is, you will want to customize them. To do this, use modify-services (see modify-services) to modify the list.

For example, suppose you want to modify guix-daemon and Mingetty (the console log-in) in the %base-services list (see %base-services). To do that, you can write the following in your operating system declaration:

(define %my-services
  ;; My very own list of services.
  (modify-services %base-services
    (guix-service-type config =>
                       (guix-configuration
                        (inherit config)
                        (use-substitutes? #f)
                        (extra-options '("--gc-keep-derivations"))))
    (mingetty-service-type config =>
                           (mingetty-configuration
                            (inherit config)))))

(operating-system
  ;; …
  (services %my-services))

This changes the configuration—i.e., the service parameters—of the guix-service-type instance, and that of all the mingetty-service-type instances in the %base-services list. Observe how this is accomplished: first, we arrange for the original configuration to be bound to the identifier config in the body, and then we write the body so that it evaluates to the desired configuration. In particular, notice how we use inherit to create a new configuration which has the same values as the old configuration, but with a few modifications.

The configuration for a typical “desktop” usage, with an encrypted root partition, the X11 display server, GNOME and Xfce (users can choose which of these desktop environments to use at the log-in screen by pressing F1), network management, power management, and more, would look like this:

;; This is an operating system configuration template
;; for a "desktop" setup with GNOME and Xfce where the
;; root partition is encrypted with LUKS.

(use-modules (gnu) (gnu system nss))
(use-service-modules desktop xorg)
(use-package-modules certs gnome)

(operating-system
  (host-name "antelope")
  (timezone "Europe/Paris")
  (locale "en_US.utf8")

  ;; Choose US English keyboard layout.  The "altgr-intl"
  ;; variant provides dead keys for accented characters.
  (keyboard-layout (keyboard-layout "us" "altgr-intl"))

  ;; Use the UEFI variant of GRUB with the EFI System
  ;; Partition mounted on /boot/efi.
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")
                (keyboard-layout keyboard-layout)))

  ;; Specify a mapped device for the encrypted root partition.
  ;; The UUID is that returned by 'cryptsetup luksUUID'.
  (mapped-devices
   (list (mapped-device
          (source (uuid "12345678-1234-1234-1234-123456789abc"))
          (target "my-root")
          (type luks-device-mapping))))

  (file-systems (append
                 (list (file-system
                         (device (file-system-label "my-root"))
                         (mount-point "/")
                         (type "ext4")
                         (dependencies mapped-devices))
                       (file-system
                         (device (uuid "1234-ABCD" 'fat))
                         (mount-point "/boot/efi")
                         (type "vfat")))
                 %base-file-systems))

  (users (cons (user-account
                (name "bob")
                (comment "Alice's brother")
                (group "users")
                (supplementary-groups '("wheel" "netdev"
                                        "audio" "video")))
               %base-user-accounts))

  ;; This is where we specify system-wide packages.
  (packages (append (list
                     ;; for HTTPS access
                     nss-certs
                     ;; for user mounts
                     gvfs)
                    %base-packages))

  ;; Add GNOME and Xfce---we can choose at the log-in screen
  ;; by clicking the gear.  Use the "desktop" services, which
  ;; include the X11 log-in service, networking with
  ;; NetworkManager, and more.
  (services (append (list (service gnome-desktop-service-type)
                          (service xfce-desktop-service-type)
                          (set-xorg-configuration
                           (xorg-configuration
                            (keyboard-layout keyboard-layout))))
                    %desktop-services))

  ;; Allow resolution of '.local' host names with mDNS.
  (name-service-switch %mdns-host-lookup-nss))

A graphical system with a choice of lightweight window managers instead of full-blown desktop environments would look like this:

;; This is an operating system configuration template
;; for a "desktop" setup without full-blown desktop
;; environments.

(use-modules (gnu) (gnu system nss))
(use-service-modules desktop)
(use-package-modules bootloaders certs ratpoison suckless wm)

(operating-system
  (host-name "antelope")
  (timezone "Europe/Paris")
  (locale "en_US.utf8")

  ;; Use the UEFI variant of GRUB with the EFI System
  ;; Partition mounted on /boot/efi.
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")))

  ;; Assume the target root file system is labelled "my-root",
  ;; and the EFI System Partition has UUID 1234-ABCD.
  (file-systems (append
                 (list (file-system
                         (device (file-system-label "my-root"))
                         (mount-point "/")
                         (type "ext4"))
                       (file-system
                         (device (uuid "1234-ABCD" 'fat))
                         (mount-point "/boot/efi")
                         (type "vfat")))
                 %base-file-systems))

  (users (cons (user-account
                (name "alice")
                (comment "Bob's sister")
                (group "users")
                (supplementary-groups '("wheel" "netdev"
                                        "audio" "video")))
               %base-user-accounts))

  ;; Add a bunch of window managers; we can choose one at
  ;; the log-in screen with F1.
  (packages (append (list
                     ;; window managers
                     ratpoison i3-wm i3status dmenu
                     ;; for HTTPS access
                     nss-certs)
                    %base-packages))

  ;; Use the "desktop" services, which include the X11
  ;; log-in service, networking with NetworkManager, and more.
  (services %desktop-services)

  ;; Allow resolution of '.local' host names with mDNS.
  (name-service-switch %mdns-host-lookup-nss))

This example refers to the /boot/efi file system by its UUID, 1234-ABCD. Replace this UUID with the right UUID on your system, as returned by the blkid command.

See Сервисы рабочего стола, for the exact list of services provided by %desktop-services. See Сертификаты X.509, for background information about the nss-certs package that is used here.

Again, %desktop-services is just a list of service objects. If you want to remove services from there, you can do so using the procedures for list filtering (see SRFI-1 Filtering and Partitioning in GNU Guile Reference Manual). For instance, the following expression returns a list that contains all the services in %desktop-services minus the Avahi service:

(remove (lambda (service)
          (eq? (service-kind service) avahi-service-type))
        %desktop-services)

Instantiating the System

Assuming the operating-system declaration is stored in the my-system-config.scm file, the guix system reconfigure my-system-config.scm command instantiates that configuration, and makes it the default GRUB boot entry (see Вызов guix system).

The normal way to change the system configuration is by updating this file and re-running guix system reconfigure. One should never have to touch files in /etc or to run commands that modify the system state such as useradd or grub-install. In fact, you must avoid that since that would not only void your warranty but also prevent you from rolling back to previous versions of your system, should you ever need to.

Speaking of roll-back, each time you run guix system reconfigure, a new generation of the system is created—without modifying or deleting previous generations. Old system generations get an entry in the bootloader boot menu, allowing you to boot them in case something went wrong with the latest generation. Reassuring, no? The guix system list-generations command lists the system generations available on disk. It is also possible to roll back the system via the commands guix system roll-back and guix system switch-generation.

Although the guix system reconfigure command will not modify previous generations, you must take care when the current generation is not the latest (e.g., after invoking guix system roll-back), since the operation might overwrite a later generation (see Вызов guix system).

The Programming Interface

At the Scheme level, the bulk of an operating-system declaration is instantiated with the following monadic procedure (see Устройство склада):

Monadic Procedure: operating-system-derivation os

Return a derivation that builds os, an operating-system object (see Деривации).

The output of the derivation is a single directory that refers to all the packages, configuration files, and other supporting files needed to instantiate os.

This procedure is provided by the (gnu system) module. Along with (gnu services) (see Сервисы), this module contains the guts of Guix System. Make sure to visit it!


Next: , Previous: , Up: Конфигурирование системы   [Contents][Index]

8.2 operating-system Reference

This section summarizes all the options available in operating-system declarations (see Использование системы конфигурации).

Data Type: operating-system

This is the data type representing an operating system configuration. By that, we mean all the global system configuration, not per-user configuration (see Использование системы конфигурации).

kernel (default: linux-libre)

The package object of the operating system kernel to use23.

kernel-arguments (default: '("quiet"))

List of strings or gexps representing additional arguments to pass on the command-line of the kernel—e.g., ("console=ttyS0").

bootloader

The system bootloader configuration object. See Настройка загрузчика.

label

This is the label (a string) as it appears in the bootloader’s menu entry. The default label includes the kernel name and version.

keyboard-layout (default: #f)

This field specifies the keyboard layout to use in the console. It can be either #f, in which case the default keyboard layout is used (usually US English), or a <keyboard-layout> record.

This keyboard layout is in effect as soon as the kernel has booted. For instance, it is the keyboard layout in effect when you type a passphrase if your root file system is on a luks-device-mapping mapped device (see Размеченные устройства).

Заметка: This does not specify the keyboard layout used by the bootloader, nor that used by the graphical display server. See Настройка загрузчика, for information on how to specify the bootloader’s keyboard layout. See Оконная система X, for information on how to specify the keyboard layout used by the X Window System.

initrd-modules (default: %base-initrd-modules)

The list of Linux kernel modules that need to be available in the initial RAM disk. See Начальный RAM-диск.

initrd (default: base-initrd)

A procedure that returns an initial RAM disk for the Linux kernel. This field is provided to support low-level customization and should rarely be needed for casual use. See Начальный RAM-диск.

firmware (default: %base-firmware)

List of firmware packages loadable by the operating system kernel.

The default includes firmware needed for Atheros- and Broadcom-based WiFi devices (Linux-libre modules ath9k and b43-open, respectively). See По поводу железа, for more info on supported hardware.

host-name

The host name.

hosts-file

A file-like object (see file-like objects) for use as /etc/hosts (see Host Names in The GNU C Library Reference Manual). The default is a file with entries for localhost and host-name.

mapped-devices (default: '())

A list of mapped devices. See Размеченные устройства.

file-systems

A list of file systems. See Файловые системы.

swap-devices (default: '())

A list of strings identifying devices or files to be used for “swap space” (see Memory Concepts in The GNU C Library Reference Manual). For example, '("/dev/sda3") or '("/swapfile"). It is possible to specify a swap file in a file system on a mapped device, provided that the necessary device mapping and file system are also specified. See Размеченные устройства and Файловые системы.

users (default: %base-user-accounts)
groups (default: %base-groups)

List of user accounts and groups. See Учётные записи пользователей.

If the users list lacks a user account with UID 0, a “root” account with UID 0 is automatically added.

skeletons (default: (default-skeletons))

A list target file name/file-like object tuples (see file-like objects). These are the skeleton files that will be added to the home directory of newly-created user accounts.

For instance, a valid value may look like this:

`((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
  (".guile" ,(plain-file "guile"
                         "(use-modules (ice-9 readline))
                          (activate-readline)")))
issue (default: %default-issue)

A string denoting the contents of the /etc/issue file, which is displayed when users log in on a text console.

packages (default: %base-packages)

The set of packages installed in the global profile, which is accessible at /run/current-system/profile.

The default set includes core utilities and it is good practice to install non-core utilities in user profiles (see Вызов guix package).

timezone

A timezone identifying string—e.g., "Europe/Paris".

You can run the tzselect command to find out which timezone string corresponds to your region. Choosing an invalid timezone name causes guix system to fail.

locale (default: "en_US.utf8")

The name of the default locale (see Locale Names in The GNU C Library Reference Manual). See Локали, for more information.

locale-definitions (default: %default-locale-definitions)

The list of locale definitions to be compiled and that may be used at run time. See Локали.

locale-libcs (default: (list glibc))

The list of GNU libc packages whose locale data and tools are used to build the locale definitions. See Локали, for compatibility considerations that justify this option.

name-service-switch (default: %default-nss)

Configuration of the libc name service switch (NSS)—a <name-service-switch> object. See Служба выбора имён, for details.

services (default: %base-services)

A list of service objects denoting system services. See Сервисы.

essential-services (default: ...)

The list of “essential services”—i.e., things like instances of system-service-type and host-name-service-type (see Интерфейс сервиса), which are derived from the operating system definition itself. As a user you should never need to touch this field.

pam-services (default: (base-pam-services))

Linux pluggable authentication module (PAM) services.

setuid-programs (default: %setuid-programs)

List of string-valued G-expressions denoting setuid programs. See Программы setuid.

sudoers-file (default: %sudoers-specification)

The contents of the /etc/sudoers file as a file-like object (see local-file and plain-file).

This file specifies which users can use the sudo command, what they are allowed to do, and what privileges they may gain. The default is that only root and members of the wheel group may use sudo.

Scheme Syntax: this-operating-system

When used in the lexical scope of an operating system field definition, this identifier resolves to the operating system being defined.

The example below shows how to refer to the operating system being defined in the definition of the label field:

(use-modules (gnu) (guix))

(operating-system
  ;; ...
  (label (package-full-name
          (operating-system-kernel this-operating-system))))

It is an error to refer to this-operating-system outside an operating system definition.


Next: , Previous: , Up: Конфигурирование системы   [Contents][Index]

8.3 Файловые системы

The list of file systems to be mounted is specified in the file-systems field of the operating system declaration (see Использование системы конфигурации). Each file system is declared using the file-system form, like this:

(file-system
  (mount-point "/home")
  (device "/dev/sda3")
  (type "ext4"))

As usual, some of the fields are mandatory—those shown in the example above—while others can be omitted. These are described below.

Data Type: file-system

Objects of this type represent file systems to be mounted. They contain the following members:

type

This is a string specifying the type of the file system—e.g., "ext4".

mount-point

This designates the place where the file system is to be mounted.

device

This names the “source” of the file system. It can be one of three things: a file system label, a file system UUID, or the name of a /dev node. Labels and UUIDs offer a way to refer to file systems without having to hard-code their actual device name24.

File system labels are created using the file-system-label procedure, UUIDs are created using uuid, and /dev node are plain strings. Here’s an example of a file system referred to by its label, as shown by the e2label command:

(file-system
  (mount-point "/home")
  (type "ext4")
  (device (file-system-label "my-home")))

UUIDs are converted from their string representation (as shown by the tune2fs -l command) using the uuid form25, like this:

(file-system
  (mount-point "/home")
  (type "ext4")
  (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))

When the source of a file system is a mapped device (see Размеченные устройства), its device field must refer to the mapped device name—e.g., "/dev/mapper/root-partition". This is required so that the system knows that mounting the file system depends on having the corresponding device mapping established.

flags (default: '())

This is a list of symbols denoting mount flags. Recognized flags include read-only, bind-mount, no-dev (disallow access to special files), no-suid (ignore setuid and setgid bits), no-atime (do not update file access times), and no-exec (disallow program execution). See Mount-Unmount-Remount in The GNU C Library Reference Manual, for more information on these flags.

options (default: #f)

This is either #f, or a string denoting mount options passed to the file system driver. See Mount-Unmount-Remount in The GNU C Library Reference Manual, for details and run man 8 mount for options for various file systems.

mount? (default: #t)

This value indicates whether to automatically mount the file system when the system is brought up. When set to #f, the file system gets an entry in /etc/fstab (read by the mount command) but is not automatically mounted.

needed-for-boot? (default: #f)

This Boolean value indicates whether the file system is needed when booting. If that is true, then the file system is mounted when the initial RAM disk (initrd) is loaded. This is always the case, for instance, for the root file system.

check? (default: #t)

This Boolean indicates whether the file system needs to be checked for errors before being mounted.

create-mount-point? (default: #f)

When true, the mount point is created if it does not exist yet.

dependencies (default: '())

This is a list of <file-system> or <mapped-device> objects representing file systems that must be mounted or mapped devices that must be opened before (and unmounted or closed after) this one.

As an example, consider a hierarchy of mounts: /sys/fs/cgroup is a dependency of /sys/fs/cgroup/cpu and /sys/fs/cgroup/memory.

Another example is a file system that depends on a mapped device, for example for an encrypted partition (see Размеченные устройства).

The (gnu system file-systems) exports the following useful variables.

Scheme Variable: %base-file-systems

These are essential file systems that are required on normal systems, such as %pseudo-terminal-file-system and %immutable-store (see below.) Operating system declarations should always contain at least these.

Scheme Variable: %pseudo-terminal-file-system

This is the file system to be mounted as /dev/pts. It supports pseudo-terminals created via openpty and similar functions (see Pseudo-Terminals in The GNU C Library Reference Manual). Pseudo-terminals are used by terminal emulators such as xterm.

Scheme Variable: %shared-memory-file-system

This file system is mounted as /dev/shm and is used to support memory sharing across processes (see shm_open in The GNU C Library Reference Manual).

Scheme Variable: %immutable-store

This file system performs a read-only “bind mount” of /gnu/store, making it read-only for all the users including root. This prevents against accidental modification by software running as root or by system administrators.

The daemon itself is still able to write to the store: it remounts it read-write in its own “name space.”

Scheme Variable: %binary-format-file-system

The binfmt_misc file system, which allows handling of arbitrary executable file types to be delegated to user space. This requires the binfmt.ko kernel module to be loaded.

Scheme Variable: %fuse-control-file-system

The fusectl file system, which allows unprivileged users to mount and unmount user-space FUSE file systems. This requires the fuse.ko kernel module to be loaded.


Next: , Previous: , Up: Конфигурирование системы   [Contents][Index]

8.4 Размеченные устройства

The Linux kernel has a notion of device mapping: a block device, such as a hard disk partition, can be mapped into another device, usually in /dev/mapper/, with additional processing over the data that flows through it26. A typical example is encryption device mapping: all writes to the mapped device are encrypted, and all reads are deciphered, transparently. Guix extends this notion by considering any device or set of devices that are transformed in some way to create a new device; for instance, RAID devices are obtained by assembling several other devices, such as hard disks or partitions, into a new one that behaves as one partition. Other examples, not yet implemented, are LVM logical volumes.

Mapped devices are declared using the mapped-device form, defined as follows; for examples, see below.

Data Type: mapped-device

Objects of this type represent device mappings that will be made when the system boots up.

source

This is either a string specifying the name of the block device to be mapped, such as "/dev/sda3", or a list of such strings when several devices need to be assembled for creating a new one.

target

This string specifies the name of the resulting mapped device. For kernel mappers such as encrypted devices of type luks-device-mapping, specifying "my-partition" leads to the creation of the "/dev/mapper/my-partition" device. For RAID devices of type raid-device-mapping, the full device name such as "/dev/md0" needs to be given.

type

This must be a mapped-device-kind object, which specifies how source is mapped to target.

Scheme Variable: luks-device-mapping

This defines LUKS block device encryption using the cryptsetup command from the package with the same name. It relies on the dm-crypt Linux kernel module.

Scheme Variable: raid-device-mapping

This defines a RAID device, which is assembled using the mdadm command from the package with the same name. It requires a Linux kernel module for the appropriate RAID level to be loaded, such as raid456 for RAID-4, RAID-5 or RAID-6, or raid10 for RAID-10.

The following example specifies a mapping from /dev/sda3 to /dev/mapper/home using LUKS—the Linux Unified Key Setup, a standard mechanism for disk encryption. The /dev/mapper/home device can then be used as the device of a file-system declaration (see Файловые системы).

(mapped-device
  (source "/dev/sda3")
  (target "home")
  (type luks-device-mapping))

Alternatively, to become independent of device numbering, one may obtain the LUKS UUID (unique identifier) of the source device by a command like:

cryptsetup luksUUID /dev/sda3

and use it as follows:

(mapped-device
  (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
  (target "home")
  (type luks-device-mapping))

It is also desirable to encrypt swap space, since swap space may contain sensitive data. One way to accomplish that is to use a swap file in a file system on a device mapped via LUKS encryption. In this way, the swap file is encrypted because the entire device is encrypted. See Disk Partitioning, for an example.

A RAID device formed of the partitions /dev/sda1 and /dev/sdb1 may be declared as follows:

(mapped-device
  (source (list "/dev/sda1" "/dev/sdb1"))
  (target "/dev/md0")
  (type raid-device-mapping))

The /dev/md0 device can then be used as the device of a file-system declaration (see Файловые системы). Note that the RAID level need not be given; it is chosen during the initial creation and formatting of the RAID device and is determined automatically later.


Next: , Previous: , Up: Конфигурирование системы   [Contents][Index]

8.5 Учётные записи пользователей

User accounts and groups are entirely managed through the operating-system declaration. They are specified with the user-account and user-group forms:

(user-account
  (name "alice")
  (group "users")
  (supplementary-groups '("wheel"   ;allow use of sudo, etc.
                          "audio"   ;sound card
                          "video"   ;video devices such as webcams
                          "cdrom")) ;the good ol' CD-ROM
  (comment "Bob's sister")
  (home-directory "/home/alice"))

When booting or upon completion of guix system reconfigure, the system ensures that only the user accounts and groups specified in the operating-system declaration exist, and with the specified properties. Thus, account or group creations or modifications made by directly invoking commands such as useradd are lost upon reconfiguration or reboot. This ensures that the system remains exactly as declared.

Data Type: user-account

Objects of this type represent user accounts. The following members may be specified:

name

The name of the user account.

group

This is the name (a string) or identifier (a number) of the user group this account belongs to.

supplementary-groups (default: '())

Optionally, this can be defined as a list of group names that this account belongs to.

uid (default: #f)

This is the user ID for this account (a number), or #f. In the latter case, a number is automatically chosen by the system when the account is created.

comment (default: "")

A comment about the account, such as the account owner’s full name.

home-directory

This is the name of the home directory for the account.

create-home-directory? (default: #t)

Indicates whether the home directory of this account should be created if it does not exist yet.

shell (default: Bash)

This is a G-expression denoting the file name of a program to be used as the shell (see G-Expressions).

system? (default: #f)

This Boolean value indicates whether the account is a “system” account. System accounts are sometimes treated specially; for instance, graphical login managers do not list them.

password (default: #f)

You would normally leave this field to #f, initialize user passwords as root with the passwd command, and then let users change it with passwd. Passwords set with passwd are of course preserved across reboot and reconfiguration.

If you do want to set an initial password for an account, then this field must contain the encrypted password, as a string. You can use the crypt procedure for this purpose:

(user-account
  (name "charlie")
  (group "users")

  ;; Specify a SHA-512-hashed initial password.
  (password (crypt "InitialPassword!" "$6$abc")))

Заметка: The hash of this initial password will be available in a file in /gnu/store, readable by all the users, so this method must be used with care.

See Passphrase Storage in The GNU C Library Reference Manual, for more information on password encryption, and Encryption in GNU Guile Reference Manual, for information on Guile’s crypt procedure.

User group declarations are even simpler:

(user-group (name "students"))
Data Type: user-group

This type is for, well, user groups. There are just a few fields:

name

The name of the group.

id (default: #f)

The group identifier (a number). If #f, a new number is automatically allocated when the group is created.

system? (default: #f)

This Boolean value indicates whether the group is a “system” group. System groups have low numerical IDs.

password (default: #f)

What, user groups can have a password? Well, apparently yes. Unless #f, this field specifies the password of the group.

For convenience, a variable lists all the basic user groups one may expect:

Scheme Variable: %base-groups

This is the list of basic user groups that users and/or packages expect to be present on the system. This includes groups such as “root”, “wheel”, and “users”, as well as groups used to control access to specific devices such as “audio”, “disk”, and “cdrom”.

Scheme Variable: %base-user-accounts

This is the list of basic system accounts that programs may expect to find on a GNU/Linux system, such as the “nobody” account.

Note that the “root” account is not included here. It is a special-case and is automatically added whether or not it is specified.


Next: , Previous: , Up: Конфигурирование системы   [Contents][Index]

8.6 Раскладка клавиатуры

To specify what each key of your keyboard does, you need to tell the operating system what keyboard layout you want to use. The default, when nothing is specified, is the US English QWERTY layout for 105-key PC keyboards. However, German speakers will usually prefer the German QWERTZ layout, French speakers will want the AZERTY layout, and so on; hackers might prefer Dvorak or bépo, and they might even want to further customize the effect of some of the keys. This section explains how to get that done.

There are three components that will want to know about your keyboard layout:

Guix allows you to configure all three separately but, fortunately, it allows you to share the same keyboard layout for all three components.

Keyboard layouts are represented by records created by the keyboard-layout procedure of (gnu system keyboard). Following the X Keyboard extension (XKB), each layout has four attributes: a name (often a language code such as “fi” for Finnish or “jp” for Japanese), an optional variant name, an optional keyboard model name, and a possibly empty list of additional options. In most cases the layout name is all you care about. Here are a few example:

;; The German QWERTZ layout.  Here we assume a standard
;; "pc105" keyboard model.
(keyboard-layout "de")

;; The bépo variant of the French layout.
(keyboard-layout "fr" "bepo")

;; The Catalan layout.
(keyboard-layout "es" "cat")

;; The Latin American Spanish layout.  In addition, the
;; "Caps Lock" key is used as an additional "Ctrl" key,
;; and the "Menu" key is used as a "Compose" key to enter
;; accented letters.
(keyboard-layout "latam"
                 #:options '("ctrl:nocaps" "compose:menu"))

;; The Russian layout for a ThinkPad keyboard.
(keyboard-layout "ru" #:model "thinkpad")

;; The "US international" layout, which is the US layout plus
;; dead keys to enter accented characters.  This is for an
;; Apple MacBook keyboard.
(keyboard-layout "us" "intl" #:model "macbook78")

See the share/X11/xkb directory of the xkeyboard-config package for a complete list of supported layouts, variants, and models.

Let’s say you want your system to use the Turkish keyboard layout throughout your system—bootloader, console, and Xorg. Here’s what your system configuration would look like:

;; Using the Turkish layout for the bootloader, the console,
;; and for Xorg.

(operating-system
  ;; ...
  (keyboard-layout (keyboard-layout "tr"))  ;for the console
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")
                (keyboard-layout keyboard-layout))) ;for GRUB
  (services (cons (set-xorg-configuration
                    (xorg-configuration             ;for Xorg
                      (keyboard-layout keyboard-layout)))
                  %desktop-services)))

In the example above, for GRUB and for Xorg, we just refer to the keyboard-layout field defined above, but we could just as well refer to a different layout. The set-xorg-configuration procedure communicates the desired Xorg configuration to the graphical log-in manager, by default GDM.

We’ve discussed how to specify the default keyboard layout of your system when it starts, but you can also adjust it at run time:


Next: , Previous: , Up: Конфигурирование системы   [Contents][Index]

8.7 Локали

A locale defines cultural conventions for a particular language and region of the world (see Локали in The GNU C Library Reference Manual). Each locale has a name that typically has the form language_territory.codeset—e.g., fr_LU.utf8 designates the locale for the French language, with cultural conventions from Luxembourg, and using the UTF-8 encoding.

Usually, you will want to specify the default locale for the machine using the locale field of the operating-system declaration (see locale).

The selected locale is automatically added to the locale definitions known to the system if needed, with its codeset inferred from its name—e.g., bo_CN.utf8 will be assumed to use the UTF-8 codeset. Additional locale definitions can be specified in the locale-definitions slot of operating-system—this is useful, for instance, if the codeset could not be inferred from the locale name. The default set of locale definitions includes some widely used locales, but not all the available locales, in order to save space.

For instance, to add the North Frisian locale for Germany, the value of that field may be:

(cons (locale-definition
        (name "fy_DE.utf8") (source "fy_DE"))
      %default-locale-definitions)

Likewise, to save space, one might want locale-definitions to list only the locales that are actually used, as in:

(list (locale-definition
        (name "ja_JP.eucjp") (source "ja_JP")
        (charset "EUC-JP")))

The compiled locale definitions are available at /run/current-system/locale/X.Y, where X.Y is the libc version, which is the default location where the GNU libc provided by Guix looks for locale data. This can be overridden using the LOCPATH environment variable (see LOCPATH and locale packages).

The locale-definition form is provided by the (gnu system locale) module. Details are given below.

Data Type: locale-definition

This is the data type of a locale definition.

name

The name of the locale. See Locale Names in The GNU C Library Reference Manual, for more information on locale names.

source

The name of the source for that locale. This is typically the language_territory part of the locale name.

charset (default: "UTF-8")

The “character set” or “code set” for that locale, as defined by IANA.

Scheme Variable: %default-locale-definitions

A list of commonly used UTF-8 locales, used as the default value of the locale-definitions field of operating-system declarations.

These locale definitions use the normalized codeset for the part that follows the dot in the name (see normalized codeset in The GNU C Library Reference Manual). So for instance it has uk_UA.utf8 but not, say, uk_UA.UTF-8.

8.7.1 Locale Data Compatibility Considerations

operating-system declarations provide a locale-libcs field to specify the GNU libc packages that are used to compile locale declarations (see Интерфейс operating-system). “Why would I care?”, you may ask. Well, it turns out that the binary format of locale data is occasionally incompatible from one libc version to another.

For instance, a program linked against libc version 2.21 is unable to read locale data produced with libc 2.22; worse, that program aborts instead of simply ignoring the incompatible locale data27. Similarly, a program linked against libc 2.22 can read most, but not all, of the locale data from libc 2.21 (specifically, LC_COLLATE data is incompatible); thus calls to setlocale may fail, but programs will not abort.

The “problem” with Guix is that users have a lot of freedom: They can choose whether and when to upgrade software in their profiles, and might be using a libc version different from the one the system administrator used to build the system-wide locale data.

Fortunately, unprivileged users can also install their own locale data and define GUIX_LOCPATH accordingly (see GUIX_LOCPATH and locale packages).

Still, it is best if the system-wide locale data at /run/current-system/locale is built for all the libc versions actually in use on the system, so that all the programs can access it—this is especially crucial on a multi-user system. To do that, the administrator can specify several libc packages in the locale-libcs field of operating-system:

(use-package-modules base)

(operating-system
  ;; …
  (locale-libcs (list glibc-2.21 (canonical-package glibc))))

This example would lead to a system containing locale definitions for both libc 2.21 and the current version of libc in /run/current-system/locale.


Next: , Previous: , Up: Конфигурирование системы   [Contents][Index]

8.8 Сервисы

An important part of preparing an operating-system declaration is listing system services and their configuration (see Использование системы конфигурации). System services are typically daemons launched when the system boots, or other actions needed at that time—e.g., configuring network access.

Guix has a broad definition of “service” (see Производство сервисов.), but many services are managed by the GNU Shepherd (see Сервисы Shepherd). On a running system, the herd command allows you to list the available services, show their status, start and stop them, or do other specific operations (see Jump Start in The GNU Shepherd Manual). For example:

# herd status

The above command, run as root, lists the currently defined services. The herd doc command shows a synopsis of the given service and its associated actions:

# herd doc nscd
Run libc's name service cache daemon (nscd).

# herd doc nscd action invalidate
invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.

The start, stop, and restart sub-commands have the effect you would expect. For instance, the commands below stop the nscd service and restart the Xorg display server:

# herd stop nscd
Service nscd has been stopped.
# herd restart xorg-server
Service xorg-server has been stopped.
Service xorg-server has been started.

The following sections document the available services, starting with the core services, that may be used in an operating-system declaration.


Next: , Up: Сервисы   [Contents][Index]

8.8.1 Базовые сервисы

The (gnu services base) module provides definitions for the basic services that one expects from the system. The services exported by this module are listed below.

Scheme Variable: %base-services

This variable contains a list of basic services (see Типы сервисов и сервисы, for more information on service objects) one would expect from the system: a login service (mingetty) on each tty, syslogd, the libc name service cache daemon (nscd), the udev device manager, and more.

This is the default value of the services field of operating-system declarations. Usually, when customizing a system, you will want to append services to %base-services, like this:

(append (list (service avahi-service-type)
              (service openssh-service-type))
        %base-services)
Scheme Variable: special-files-service-type

This is the service that sets up “special files” such as /bin/sh; an instance of it is part of %base-services.

The value associated with special-files-service-type services must be a list of tuples where the first element is the “special file” and the second element is its target. By default it is:

`(("/bin/sh" ,(file-append bash "/bin/sh")))

If you want to add, say, /usr/bin/env to your system, you can change it to:

`(("/bin/sh" ,(file-append bash "/bin/sh"))
  ("/usr/bin/env" ,(file-append coreutils "/bin/env")))

Since this is part of %base-services, you can use modify-services to customize the set of special files (see modify-services). But the simple way to add a special file is via the extra-special-file procedure (see below.)

Scheme Procedure: extra-special-file file target

Use target as the “special file” file.

For example, adding the following lines to the services field of your operating system declaration leads to a /usr/bin/env symlink:

(extra-special-file "/usr/bin/env"
                    (file-append coreutils "/bin/env"))
Scheme Procedure: host-name-service name

Return a service that sets the host name to name.

Scheme Procedure: login-service config

Return a service to run login according to config, a <login-configuration> object, which specifies the message of the day, among other things.

Data Type: login-configuration

This is the data type representing the configuration of login.

motd

A file-like object containing the “message of the day”.

allow-empty-passwords? (default: #t)

Allow empty passwords by default so that first-time users can log in when the ’root’ account has just been created.

Scheme Procedure: mingetty-service config

Return a service to run mingetty according to config, a <mingetty-configuration> object, which specifies the tty to run, among other things.

Data Type: mingetty-configuration

This is the data type representing the configuration of Mingetty, which provides the default implementation of virtual console log-in.

tty

The name of the console this Mingetty runs on—e.g., "tty1".

auto-login (default: #f)

When true, this field must be a string denoting the user name under which the system automatically logs in. When it is #f, a user name and password must be entered to log in.

login-program (default: #f)

This must be either #f, in which case the default log-in program is used (login from the Shadow tool suite), or a gexp denoting the name of the log-in program.

login-pause? (default: #f)

When set to #t in conjunction with auto-login, the user will have to press a key before the log-in shell is launched.

mingetty (default: mingetty)

The Mingetty package to use.

Scheme Procedure: agetty-service config

Return a service to run agetty according to config, an <agetty-configuration> object, which specifies the tty to run, among other things.

Data Type: agetty-configuration

This is the data type representing the configuration of agetty, which implements virtual and serial console log-in. See the agetty(8) man page for more information.

tty

The name of the console this agetty runs on, as a string—e.g., "ttyS0". This argument is optional, it will default to a reasonable default serial port used by the kernel Linux.

For this, if there is a value for an option agetty.tty in the kernel command line, agetty will extract the device name of the serial port from it and use that.

If not and if there is a value for an option console with a tty in the Linux command line, agetty will extract the device name of the serial port from it and use that.

In both cases, agetty will leave the other serial device settings (baud rate etc.) alone—in the hope that Linux pinned them to the correct values.

baud-rate (default: #f)

A string containing a comma-separated list of one or more baud rates, in descending order.

term (default: #f)

A string containing the value used for the TERM environment variable.

eight-bits? (default: #f)

When #t, the tty is assumed to be 8-bit clean, and parity detection is disabled.

auto-login (default: #f)

When passed a login name, as a string, the specified user will be logged in automatically without prompting for their login name or password.

no-reset? (default: #f)

When #t, don’t reset terminal cflags (control modes).

host (default: #f)

This accepts a string containing the "login_host", which will be written into the /var/run/utmpx file.

remote? (default: #f)

When set to #t in conjunction with host, this will add an -r fakehost option to the command line of the login program specified in login-program.

flow-control? (default: #f)

When set to #t, enable hardware (RTS/CTS) flow control.

no-issue? (default: #f)

When set to #t, the contents of the /etc/issue file will not be displayed before presenting the login prompt.

init-string (default: #f)

This accepts a string that will be sent to the tty or modem before sending anything else. It can be used to initialize a modem.

no-clear? (default: #f)

When set to #t, agetty will not clear the screen before showing the login prompt.

login-program (default: (file-append shadow "/bin/login"))

This must be either a gexp denoting the name of a log-in program, or unset, in which case the default value is the login from the Shadow tool suite.

local-line (default: #f)

Control the CLOCAL line flag. This accepts one of three symbols as arguments, 'auto, 'always, or 'never. If #f, the default value chosen by agetty is 'auto.

extract-baud? (default: #f)

When set to #t, instruct agetty to try to extract the baud rate from the status messages produced by certain types of modems.

skip-login? (default: #f)

When set to #t, do not prompt the user for a login name. This can be used with login-program field to use non-standard login systems.

no-newline? (default: #f)

When set to #t, do not print a newline before printing the /etc/issue file.

login-options (default: #f)

This option accepts a string containing options that are passed to the login program. When used with the login-program, be aware that a malicious user could try to enter a login name containing embedded options that could be parsed by the login program.

login-pause (default: #f)

When set to #t, wait for any key before showing the login prompt. This can be used in conjunction with auto-login to save memory by lazily spawning shells.

chroot (default: #f)

Change root to the specified directory. This option accepts a directory path as a string.

hangup? (default: #f)

Use the Linux system call vhangup to do a virtual hangup of the specified terminal.

keep-baud? (default: #f)

When set to #t, try to keep the existing baud rate. The baud rates from baud-rate are used when agetty receives a BREAK character.

timeout (default: #f)

When set to an integer value, terminate if no user name could be read within timeout seconds.

detect-case? (default: #f)

When set to #t, turn on support for detecting an uppercase-only terminal. This setting will detect a login name containing only uppercase letters as indicating an uppercase-only terminal and turn on some upper-to-lower case conversions. Note that this will not support Unicode characters.

wait-cr? (default: #f)

When set to #t, wait for the user or modem to send a carriage-return or linefeed character before displaying /etc/issue or login prompt. This is typically used with the init-string option.

no-hints? (default: #f)

When set to #t, do not print hints about Num, Caps, and Scroll locks.

no-hostname? (default: #f)

By default, the hostname is printed. When this option is set to #t, no hostname will be shown at all.

long-hostname? (default: #f)

By default, the hostname is only printed until the first dot. When this option is set to #t, the fully qualified hostname by gethostname or getaddrinfo is shown.

erase-characters (default: #f)

This option accepts a string of additional characters that should be interpreted as backspace when the user types their login name.

kill-characters (default: #f)

This option accepts a string that should be interpreted to mean "ignore all previous characters" (also called a "kill" character) when the user types their login name.

chdir (default: #f)

This option accepts, as a string, a directory path that will be changed to before login.

delay (default: #f)

This options accepts, as an integer, the number of seconds to sleep before opening the tty and displaying the login prompt.

nice (default: #f)

This option accepts, as an integer, the nice value with which to run the login program.

extra-options (default: '())

This option provides an "escape hatch" for the user to provide arbitrary command-line arguments to agetty as a list of strings.

Scheme Procedure: kmscon-service-type config

Return a service to run kmscon according to config, a <kmscon-configuration> object, which specifies the tty to run, among other things.

Data Type: kmscon-configuration

This is the data type representing the configuration of Kmscon, which implements virtual console log-in.

virtual-terminal

The name of the console this Kmscon runs on—e.g., "tty1".

login-program (default: #~(string-append #$shadow "/bin/login"))

A gexp denoting the name of the log-in program. The default log-in program is login from the Shadow tool suite.

login-arguments (default: '("-p"))

A list of arguments to pass to login.

auto-login (default: #f)

When passed a login name, as a string, the specified user will be logged in automatically without prompting for their login name or password.

hardware-acceleration? (default: #f)

Whether to use hardware acceleration.

kmscon (default: kmscon)

The Kmscon package to use.

Scheme Procedure: nscd-service [config] [#:glibc glibc] [#:name-services '()] Return a service that runs the libc name service cache

daemon (nscd) with the given config—an <nscd-configuration> object. See Служба выбора имён, for an example.

For convenience, the Shepherd service for nscd provides the following actions:

invalidate

This invalidate the given cache. For instance, running:

herd invalidate nscd hosts

invalidates the host name lookup cache of nscd.

statistics

Running herd statistics nscd displays information about nscd usage and caches.

Scheme Variable: %nscd-default-configuration

This is the default <nscd-configuration> value (see below) used by nscd-service. It uses the caches defined by %nscd-default-caches; see below.

Data Type: nscd-configuration

This is the data type representing the name service cache daemon (nscd) configuration.

name-services (default: '())

List of packages denoting name services that must be visible to the nscd—e.g., (list nss-mdns).

glibc (default: glibc)

Package object denoting the GNU C Library providing the nscd command.

log-file (default: "/var/log/nscd.log")

Name of the nscd log file. This is where debugging output goes when debug-level is strictly positive.

debug-level (default: 0)

Integer denoting the debugging levels. Higher numbers mean that more debugging output is logged.

caches (default: %nscd-default-caches)

List of <nscd-cache> objects denoting things to be cached; see below.

Data Type: nscd-cache

Data type representing a cache database of nscd and its parameters.

database

This is a symbol representing the name of the database to be cached. Valid values are passwd, group, hosts, and services, which designate the corresponding NSS database (see NSS Basics in The GNU C Library Reference Manual).

positive-time-to-live
negative-time-to-live (default: 20)

A number representing the number of seconds during which a positive or negative lookup result remains in cache.

check-files? (default: #t)

Whether to check for updates of the files corresponding to database.

For instance, when database is hosts, setting this flag instructs nscd to check for updates in /etc/hosts and to take them into account.

persistent? (default: #t)

Whether the cache should be stored persistently on disk.

shared? (default: #t)

Whether the cache should be shared among users.

max-database-size (default: 32 MiB)

Maximum size in bytes of the database cache.

Scheme Variable: %nscd-default-caches

List of <nscd-cache> objects used by default by nscd-configuration (see above).

It enables persistent and aggressive caching of service and host name lookups. The latter provides better host name lookup performance, resilience in the face of unreliable name servers, and also better privacy—often the result of host name lookups is in local cache, so external name servers do not even need to be queried.

Data Type: syslog-configuration

This data type represents the configuration of the syslog daemon.

syslogd (default: #~(string-append #$inetutils "/libexec/syslogd"))

The syslog daemon to use.

config-file (default: %default-syslog.conf)

The syslog configuration file to use.

Scheme Procedure: syslog-service config

Return a service that runs a syslog daemon according to config.

See syslogd invocation in GNU Inetutils, for more information on the configuration file syntax.

Scheme Variable: guix-service-type

This is the type of the service that runs the build daemon, guix-daemon (see Вызов guix-daemon). Its value must be a guix-configuration record as described below.

Data Type: guix-configuration

This data type represents the configuration of the Guix build daemon. See Вызов guix-daemon, for more information.

guix (default: guix)

The Guix package to use.

build-group (default: "guixbuild")

Name of the group for build user accounts.

build-accounts (default: 10)

Number of build user accounts to create.

authorize-key? (default: #t)

Whether to authorize the substitute keys listed in authorized-keys—by default that of ci.guix.gnu.org (see Подстановки).

authorized-keys (default: %default-authorized-guix-keys)

The list of authorized key files for archive imports, as a list of string-valued gexps (see Вызов guix archive). By default, it contains that of ci.guix.gnu.org (see Подстановки).

use-substitutes? (default: #t)

Whether to use substitutes.

substitute-urls (default: %default-substitute-urls)

The list of URLs where to look for substitutes by default.

max-silent-time (default: 0)
timeout (default: 0)

The number of seconds of silence and the number of seconds of activity, respectively, after which a build process times out. A value of zero disables the timeout.

log-compression (default: 'bzip2)

The type of compression used for build logs—one of gzip, bzip2, or none.

extra-options (default: '())

List of extra command-line options for guix-daemon.

log-file (default: "/var/log/guix-daemon.log")

File where guix-daemon’s standard output and standard error are written.

http-proxy (default: #f)

The HTTP proxy used for downloading fixed-output derivations and substitutes.

tmpdir (default: #f)

A directory path where the guix-daemon will perform builds.

Scheme Procedure: udev-service [#:udev eudev #:rules '()]

Run udev, which populates the /dev directory dynamically. udev rules can be provided as a list of files through the rules variable. The procedures udev-rule and file->udev-rule from (gnu services base) simplify the creation of such rule files.

Scheme Procedure: udev-rule [file-name contents]

Return a udev-rule file named file-name containing the rules defined by the contents literal.

In the following example, a rule for a USB device is defined to be stored in the file 90-usb-thing.rules. The rule runs a script upon detecting a USB device with a given product identifier.

(define %example-udev-rule
  (udev-rule
    "90-usb-thing.rules"
    (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
                   "ATTR{product}==\"Example\", "
                   "RUN+=\"/path/to/script\"")))

The herd rules udev command, as root, returns the name of the directory containing all the active udev rules.

Here we show how the default udev-service can be extended with it.

(operating-system
 ;; …
 (services
 (modify-services %desktop-services
   (udev-service-type config =>
     (udev-configuration (inherit config)
      (rules (append (udev-configuration-rules config)
                     (list %example-udev-rule))))))))
Scheme Procedure: file->udev-rule [file-name file]

Return a udev file named file-name containing the rules defined within file, a file-like object.

The following example showcases how we can use an existing rule file.

(use-modules (guix download)     ;for url-fetch
             (guix packages)     ;for origin
             ;; …)

(define %android-udev-rules
  (file->udev-rule
    "51-android-udev.rules"
    (let ((version "20170910"))
      (origin
       (method url-fetch)
       (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
                           "android-udev-rules/" version "/51-android.rules"))
       (sha256
        (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))

Additionally, Guix package definitions can be included in rules in order to extend the udev rules with the definitions found under their lib/udev/rules.d sub-directory. In lieu of the previous file->udev-rule example, we could have used the android-udev-rules package which exists in Guix in the (gnu packages android) module.

The following example shows how to use the android-udev-rules package so that the Android tool adb can detect devices without root privileges. It also details how to create the adbusers group, which is required for the proper functioning of the rules defined within the android-udev-rules package. To create such a group, we must define it both as part of the supplementary-groups of our user-account declaration, as well as in the groups field of the operating-system record.

(use-modules (gnu packages android)  ;for android-udev-rules
             (gnu system shadow)     ;for user-group
             ;; …)

(operating-system
  ;; …
  (users (cons (user-acount
                ;; …
                (supplementary-groups
                 '("adbusers"   ;for adb
                   "wheel" "netdev" "audio" "video"))
                ;; …)))

  (groups (cons (user-group (system? #t) (name "adbusers"))
                %base-groups))

  ;; …

  (services
   (modify-services %desktop-services
     (udev-service-type
      config =>
      (udev-configuration (inherit config)
                          (rules (cons android-udev-rules
                                       (udev-configuration-rules config))))))))
Scheme Variable: urandom-seed-service-type

Save some entropy in %random-seed-file to seed /dev/urandom when rebooting. It also tries to seed /dev/urandom from /dev/hwrng while booting, if /dev/hwrng exists and is readable.

Scheme Variable: %random-seed-file

This is the name of the file where some random bytes are saved by urandom-seed-service to seed /dev/urandom when rebooting. It defaults to /var/lib/random-seed.

Scheme Variable: gpm-service-type

This is the type of the service that runs GPM, the general-purpose mouse daemon, which provides mouse support to the Linux console. GPM allows users to use the mouse in the console, notably to select, copy, and paste text.

The value for services of this type must be a gpm-configuration (see below). This service is not part of %base-services.

Data Type: gpm-configuration

Data type representing the configuration of GPM.

options (default: %default-gpm-options)

Command-line options passed to gpm. The default set of options instruct gpm to listen to mouse events on /dev/input/mice. See Command Line in gpm manual, for more information.

gpm (default: gpm)

The GPM package to use.

Scheme Variable: guix-publish-service-type

This is the service type for guix publish (see Вызов guix publish). Its value must be a guix-configuration object, as described below.

This assumes that /etc/guix already contains a signing key pair as created by guix archive --generate-key (see Вызов guix archive). If that is not the case, the service will fail to start.

Data Type: guix-publish-configuration

Data type representing the configuration of the guix publish service.

guix (default: guix)

The Guix package to use.

port (default: 80)

The TCP port to listen for connections.

host (default: "localhost")

The host (and thus, network interface) to listen to. Use "0.0.0.0" to listen on all the network interfaces.

compression-level (default: 3)

The gzip compression level at which substitutes are compressed. Use 0 to disable compression altogether, and 9 to get the best compression ratio at the expense of increased CPU usage.

nar-path (default: "nar")

The URL path at which “nars” can be fetched. See --nar-path, for details.

cache (default: #f)

When it is #f, disable caching and instead generate archives on demand. Otherwise, this should be the name of a directory—e.g., "/var/cache/guix/publish"—where guix publish caches archives and meta-data ready to be sent. See --cache, for more information on the tradeoffs involved.

workers (default: #f)

When it is an integer, this is the number of worker threads used for caching; when #f, the number of processors is used. See --workers, for more information.

ttl (default: #f)

When it is an integer, this denotes the time-to-live in seconds of the published archives. See --ttl, for more information.

Scheme Procedure: rngd-service [#:rng-tools rng-tools] [#:device "/dev/hwrng"] Return a service that runs the rngd

program from rng-tools to add device to the kernel’s entropy pool. The service will fail if device does not exist.

Scheme Procedure: pam-limits-service [#:limits '()]

Return a service that installs a configuration file for the pam_limits module. The procedure optionally takes a list of pam-limits-entry values, which can be used to specify ulimit limits and nice priority limits to user sessions.

The following limits definition sets two hard and soft limits for all login sessions of users in the realtime group:

(pam-limits-service
 (list
  (pam-limits-entry "@realtime" 'both 'rtprio 99)
  (pam-limits-entry "@realtime" 'both 'memlock 'unlimited)))

The first entry increases the maximum realtime priority for non-privileged processes; the second entry lifts any restriction of the maximum address space that can be locked in memory. These settings are commonly used for real-time audio systems.


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.2 Запланированное исполнения задач

The (gnu services mcron) module provides an interface to GNU mcron, a daemon to run jobs at scheduled times (see GNU mcron). GNU mcron is similar to the traditional Unix cron daemon; the main difference is that it is implemented in Guile Scheme, which provides a lot of flexibility when specifying the scheduling of jobs and their actions.

The example below defines an operating system that runs the updatedb (see Invoking updatedb in Finding Files) and the guix gc commands (see Вызов guix gc) daily, as well as the mkid command on behalf of an unprivileged user (see mkid invocation in ID Database Utilities). It uses gexps to introduce job definitions that are passed to mcron (see G-Expressions).

(use-modules (guix) (gnu) (gnu services mcron))
(use-package-modules base idutils)

(define updatedb-job
  ;; Run 'updatedb' at 3AM every day.  Here we write the
  ;; job's action as a Scheme procedure.
  #~(job '(next-hour '(3))
         (lambda ()
           (execl (string-append #$findutils "/bin/updatedb")
                  "updatedb"
                  "--prunepaths=/tmp /var/tmp /gnu/store"))))

(define garbage-collector-job
  ;; Collect garbage 5 minutes after midnight every day.
  ;; The job's action is a shell command.
  #~(job "5 0 * * *"            ;Vixie cron syntax
         "guix gc -F 1G"))

(define idutils-job
  ;; Update the index database as user "charlie" at 12:15PM
  ;; and 19:15PM.  This runs from the user's home directory.
  #~(job '(next-minute-from (next-hour '(12 19)) '(15))
         (string-append #$idutils "/bin/mkid src")
         #:user "charlie"))

(operating-system
  ;; …
  (services (cons (service mcron-service-type
                           (mcron-configuration
                            (jobs (list garbage-collector-job
                                        updatedb-job
                                        idutils-job))))
                  %base-services)))

See mcron job specifications in GNU mcron, for more information on mcron job specifications. Below is the reference of the mcron service.

On a running system, you can use the schedule action of the service to visualize the mcron jobs that will be executed next:

# herd schedule mcron

The example above lists the next five tasks that will be executed, but you can also specify the number of tasks to display:

# herd schedule mcron 10
Scheme Variable: mcron-service-type

This is the type of the mcron service, whose value is an mcron-configuration object.

This service type can be the target of a service extension that provides it additional job specifications (see Производство сервисов.). In other words, it is possible to define services that provide additional mcron jobs to run.

Data Type: mcron-configuration

Data type representing the configuration of mcron.

mcron (default: mcron)

The mcron package to use.

jobs

This is a list of gexps (see G-Expressions), where each gexp corresponds to an mcron job specification (see mcron job specifications in GNU mcron).


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.3 Ротация логов

Log files such as those found in /var/log tend to grow endlessly, so it’s a good idea to rotate them once in a while—i.e., archive their contents in separate files, possibly compressed. The (gnu services admin) module provides an interface to GNU Rot[t]log, a log rotation tool (see GNU Rot[t]log Manual).

The example below defines an operating system that provides log rotation with the default settings, for commonly encountered log files.

(use-modules (guix) (gnu))
(use-service-modules admin mcron)
(use-package-modules base idutils)

(operating-system
  ;; …
  (services (cons (service rottlog-service-type)
                  %base-services)))
Scheme Variable: rottlog-service-type

This is the type of the Rottlog service, whose value is a rottlog-configuration object.

Other services can extend this one with new log-rotation objects (see below), thereby augmenting the set of files to be rotated.

This service type can define mcron jobs (see Запланированное исполнения задач) to run the rottlog service.

Data Type: rottlog-configuration

Data type representing the configuration of rottlog.

rottlog (default: rottlog)

The Rottlog package to use.

rc-file (default: (file-append rottlog "/etc/rc"))

The Rottlog configuration file to use (see Mandatory RC Variables in GNU Rot[t]log Manual).

rotations (default: %default-rotations)

A list of log-rotation objects as defined below.

jobs

This is a list of gexps where each gexp corresponds to an mcron job specification (see Запланированное исполнения задач).

Data Type: log-rotation

Data type representing the rotation of a group of log files.

Taking an example from the Rottlog manual (see Period Related File Examples in GNU Rot[t]log Manual), a log rotation might be defined like this:

(log-rotation
  (frequency 'daily)
  (files '("/var/log/apache/*"))
  (options '("storedir apache-archives"
             "rotate 6"
             "notifempty"
             "nocompress")))

The list of fields is as follows:

frequency (default: 'weekly)

The log rotation frequency, a symbol.

files

The list of files or file glob patterns to rotate.

options (default: '())

The list of rottlog options for this rotation (see Configuration parameters in GNU Rot[t]lg Manual).

post-rotate (default: #f)

Either #f or a gexp to execute once the rotation has completed.

Scheme Variable: %default-rotations

Specifies weekly rotation of %rotated-files and a couple of other files.

Scheme Variable: %rotated-files

The list of syslog-controlled files to be rotated. By default it is: '("/var/log/messages" "/var/log/secure").


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.4 Сервисы сети

The (gnu services networking) module provides services to configure the network interface.

Scheme Variable: dhcp-client-service-type

This is the type of services that run dhcp, a Dynamic Host Configuration Protocol (DHCP) client, on all the non-loopback network interfaces. Its value is the DHCP client package to use, isc-dhcp by default.

Scheme Procedure: dhcpd-service-type

This type defines a service that runs a DHCP daemon. To create a service of this type, you must supply a <dhcpd-configuration>. For example:

(service dhcpd-service-type
         (dhcpd-configuration
          (config-file (local-file "my-dhcpd.conf"))
          (interfaces '("enp0s25"))))
Data Type: dhcpd-configuration
package (default: isc-dhcp)

The package that provides the DHCP daemon. This package is expected to provide the daemon at sbin/dhcpd relative to its output directory. The default package is the ISC’s DHCP server.

config-file (default: #f)

The configuration file to use. This is required. It will be passed to dhcpd via its -cf option. This may be any “file-like” object (see file-like objects). See man dhcpd.conf for details on the configuration file syntax.

version (default: "4")

The DHCP version to use. The ISC DHCP server supports the values “4”, “6”, and “4o6”. These correspond to the dhcpd program options -4, -6, and -4o6. See man dhcpd for details.

run-directory (default: "/run/dhcpd")

The run directory to use. At service activation time, this directory will be created if it does not exist.

pid-file (default: "/run/dhcpd/dhcpd.pid")

The PID file to use. This corresponds to the -pf option of dhcpd. See man dhcpd for details.

interfaces (default: '())

The names of the network interfaces on which dhcpd should listen for broadcasts. If this list is not empty, then its elements (which must be strings) will be appended to the dhcpd invocation when starting the daemon. It may not be necessary to explicitly specify any interfaces here; see man dhcpd for details.

Scheme Variable: static-networking-service-type

This is the type for statically-configured network interfaces.

Scheme Procedure: static-networking-service interface ip [#:netmask #f] [#:gateway #f] [#:name-servers '()]  [#:requirement

'(udev)] Return a service that starts interface with address ip. If netmask is true, use it as the network mask. If gateway is true, it must be a string specifying the default network gateway. requirement can be used to declare a dependency on another service before configuring the interface.

This procedure can be called several times, one for each network interface of interest. Behind the scenes what it does is extend static-networking-service-type with additional network interfaces to handle.

For example:

(static-networking-service "eno1" "192.168.1.82"
                           #:gateway "192.168.1.2"
                           #:name-servers '("192.168.1.2"))
Scheme Procedure: wicd-service [#:wicd wicd]

Return a service that runs Wicd, a network management daemon that aims to simplify wired and wireless networking.

This service adds the wicd package to the global profile, providing several commands to interact with the daemon and configure networking: wicd-client, a graphical user interface, and the wicd-cli and wicd-curses user interfaces.

Scheme Variable: modem-manager-service-type

This is the service type for the ModemManager service. The value for this service type is a modem-manager-configuration record.

This service is part of %desktop-services (see Сервисы рабочего стола).

Data Type: modem-manager-configuration

Data type representing the configuration of ModemManager.

modem-manager (default: modem-manager)

The ModemManager package to use.

Scheme Variable: network-manager-service-type

This is the service type for the NetworkManager service. The value for this service type is a network-manager-configuration record.

This service is part of %desktop-services (see Сервисы рабочего стола).

Data Type: network-manager-configuration

Data type representing the configuration of NetworkManager.

network-manager (default: network-manager)

The NetworkManager package to use.

dns (default: "default")

Processing mode for DNS, which affects how NetworkManager uses the resolv.conf configuration file.

default

NetworkManager will update resolv.conf to reflect the nameservers provided by currently active connections.

dnsmasq

NetworkManager will run dnsmasq as a local caching nameserver, using a "split DNS" configuration if you are connected to a VPN, and then update resolv.conf to point to the local nameserver.

none

NetworkManager will not modify resolv.conf.

vpn-plugins (default: '())

This is the list of available plugins for virtual private networks (VPNs). An example of this is the network-manager-openvpn package, which allows NetworkManager to manage VPNs via OpenVPN.

Scheme Variable: connman-service-type

This is the service type to run Connman, a network connection manager.

Its value must be an connman-configuration record as in this example:

(service connman-service-type
         (connman-configuration
           (disable-vpn? #t)))

See below for details about connman-configuration.

Data Type: connman-configuration

Data Type representing the configuration of connman.

connman (default: connman)

The connman package to use.

disable-vpn? (default: #f)

When true, disable connman’s vpn plugin.

Scheme Variable: wpa-supplicant-service-type

This is the service type to run WPA supplicant, an authentication daemon required to authenticate against encrypted WiFi or ethernet networks.

Data Type: wpa-supplicant-configuration

Data type representing the configuration of WPA Supplicant.

It takes the following parameters:

wpa-supplicant (default: wpa-supplicant)

The WPA Supplicant package to use.

dbus? (default: #t)

Whether to listen for requests on D-Bus.

pid-file (default: "/var/run/wpa_supplicant.pid")

Where to store the PID file.

interface (default: #f)

If this is set, it must specify the name of a network interface that WPA supplicant will control.

config-file (default: #f)

Optional configuration file to use.

extra-options (default: '())

List of additional command-line arguments to pass to the daemon.

Scheme Variable: iptables-service-type

This is the service type to set up an iptables configuration. iptables is a packet filtering framework supported by the Linux kernel. This service supports configuring iptables for both IPv4 and IPv6. A simple example configuration rejecting all incoming connections except those to the ssh port 22 is shown below.

(service iptables-service-type
         (iptables-configuration
          (ipv4-rules (plain-file "iptables.rules" "*filter
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-port-unreachable
COMMIT
"))
          (ipv6-rules (plain-file "ip6tables.rules" "*filter
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp6-port-unreachable
COMMIT
"))))
Data Type: iptables-configuration

The data type representing the configuration of iptables.

iptables (default: iptables)

The iptables package that provides iptables-restore and ip6tables-restore.

ipv4-rules (default: %iptables-accept-all-rules)

The iptables rules to use. It will be passed to iptables-restore. This may be any “file-like” object (see file-like objects).

ipv6-rules (default: %iptables-accept-all-rules)

The ip6tables rules to use. It will be passed to ip6tables-restore. This may be any “file-like” object (see file-like objects).

Scheme Variable: ntp-service-type

This is the type of the service running the Network Time Protocol (NTP) daemon, ntpd. The daemon will keep the system clock synchronized with that of the specified NTP servers.

The value of this service is an ntpd-configuration object, as described below.

Data Type: ntp-configuration

This is the data type for the NTP service configuration.

servers (default: %ntp-servers)

This is the list of servers (host names) with which ntpd will be synchronized.

allow-large-adjustment? (default: #f)

This determines whether ntpd is allowed to make an initial adjustment of more than 1,000 seconds.

ntp (default: ntp)

The NTP package to use.

Scheme Variable: %ntp-servers

List of host names used as the default NTP servers. These are servers of the NTP Pool Project.

Scheme Procedure: openntpd-service-type

Run the ntpd, the Network Time Protocol (NTP) daemon, as implemented by OpenNTPD. The daemon will keep the system clock synchronized with that of the given servers.

(service
 openntpd-service-type
 (openntpd-configuration
  (listen-on '("127.0.0.1" "::1"))
  (sensor '("udcf0 correction 70000"))
  (constraint-from '("www.gnu.org"))
  (constraints-from '("https://www.google.com/"))
  (allow-large-adjustment? #t)))

Data Type: openntpd-configuration
openntpd (default: (file-append openntpd "/sbin/ntpd"))

The openntpd executable to use.

listen-on (default: '("127.0.0.1" "::1"))

A list of local IP addresses or hostnames the ntpd daemon should listen on.

query-from (default: '())

A list of local IP address the ntpd daemon should use for outgoing queries.

sensor (default: '())

Specify a list of timedelta sensor devices ntpd should use. ntpd will listen to each sensor that actually exists and ignore non-existent ones. See upstream documentation for more information.

server (default: %ntp-servers)

Specify a list of IP addresses or hostnames of NTP servers to synchronize to.

servers (default: '())

Specify a list of IP addresses or hostnames of NTP pools to synchronize to.

constraint-from (default: '())

ntpd can be configured to query the ‘Date’ from trusted HTTPS servers via TLS. This time information is not used for precision but acts as an authenticated constraint, thereby reducing the impact of unauthenticated NTP man-in-the-middle attacks. Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide a constraint.

constraints-from (default: '())

As with constraint from, specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide a constraint. Should the hostname resolve to multiple IP addresses, ntpd will calculate a median constraint from all of them.

allow-large-adjustment? (default: #f)

Determines if ntpd is allowed to make an initial adjustment of more than 180 seconds.

Scheme variable: inetd-service-type

This service runs the inetd (see inetd invocation in GNU Inetutils) daemon. inetd listens for connections on internet sockets, and lazily starts the specified server program when a connection is made on one of these sockets.

The value of this service is an inetd-configuration object. The following example configures the inetd daemon to provide the built-in echo service, as well as an smtp service which forwards smtp traffic over ssh to a server smtp-server behind a gateway hostname:

(service
 inetd-service-type
 (inetd-configuration
  (entries (list
            (inetd-entry
             (name "echo")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root"))
            (inetd-entry
             (node "127.0.0.1")
             (name "smtp")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root")
             (program (file-append openssh "/bin/ssh"))
             (arguments
              '("ssh" "-qT" "-i" "/path/to/ssh_key"
                "-W" "smtp-server:25" "user@hostname")))))

See below for more details about inetd-configuration.

Data Type: inetd-configuration

Data type representing the configuration of inetd.

program (default: (file-append inetutils "/libexec/inetd"))

The inetd executable to use.

entries (default: '())

A list of inetd service entries. Each entry should be created by the inetd-entry constructor.

Data Type: inetd-entry

Data type representing an entry in the inetd configuration. Each entry corresponds to a socket where inetd will listen for requests.

node (default: #f)

Optional string, a comma-separated list of local addresses inetd should use when listening for this service. See Configuration file in GNU Inetutils for a complete description of all options.

name

A string, the name must correspond to an entry in /etc/services.

socket-type

One of 'stream, 'dgram, 'raw, 'rdm or 'seqpacket.

protocol

A string, must correspond to an entry in /etc/protocols.

wait? (default: #t)

Whether inetd should wait for the server to exit before listening to new service requests.

user

A string containing the user (and, optionally, group) name of the user as whom the server should run. The group name can be specified in a suffix, separated by a colon or period, i.e. "user", "user:group" or "user.group".

program (default: "internal")

The server program which will serve the requests, or "internal" if inetd should use a built-in service.

arguments (default: '())

A list strings or file-like objects, which are the server program’s arguments, starting with the zeroth argument, i.e. the name of the program itself. For inetd’s internal services, this entry must be '() or '("internal").

See Configuration file in GNU Inetutils for a more detailed discussion of each configuration field.

Scheme Variable: tor-service-type

This is the type for a service that runs the Tor anonymous networking daemon. The service is configured using a <tor-configuration> record. By default, the Tor daemon runs as the tor unprivileged user, which is a member of the tor group.

Data Type: tor-configuration
tor (default: tor)

The package that provides the Tor daemon. This package is expected to provide the daemon at bin/tor relative to its output directory. The default package is the Tor Project’s implementation.

config-file (default: (plain-file "empty" ""))

The configuration file to use. It will be appended to a default configuration file, and the final configuration file will be passed to tor via its -f option. This may be any “file-like” object (see file-like objects). See man tor for details on the configuration file syntax.

hidden-services (default: '())

The list of <hidden-service> records to use. For any hidden service you include in this list, appropriate configuration to enable the hidden service will be automatically added to the default configuration file. You may conveniently create <hidden-service> records using the tor-hidden-service procedure described below.

socks-socket-type (default: 'tcp)

The default socket type that Tor should use for its SOCKS socket. This must be either 'tcp or 'unix. If it is 'tcp, then by default Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost). If it is 'unix, then Tor will listen on the UNIX domain socket /var/run/tor/socks-sock, which will be made writable by members of the tor group.

If you want to customize the SOCKS socket in more detail, leave socks-socket-type at its default value of 'tcp and use config-file to override the default by providing your own SocksPort option.

Scheme Procedure: tor-hidden-service name mapping

Define a new Tor hidden service called name and implementing mapping. mapping is a list of port/host tuples, such as:

 '((22 "127.0.0.1:22")
   (80 "127.0.0.1:8080"))

In this example, port 22 of the hidden service is mapped to local port 22, and port 80 is mapped to local port 8080.

This creates a /var/lib/tor/hidden-services/name directory, where the hostname file contains the .onion host name for the hidden service.

See the Tor project’s documentation for more information.

The (gnu services rsync) module provides the following services:

You might want an rsync daemon if you have files that you want available so anyone (or just yourself) can download existing files or upload new files.

Scheme Variable: rsync-service-type

This is the service type for the rsync daemon, The value for this service type is a rsync-configuration record as in this example:

(service rsync-service-type)

See below for details about rsync-configuration.

Data Type: rsync-configuration

Data type representing the configuration for rsync-service.

package (default: rsync)

rsync package to use.

port-number (default: 873)

TCP port on which rsync listens for incoming connections. If port is less than 1024 rsync needs to be started as the root user and group.

pid-file (default: "/var/run/rsyncd/rsyncd.pid")

Name of the file where rsync writes its PID.

lock-file (default: "/var/run/rsyncd/rsyncd.lock")

Name of the file where rsync writes its lock file.

log-file (default: "/var/log/rsyncd.log")

Name of the file where rsync writes its log file.

use-chroot? (default: #t)

Whether to use chroot for rsync shared directory.

share-path (default: /srv/rsync)

Location of the rsync shared directory.

share-comment (default: "Rsync share")

Comment of the rsync shared directory.

read-only? (default: #f)

Read-write permissions to shared directory.

timeout (default: 300)

I/O timeout in seconds.

user (default: "root")

Owner of the rsync process.

group (default: "root")

Group of the rsync process.

uid (default: "rsyncd")

User name or user ID that file transfers to and from that module should take place as when the daemon was run as root.

gid (default: "rsyncd")

Group name or group ID that will be used when accessing the module.

Furthermore, (gnu services ssh) provides the following services.

Scheme Procedure: lsh-service [#:host-key "/etc/lsh/host-key"] [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] [#:allow-empty-passwords? #f] [#:root-login? #f]  [#:syslog-output? #t]

[#:x11-forwarding? #t]  [#:tcp/ip-forwarding? #t] [#:password-authentication? #t]  [#:public-key-authentication? #t] [#:initialize? #t] Run the lshd program from lsh to listen on port port-number. host-key must designate a file containing the host key, and readable only by root.

When daemonic? is true, lshd will detach from the controlling terminal and log its output to syslogd, unless one sets syslog-output? to false. Obviously, it also makes lsh-service depend on existence of syslogd service. When pid-file? is true, lshd writes its PID to the file called pid-file.

When initialize? is true, automatically create the seed and host key upon service activation if they do not exist yet. This may take long and require interaction.

When initialize? is false, it is up to the user to initialize the randomness generator (see lsh-make-seed in LSH Manual), and to create a key pair with the private key stored in file host-key (see lshd basics in LSH Manual).

When interfaces is empty, lshd listens for connections on all the network interfaces; otherwise, interfaces must be a list of host names or addresses.

allow-empty-passwords? specifies whether to accept log-ins with empty passwords, and root-login? specifies whether to accept log-ins as root.

The other options should be self-descriptive.

Scheme Variable: openssh-service-type

This is the type for the OpenSSH secure shell daemon, sshd. Its value must be an openssh-configuration record as in this example:

(service openssh-service-type
         (openssh-configuration
           (x11-forwarding? #t)
           (permit-root-login 'without-password)
           (authorized-keys
             `(("alice" ,(local-file "alice.pub"))
               ("bob" ,(local-file "bob.pub"))))))

See below for details about openssh-configuration.

This service can be extended with extra authorized keys, as in this example:

(service-extension openssh-service-type
                   (const `(("charlie"
                             ,(local-file "charlie.pub")))))
Data Type: openssh-configuration

This is the configuration record for OpenSSH’s sshd.

pid-file (default: "/var/run/sshd.pid")

Name of the file where sshd writes its PID.

port-number (default: 22)

TCP port on which sshd listens for incoming connections.

permit-root-login (default: #f)

This field determines whether and when to allow logins as root. If #f, root logins are disallowed; if #t, they are allowed. If it’s the symbol 'without-password, then root logins are permitted but not with password-based authentication.

allow-empty-passwords? (default: #f)

When true, users with empty passwords may log in. When false, they may not.

password-authentication? (default: #t)

When true, users may log in with their password. When false, they have other authentication methods.

public-key-authentication? (default: #t)

When true, users may log in using public key authentication. When false, users have to use other authentication method.

Authorized public keys are stored in ~/.ssh/authorized_keys. This is used only by protocol version 2.

x11-forwarding? (default: #f)

When true, forwarding of X11 graphical client connections is enabled—in other words, ssh options -X and -Y will work.

allow-agent-forwarding? (default: #t)

Whether to allow agent forwarding.

allow-tcp-forwarding? (default: #t)

Whether to allow TCP forwarding.

gateway-ports? (default: #f)

Whether to allow gateway ports.

challenge-response-authentication? (default: #f)

Specifies whether challenge response authentication is allowed (e.g. via PAM).

use-pam? (default: #t)

Enables the Pluggable Authentication Module interface. If set to #t, this will enable PAM authentication using challenge-response-authentication? and password-authentication?, in addition to PAM account and session module processing for all authentication types.

Because PAM challenge response authentication usually serves an equivalent role to password authentication, you should disable either challenge-response-authentication? or password-authentication?.

print-last-log? (default: #t)

Specifies whether sshd should print the date and time of the last user login when a user logs in interactively.

subsystems (default: '(("sftp" "internal-sftp")))

Configures external subsystems (e.g. file transfer daemon).

This is a list of two-element lists, each of which containing the subsystem name and a command (with optional arguments) to execute upon subsystem request.

The command internal-sftp implements an in-process SFTP server. Alternately, one can specify the sftp-server command:

(service openssh-service-type
         (openssh-configuration
          (subsystems
           `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
accepted-environment (default: '())

List of strings describing which environment variables may be exported.

Each string gets on its own line. See the AcceptEnv option in man sshd_config.

This example allows ssh-clients to export the COLORTERM variable. It is set by terminal emulators, which support colors. You can use it in your shell’s ressource file to enable colors for the prompt and commands if this variable is set.

(service openssh-service-type
         (openssh-configuration
           (accepted-environment '("COLORTERM"))))
authorized-keys (default: '())

This is the list of authorized keys. Each element of the list is a user name followed by one or more file-like objects that represent SSH public keys. For example:

(openssh-configuration
  (authorized-keys
    `(("rekado" ,(local-file "rekado.pub"))
      ("chris" ,(local-file "chris.pub"))
      ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))

registers the specified public keys for user accounts rekado, chris, and root.

Additional authorized keys can be specified via service-extension.

Note that this does not interfere with the use of ~/.ssh/authorized_keys.

log-level (default: 'info)

This is a symbol specifying the logging level: quiet, fatal, error, info, verbose, debug, etc. See the man page for sshd_config for the full list of level names.

extra-content (default: "")

This field can be used to append arbitrary text to the configuration file. It is especially useful for elaborate configurations that cannot be expressed otherwise. This configuration, for example, would generally disable root logins, but permit them from one specific IP address:

(openssh-configuration
  (extra-content "\
Match Address 192.168.0.1
  PermitRootLogin yes"))
Scheme Procedure: dropbear-service [config]

Run the Dropbear SSH daemon with the given config, a <dropbear-configuration> object.

For example, to specify a Dropbear service listening on port 1234, add this call to the operating system’s services field:

(dropbear-service (dropbear-configuration
                    (port-number 1234)))
Data Type: dropbear-configuration

This data type represents the configuration of a Dropbear SSH daemon.

dropbear (default: dropbear)

The Dropbear package to use.

port-number (default: 22)

The TCP port where the daemon waits for incoming connections.

syslog-output? (default: #t)

Whether to enable syslog output.

pid-file (default: "/var/run/dropbear.pid")

File name of the daemon’s PID file.

root-login? (default: #f)

Whether to allow root logins.

allow-empty-passwords? (default: #f)

Whether to allow empty passwords.

password-authentication? (default: #t)

Whether to enable password-based authentication.

Scheme Variable: %facebook-host-aliases

This variable contains a string for use in /etc/hosts (see Host Names in The GNU C Library Reference Manual). Each line contains a entry that maps a known server name of the Facebook on-line service—e.g., www.facebook.com—to the local host—127.0.0.1 or its IPv6 equivalent, ::1.

This variable is typically used in the hosts-file field of an operating-system declaration (see /etc/hosts):

(use-modules (gnu) (guix))

(operating-system
  (host-name "mymachine")
  ;; ...
  (hosts-file
    ;; Create a /etc/hosts file with aliases for "localhost"
    ;; and "mymachine", as well as for Facebook servers.
    (plain-file "hosts"
                (string-append (local-host-aliases host-name)
                               %facebook-host-aliases))))

This mechanism can prevent programs running locally, such as Web browsers, from accessing Facebook.

The (gnu services avahi) provides the following definition.

Scheme Variable: avahi-service-type

This is the service that runs avahi-daemon, a system-wide mDNS/DNS-SD responder that allows for service discovery and “zero-configuration” host name lookups (see https://avahi.org/). Its value must be a zero-configuration record—see below.

This service extends the name service cache daemon (nscd) so that it can resolve .local host names using nss-mdns. See Служба выбора имён, for information on host name resolution.

Additionally, add the avahi package to the system profile so that commands such as avahi-browse are directly usable.

Data Type: avahi-configuration

Data type representation the configuration for Avahi.

host-name (default: #f)

If different from #f, use that as the host name to publish for this machine; otherwise, use the machine’s actual host name.

publish? (default: #t)

When true, allow host names and services to be published (broadcast) over the network.

publish-workstation? (default: #t)

When true, avahi-daemon publishes the machine’s host name and IP address via mDNS on the local network. To view the host names published on your local network, you can run:

avahi-browse _workstation._tcp
wide-area? (default: #f)

When true, DNS-SD over unicast DNS is enabled.

ipv4? (default: #t)
ipv6? (default: #t)

These fields determine whether to use IPv4/IPv6 sockets.

domains-to-browse (default: '())

This is a list of domains to browse.

Scheme Variable: openvswitch-service-type

This is the type of the Open vSwitch service, whose value should be an openvswitch-configuration object.

Data Type: openvswitch-configuration

Data type representing the configuration of Open vSwitch, a multilayer virtual switch which is designed to enable massive network automation through programmatic extension.

package (default: openvswitch)

Package object of the Open vSwitch.


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.5 Оконная система X

Support for the X Window graphical display system—specifically Xorg—is provided by the (gnu services xorg) module. Note that there is no xorg-service procedure. Instead, the X server is started by the login manager, by default the GNOME Display Manager (GDM).

GDM of course allows users to log in into window managers and desktop environments other than GNOME; for those using GNOME, GDM is required for features such as automatic screen locking.

To use X11, you must install at least one window manager—for example the windowmaker or openbox packages—preferably by adding it to the packages field of your operating system definition (see system-wide packages).

Scheme Variable: gdm-service-type

This is the type for the GNOME Desktop Manager (GDM), a program that manages graphical display servers and handles graphical user logins. Its value must be a gdm-configuration (see below.)

GDM looks for session types described by the .desktop files in /run/current-system/profile/share/xsessions and allows users to choose a session from the log-in screen. Packages such as gnome, xfce, and i3 provide .desktop files; adding them to the system-wide set of packages automatically makes them available at the log-in screen.

In addition, ~/.xsession files are honored. When available, ~/.xsession must be an executable that starts a window manager and/or other X clients.

Data Type: gdm-configuration
auto-login? (default: #f)
default-user (default: #f)

When auto-login? is false, GDM presents a log-in screen.

When auto-login? is true, GDM logs in directly as default-user.

gnome-shell-assets (default: ...)

List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.

xorg-configuration (default: (xorg-configuration))

Configuration of the Xorg graphical server.

xsession (default: (xinitrc))

Script to run before starting a X session.

dbus-daemon (default: dbus-daemon-wrapper)

File name of the dbus-daemon executable.

gdm (default: gdm)

The GDM package to use.

Scheme Variable: slim-service-type

This is the type for the SLiM graphical login manager for X11.

Like GDM, SLiM looks for session types described by .desktop files and allows users to choose a session from the log-in screen using F1. It also honors ~/.xsession files.

Unlike GDM, SLiM does not spawn the user session on a different VT after logging in, which means that you can only start one graphical session. If you want to be able to run multiple graphical sessions at the same time you have to add multiple SLiM services to your system services. The following example shows how to replace the default GDM service with two SLiM services on tty7 and tty8.

(use-modules (gnu services)
             (gnu services desktop)
             (gnu services xorg)
             (srfi srfi-1))  ;for 'remove'

(operating-system
  ;; ...
  (services (cons* (service slim-service-type (slim-configuration
                                               (display ":0")
                                               (vt "vt7")))
                   (service slim-service-type (slim-configuration
                                               (display ":1")
                                               (vt "vt8")))
                   (remove (lambda (service)
                             (eq? (service-kind service) gdm-service-type))
                           %desktop-services))))
Data Type: slim-configuration

Data type representing the configuration of slim-service-type.

allow-empty-passwords? (default: #t)

Whether to allow logins with empty passwords.

auto-login? (default: #f)
default-user (default: "")

When auto-login? is false, SLiM presents a log-in screen.

When auto-login? is true, SLiM logs in directly as default-user.

theme (default: %default-slim-theme)
theme-name (default: %default-slim-theme-name)

The graphical theme to use and its name.

auto-login-session (default: #f)

If true, this must be the name of the executable to start as the default session—e.g., (file-append windowmaker "/bin/windowmaker").

If false, a session described by one of the available .desktop files in /run/current-system/profile and ~/.guix-profile will be used.

Заметка: You must install at least one window manager in the system profile or in your user profile. Failing to do that, if auto-login-session is false, you will be unable to log in.

xorg-configuration (default (xorg-configuration))

Configuration of the Xorg graphical server.

display (default ":0")

The display on which to start the Xorg graphical server.

vt (default "vt7")

The VT on which to start the Xorg graphical server.

xauth (default: xauth)

The XAuth package to use.

shepherd (default: shepherd)

The Shepherd package used when invoking halt and reboot.

sessreg (default: sessreg)

The sessreg package used in order to register the session.

slim (default: slim)

The SLiM package to use.

Scheme Variable: %default-theme
Scheme Variable: %default-theme-name

The default SLiM theme and its name.

Data Type: sddm-configuration

This is the data type representing the sddm service configuration.

display-server (default: "x11")

Select display server to use for the greeter. Valid values are "x11" or "wayland".

numlock (default: "on")

Valid values are "on", "off" or "none".

halt-command (default #~(string-apppend #$shepherd "/sbin/halt"))

Command to run when halting.

reboot-command (default #~(string-append #$shepherd "/sbin/reboot"))

Command to run when rebooting.

theme (default "maldives")

Theme to use. Default themes provided by SDDM are "elarun" or "maldives".

themes-directory (default "/run/current-system/profile/share/sddm/themes")

Directory to look for themes.

faces-directory (default "/run/current-system/profile/share/sddm/faces")

Directory to look for faces.

default-path (default "/run/current-system/profile/bin")

Default PATH to use.

minimum-uid (default 1000)

Minimum UID to display in SDDM.

maximum-uid (default 2000)

Maximum UID to display in SDDM

remember-last-user? (default #t)

Remember last user.

remember-last-session? (default #t)

Remember last session.

hide-users (default "")

Usernames to hide from SDDM greeter.

hide-shells (default #~(string-append #$shadow "/sbin/nologin"))

Users with shells listed will be hidden from the SDDM greeter.

session-command (default #~(string-append #$sddm "/share/sddm/scripts/wayland-session"))

Script to run before starting a wayland session.

sessions-directory (default "/run/current-system/profile/share/wayland-sessions")

Directory to look for desktop files starting wayland sessions.

xorg-configuration (default (xorg-configuration))

Configuration of the Xorg graphical server.

xauth-path (default #~(string-append #$xauth "/bin/xauth"))

Path to xauth.

xephyr-path (default #~(string-append #$xorg-server "/bin/Xephyr"))

Path to Xephyr.

xdisplay-start (default #~(string-append #$sddm "/share/sddm/scripts/Xsetup"))

Script to run after starting xorg-server.

xdisplay-stop (default #~(string-append #$sddm "/share/sddm/scripts/Xstop"))

Script to run before stopping xorg-server.

xsession-command (default: xinitrc)

Script to run before starting a X session.

xsessions-directory (default: "/run/current-system/profile/share/xsessions")

Directory to look for desktop files starting X sessions.

minimum-vt (default: 7)

Minimum VT to use.

auto-login-user (default "")

User to use for auto-login.

auto-login-session (default "")

Desktop file to use for auto-login.

relogin? (default #f)

Relogin after logout.

Scheme Procedure: sddm-service config

Return a service that spawns the SDDM graphical login manager for config of type <sddm-configuration>.

  (sddm-service (sddm-configuration
                 (auto-login-user "Alice")
                 (auto-login-session "xfce.desktop")))
Data Type: xorg-configuration

This data type represents the configuration of the Xorg graphical display server. Note that there is not Xorg service; instead, the X server is started by a “display manager” such as GDM, SDDM, and SLiM. Thus, the configuration of these display managers aggregates an xorg-configuration record.

modules (default: %default-xorg-modules)

This is a list of module packages loaded by the Xorg server—e.g., xf86-video-vesa, xf86-input-keyboard, and so on.

fonts (default: %default-xorg-fonts)

This is a list of font directories to add to the server’s font path.

drivers (default: '())

This must be either the empty list, in which case Xorg chooses a graphics driver automatically, or a list of driver names that will be tried in this order—e.g., ("modesetting" "vesa").

resolutions (default: '())

When resolutions is the empty list, Xorg chooses an appropriate screen resolution. Otherwise, it must be a list of resolutions—e.g., ((1024 768) (640 480)).

keyboard-layout (default: #f)

If this is #f, Xorg uses the default keyboard layout—usually US English (“qwerty”) for a 105-key PC keyboard.

Otherwise this must be a keyboard-layout object specifying the keyboard layout in use when Xorg is running. See Раскладка клавиатуры, for more information on how to specify the keyboard layout.

extra-config (default: '())

This is a list of strings or objects appended to the configuration file. It is used to pass extra text to be added verbatim to the configuration file.

server (default: xorg-server)

This is the package providing the Xorg server.

server-arguments (default: %default-xorg-server-arguments)

This is the list of command-line arguments to pass to the X server. The default is -nolisten tcp.

Scheme Procedure: set-xorg-configuration config [login-manager-service-type] Tell the log-in manager (of type

login-manager-service-type) to use config, an <xorg-configuration> record.

Since the Xorg configuration is embedded in the log-in manager’s configuration—e.g., gdm-configuration—this procedure provides a shorthand to set the Xorg configuration.

Scheme Procedure: xorg-start-command [config]

Return a startx script in which the modules, fonts, etc. specified in config, are available. The result should be used in place of startx.

Usually the X server is started by a login manager.

Scheme Procedure: screen-locker-service package [program]

Add package, a package for a screen locker or screen saver whose command is program, to the set of setuid programs and add a PAM entry for it. For example:

(screen-locker-service xlockmore "xlock")

makes the good ol’ XlockMore usable.


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.6 Сервисы печати

The (gnu services cups) module provides a Guix service definition for the CUPS printing service. To add printer support to a Guix system, add a cups-service to the operating system definition:

Scheme Variable: cups-service-type

The service type for the CUPS print server. Its value should be a valid CUPS configuration (see below). To use the default settings, simply write:

(service cups-service-type)

The CUPS configuration controls the basic things about your CUPS installation: what interfaces it listens on, what to do if a print job fails, how much logging to do, and so on. To actually add a printer, you have to visit the http://localhost:631 URL, or use a tool such as GNOME’s printer configuration services. By default, configuring a CUPS service will generate a self-signed certificate if needed, for secure connections to the print server.

Suppose you want to enable the Web interface of CUPS and also add support for Epson printers via the escpr package and for HP printers via the hplip-minimal package. You can do that directly, like this (you need to use the (gnu packages cups) module):

(service cups-service-type
         (cups-configuration
           (web-interface? #t)
           (extensions
             (list cups-filters escpr hplip-minimal))))

Note: If you wish to use the Qt5 based GUI which comes with the hplip package then it is suggested that you install the hplip package, either in your OS configuration file or as your user.

The available configuration parameters follow. Each parameter definition is preceded by its type; for example, ‘string-list foo’ indicates that the foo parameter should be specified as a list of strings. There is also a way to specify the configuration as a string, if you have an old cupsd.conf file that you want to port over from some other system; see the end for more details.

Available cups-configuration fields are:

cups-configuration parameter: package cups

The CUPS package.

cups-configuration parameter: package-list extensions

Drivers and other extensions to the CUPS package.

cups-configuration parameter: files-configuration files-configuration

Configuration of where to write logs, what directories to use for print spools, and related privileged configuration parameters.

Available files-configuration fields are:

files-configuration parameter: log-location access-log

Defines the access log filename. Specifying a blank filename disables access log generation. The value stderr causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background. The value syslog causes log entries to be sent to the system log daemon. The server name may be included in filenames using the string %s, as in /var/log/cups/%s-access_log.

Defaults to ‘"/var/log/cups/access_log"’.

files-configuration parameter: file-name cache-dir

Where CUPS should cache data.

Defaults to ‘"/var/cache/cups"’.

files-configuration parameter: string config-file-perm

Specifies the permissions for all configuration files that the scheduler writes.

Note that the permissions for the printers.conf file are currently masked to only allow access from the scheduler user (typically root). This is done because printer device URIs sometimes contain sensitive authentication information that should not be generally known on the system. There is no way to disable this security feature.

Defaults to ‘"0640"’.

files-configuration parameter: log-location error-log

Defines the error log filename. Specifying a blank filename disables error log generation. The value stderr causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background. The value syslog causes log entries to be sent to the system log daemon. The server name may be included in filenames using the string %s, as in /var/log/cups/%s-error_log.

Defaults to ‘"/var/log/cups/error_log"’.

files-configuration parameter: string fatal-errors

Specifies which errors are fatal, causing the scheduler to exit. The kind strings are:

none

No errors are fatal.

all

All of the errors below are fatal.

browse

Browsing initialization errors are fatal, for example failed connections to the DNS-SD daemon.

config

Configuration file syntax errors are fatal.

listen

Listen or Port errors are fatal, except for IPv6 failures on the loopback or any addresses.

log

Log file creation or write errors are fatal.

permissions

Bad startup file permissions are fatal, for example shared TLS certificate and key files with world-read permissions.

Defaults to ‘"all -browse"’.

files-configuration parameter: boolean file-device?

Specifies whether the file pseudo-device can be used for new printer queues. The URI file:///dev/null is always allowed.

Defaults to ‘#f’.

files-configuration parameter: string group

Specifies the group name or ID that will be used when executing external programs.

Defaults to ‘"lp"’.

files-configuration parameter: string log-file-perm

Specifies the permissions for all log files that the scheduler writes.

Defaults to ‘"0644"’.

files-configuration parameter: log-location page-log

Defines the page log filename. Specifying a blank filename disables page log generation. The value stderr causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background. The value syslog causes log entries to be sent to the system log daemon. The server name may be included in filenames using the string %s, as in /var/log/cups/%s-page_log.

Defaults to ‘"/var/log/cups/page_log"’.

files-configuration parameter: string remote-root

Specifies the username that is associated with unauthenticated accesses by clients claiming to be the root user. The default is remroot.

Defaults to ‘"remroot"’.

files-configuration parameter: file-name request-root

Specifies the directory that contains print jobs and other HTTP request data.

Defaults to ‘"/var/spool/cups"’.

files-configuration parameter: sandboxing sandboxing

Specifies the level of security sandboxing that is applied to print filters, backends, and other child processes of the scheduler; either relaxed or strict. This directive is currently only used/supported on macOS.

Defaults to ‘strict’.

files-configuration parameter: file-name server-keychain

Specifies the location of TLS certificates and private keys. CUPS will look for public and private keys in this directory: a .crt files for PEM-encoded certificates and corresponding .key files for PEM-encoded private keys.

Defaults to ‘"/etc/cups/ssl"’.

files-configuration parameter: file-name server-root

Specifies the directory containing the server configuration files.

Defaults to ‘"/etc/cups"’.

files-configuration parameter: boolean sync-on-close?

Specifies whether the scheduler calls fsync(2) after writing configuration or state files.

Defaults to ‘#f’.

files-configuration parameter: space-separated-string-list system-group

Specifies the group(s) to use for @SYSTEM group authentication.

files-configuration parameter: file-name temp-dir

Specifies the directory where temporary files are stored.

Defaults to ‘"/var/spool/cups/tmp"’.

files-configuration parameter: string user

Specifies the user name or ID that is used when running external programs.

Defaults to ‘"lp"’.

cups-configuration parameter: access-log-level access-log-level

Specifies the logging level for the AccessLog file. The config level logs when printers and classes are added, deleted, or modified and when configuration files are accessed or updated. The actions level logs when print jobs are submitted, held, released, modified, or canceled, and any of the conditions for config. The all level logs all requests.

Defaults to ‘actions’.

cups-configuration parameter: boolean auto-purge-jobs?

Specifies whether to purge job history data automatically when it is no longer required for quotas.

Defaults to ‘#f’.

cups-configuration parameter: browse-local-protocols browse-local-protocols

Specifies which protocols to use for local printer sharing.

Defaults to ‘dnssd’.

cups-configuration parameter: boolean browse-web-if?

Specifies whether the CUPS web interface is advertised.

Defaults to ‘#f’.

cups-configuration parameter: boolean browsing?

Specifies whether shared printers are advertised.

Defaults to ‘#f’.

cups-configuration parameter: string classification

Specifies the security classification of the server. Any valid banner name can be used, including "classified", "confidential", "secret", "topsecret", and "unclassified", or the banner can be omitted to disable secure printing functions.

Defaults to ‘""’.

cups-configuration parameter: boolean classify-override?

Specifies whether users may override the classification (cover page) of individual print jobs using the job-sheets option.

Defaults to ‘#f’.

cups-configuration parameter: default-auth-type default-auth-type

Specifies the default type of authentication to use.

Defaults to ‘Basic’.

cups-configuration parameter: default-encryption default-encryption

Specifies whether encryption will be used for authenticated requests.

Defaults to ‘Required’.

cups-configuration parameter: string default-language

Specifies the default language to use for text and web content.

Defaults to ‘"en"’.

cups-configuration parameter: string default-paper-size

Specifies the default paper size for new print queues. ‘"Auto"’ uses a locale-specific default, while ‘"None"’ specifies there is no default paper size. Specific size names are typically ‘"Letter"’ or ‘"A4"’.

Defaults to ‘"Auto"’.

cups-configuration parameter: string default-policy

Specifies the default access policy to use.

Defaults to ‘"default"’.

cups-configuration parameter: boolean default-shared?

Specifies whether local printers are shared by default.

Defaults to ‘#t’.

cups-configuration parameter: non-negative-integer dirty-clean-interval

Specifies the delay for updating of configuration and state files, in seconds. A value of 0 causes the update to happen as soon as possible, typically within a few milliseconds.

Defaults to ‘30’.

cups-configuration parameter: error-policy error-policy

Specifies what to do when an error occurs. Possible values are abort-job, which will discard the failed print job; retry-job, which will retry the job at a later time; retry-this-job, which retries the failed job immediately; and stop-printer, which stops the printer.

Defaults to ‘stop-printer’.

cups-configuration parameter: non-negative-integer filter-limit

Specifies the maximum cost of filters that are run concurrently, which can be used to minimize disk, memory, and CPU resource problems. A limit of 0 disables filter limiting. An average print to a non-PostScript printer needs a filter limit of about 200. A PostScript printer needs about half that (100). Setting the limit below these thresholds will effectively limit the scheduler to printing a single job at any time.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer filter-nice

Specifies the scheduling priority of filters that are run to print a job. The nice value ranges from 0, the highest priority, to 19, the lowest priority.

Defaults to ‘0’.

cups-configuration parameter: host-name-lookups host-name-lookups

Specifies whether to do reverse lookups on connecting clients. The double setting causes cupsd to verify that the hostname resolved from the address matches one of the addresses returned for that hostname. Double lookups also prevent clients with unregistered addresses from connecting to your server. Only set this option to #t or double if absolutely required.

Defaults to ‘#f’.

cups-configuration parameter: non-negative-integer job-kill-delay

Specifies the number of seconds to wait before killing the filters and backend associated with a canceled or held job.

Defaults to ‘30’.

cups-configuration parameter: non-negative-integer job-retry-interval

Specifies the interval between retries of jobs in seconds. This is typically used for fax queues but can also be used with normal print queues whose error policy is retry-job or retry-current-job.

Defaults to ‘30’.

cups-configuration parameter: non-negative-integer job-retry-limit

Specifies the number of retries that are done for jobs. This is typically used for fax queues but can also be used with normal print queues whose error policy is retry-job or retry-current-job.

Defaults to ‘5’.

cups-configuration parameter: boolean keep-alive?

Specifies whether to support HTTP keep-alive connections.

Defaults to ‘#t’.

cups-configuration parameter: non-negative-integer keep-alive-timeout

Specifies how long an idle client connection remains open, in seconds.

Defaults to ‘30’.

cups-configuration parameter: non-negative-integer limit-request-body

Specifies the maximum size of print files, IPP requests, and HTML form data. A limit of 0 disables the limit check.

Defaults to ‘0’.

cups-configuration parameter: multiline-string-list listen

Listens on the specified interfaces for connections. Valid values are of the form address:port, where address is either an IPv6 address enclosed in brackets, an IPv4 address, or * to indicate all addresses. Values can also be file names of local UNIX domain sockets. The Listen directive is similar to the Port directive but allows you to restrict access to specific interfaces or networks.

cups-configuration parameter: non-negative-integer listen-back-log

Specifies the number of pending connections that will be allowed. This normally only affects very busy servers that have reached the MaxClients limit, but can also be triggered by large numbers of simultaneous connections. When the limit is reached, the operating system will refuse additional connections until the scheduler can accept the pending ones.

Defaults to ‘128’.

cups-configuration parameter: location-access-control-list location-access-controls

Specifies a set of additional access controls.

Available location-access-controls fields are:

location-access-controls parameter: file-name path

Specifies the URI path to which the access control applies.

location-access-controls parameter: access-control-list access-controls

Access controls for all access to this path, in the same format as the access-controls of operation-access-control.

Defaults to ‘()’.

location-access-controls parameter: method-access-control-list method-access-controls

Access controls for method-specific access to this path.

Defaults to ‘()’.

Available method-access-controls fields are:

method-access-controls parameter: boolean reverse?

If #t, apply access controls to all methods except the listed methods. Otherwise apply to only the listed methods.

Defaults to ‘#f’.

method-access-controls parameter: method-list methods

Methods to which this access control applies.

Defaults to ‘()’.

method-access-controls parameter: access-control-list access-controls

Access control directives, as a list of strings. Each string should be one directive, such as "Order allow,deny".

Defaults to ‘()’.

cups-configuration parameter: non-negative-integer log-debug-history

Specifies the number of debugging messages that are retained for logging if an error occurs in a print job. Debug messages are logged regardless of the LogLevel setting.

Defaults to ‘100’.

cups-configuration parameter: log-level log-level

Specifies the level of logging for the ErrorLog file. The value none stops all logging while debug2 logs everything.

Defaults to ‘info’.

cups-configuration parameter: log-time-format log-time-format

Specifies the format of the date and time in the log files. The value standard logs whole seconds while usecs logs microseconds.

Defaults to ‘standard’.

cups-configuration parameter: non-negative-integer max-clients

Specifies the maximum number of simultaneous clients that are allowed by the scheduler.

Defaults to ‘100’.

cups-configuration parameter: non-negative-integer max-clients-per-host

Specifies the maximum number of simultaneous clients that are allowed from a single address.

Defaults to ‘100’.

cups-configuration parameter: non-negative-integer max-copies

Specifies the maximum number of copies that a user can print of each job.

Defaults to ‘9999’.

cups-configuration parameter: non-negative-integer max-hold-time

Specifies the maximum time a job may remain in the indefinite hold state before it is canceled. A value of 0 disables cancellation of held jobs.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer max-jobs

Specifies the maximum number of simultaneous jobs that are allowed. Set to 0 to allow an unlimited number of jobs.

Defaults to ‘500’.

cups-configuration parameter: non-negative-integer max-jobs-per-printer

Specifies the maximum number of simultaneous jobs that are allowed per printer. A value of 0 allows up to MaxJobs jobs per printer.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer max-jobs-per-user

Specifies the maximum number of simultaneous jobs that are allowed per user. A value of 0 allows up to MaxJobs jobs per user.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer max-job-time

Specifies the maximum time a job may take to print before it is canceled, in seconds. Set to 0 to disable cancellation of "stuck" jobs.

Defaults to ‘10800’.

cups-configuration parameter: non-negative-integer max-log-size

Specifies the maximum size of the log files before they are rotated, in bytes. The value 0 disables log rotation.

Defaults to ‘1048576’.

cups-configuration parameter: non-negative-integer multiple-operation-timeout

Specifies the maximum amount of time to allow between files in a multiple file print job, in seconds.

Defaults to ‘300’.

cups-configuration parameter: string page-log-format

Specifies the format of PageLog lines. Sequences beginning with percent (‘%’) characters are replaced with the corresponding information, while all other characters are copied literally. The following percent sequences are recognized:

%%

insert a single percent character

%{name}

insert the value of the specified IPP attribute

%C

insert the number of copies for the current page

%P

insert the current page number

%T

insert the current date and time in common log format

%j

insert the job ID

%p

insert the printer name

%u

insert the username

A value of the empty string disables page logging. The string %p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides} creates a page log with the standard items.

Defaults to ‘""’.

cups-configuration parameter: environment-variables environment-variables

Passes the specified environment variable(s) to child processes; a list of strings.

Defaults to ‘()’.

cups-configuration parameter: policy-configuration-list policies

Specifies named access control policies.

Available policy-configuration fields are:

policy-configuration parameter: string name

Name of the policy.

policy-configuration parameter: string job-private-access

Specifies an access list for a job’s private values. @ACL maps to the printer’s requesting-user-name-allowed or requesting-user-name-denied values. @OWNER maps to the job’s owner. @SYSTEM maps to the groups listed for the system-group field of the files-config configuration, which is reified into the cups-files.conf(5) file. Other possible elements of the access list include specific user names, and @group to indicate members of a specific group. The access list may also be simply all or default.

Defaults to ‘"@OWNER @SYSTEM"’.

policy-configuration parameter: string job-private-values

Specifies the list of job values to make private, or all, default, or none.

Defaults to ‘"job-name job-originating-host-name job-originating-user-name phone"’.

policy-configuration parameter: string subscription-private-access

Specifies an access list for a subscription’s private values. @ACL maps to the printer’s requesting-user-name-allowed or requesting-user-name-denied values. @OWNER maps to the job’s owner. @SYSTEM maps to the groups listed for the system-group field of the files-config configuration, which is reified into the cups-files.conf(5) file. Other possible elements of the access list include specific user names, and @group to indicate members of a specific group. The access list may also be simply all or default.

Defaults to ‘"@OWNER @SYSTEM"’.

policy-configuration parameter: string subscription-private-values

Specifies the list of job values to make private, or all, default, or none.

Defaults to ‘"notify-events notify-pull-method notify-recipient-uri notify-subscriber-user-name notify-user-data"’.

policy-configuration parameter: operation-access-control-list access-controls

Access control by IPP operation.

Defaults to ‘()’.

cups-configuration parameter: boolean-or-non-negative-integer preserve-job-files

Specifies whether job files (documents) are preserved after a job is printed. If a numeric value is specified, job files are preserved for the indicated number of seconds after printing. Otherwise a boolean value applies indefinitely.

Defaults to ‘86400’.

cups-configuration parameter: boolean-or-non-negative-integer preserve-job-history

Specifies whether the job history is preserved after a job is printed. If a numeric value is specified, the job history is preserved for the indicated number of seconds after printing. If #t, the job history is preserved until the MaxJobs limit is reached.

Defaults to ‘#t’.

cups-configuration parameter: non-negative-integer reload-timeout

Specifies the amount of time to wait for job completion before restarting the scheduler.

Defaults to ‘30’.

cups-configuration parameter: string rip-cache

Specifies the maximum amount of memory to use when converting documents into bitmaps for a printer.

Defaults to ‘"128m"’.

cups-configuration parameter: string server-admin

Specifies the email address of the server administrator.

Defaults to ‘"root@localhost.localdomain"’.

cups-configuration parameter: host-name-list-or-* server-alias

The ServerAlias directive is used for HTTP Host header validation when clients connect to the scheduler from external interfaces. Using the special name * can expose your system to known browser-based DNS rebinding attacks, even when accessing sites through a firewall. If the auto-discovery of alternate names does not work, we recommend listing each alternate name with a ServerAlias directive instead of using *.

Defaults to ‘*’.

cups-configuration parameter: string server-name

Specifies the fully-qualified host name of the server.

Defaults to ‘"localhost"’.

cups-configuration parameter: server-tokens server-tokens

Specifies what information is included in the Server header of HTTP responses. None disables the Server header. ProductOnly reports CUPS. Major reports CUPS 2. Minor reports CUPS 2.0. Minimal reports CUPS 2.0.0. OS reports CUPS 2.0.0 (uname) where uname is the output of the uname command. Full reports CUPS 2.0.0 (uname) IPP/2.0.

Defaults to ‘Minimal’.

cups-configuration parameter: string set-env

Set the specified environment variable to be passed to child processes.

Defaults to ‘"variable value"’.

cups-configuration parameter: multiline-string-list ssl-listen

Listens on the specified interfaces for encrypted connections. Valid values are of the form address:port, where address is either an IPv6 address enclosed in brackets, an IPv4 address, or * to indicate all addresses.

Defaults to ‘()’.

cups-configuration parameter: ssl-options ssl-options

Sets encryption options. By default, CUPS only supports encryption using TLS v1.0 or higher using known secure cipher suites. The AllowRC4 option enables the 128-bit RC4 cipher suites, which are required for some older clients that do not implement newer ones. The AllowSSL3 option enables SSL v3.0, which is required for some older clients that do not support TLS v1.0.

Defaults to ‘()’.

cups-configuration parameter: boolean strict-conformance?

Specifies whether the scheduler requires clients to strictly adhere to the IPP specifications.

Defaults to ‘#f’.

cups-configuration parameter: non-negative-integer timeout

Specifies the HTTP request timeout, in seconds.

Defaults to ‘300’.

cups-configuration parameter: boolean web-interface?

Specifies whether the web interface is enabled.

Defaults to ‘#f’.

At this point you’re probably thinking “oh dear, Guix manual, I like you but you can stop already with the configuration options”. Indeed. However, one more point: it could be that you have an existing cupsd.conf that you want to use. In that case, you can pass an opaque-cups-configuration as the configuration of a cups-service-type.

Available opaque-cups-configuration fields are:

opaque-cups-configuration parameter: package cups

The CUPS package.

opaque-cups-configuration parameter: string cupsd.conf

The contents of the cupsd.conf, as a string.

opaque-cups-configuration parameter: string cups-files.conf

The contents of the cups-files.conf file, as a string.

For example, if your cupsd.conf and cups-files.conf are in strings of the same name, you could instantiate a CUPS service like this:

(service cups-service-type
         (opaque-cups-configuration
           (cupsd.conf cupsd.conf)
           (cups-files.conf cups-files.conf)))

Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.7 Сервисы рабочего стола

The (gnu services desktop) module provides services that are usually useful in the context of a “desktop” setup—that is, on a machine running a graphical display server, possibly with graphical user interfaces, etc. It also defines services that provide specific desktop environments like GNOME, Xfce or MATE.

To simplify things, the module defines a variable containing the set of services that users typically expect on a machine with a graphical environment and networking:

Scheme Variable: %desktop-services

This is a list of services that builds upon %base-services and adds or adjusts services for a typical “desktop” setup.

In particular, it adds a graphical login manager (see gdm-service-type), screen lockers, a network management tool (see network-manager-service-type) with modem support (see modem-manager-service-type), energy and color management services, the elogind login and seat manager, the Polkit privilege service, the GeoClue location service, the AccountsService daemon that allows authorized users change system passwords, an NTP client (see Сервисы сети), the Avahi daemon, and has the name service switch service configured to be able to use nss-mdns (see mDNS).

The %desktop-services variable can be used as the services field of an operating-system declaration (see services).

Additionally, the gnome-desktop-service-type, xfce-desktop-service, mate-desktop-service-type and enlightenment-desktop-service-type procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To “add GNOME” means that system-level services like the backlight adjustment helpers and the power management utilities are added to the system, extending polkit and dbus appropriately, allowing GNOME to operate with elevated privileges on a limited number of special-purpose system interfaces. Additionally, adding a service made by gnome-desktop-service-type adds the GNOME metapackage to the system profile. Likewise, adding the Xfce service not only adds the xfce metapackage to the system profile, but it also gives the Thunar file manager the ability to open a “root-mode” file management window, if the user authenticates using the administrator’s password via the standard polkit graphical interface. To “add MATE” means that polkit and dbus are extended appropriately, allowing MATE to operate with elevated privileges on a limited number of special-purpose system interfaces. Additionally, adding a service of type mate-desktop-service-type adds the MATE metapackage to the system profile. “Adding Enlightenment” means that dbus is extended appropriately, and several of Enlightenment’s binaries are set as setuid, allowing Enlightenment’s screen locker and other functionality to work as expetected.

The desktop environments in Guix use the Xorg display server by default. If you’d like to use the newer display server protocol called Wayland, you need to use the sddm-service instead of GDM as the graphical login manager. You should then select the “GNOME (Wayland)” session in SDDM. Alternatively you can also try starting GNOME on Wayland manually from a TTY with the command “XDG_SESSION_TYPE=wayland exec dbus-run-session gnome-session“. Currently only GNOME has support for Wayland.

Scheme Variable: gnome-desktop-service-type

This is the type of the service that adds the GNOME desktop environment. Its value is a gnome-desktop-configuration object (see below.)

This service adds the gnome package to the system profile, and extends polkit with the actions from gnome-settings-daemon.

Data Type: gnome-desktop-configuration

Configuration record for the GNOME desktop environment.

gnome (default: gnome)

The GNOME package to use.

Scheme Variable: xfce-desktop-service-type

This is the type of a service to run the https://xfce.org/ desktop environment. Its value is an xfce-desktop-configuration object (see below.)

This service adds the xfce package to the system profile, and extends polkit with the ability for thunar to manipulate the file system as root from within a user session, after the user has authenticated with the administrator’s password.

Data Type: xfce-desktop-configuration

Configuration record for the Xfce desktop environment.

xfce (default: xfce)

The Xfce package to use.

Scheme Variable: mate-desktop-service-type

This is the type of the service that runs the MATE desktop environment. Its value is a mate-desktop-configuration object (see below.)

This service adds the mate package to the system profile, and extends polkit with the actions from mate-settings-daemon.

Data Type: mate-desktop-configuration

Configuration record for the MATE desktop environment.

mate (default: mate)

The MATE package to use.

Scheme Variable: enlightenment-desktop-service-type

Return a service that adds the enlightenment package to the system profile, and extends dbus with actions from efl.

Data Type: enlightenment-desktop-service-configuration
enlightenment (default: enlightenment)

The enlightenment package to use.

Because the GNOME, Xfce and MATE desktop services pull in so many packages, the default %desktop-services variable doesn’t include any of them by default. To add GNOME, Xfce or MATE, just cons them onto %desktop-services in the services field of your operating-system:

(use-modules (gnu))
(use-service-modules desktop)
(operating-system
  ...
  ;; cons* adds items to the list given as its last argument.
  (services (cons* (service gnome-desktop-service-type)
                   (service xfce-desktop-service)
                   %desktop-services))
  ...)

These desktop environments will then be available as options in the graphical login window.

The actual service definitions included in %desktop-services and provided by (gnu services dbus) and (gnu services desktop) are described below.

Scheme Procedure: dbus-service [#:dbus dbus] [#:services '()]

Return a service that runs the “system bus”, using dbus, with support for services.

D-Bus is an inter-process communication facility. Its system bus is used to allow system services to communicate and to be notified of system-wide events.

services must be a list of packages that provide an etc/dbus-1/system.d directory containing additional D-Bus configuration and policy files. For example, to allow avahi-daemon to use the system bus, services must be equal to (list avahi).

Scheme Procedure: elogind-service [#:config config]

Return a service that runs the elogind login and seat management daemon. Elogind exposes a D-Bus interface that can be used to know which users are logged in, know what kind of sessions they have open, suspend the system, inhibit system suspend, reboot the system, and other tasks.

Elogind handles most system-level power events for a computer, for example suspending the system when a lid is closed, or shutting it down when the power button is pressed.

The config keyword argument specifies the configuration for elogind, and should be the result of an (elogind-configuration (parameter value)...) invocation. Available parameters and their default values are:

kill-user-processes?

#f

kill-only-users

()

kill-exclude-users

("root")

inhibit-delay-max-seconds

5

handle-power-key

poweroff

handle-suspend-key

suspend

handle-hibernate-key

hibernate

handle-lid-switch

suspend

handle-lid-switch-docked

ignore

power-key-ignore-inhibited?

#f

suspend-key-ignore-inhibited?

#f

hibernate-key-ignore-inhibited?

#f

lid-switch-ignore-inhibited?

#t

holdoff-timeout-seconds

30

idle-action

ignore

idle-action-seconds

(* 30 60)

runtime-directory-size-percent

10

runtime-directory-size

#f

remove-ipc?

#t

suspend-state

("mem" "standby" "freeze")

suspend-mode

()

hibernate-state

("disk")

hibernate-mode

("platform" "shutdown")

hybrid-sleep-state

("disk")

hybrid-sleep-mode

("suspend" "platform" "shutdown")

Scheme Procedure: accountsservice-service [#:accountsservice accountsservice] Return a service that runs

AccountsService, a system service that can list available accounts, change their passwords, and so on. AccountsService integrates with PolicyKit to enable unprivileged users to acquire the capability to modify their system configuration. the accountsservice web site for more information.

The accountsservice keyword argument is the accountsservice package to expose as a service.

Scheme Procedure: polkit-service [#:polkit polkit] Return a service that runs the

Polkit privilege management service, which allows system administrators to grant access to privileged operations in a structured way. By querying the Polkit service, a privileged system component can know when it should grant additional capabilities to ordinary users. For example, an ordinary user can be granted the capability to suspend the system if the user is logged in locally.

Scheme Variable: upower-service-type

Service that runs upowerd, a system-wide monitor for power consumption and battery levels, with the given configuration settings.

It implements the org.freedesktop.UPower D-Bus interface, and is notably used by GNOME.

Data Type: upower-configuration

Data type representation the configuration for UPower.

upower (default: upower)

Package to use for upower.

watts-up-pro? (default: #f)

Enable the Watts Up Pro device.

poll-batteries? (default: #t)

Enable polling the kernel for battery level changes.

ignore-lid? (default: #f)

Ignore the lid state, this can be useful if it’s incorrect on a device.

use-percentage-for-policy? (default: #f)

Whether battery percentage based policy should be used. The default is to use the time left, change to #t to use the percentage.

percentage-low (default: 10)

When use-percentage-for-policy? is #t, this sets the percentage at which the battery is considered low.

percentage-critical (default: 3)

When use-percentage-for-policy? is #t, this sets the percentage at which the battery is considered critical.

percentage-action (default: 2)

When use-percentage-for-policy? is #t, this sets the percentage at which action will be taken.

time-low (default: 1200)

When use-time-for-policy? is #f, this sets the time remaining in seconds at which the battery is considered low.

time-critical (default: 300)

When use-time-for-policy? is #f, this sets the time remaining in seconds at which the battery is considered critical.

time-action (default: 120)

When use-time-for-policy? is #f, this sets the time remaining in seconds at which action will be taken.

critical-power-action (default: 'hybrid-sleep)

The action taken when percentage-action or time-action is reached (depending on the configuration of use-percentage-for-policy?).

Possible values are:

  • 'power-off
  • 'hibernate
  • 'hybrid-sleep.
Scheme Procedure: udisks-service [#:udisks udisks]

Return a service for UDisks, a disk management daemon that provides user interfaces with notifications and ways to mount/unmount disks. Programs that talk to UDisks include the udisksctl command, part of UDisks, and GNOME Disks.

Scheme Procedure: colord-service [#:colord colord]

Return a service that runs colord, a system service with a D-Bus interface to manage the color profiles of input and output devices such as screens and scanners. It is notably used by the GNOME Color Manager graphical tool. See the colord web site for more information.

Scheme Procedure: geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]

Return a configuration allowing an application to access GeoClue location data. name is the Desktop ID of the application, without the .desktop part. If allowed? is true, the application will have access to location information by default. The boolean system? value indicates whether an application is a system component or not. Finally users is a list of UIDs of all users for which this application is allowed location info access. An empty users list means that all users are allowed.

Scheme Variable: %standard-geoclue-applications

The standard list of well-known GeoClue application configurations, granting authority to the GNOME date-and-time utility to ask for the current location in order to set the time zone, and allowing the IceCat and Epiphany web browsers to request location information. IceCat and Epiphany both query the user before allowing a web page to know the user’s location.

Scheme Procedure: geoclue-service [#:colord colord] [#:whitelist '()]  [#:wifi-geolocation-url

"https://location.services.mozilla.com/v1/geolocate?key=geoclue"]  [#:submit-data? #f] [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"]  [#:submission-nick "geoclue"]  [#:applications %standard-geoclue-applications] Return a service that runs the GeoClue location service. This service provides a D-Bus interface to allow applications to request access to a user’s physical location, and optionally to add information to online location databases. See the GeoClue web site for more information.

Scheme Procedure: bluetooth-service [#:bluez bluez] [#:auto-enable? #f] Return a service that runs the bluetoothd

daemon, which manages all the Bluetooth devices and provides a number of D-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller is powered automatically at boot, which can be useful when using a bluetooth keyboard or mouse.

Users need to be in the lp group to access the D-Bus service.


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.8 Звуковые сервисы

The (gnu services sound) module provides a service to configure the Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the preferred ALSA output driver.

Scheme Variable: alsa-service-type

This is the type for the Advanced Linux Sound Architecture (ALSA) system, which generates the /etc/asound.conf configuration file. The value for this type is a alsa-configuration record as in this example:

(service alsa-service-type)

See below for details about alsa-configuration.

Data Type: alsa-configuration

Data type representing the configuration for alsa-service.

alsa-plugins (default: alsa-plugins)

alsa-plugins package to use.

pulseaudio? (default: #t)

Whether ALSA applications should transparently be made to use the PulseAudio sound server.

Using PulseAudio allows you to run several sound-producing applications at the same time and to individual control them via pavucontrol, among other things.

extra-options (default: "")

String to append to the /etc/asound.conf file.

Individual users who want to override the system configuration of ALSA can do it with the ~/.asoundrc file:

# In guix, we have to specify the absolute path for plugins.
pcm_type.jack {
  lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
}

# Routing ALSA to jack:
# <http://jackaudio.org/faq/routing_alsa.html>.
pcm.rawjack {
  type jack
  playback_ports {
    0 system:playback_1
    1 system:playback_2
  }

  capture_ports {
    0 system:capture_1
    1 system:capture_2
  }
}

pcm.!default {
  type plug
  slave {
    pcm "rawjack"
  }
}

See https://www.alsa-project.org/main/index.php/Asoundrc for the details.


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.9 Сервисы баз данных

The (gnu services databases) module provides the following services.

Scheme Procedure: postgresql-service [#:postgresql postgresql] [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']  [#:port

5432] [#:locale “en_US.utf8”] [#:extension-packages ’()] Return a service that runs postgresql, the PostgreSQL database server.

The PostgreSQL daemon loads its runtime configuration from config-file, creates a database cluster with locale as the default locale, stored in data-directory. It then listens on port.

Additional extensions are loaded from packages listed in extension-packages. Extensions are available at runtime. For instance, to create a geographic database using the postgis extension, a user can configure the postgresql-service as in this example:

(use-package-modules databases geo)

(operating-system
  ...
  ;; postgresql is required to run `psql' but postgis is not required for
  ;; proper operation.
  (packages (cons* postgresql %base-packages))
  (services
    (cons*
      (postgresql-service #:extension-packages (list postgis))
      %base-services)))

Then the extension becomes visible and you can initialise an empty geographic database in this way:

psql -U postgres
> create database postgistest;
> \connect postgistest;
> create extension postgis;
> create extension postgis_topology;

There is no need to add this field for contrib extensions such as hstore or dblink as they are already loadable by postgresql. This field is only required to add extensions provided by other packages.

Scheme Procedure: mysql-service [#:config (mysql-configuration)]

Return a service that runs mysqld, the MySQL or MariaDB database server.

The optional config argument specifies the configuration for mysqld, which should be a <mysql-configuration> object.

Data Type: mysql-configuration

Data type representing the configuration of mysql-service.

mysql (default: mariadb)

Package object of the MySQL database server, can be either mariadb or mysql.

For MySQL, a temporary root password will be displayed at activation time. For MariaDB, the root password is empty.

port (default: 3306)

TCP port on which the database server listens for incoming connections.

Scheme Variable: memcached-service-type

This is the service type for the Memcached service, which provides a distributed in memory cache. The value for the service type is a memcached-configuration object.

(service memcached-service-type)
Data Type: memcached-configuration

Data type representing the configuration of memcached.

memcached (default: memcached)

The Memcached package to use.

interfaces (default: '("0.0.0.0"))

Network interfaces on which to listen.

tcp-port (default: 11211)

Port on which to accept connections on,

udp-port (default: 11211)

Port on which to accept UDP connections on, a value of 0 will disable listening on a UDP socket.

additional-options (default: '())

Additional command line options to pass to memcached.

Scheme Variable: mongodb-service-type

This is the service type for MongoDB. The value for the service type is a mongodb-configuration object.

(service mongodb-service-type)
Data Type: mongodb-configuration

Data type representing the configuration of mongodb.

mongodb (default: mongodb)

The MongoDB package to use.

config-file (default: %default-mongodb-configuration-file)

The configuration file for MongoDB.

data-directory (default: "/var/lib/mongodb")

This value is used to create the directory, so that it exists and is owned by the mongodb user. It should match the data-directory which MongoDB is configured to use through the configuration file.

Scheme Variable: redis-service-type

This is the service type for the Redis key/value store, whose value is a redis-configuration object.

Data Type: redis-configuration

Data type representing the configuration of redis.

redis (default: redis)

The Redis package to use.

bind (default: "127.0.0.1")

Network interface on which to listen.

port (default: 6379)

Port on which to accept connections on, a value of 0 will disable listening on a TCP socket.

working-directory (default: "/var/lib/redis")

Directory in which to store the database and related files.


Next: , Previous: , Up: Сервисы   [Contents][Index]

8.8.10 Почтовые сервисы

The (gnu services mail) module provides Guix service definitions for email services: IMAP, POP3, and LMTP servers, as well as mail transport agents (MTAs). Lots of acronyms! These services are detailed in the subsections below.

Dovecot Service

Scheme Procedure: dovecot-service [#:config (dovecot-configuration)]

Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.

By default, Dovecot does not need much configuration; the default configuration object created by (dovecot-configuration) will suffice if your mail is delivered to ~/Maildir. A self-signed certificate will be generated for TLS-protected connections, though Dovecot will also listen on cleartext ports by default. There are a number of options, though, which mail administrators might need to change, and as is the case with other services, Guix allows the system administrator to specify these parameters via a uniform Scheme interface.

For example, to specify that mail is located at maildir~/.mail, one would instantiate the Dovecot service like this:

(dovecot-service #:config
                 (dovecot-configuration
                  (mail-location "maildir:~/.mail")))

The available configuration parameters follow. Each parameter definition is preceded by its type; for example, ‘string-list foo’ indicates that the foo parameter should be specified as a list of strings. There is also a way to specify the configuration as a string, if you have an old dovecot.conf file that you want to port over from some other system; see the end for more details.

Available dovecot-configuration fields are:

dovecot-configuration parameter: package dovecot

The dovecot package.

dovecot-configuration parameter: comma-separated-string-list listen

A list of IPs or hosts where to listen for connections. ‘*’ listens on all IPv4 interfaces, ‘::’ listens on all IPv6 interfaces. If you want to specify non-default ports or anything more complex, customize the address and port fields of the ‘inet-listener’ of the specific services you are interested in.

dovecot-configuration parameter: protocol-configuration-list protocols

List of protocols we want to serve. Available protocols include ‘imap’, ‘pop3’, and ‘lmtp’.

Available protocol-configuration fields are:

protocol-configuration parameter: string name

The name of the protocol.

protocol-configuration parameter: string auth-socket-path

UNIX socket path to the master authentication server to find users. This is used by imap (for shared users) and lda. It defaults to ‘"/var/run/dovecot/auth-userdb"’.

protocol-configuration parameter: space-separated-string-list mail-plugins

Space separated list of plugins to load.

protocol-configuration parameter: non-negative-integer mail-max-userip-connections

Maximum number of IMAP connections allowed for a user from each IP address. NOTE: The username is compared case-sensitively. Defaults to ‘10’.

dovecot-configuration parameter: service-configuration-list services

List of services to enable. Available services include ‘imap’, ‘imap-login’, ‘pop3’, ‘pop3-login’, ‘auth’, and ‘lmtp’.

Available service-configuration fields are:

service-configuration parameter: string kind

The service kind. Valid values include director, imap-login, pop3-login, lmtp, imap, pop3, auth, auth-worker, dict, tcpwrap, quota-warning, or anything else.

service-configuration parameter: listener-configuration-list listeners

Listeners for the service. A listener is either a unix-listener-configuration, a fifo-listener-configuration, or an inet-listener-configuration. Defaults to ‘()’.

Available unix-listener-configuration fields are:

unix-listener-configuration parameter: string path

Path to the file, relative to base-dir field. This is also used as the section name.

unix-listener-configuration parameter: string mode

The access mode for the socket. Defaults to ‘"0600"’.

unix-listener-configuration parameter: string user

The user to own the socket. Defaults to ‘""’.

unix-listener-configuration parameter: string group

The group to own the socket. Defaults to ‘""’.

Available fifo-listener-configuration fields are:

fifo-listener-configuration parameter: string path

Path to the file, relative to base-dir field. This is also used as the section name.

fifo-listener-configuration parameter: string mode

The access mode for the socket. Defaults to ‘"0600"’.

fifo-listener-configuration parameter: string user

The user to own the socket. Defaults to ‘""’.

fifo-listener-configuration parameter: string group

The group to own the socket. Defaults to ‘""’.

Available inet-listener-configuration fields are:

inet-listener-configuration parameter: string protocol

The protocol to listen for.

inet-listener-configuration parameter: string address

The address on which to listen, or empty for all addresses. Defaults to ‘""’.

inet-listener-configuration parameter: non-negative-integer port

The port on which to listen.

inet-listener-configuration parameter: boolean ssl?

Whether to use SSL for this service; ‘yes’, ‘no’, or ‘required’. Defaults to ‘#t’.

service-configuration parameter: non-negative-integer client-limit

Maximum number of simultaneous client connections per process. Once this number of connections is received, the next incoming connection will prompt Dovecot to spawn another process. If set to 0, default-client-limit is used instead.

Defaults to ‘0’.

service-configuration parameter: non-negative-integer service-count

Number of connections to handle before starting a new process. Typically the only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 is faster. <doc/wiki/LoginProcess.txt>. Defaults to ‘1’.

service-configuration parameter: non-negative-integer process-limit

Maximum number of processes that can exist for this service. If set to 0, default-process-limit is used instead.

Defaults to ‘0’.

service-configuration parameter: non-negative-integer process-min-avail

Number of processes to always keep waiting for more connections. Defaults to ‘0’.

service-configuration parameter: non-negative-integer vsz-limit

If you set ‘service-count 0’, you probably need to grow this. Defaults to ‘256000000’.

dovecot-configuration parameter: dict-configuration dict

Dict configuration, as created by the dict-configuration constructor.

Available dict-configuration fields are:

dict-configuration parameter: free-form-fields entries

A list of key-value pairs that this dict should hold. Defaults to ‘()’.

dovecot-configuration parameter: passdb-configuration-list passdbs

A list of passdb configurations, each one created by the passdb-configuration constructor.

Available passdb-configuration fields are:

passdb-configuration parameter: string driver

The driver that the passdb should use. Valid values include ‘pam’, ‘passwd’, ‘shadow’, ‘bsdauth’, and ‘static’. Defaults to ‘"pam"’.

passdb-configuration parameter: space-separated-string-list args

Space separated list of arguments to the passdb driver. Defaults to ‘""’.

dovecot-configuration parameter: userdb-configuration-list userdbs

List of userdb configurations, each one created by the userdb-configuration constructor.

Available userdb-configuration fields are:

userdb-configuration parameter: string driver

The driver that the userdb should use. Valid values include ‘passwd’ and ‘static’. Defaults to ‘"passwd"’.

userdb-configuration parameter: space-separated-string-list args

Space separated list of arguments to the userdb driver. Defaults to ‘""’.

userdb-configuration parameter: free-form-args override-fields

Override fields from passwd. Defaults to ‘()’.

dovecot-configuration parameter: plugin-configuration plugin-configuration

Plug-in configuration, created by the plugin-configuration constructor.

dovecot-configuration parameter: list-of-namespace-configuration namespaces

List of namespaces. Each item in the list is created by the namespace-configuration constructor.

Available namespace-configuration fields are:

namespace-configuration parameter: string name

Name for this namespace.

namespace-configuration parameter: string type

Namespace type: ‘private’, ‘shared’ or ‘public’. Defaults to ‘"private"’.

namespace-configuration parameter: string separator

Hierarchy separator to use. You should use the same separator for all namespaces or some clients get confused. ‘/’ is usually a good one. The default however depends on the underlying mail storage format. Defaults to ‘""’.

namespace-configuration parameter: string prefix

Prefix required to access this namespace. This needs to be different for all namespaces. For example ‘Public/’. Defaults to ‘""’.

namespace-configuration parameter: string location

Physical location of the mailbox. This is in the same format as mail_location, which is also the default for it. Defaults to ‘""’.

namespace-configuration parameter: boolean inbox?

There can be only one INBOX, and this setting defines which namespace has it. Defaults to ‘#f’.

namespace-configuration parameter: boolean hidden?

If namespace is hidden, it’s not advertised to clients via NAMESPACE extension. You’ll most likely also want to set ‘list? #f’. This is mostly useful when converting from another server with different namespaces which you want to deprecate but still keep working. For example you can create hidden namespaces with prefixes ‘~/mail/’, ‘~%u/mail/’ and ‘mail/’. Defaults to ‘#f’.

namespace-configuration parameter: boolean list?

Show the mailboxes under this namespace with the LIST command. This makes the namespace visible for clients that do not support the NAMESPACE extension. The special children value lists child mailboxes, but hides the namespace prefix. Defaults to ‘#t’.

namespace-configuration parameter: boolean subscriptions?

Namespace handles its own subscriptions. If set to #f, the parent namespace handles them. The empty prefix should always have this as #t). Defaults to ‘#t’.

namespace-configuration parameter: mailbox-configuration-list mailboxes

List of predefined mailboxes in this namespace. Defaults to ‘()’.

Available mailbox-configuration fields are:

mailbox-configuration parameter: string name

Name for this mailbox.

mailbox-configuration parameter: string auto

create’ will automatically create this mailbox. ‘subscribe’ will both create and subscribe to the mailbox. Defaults to ‘"no"’.

mailbox-configuration parameter: space-separated-string-list special-use

List of IMAP SPECIAL-USE attributes as specified by RFC 6154. Valid values are \All, \Archive, \Drafts, \Flagged, \Junk, \Sent, and \Trash. Defaults to ‘()’.

dovecot-configuration parameter: file-name base-dir

Base directory where to store runtime data. Defaults to ‘"/var/run/dovecot/"’.

dovecot-configuration parameter: string login-greeting

Greeting message for clients. Defaults to ‘"Dovecot ready."’.

dovecot-configuration parameter: space-separated-string-list login-trusted-networks

List of trusted network ranges. Connections from these IPs are allowed to override their IP addresses and ports (for logging and for authentication checks). ‘disable-plaintext-auth’ is also ignored for these networks. Typically you would specify your IMAP proxy servers here. Defaults to ‘()’.

dovecot-configuration parameter: space-separated-string-list login-access-sockets

List of login access check sockets (e.g. tcpwrap). Defaults to ‘()’.

dovecot-configuration parameter: boolean verbose-proctitle?

Show more verbose process titles (in ps). Currently shows user name and IP address. Useful for seeing who is actually using the IMAP processes (e.g. shared mailboxes or if the same uid is used for multiple accounts). Defaults to ‘#f’.

dovecot-configuration parameter: boolean shutdown-clients?

Should all processes be killed when Dovecot master process shuts down. Setting this to #f means that Dovecot can be upgraded without forcing existing client connections to close (although that could also be a problem if the upgrade is e.g. due to a security fix). Defaults to ‘#t’.

dovecot-configuration parameter: non-negative-integer doveadm-worker-count

If non-zero, run mail commands via this many connections to doveadm server, instead of running them directly in the same process. Defaults to ‘0’.

dovecot-configuration parameter: string doveadm-socket-path

UNIX socket or host:port used for connecting to doveadm server. Defaults to ‘"doveadm-server"’.

dovecot-configuration parameter: space-separated-string-list import-environment

List of environment variables that are preserved on Dovecot startup and passed down to all of its child processes. You can also give key=value pairs to always set specific settings.

dovecot-configuration parameter: boolean disable-plaintext-auth?

Disable LOGIN command and all other plaintext authentications unless SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP matches the local IP (i.e. you’re connecting from the same computer), the connection is considered secure and plaintext authentication is allowed. See also ssl=required setting. Defaults to ‘#t’.

dovecot-configuration parameter: non-negative-integer auth-cache-size

Authentication cache size (e.g. ‘#e10e6’). 0 means it’s disabled. Note that bsdauth, PAM and vpopmail require ‘cache-key’ to be set for caching to be used. Defaults to ‘0’.

dovecot-configuration parameter: string auth-cache-ttl

Time to live for cached data. After TTL expires the cached record is no longer used, *except* if the main database lookup returns internal failure. We also try to handle password changes automatically: If user’s previous authentication was successful, but this one wasn’t, the cache isn’t used. For now this works only with plaintext authentication. Defaults to ‘"1 hour"’.

dovecot-configuration parameter: string auth-cache-negative-ttl

TTL for negative hits (user not found, password mismatch). 0 disables caching them completely. Defaults to ‘"1 hour"’.

dovecot-configuration parameter: space-separated-string-list auth-realms

List of realms for SASL authentication mechanisms that need them. You can leave it empty if you don’t want to support multiple realms. Many clients simply use the first one listed here, so keep the default realm first. Defaults to ‘()’.

dovecot-configuration parameter: string auth-default-realm

Default realm/domain to use if none was specified. This is used for both SASL realms and appending @domain to username in plaintext logins. Defaults to ‘""’.

dovecot-configuration parameter: string auth-username-chars

List of allowed characters in username. If the user-given username contains a character not listed in here, the login automatically fails. This is just an extra check to make sure user can’t exploit any potential quote escaping vulnerabilities with SQL/LDAP databases. If you want to allow all characters, set this value to empty. Defaults to ‘"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@"’.

dovecot-configuration parameter: string auth-username-translation

Username character translations before it’s looked up from databases. The value contains series of from -> to characters. For example ‘#@/@’ means that ‘#’ and ‘/’ characters are translated to ‘@’. Defaults to ‘""’.

dovecot-configuration parameter: string auth-username-format

Username formatting before it’s looked up from databases. You can use the standard variables here, e.g. %Lu would lowercase the username, %n would drop away the domain if it was given, or ‘%n-AT-%d’ would change the ‘@’ into ‘-AT-’. This translation is done after ‘auth-username-translation’ changes. Defaults to ‘"%Lu"’.

dovecot-configuration parameter: string auth-master-user-separator

If you want to allow master users to log in by specifying the master username within the normal username string (i.e. not using SASL mechanism’s support for it), you can specify the separator character here. The format is then <username><separator><master username>. UW-IMAP uses ‘*’ as the separator, so that could be a good choice. Defaults to ‘""’.

dovecot-configuration parameter: string auth-anonymous-username

Username to use for users logging in with ANONYMOUS SASL mechanism. Defaults to ‘"anonymous"’.

dovecot-configuration parameter: non-negative-integer auth-worker-max-count

Maximum number of dovecot-auth worker processes. They’re used to execute blocking passdb and userdb queries (e.g. MySQL and PAM). They’re automatically created and destroyed as needed. Defaults to ‘30’.

dovecot-configuration parameter: string auth-gssapi-hostname

Host name to use in GSSAPI principal names. The default is to use the name returned by gethostname(). Use ‘$ALL’ (with quotes) to allow all keytab entries. Defaults to ‘""’.

dovecot-configuration parameter: string auth-krb5-keytab

Kerberos keytab to use for the GSSAPI mechanism. Will use the system default (usually /etc/krb5.keytab) if not specified. You may need to change the auth service to run as root to be able to read this file. Defaults to ‘""’.

dovecot-configuration parameter: boolean auth-use-winbind?

Do NTLM and GSS-SPNEGO authentication using Samba’s winbind daemon and ‘ntlm-auth’ helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>. Defaults to ‘#f’.

dovecot-configuration parameter: file-name auth-winbind-helper-path

Path for Samba’s ‘ntlm-auth’ helper binary. Defaults to ‘"/usr/bin/ntlm_auth"’.

dovecot-configuration parameter: string auth-failure-delay

Time to delay before replying to failed authentications. Defaults to ‘"2 secs"’.