7.1 Вызов guix shell

The purpose of guix shell is to make it easy to create one-off software environments, without changing one’s profile. It is typically used to create development environments; it is also a convenient way to run applications without “polluting” your profile.

Примечание: The guix shell command was recently introduced to supersede guix environment (see Вызов guix environment). If you are familiar with guix environment, you will notice that it is similar but also—we hope!—more convenient.

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

guix shell [options] [package…]

The following example creates an environment containing Python and NumPy, building or downloading any missing package, and runs the python3 command in that environment:

guix shell python python-numpy -- python3

Note that it is necessary to include the main python package in this command even if it is already installed into your environment. This is so that the shell environment knows to set PYTHONPATH and other related variables. The shell environment cannot check the previously installed environment, because then it would be non-deterministic. This is true for most libraries: their corresponding language package should be included in the shell invocation.

Примечание: guix shell can be also be used as a script interpreter, also known as shebang. Here is an example self-contained Python script making use of this feature:

#!/usr/bin/env -S guix shell python python-numpy -- python3
import numpy
print("This is numpy", numpy.version.version)

You may pass any guix shell option, but there’s one caveat: the Linux kernel has a limit of 127 bytes on shebang length.

Development environments can be created as in the example below, which spawns an interactive shell containing all the dependencies and environment variables needed to work on Inkscape:

guix shell --development inkscape

Exiting the shell places the user back in the original environment before guix shell was invoked. The next garbage collection (see Вызов guix gc) may clean up packages that were installed in the environment and that are no longer used outside of it.

As an added convenience, guix shell will try to do what you mean when it is invoked interactively without any other arguments as in:

guix shell

If it finds a manifest.scm in the current working directory or any of its parents, it uses this manifest as though it was given via --manifest. Likewise, if it finds a guix.scm in the same directories, it uses it to build a development profile as though both --development and --file were present. In either case, the file will only be loaded if the directory it resides in is listed in ~/.config/guix/shell-authorized-directories. This provides an easy way to define, share, and enter development environments.

By default, the shell session or command runs in an augmented environment, where the new packages are added to search path environment variables such as PATH. You can, instead, choose to create an isolated environment containing nothing but the packages you asked for. Passing the --pure option clears environment variable definitions found in the parent environment¹⁴; passing --container goes one step further by spawning a container isolated from the rest of the system:

guix shell --container emacs gcc-toolchain

The command above spawns an interactive shell in a container where nothing but emacs, gcc-toolchain, and their dependencies is available. The container lacks network access and shares no files other than the current working directory with the surrounding environment. This is useful to prevent access to system-wide resources such as /usr/bin on foreign distros.

This --container option can also prove useful if you wish to run a security-sensitive application, such as a web browser, in an isolated environment. For example, the command below launches Ungoogled-Chromium in an isolated environment, which:

• shares network access with the host
• inherits host’s environment variables DISPLAY and XAUTHORITY
• has access to host’s authentication records from the XAUTHORITY file
• has no information about host’s current directory

guix shell --container --network --no-cwd ungoogled-chromium \
  --preserve='^XAUTHORITY$' --expose="${XAUTHORITY}" \
  --preserve='^DISPLAY$' -- chromium

guix shell определяет переменную 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"

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

--check

Set up the environment and check whether the shell would clobber environment variables. It’s a good idea to use this option the first time you run guix shell for an interactive session to make sure your setup is correct.

For example, if the shell modifies the PATH environment variable, report it since you would get a different environment than what you asked for.

Such problems usually indicate that the shell startup files are unexpectedly modifying those environment variables. For example, if you are using Bash, make sure that environment variables are set or modified in ~/.bash_profile and not in ~/.bashrc—the former is sourced only by log-in shells. See Bash Startup Files in The GNU Bash Reference Manual, for details on Bash start-up files.

--development

-D

Cause guix shell to include in the environment the dependencies of the following package rather than the package itself. This can be combined with other packages. For instance, the command below starts an interactive shell containing the build-time dependencies of GNU Guile, plus Autoconf, Automake, and Libtool:

guix shell -D guile autoconf automake libtool

--expression=expr

-e expr

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

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

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

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

Запуск:

guix shell -e '(@ (gnu) %base-packages)'

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

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

guix shell -e '(list (@ (gnu packages bash) bash) "include")'

See package->development-manifest, for information on how to write a manifest for the development environment of a package.

--file=file

-f file

Create an environment containing the package or list of packages that the code within file evaluates to.

Например, 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 (modify-inputs (package-native-inputs gdb)
                   (prepend autoconf-2.69 automake texinfo))))

With the file above, you can enter a development environment for GDB by running:

guix shell -D -f gdb-devel.scm

--manifest=file

-m file

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

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

See Writing Manifests, for information on how to write a manifest. See --export-manifest below on how to obtain a first manifest.

--export-manifest

Write to standard output a manifest suitable for --manifest corresponding to given command-line options.

This is a way to “convert” command-line arguments into a manifest. For example, imagine you are tired of typing long lines and would like to get a manifest equivalent to this command line:

guix shell -D guile git emacs emacs-geiser emacs-geiser-guile

Just add --export-manifest to the command line above:

guix shell --export-manifest \
  -D guile git emacs emacs-geiser emacs-geiser-guile

... and you get a manifest along these lines:

(concatenate-manifests
  (list (specifications->manifest
          (list "git"
                "emacs"
                "emacs-geiser"
                "emacs-geiser-guile"))
        (package->development-manifest
          (specification->package "guile"))))

You can store it into a file, say manifest.scm, and from there pass it to guix shell or indeed pretty much any guix command:

guix shell -m manifest.scm

Voilà, you’ve converted a long command line into a manifest! That conversion process honors package transformation options (see Параметры преобразования пакета) so it should be lossless.

--profile=profile

-p profile

Создает окружение, содержащее пакеты, установленные в profile. Используйте guix package (see Вызов guix package) для создания и управления профилями.

--pure

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

--preserve=regexp

-E regexp

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

guix shell --pure --preserve=^SLURM 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 shell вызвана в домашней директории пользователя.

Определённые пакеты сконфигурированы, чтобы смотреть конфигурационные файлы и данные в ~/.guix-profile;¹⁵ --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 shell --container --user=foo \
     --expose=$HOME/test \
     --expose=/tmp/target=$HOME/target

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

--no-cwd

Для контейнеров стандартным поведением является разделение текущего рабочего каталога с изолированным контейнером и немедленное переключение на этот каталог в контейнере. Если это нежелательно, --no-cwd приведет к автоматическому доступу к текущему рабочему каталогу not, который изменится на домашний каталог пользователя в контейнере. Смотрите также --user.

--expose=source[=target]

--share=source[=target]

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

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

guix shell --container --expose=$HOME=/exchange guile -- guile

--symlink=spec

-S spec

For containers, create the symbolic links specified by spec, as documented in pack-symlink-option.

--emulate-fhs

-F

When used with --container, emulate a Filesystem Hierarchy Standard (FHS) configuration within the container, providing /bin, /lib, and other directories and files specified by the FHS.

As Guix deviates from the FHS specification, this option sets up the container to more closely mimic that of other GNU/Linux distributions. This is useful for reproducing other development environments, testing, and using programs which expect the FHS specification to be followed. With this option, the container will include a version of glibc that will read /etc/ld.so.cache within the container for the shared library cache (contrary to glibc in regular Guix usage) and set up the expected FHS directories: /bin, /etc, /lib, and /usr from the container’s profile.

--nesting

-W

When used with --container, provide Guix inside the container and arrange so that it can interact with the build daemon that runs outside the container. This is useful if you want, within your isolated container, to create other containers, as in this sample session:

$ guix shell -CW coreutils
[env]$ guix shell -C guile -- guile -c '(display "hello!\n")'
hello!
[env]$ exit

The session above starts a container with coreutils programs available in PATH. From there, we spawn guix shell to create a nested container that provides nothing but Guile.

Another example is evaluating a guix.scm file that is untrusted, as shown here:

guix shell -CW -- guix build -f guix.scm

The guix build command as executed above can only access the current directory.

Under the hood, the -W option does several things:

• отобразит сокет демона (по умолчанию /var/guix/daemon-socket/socket) внутри контейнера;
• map the whole store (by default /gnu/store) inside the container such that store items made available by nested guix invocations are visible;
• add the currently-used guix command to the profile in the container, such that guix describe returns the same state inside and outside the container;
• share the cache (by default ~/.cache/guix) with the host, to speed up operations such as guix time-machine and guix shell.

--rebuild-cache ¶

In most cases, guix shell caches the environment so that subsequent uses are instantaneous. Least-recently used cache entries are periodically removed. The cache is also invalidated, when using --file or --manifest, anytime the corresponding file is modified.

The --rebuild-cache forces the cached environment to be refreshed. This is useful when using --file or --manifest and the guix.scm or manifest.scm file has external dependencies, or if its behavior depends, say, on environment variables.

--root=file ¶

-r file

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

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

When this option is omitted, guix shell caches profiles so that subsequent uses of the same environment are instantaneous—this is comparable to using --root except that guix shell takes care of periodically removing the least-recently used garbage collector roots.

In some cases, guix shell does not cache profiles—e.g., if transformation options such as --with-latest are used. In those cases, the environment is protected from garbage collection only for the duration of the guix shell session. This means that next time you recreate the same environment, you could have to rebuild or re-download packages.

See Вызов guix gc, for more on GC roots.

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