1.1 Gerenciando software do jeito do Guix

O Guix fornece uma interface de gerenciamento de pacotes de linha de comando (veja Gerenciamento de pacote), ferramentas para ajudar no desenvolvimento de software (veja Desenvolvimento), utilitários de linha de comando para uso mais avançado (veja Utilitários), bem como interfaces de programação Scheme (veja Interface de programação). O build daemon é responsável por compilar pacotes em nome dos usuários (veja Configurando o daemon) e por baixar binários pré-compilados de fontes autorizados (veja Substitutos).

Guix inclui definições de pacotes para muitos pacotes GNU e não-GNU, todos os quais respeitam a liberdade de computação do usuário. É extensível: os usuários podem escrever suas próprias definições de pacotes (veja Definindo pacotes) e disponibilizá-los como módulos de pacotes independentes (veja Módulos de pacote). Também é personalizável: os usuários podem derivar definições de pacotes especializados das existentes, incluindo da linha de comando (veja Opções de transformação de pacote).

Nos bastidores, a Guix implementa a disciplina gerenciamento de pacotes funcional pioneira da Nix (veja Agradecimentos). No Guix, o processo de compilação e instalação de pacotes é visto como uma função, no sentido matemático. Essa função recebe entradas, como scripts de compilação, um compilador e bibliotecas, e retorna um pacote instalado. Como uma função pura, seu resultado depende apenas de suas entradas – por exemplo, não pode fazer referência a um software ou scripts que não foram explicitamente passados como entradas. Uma função de compilação sempre produz o mesmo resultado ao passar por um determinado conjunto de entradas. Não pode alterar o ambiente do sistema em execução de qualquer forma; por exemplo, ele não pode criar, modificar ou excluir arquivos fora de seus diretórios de compilação e instalação. Isto é conseguido através da execução de processos de compilação em ambientes isolados (ou containers), onde somente suas entradas explícitas são visíveis.

O resultado das funções de compilação do pacote é mantido (cached) no sistema de arquivos, em um diretório especial chamado armazém (veja O armazém). Cada pacote é instalado em um diretório próprio no armazém – por padrão, em /gnu/store. O nome do diretório contém um hash de todas as entradas usadas para compilar esse pacote; Assim, a alteração uma entrada gera um nome de diretório diferente.

Essa abordagem é a fundação para os principais recursos do Guix: suporte para atualização transacional de pacotes e reversão, instalação por usuário e coleta de lixo de pacotes (veja Recursos).

1.2 Distribuição GNU

O Guix vem com uma distribuição do sistema GNU que consiste inteiramente de software livre³. A distribuição pode ser instalada por conta própria (veja Instalação do sistema), mas também é possível instalar o Guix como um gerenciador de pacotes em cima de um sistema GNU/Linux instalado (veja Instalação). Quando precisamos distinguir entre os dois, nos referimos à distribuição independente como Guix System.

A distribuição fornece pacotes GNU principais, como GNU libc, GCC e Binutils, além de muitos aplicativos GNU e não GNU. A lista completa de pacotes disponíveis pode ser acessada online ou executando guix package (veja Invocando guix package):

guix package --list-available

Nosso objetivo é fornecer uma distribuição prática e 100% de software livre, baseada em Linux e outras variantes do GNU, com foco na promoção e forte integração de componentes do GNU e ênfase em programas e ferramentas que ajudam os usuários a exercer essa liberdade.

Os pacotes estão atualmente disponíveis nas seguintes plataformas:

x86_64-linux

Arquitetura Intel/AMD x86_64, kernel Linux-Libre.

i686-linux

Arquitetura Intel de 32 bits (IA32), kernel Linux-Libre.

armhf-linux

Arquitetura ARMv7-A com hard float, Thumb-2 e NEON, usando a interface binária de aplicativos EABI hard-float (ABI) e o kernel Linux-Libre.

aarch64-linux

Processadores ARMv8-A little-endian de 64 bits, kernel Linux-Libre.

i586-gnu

GNU/Hurd sobre a arquitetura Intel de 32 bits (IA32).

Esta configuração é experimental e está em desenvolvimento. A maneira mais fácil de você tentar é configurando uma instância de hurd-vm-service-type na sua máquina GNU/Linux (veja hurd-vm-service-type). Veja Contribuindo, sobre como ajudar!

mips64el-linux (sem suporte)

processadores little-endian MIPS de 64 bits, especificamente a série Loongson, n32 ABI e kernel Linux-Libre. Esta configuração não é mais totalmente suportada; em particular, não há trabalho em andamento para garantir que esta arquitetura ainda funcione. Caso alguém decida que deseja reviver esta arquitetura, o código ainda estará disponível.

powerpc-linux (sem suporte)

processadores PowerPC big-endian de 32 bits, especificamente o PowerPC G4 com suporte AltiVec e kernel Linux-Libre. Esta configuração não é totalmente suportada e não há trabalho em andamento para garantir que esta arquitetura funcione.

powerpc64le-linux

processadores little-endian 64 bits Power ISA, kernel Linux-Libre. Isso inclui sistemas POWER9 como o placa-mãe RYF Talos II. Esta plataforma está disponível como uma "prévia de tecnologia": embora seja suportada, substitutos ainda não estão disponíveis na fazenda de construção (veja Substitutos), e alguns pacotes podem falhar na construção (veja Rastreando Bugs e Mudanças). Dito isso, a comunidade Guix está trabalhando ativamente para melhorar esse suporte, e agora é um ótimo momento para experimentá-lo e se envolver!

riscv64-linux

processadores little-endian RISC-V de 64 bits, especificamente RV64GC, e kernel Linux-Libre. Esta plataforma está disponível como uma "prévia de tecnologia": embora seja suportada, substitutos ainda não estão disponíveis na build farm (veja Substitutos), e alguns pacotes podem falhar na compilação (veja Rastreando Bugs e Mudanças). Dito isto, a comunidade Guix está trabalhando ativamente para melhorar este suporte, e agora é um ótimo momento para experimentá-lo e se envolver!

Com o Guix System, você declara todos os aspectos da configuração do sistema operacional, e o Guix cuida de instanciar a configuração de maneira transacional, reproduzível e sem estado (veja Configuração do sistema). O Guix System usa o kernel Linux-libre, o sistema de inicialização Shepherd (veja Introduction em The GNU Shepherd Manual), os conhecidos utilitários do GNU e cadeia de ferramentas, bem como o ambiente gráfico ou os serviços de sistema do sua escolha.

Guix System is available on all the above platforms except mips64el-linux, powerpc-linux, powerpc64le-linux and riscv64-linux.

Para obter informações sobre como portar para outras arquiteturas ou kernels, veja Portando para uma nova plataforma.

A construção desta distribuição é um esforço cooperativo e você está convidado a participar! Veja Contribuindo, para obter informações sobre como você pode ajudar.

2.1 Instalação de binários

This section describes how to install Guix from a self-contained tarball providing binaries for Guix and for all its dependencies. This is often quicker than installing from source, described later (veja Compilando do git).

Importante: Esta seção se aplica somente a sistemas sem Guix. Segui-la para instalações Guix existentes sobrescreverá arquivos importantes do sistema.

Algumas distribuições GNU/Linux, como Debian, Ubuntu e openSUSE fornecem Guix por meio de seus próprios gerenciadores de pacotes. A versão do Guix pode ser mais antiga que 9b1de85, mas você pode atualizá-la depois executando ‘guix pull’.

Aconselhamos os administradores de sistema que instalam o Guix, tanto a partir do script de instalação quanto por meio do gerenciador de pacotes nativo de sua distribuição estrangeira, a também ler e seguir regularmente os avisos de segurança, conforme mostrado pelo guix pull.

Para Debian ou derivados como Ubuntu ou Trisquel, chame:

sudo apt install guix

Da mesma forma, no openSUSE:

sudo zypper install guix

Se você estiver executando o Parabola, depois de habilitar o repositório pcr (Parabola Community Repo), você pode instalar o Guix com:

sudo pacman -S guix

O projeto Guix também fornece um script de shell, guix-install.sh, que automatiza o processo de instalação binária sem o uso de um gerenciador de pacotes de distro estrangeiro⁵. O uso de guix-install.sh requer Bash, GnuPG, GNU tar, wget e Xz.

The script guides you through the following:

• Baixando e extraindo o tarball binário
• Setting up the build daemon
• Disponibilizando o comando ‘guix’ para usuários não root
• Configuring substitute servers

Como root, execute:

# cd /tmp
# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
# chmod +x guix-install.sh
# ./guix-install.sh

O script para instalar o Guix também está empacotado no Parabola (no repositório pcr). Você pode instalá-lo e executá-lo com:

sudo pacman -S guix-installer
sudo guix-install.sh

Nota: Por padrão, guix-install.sh configurará o Guix para baixar binários de pacotes pré-construídos, chamados substitutes (veja Substitutos), das fazendas de construção do projeto. Se você escolher não permitir isso, o Guix construirá tudo a partir da fonte, tornando cada instalação e atualização muito cara. Veja Confiança em binários para uma discussão sobre por que você pode querer construir pacotes a partir da fonte.

Para usar substitutos de bordeaux.guix.gnu.org, ci.guix.gnu.org ou um espelho, você deve autorizá-los. Por exemplo,

# guix archive --authorize < \
     ~root/.config/guix/current/share/guix/bordeaux.guix.gnu.org.pub
# guix archive --authorize < \
     ~root/.config/guix/current/share/guix/ci.guix.gnu.org.pub

Quando terminar de instalar o Guix, veja Configuração de aplicativo para configurações extras que você pode precisar e Começando para seus primeiros passos!

Nota: O tarball da instalação binária pode ser (re)produzido e verificado simplesmente executando o seguinte comando na árvore de código-fonte do Guix:

make guix-binary.system.tar.xz

... que, por sua vez, executa:

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

Veja Invocando guix pack, para mais informações sobre essa ferramenta útil.

Caso você queira desinstalar o Guix, execute o mesmo script com o sinalizador --uninstall:

./guix-install.sh --uninstall

Com --uninstall, o script exclui irreversivelmente todos os arquivos Guix, configuração e serviços.

2.2 Configurando o daemon

Durante a instalação, o build daemon que deve estar em execução para usar o Guix já foi configurado e você pode executar comandos guix no seu programa de terminal, veja Começando:

guix build hello

Se isso ocorrer sem erros, sinta-se à vontade para pular esta seção. Você deve continuar com a seção seguinte, Configuração de aplicativo.

No entanto, agora seria um bom momento para substituir versões desatualizadas do daemon, ajustá-lo, executar compilações em outras máquinas (veja Usando o recurso de descarregamento) ou iniciá-lo manualmente em ambientes especiais como “chroots” (veja Acessando um sistema existente via chroot) ou WSL (não necessário para imagens WSL criadas com Guix, veja wsl2-image-type). Se você quiser saber mais ou otimizar seu sistema, vale a pena ler esta seção.

Operações como compilar um pacote ou executar o coletor de lixo são todas executadas por um processo especializado, o build daemon, em nome dos clientes. Apenas o daemon pode acessar o armazém e seu banco de dados associado. Assim, qualquer operação que manipule o armazém passa pelo daemon. Por exemplo, ferramentas de linha de comando como guix package e guix build se comunicam com o daemon (via chamadas de procedimento remoto) para instruir o que fazer.

As seções a seguir explicam como preparar o ambiente do daemon de compilação. Veja Substitutos para informações sobre como permitir que o daemon baixe binários pré-compilados.

• Configuração do ambiente de compilação
• Usando o recurso de descarregamento
• Suporte a SELinux

# 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

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

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

      (build-machine
        (name "armeight.example.org")
        (systems (list "aarch64-linux"))
        (host-key "ssh-rsa AAAAB3Nza…")
        (user "alice")

        ;; Lembre-se de que 'guix offload' é gerado por
        ;; 'guix-daemon' como root.
        (private-key "/root/.ssh/identity-for-guix")))

ssh build-machine guix repl --version

# guix archive --generate-key

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

# guix offload test

# guix offload test machines-qualif.scm

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

# guix offload status

semodule -i /var/guix/profiles/per-user/root/current-guix/share/selinux/guix-daemon.cil

mount -o remount,rw /gnu/store
restorecon -R /gnu /var/guix

systemctl restart guix-daemon

ps -Zax | grep guix-daemon

2.3 Invocando guix-daemon

O programa guix-daemon implementa todas as funcionalidades para acessar o armazém. Isso inclui iniciar processos de compilação, executar o coletor de lixo, consultar a disponibilidade de um resultado da compilação etc. É normalmente executado como root, assim:

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

Este daemon também pode ser iniciado seguindo o protocolo de “ativação de soquete” do systemd (veja make-systemd-constructor em The GNU Shepherd Manual).

Para detalhes sobre como configurá-lo, veja Configurando o daemon.

Por padrão, guix-daemon inicia processos de compilação sob diferentes UIDs, obtidos do grupo de compilação especificado com --build-users-group. Além disso, cada processo de compilação é executado em um ambiente chroot que contém apenas o subconjunto do armazém do qual o processo de compilação depende, conforme especificado por sua derivação (veja derivação), mais um conjunto de diretórios de sistema específicos. Por padrão, o último contém /dev e /dev/pts. Além disso, no GNU/Linux, o ambiente de compilação é um container: além de ter sua própria árvore de sistema de arquivos, ele tem um espaço de nome de montagem separado, seu próprio espaço de nome PID, espaço de nome de rede, etc. Isso ajuda a obter compilações reproduzíveis (veja Recursos).

Quando o daemon executa uma compilação em nome do usuário, ele cria um diretório de compilação em /tmp ou no diretório especificado por sua variável de ambiente TMPDIR. Esse diretório é compartilhado com o contêiner durante a compilação, embora dentro do contêiner, a árvore de compilação seja sempre chamada de /tmp/guix-build-name.drv-0.

O diretório de compilação é excluído automaticamente após a conclusão, a menos que a compilação falhe e o cliente tenha especificado --keep-failed (veja --keep-failed).

O daemon escuta conexões e gera um subprocesso para cada sessão iniciada por um cliente (um dos subcomandos guix). O comando guix processes permite que você tenha uma visão geral da atividade no seu sistema visualizando cada uma das sessões e clientes ativos. Veja Invocando guix processes, para mais informações.

As seguintes opções de linha de comando são suportadas:

--build-users-group=grupo

Obtém os usuários do grupo para executar os processos de compilação (veja usuários de compilação).

--no-substitutes ¶

Não use substitutos para compilar produtos. Ou seja, sempre crie coisas localmente, em vez de permitir downloads de binários pré-compilados (veja Substitutos).

Quando o daemon é executado com --no-substitutes, os clientes ainda podem habilitar explicitamente a substituição por meio da chamada de procedimento remoto set-build-options (veja O armazém).

--substitute-urls=urls

Consider urls the default whitespace-separated list of substitute source URLs. When this option is omitted, ‘https://bordeaux.guix.gnu.org https://ci.guix.gnu.org’ is used.

Isso significa que os substitutos podem ser baixados de urls, desde que assinados por uma assinatura confiável (veja Substitutos).

Veja Obtendo substitutos de outros servidores, para mais informações sobre como configurar o daemon para obter substitutos de outros servidores.

--no-offload

Não use compilações de offload para outras máquinas (veja Usando o recurso de descarregamento). Ou seja, sempre compile as coisas localmente em vez de descarregar compilações para máquinas remotas.

--cache-failures

Armazena em cache as compilações que falharam. Por padrão, apenas compilações bem-sucedidas são armazenadas em cache.

Quando essa opção é usada, o guix gc --list-failures pode ser usado para consultar o conjunto de itens do armazém marcados como com falha; O guix gc --clear-failures remove os itens do armazém do conjunto de falhas em cache. Veja Invocando guix gc.

--cores=n

-c n

Usa n núcleos de CPU para compilar cada derivação; 0 significa todos disponíveis.

O valor padrão é 0, mas pode ser substituído pelos clientes, como a opção --cores de guix build (veja Invocando guix build).

O efeito é definir a variável de ambiente NIX_BUILD_CORES no processo de compilação, que pode então usá-la para explorar o paralelismo interno — por exemplo, executando make -j$NIX_BUILD_CORES.

--max-jobs=n

-M n

Permite no máximo n tarefas de compilação em paralelo. O valor padrão é 1. Definir como 0 significa que nenhuma compilação será executada localmente; em vez disso, o daemon descarregará as compilações (veja Usando o recurso de descarregamento) ou simplesmente falhará.

--max-silent-time=segundos

Quando o processo de compilação ou substituição permanecer em silêncio por mais de segundos, encerra-o e relata uma falha de compilação.

The default value is 3600 (one hour).

O valor especificado aqui pode ser substituído pelos clientes (veja --max-silent-time).

--timeout=segundos

Da mesma forma, quando o processo de compilação ou substituição durar mais que segundos, encerra-o e relata uma falha de compilação.

O valor padrão é 24 horas.

O valor especificado aqui pode ser substituído pelos clientes (veja --timeout).

--rounds=N

Compila cada derivação n vezes seguidas e gera um erro se os resultados consecutivos da compilação não forem idênticos bit a bit. Observe que essa configuração pode ser substituída por clientes como guix build (veja Invocando guix build).

Quando usado em conjunto com --keep-failed, uma saída de comparação é mantida no armazém, sob /gnu/store/…-check. Isso facilita procurar por diferenças entre os dois resultados.

--debug

Produz uma saída de depuração.

Isso é útil para depurar problemas de inicialização do daemon, mas pode ser substituído pelos clientes, por exemplo, a opção --verbosity de guix build (veja Invocando guix build).

--chroot-directory=dir

adiciona dir ao chroot de compilação.

Isso pode alterar o resultado dos processos de compilação – por exemplo, se eles usam dependências opcionais encontradas em dir quando estão disponíveis, e não o contrário. Por esse motivo, não é recomendável fazê-lo. Em vez disso, verifique se cada derivação declara todas as entradas necessárias.

--disable-chroot

Desabilita compilações em chroot.

O uso dessa opção não é recomendado, pois, novamente, isso permitiria que os processos de compilação obtivessem acesso a dependências não declaradas. Porém, é necessário quando o guix-daemon está sendo executado em uma conta de usuário sem privilégios.

--log-compression=tipo

Compacta logs de compilação de aconrdo com tipo, que pode ser um entre gzip, bzip2 e none.

A menos que --lose-logs seja usado, todos os logs de build são mantidos em localstatedir. Para economizar espaço, o daemon os compacta automaticamente com gzip por padrão.

--discover[=yes|no]

Se deve descobrir servidores substitutos na rede local usando mDNS e DNS-SD.

Este recurso ainda é experimental. No entanto, aqui estão algumas considerações.

1. Pode ser mais rápido/menos caro do que buscar em servidores remotos;
2. Não há riscos de segurança, apenas substitutos genuínos serão usados (veja Autenticação de substituto);
3. Um invasor anunciando guix publish na sua LAN não pode fornecer binários maliciosos, mas pode descobrir qual software você está instalando;
4. Os servidores podem servir substitutos via HTTP, sem criptografia, para que qualquer pessoa na LAN possa ver qual software você está instalando.

Também é possível habilitar ou desabilitar a descoberta de servidor substituto em tempo de execução executando:

herd discover guix-daemon on
herd discover guix-daemon off

--disable-deduplication ¶

Desabilita “deduplicação” automática de arquivos no armazém.

Por padrão, os arquivos adicionados ao armazém são automaticamente “deduplicados”: se um arquivo recém-adicionado for idêntico a outro encontrado no armazém, o daemon tornará o novo arquivo um link físico para o outro arquivo. Isso pode reduzir notavelmente o uso do disco, às custas de um leve aumento na carga de entrada/saída no final de um processo de criação. Esta opção desativa essa otimização.

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

Diz se o coletor de lixo (GC) deve manter as saídas de derivações vivas.

Quando definido como yes, o GC manterá as saídas de qualquer derivação ativa disponível no armazém—os arquivos .drv. O padrão é no, o que significa que as saídas de derivação são mantidas somente se forem acessíveis a partir de uma raiz do GC. Veja Invocando guix gc, para mais informações sobre raízes do GC.

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

Diz se o coletor de lixo (GC) deve manter as derivações correspondentes às saídas vivas.

Quando definido como yes, como é o caso por padrão, o GC mantém derivações—ou seja, arquivos .drv—desde que pelo menos uma de suas saídas esteja ativa. Isso permite que os usuários acompanhem as origens dos itens em seu armazém. Defini-lo como no economiza um pouco de espaço em disco.

Dessa forma, definir --gc-keep-derivations como yes faz com que a vivacidade flua das saídas para as derivações, e definir --gc-keep-outputs como yes faz com que a vivacidade flua das derivações para as saídas. Quando ambos são definidos como yes, o efeito é manter todos os pré-requisitos de compilação (as fontes, o compilador, as bibliotecas e outras ferramentas de tempo de compilação) de objetos ativos no armazém, independentemente de esses pré-requisitos serem acessíveis a partir de uma raiz GC. Isso é conveniente para desenvolvedores, pois economiza reconstruções ou downloads.

--impersonate-linux-2.6

Em sistemas baseados em Linux, personifique o Linux 2.6. Isso significa que a chamada de sistema uname do kernel relatará 2.6 como o número da versão.

Isso pode ser útil para criar programas que (geralmente de forma errada) dependem do número da versão do kernel.

--lose-logs

Não mantenha logs de build. Por padrão, eles são mantidos em localstatedir/guix/log.

--system=system

Assuma system como o tipo de sistema atual. Por padrão, é o par arquitetura/kernel encontrado no momento da configuração, como x86_64-linux.

--listen=endpoint

Ouça conexões em endpoint. endpoint é interpretado como o nome do arquivo de um soquete de domínio Unix se ele começar com / (sinal de barra). Caso contrário, endpoint é interpretado como um nome de host ou nome de host e porta para ouvir. Aqui estão alguns exemplos:

--listen=/gnu/var/daemon

Ouça conexões no soquete de domínio Unix /gnu/var/daemon, criando-o se necessário.

--listen=localhost ¶

Ouça as conexões TCP na interface de rede correspondente a localhost, na porta 44146.

--listen=128.0.0.42:1234

Ouça as conexões TCP na interface de rede correspondente ao 128.0.0.42, na porta 1234.

Esta opção pode ser repetida várias vezes, nesse caso guix-daemon aceita conexões em todos os endpoints especificados. Os usuários podem informar aos comandos do cliente a qual endpoint se conectar definindo a variável de ambiente GUIX_DAEMON_SOCKET (veja GUIX_DAEMON_SOCKET).

Nota: O protocolo daemon é unauthenticated and unencrypted. Usar --listen=host é adequado em redes locais, como clusters, onde apenas nós confiáveis podem se conectar ao daemon de compilação. Em outros casos em que o acesso remoto ao daemon é necessário, recomendamos usar soquetes de domínio Unix junto com SSH.

Quando --listen é omitido, guix-daemon escuta conexões no soquete de domínio Unix localizado em localstatedir/guix/daemon-socket/socket.

2.4 Configuração de aplicativo

Ao usar Guix sobre uma distribuição GNU/Linux que não seja um Guix System — uma chamada distro alheia — algumas etapas adicionais são necessárias para colocar tudo no seu lugar. Aqui estão algumas delas.

• Locales
• Name Service Switch
• Fontes X11
• Certificados X.509
• Pacotes Emacs

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

(use-modules (gnu packages base))

(define my-glibc-locales
  (make-glibc-utf8-locales
   glibc
   #:locales (list "en_CA" "fr_CA" "ik_CA" "iu_CA" "shs_CA")
   #:name "glibc-canadian-utf8-locales"))

guix install fontconfig
fc-cache -rv

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

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

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

2.5 Atualizando o Guix

Para atualizar o Guix, execute:

guix pull

Veja Invocando guix pull, para maiores informações.

Em uma distribuição estrangeira, você pode atualizar o daemon de compilação executando:

sudo -i guix pull

seguido por (supondo que sua distribuição use a ferramenta de gerenciamento de serviço systemd):

systemctl restart guix-daemon.service

No sistema Guix, a atualização do daemon é obtida reconfigurando o sistema (veja guix system reconfigure).

3.1 Limitações

Consideramos que o Guix System está pronto para uma ampla gama de casos de uso de "desktop” e servidores. As garantias de confiabilidade que ele fornece – atualizações e reversões transacionais, reprodutibilidade – tornam-no uma base sólida.

Cada vez mais serviços de sistema são fornecidos (veja Serviços).

No entanto, antes de prosseguir com a instalação, esteja ciente de que alguns serviços dos quais você depende ainda podem estar faltando na versão 9b1de85.

Mais do que um aviso de isenção de responsabilidade, este é um convite para relatar problemas (e histórias de sucesso!) e se juntar a nós para melhorá-los. Veja Contribuindo, para mais informações.

3.2 Considerações de Hardware

GNU Guix se concentra em respeitar a liberdade computacional do usuário. Ele é construído em torno do kernel Linux-libre, o que significa que apenas o hardware para o qual existem drivers e firmware de software livre é suportado. Hoje em dia, uma ampla gama de hardware disponível no mercado é suportada no GNU/Linux-libre – de teclados a placas gráficas, scanners e controladores Ethernet. Infelizmente, ainda existem áreas onde os fornecedores de hardware negam aos usuários o controle sobre sua própria computação, e tal hardware não é suportado no Guix System.

Uma das principais áreas onde faltam drivers ou firmware gratuitos são os dispositivos WiFi. Os dispositivos WiFi que funcionam incluem aqueles que usam chips Atheros (AR9271 e AR7010), que corresponde ao driver ath9k Linux-libre, e aqueles que usam chips Broadcom/AirForce (BCM43xx com Wireless-Core Revisão 5), que corresponde a o driver livre Linux b43-open. Existe firmware livre para ambos e está disponível imediatamente no Guix System, como parte do %base-firmware (veja firmware).

O instalador avisa você antecipadamente se detectar dispositivos que não funcionam devido à falta de firmware ou drivers gratuitos.

A Free Software Foundation administra Respects Your Freedom (RYF), um programa de certificação para produtos de hardware que respeitem sua liberdade e privacidade e garantam que você tenha controle sobre seu dispositivo. Recomendamos que você verifique a lista de dispositivos certificados RYF.

Outro recurso útil é o site H-Node. Ele contém um catálogo de dispositivos de hardware com informações sobre seu suporte no GNU/Linux.

3.3 Instalação em um pendrive e em DVD

Uma imagem de instalação ISO-9660 que pode ser gravada em um pendrive ou gravada em um DVD pode ser baixada em ‘https://ftp.gnu.org/gnu/guix/guix-system-install-9b1de85.x86_64-linux.iso’, onde você pode substituir x86_64-linux por um dos seguintes:

x86_64-linux

para um sistema GNU/Linux em CPUs de 64 bits compatíveis com Intel/AMD;

i686-linux

para um sistema GNU/Linux de 32 bits em CPUs compatíveis com Intel.

Certifique-se de baixar o arquivo .sig associado e verificar a autenticidade da imagem em relação a ele, seguindo estas linhas:

$ wget https://ftp.gnu.org/gnu/guix/guix-system-install-9b1de85.x86_64-linux.iso.sig
$ gpg --verify guix-system-install-9b1de85.x86_64-linux.iso.sig

Se esse comando falhar porque você não possui a chave pública requerida, execute este comando para importá-lo:

$ wget https://sv.gnu.org/people/viewgpg.php?user_id=15145 \
      -qO - | gpg --import -

e execute novamente o comando gpg --verify.

Observe que um aviso como "Esta chave não está certificada com uma assinatura confiável!” é normal.

Esta imagem contém as ferramentas necessárias para uma instalação. Ele deve ser copiado como está para um pendrive ou DVD grande o suficiente.

• Copiando para um pendrive
• Gravando em um DVD
• Inicializando

dd if=guix-system-install-9b1de85.x86_64-linux.iso of=/dev/sdX status=progress
sync

growisofs -dvd-compat -Z /dev/srX=guix-system-install-9b1de85.x86_64-linux.iso

3.4 Preparando para instalação

Depois de inicializar, você pode usar o instalador gráfico guiado, o que facilita o início (veja Instalação gráfica guiada). Alternativamente, se você já está familiarizado com GNU/Linux e deseja mais controle do que o instalador gráfico oferece, você pode escolher o processo de instalação "manual” (veja Instalação manual).

O instalador gráfico está disponível em TTY1. Você pode obter shells root em TTYs 3 a 6 pressionando ctrl-alt-f3, ctrl-alt-f4, etc. TTY2 mostra esta documentação e você pode acessá-la com ctrl-alt -f2. A documentação pode ser navegada usando os comandos do leitor de informações (veja Stand-alone GNU Info). O sistema de instalação executa o daemon do mouse GPM, que permite selecionar texto com o botão esquerdo do mouse e colá-lo com o botão do meio.

Nota: A instalação requer acesso à Internet para que quaisquer dependências ausentes na configuração do sistema possam ser baixadas. Consulte a seção "Rede" abaixo.

3.5 Instalação gráfica guiada

O instalador gráfico é uma interface de usuário baseada em texto. Ele guiará você, com caixas de diálogo, pelas etapas necessárias para instalar o GNU Guix System.

As primeiras caixas de diálogo permitem que você configure o sistema conforme você o utiliza durante a instalação: você pode escolher o idioma, o layout do teclado e configurar a rede que será usada durante a instalação. A imagem abaixo mostra a caixa de diálogo de rede.

As etapas posteriores permitem particionar seu disco rígido, conforme mostrado na imagem abaixo, escolher se deseja ou não usar sistemas de arquivos criptografados, inserir o nome do host e a senha root e criar uma conta adicional, entre outras coisas.

Observe que, a qualquer momento, o instalador permite sair da etapa de instalação atual e retomar uma etapa anterior, conforme imagem abaixo.

Quando terminar, o instalador produz uma configuração do sistema operacional e a exibe (veja Usando o sistema de configuração). Nesse ponto você pode clicar em "OK” e a instalação continuará. Se tiver sucesso, você pode reiniciar no novo sistema e aproveitar. Veja Após a instalação do sistema, para saber o que vem a seguir!

3.6 Instalação manual

Esta seção descreve como você instalaria "manualmente” o GNU Guix System em sua máquina. Esta opção requer familiaridade com GNU/Linux, com o shell e com ferramentas de administração comuns. Se você acha que isso não é para você, considere usar o instalador gráfico guiado (veja Instalação gráfica guiada).

O sistema de instalação fornece shells raiz nos TTYs 3 a 6; pressione ctrl-alt-f3, ctrl-alt-f4 e assim por diante para alcançá-los. Inclui muitas ferramentas comuns necessárias para instalar o sistema, mas também é um sistema Guix completo. Isso significa que você pode instalar pacotes adicionais, caso precise, usando guix package (veja Invocando guix package).

• Layout de teclado, rede e particionamento
• Prosseguindo com a instalação

loadkeys dvorak

ifconfig -a

ip address

dhclient -v interface

ping -c 3 gnu.org

herd set-http-proxy guix-daemon URL

herd start ssh-daemon

cfdisk

parted /dev/sda set 1 esp on

mkfs.fat -F32 /dev/sda1

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

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

mount LABEL=my-root /mnt

mkswap /dev/sda3
swapon /dev/sda3

# Este é 10 GiB de espaço de swap. Ajuste "count" para alterar o tamanho.
dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
# Por segurança, torne o arquivo legível e gravável somente pelo root.
chmod 600 /mnt/swapfile
mkswap /mnt/swapfile
swapon /mnt/swapfile

herd start cow-store /mnt

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

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

3.7 Após a instalação do sistema

Sucesso, agora você inicializou no Guix System! Você pode atualizar o sistema sempre que quiser executando:

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

Isso cria uma nova geração sistema com os pacotes e serviços mais recentes.

Agora, veja Começando, junte-se a nós no #guix na rede IRC Libera.Chat ou no guix-devel@gnu.org para compartilhar sua experiência!

3.8 Instalando Guix em uma Máquina Virtual

Se você deseja instalar o Guix System em uma máquina virtual (VM) ou em um servidor virtual privado (VPS) em vez de na sua máquina favorita, esta seção é para você.

Para inicializar uma VM QEMU para instalar o Guix System em uma imagem de disco, siga estas etapas:

1. Primeiro, recupere e descompacte a imagem de instalação do sistema Guix conforme descrito anteriormente (veja Instalação em um pendrive e em DVD).
2. Crie uma imagem de disco que irá conter o sistema instalado. Para criar uma imagem de disco formatada em qcow2, use o comando qemu-img:

   qemu-img create -f qcow2 guix-system.img 50G
   

   O arquivo resultante será muito menor que 50 GB (normalmente menos de 1 MB), mas aumentará à medida que o dispositivo de armazenamento virtualizado for preenchido.

3. Boot the USB installation image in a VM:

   qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
     -nic user,model=virtio-net-pci -boot menu=on,order=d \
     -drive file=guix-system.img \
     -drive media=cdrom,readonly=on,file=guix-system-install-9b1de85.sistema.iso
   

   -enable-kvm é opcional, mas melhora significativamente o desempenho, veja Usando o Guix em uma Máquina Virtual.

4. Agora você está como root na VM, prossiga com o processo de instalação. Veja Preparando para instalação e siga as instruções.

Quando a instalação estiver concluída, você pode inicializar o sistema que está na sua imagem guix-system.img. Veja Usando o Guix em uma Máquina Virtual, para saber como fazer isso.

3.9 Compilando a imagem de instalação

A imagem de instalação descrita acima foi criada usando o comando guix system, especificamente:

guix system image -t iso9660 gnu/system/install.scm

Dê uma olhada em gnu/system/install.scm na árvore de origem e veja também Invoking guix system para mais informações sobre a imagem de instalação.

3.10 Construindo a imagem de instalação para placas ARM

Muitas placas ARM exigem uma variante específica do bootloader U-Boot.

Se você criar uma imagem de disco e o bootloader não estiver disponível de outra forma (em outra unidade de inicialização, etc.), é aconselhável criar uma imagem que inclua o bootloader, especificamente:

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

A20-OLinuXino-Lime2 é o nome do quadro. Se você especificar um quadro inválido, uma lista de quadros possíveis será mostrada.

5.1 Recursos

Aqui presumimos que você já deu os primeiros passos com o Guix (veja Começando) e gostaria de ter uma visão geral do que está acontecendo nos bastidores.

Ao usar o Guix, cada pacote acaba no armazém de pacotes, em seu próprio diretório — algo que lembra /gnu/store/xxx-package-1.2, onde xxx é uma string base32.

Em vez de se referir a esses diretórios, os usuários têm seu próprio perfil, que aponta para os pacotes que eles realmente querem usar. Esses perfis são armazenados dentro do diretório home de cada usuário, em $HOME/.guix-profile.

Por exemplo, alice instala o GCC 4.7.2. Como resultado, /home/alice/.guix-profile/bin/gcc aponta para /gnu/store/…-gcc-4.7.2/bin/gcc. Agora, na mesma máquina, bob já tinha instalado o GCC 4.8.0. O perfil de bob simplesmente continua a apontar para /gnu/store/…-gcc-4.8.0/bin/gcc—ou seja, ambas as versões do GCC coexistem no mesmo sistema sem nenhuma interferência.

O comando guix package é a ferramenta central para gerenciar pacotes (veja Invocando guix package). Ele opera nos perfis por usuário e pode ser usado com privilégios normais de usuário.

O comando fornece as operações óbvias de instalação, remoção e atualização. Cada invocação é, na verdade, uma transação: ou a operação especificada é bem-sucedida ou nada acontece. Portanto, se o processo guix package for encerrado durante a transação, ou se ocorrer uma queda de energia durante a transação, o perfil do usuário permanecerá em seu estado anterior e continuará utilizável.

Além disso, qualquer transação de pacote pode ser revertida. Então, se, por exemplo, uma atualização instalar uma nova versão de um pacote que acabe tendo um bug sério, os usuários podem reverter para a instância anterior de seu perfil, que era conhecida por funcionar bem. Da mesma forma, a configuração global do sistema no Guix está sujeita a atualizações transacionais e roll-back (veja Começando).

Todos os pacotes no repositório de pacotes podem ser garbage-collected. O Guix pode determinar quais pacotes ainda são referenciados por perfis de usuário e remover aqueles que comprovadamente não são mais referenciados (veja Invocando guix gc). Os usuários também podem remover explicitamente gerações antigas de seus perfis para que os pacotes aos quais eles se referem possam ser coletados.

Guix adota uma abordagem puramente funcional para gerenciamento de pacotes, conforme descrito na introdução (veja Introdução). Cada nome de diretório de pacote /gnu/store contém um hash de todas as entradas que foram usadas para construir aquele pacote—compilador, bibliotecas, scripts de construção, etc. Essa correspondência direta permite que os usuários tenham certeza de que uma determinada instalação de pacote corresponde ao estado atual de sua distribuição. Também ajuda a maximizar a reprodutibilidade da construção: graças aos ambientes de construção isolados que são usados, uma determinada construção provavelmente produzirá arquivos de bits idênticos quando executada em máquinas diferentes (veja container).

Essa base permite que o Guix suporte transparent binary/source deployment. Quando um binário pré-construído para um item /gnu/store está disponível em uma fonte externa—um substituto, o Guix apenas o baixa e descompacta; caso contrário, ele constrói o pacote a partir da fonte, localmente (veja Substitutos). Como os resultados da construção são geralmente reproduzíveis bit a bit, os usuários não precisam confiar em servidores que fornecem substitutos: eles podem forçar uma construção local e desafiar os provedores (veja Invocando guix challenge).

O controle sobre o ambiente de construção é um recurso que também é útil para desenvolvedores. O comando guix shell permite que os desenvolvedores de um pacote configurem rapidamente o ambiente de desenvolvimento correto para seu pacote, sem ter que instalar manualmente as dependências do pacote em seu perfil (veja Invoking guix shell).

Todo o Guix e suas definições de pacote são controlados por versão, e guix pull permite que você "viaje no tempo” no histórico do próprio Guix (veja Invocando guix pull). Isso torna possível replicar uma instância do Guix em uma máquina diferente ou em um ponto posterior no tempo, o que por sua vez permite que você replique ambientes de software completos, enquanto retém o rastreamento de procedência preciso do software.

5.2 Invocando guix package

O comando guix package é a ferramenta que permite aos usuários instalar, atualizar e remover pacotes, bem como reverter para configurações anteriores. Essas operações funcionam no perfil de um usuário—um diretório de pacotes instalados. Cada usuário tem um perfil padrão em $HOME/.guix-profile. O comando opera apenas no próprio perfil do usuário e funciona com privilégios de usuário normais (veja Recursos). Sua sintaxe é:

guix package opções

Principalmente, opções especifica as operações a serem executadas durante a transação. Após a conclusão, um novo perfil é criado, mas as gerações anteriores do perfil permanecem disponíveis, caso o usuário queira reverter.

Por exemplo, para remover lua e instalar guile e guile-cairo em uma única transação:

guix package -r lua -i guile guile-cairo

Para sua conveniência, também fornecemos os seguintes aliases:

• guix search é um alias para guix package -s,
• guix install é um alias para guix package -i,
• guix remove é um alias para guix package -r,
• guix upgrade é um alias para guix package -u,
• e guix show é um alias para guix package --show=.

Esses aliases são menos expressivos que guix package e oferecem menos opções, então em alguns casos você provavelmente desejará usar guix package diretamente.

guix package também suporta uma abordagem declarativa em que o usuário especifica o conjunto exato de pacotes que estarão disponíveis e passa a ele via a opção --manifest (veja --manifest).

Para cada usuário, um link simbólico para o perfil padrão do usuário é criado automaticamente em $HOME/.guix-profile. Este link simbólico sempre aponta para a geração atual do perfil padrão do usuário. Assim, os usuários podem adicionar $HOME/.guix-profile/bin à sua variável de ambiente PATH e assim por diante. Se você não estiver usando o sistema Guix, considere adicionar as seguintes linhas ao seu ~/.bash_profile (veja Bash Startup Files em The GNU Bash Reference Manual) para que os shells recém-gerados obtenham todos as definições corretas de variáveis de ambiente:

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

Em uma configuração multiusuário, os perfis de usuário são armazenados em um local registrado como garbage-collector root, para o qual $HOME/.guix-profile aponta (veja Invocando guix gc). Esse diretório geralmente é localstatedir/guix/profiles/per-user/usuário, onde localstatedir é o valor passado para configure como -- localstatedir e usuário é o nome do usuário. O diretório per-user é criado quando guix-daemon é iniciado, e o subdiretório usuário é criado por guix-package.

As seguintes opções podem ser usadas:

--install=pacote …

-i pacote …

Instale os pacotes especificados.

Cada pacote pode especificar um nome de pacote simples como guile, opcionalmente seguido por uma arroba e número de versão, como guile@3.0.7 ou simplesmente guile@3.0. Neste último caso, a versão mais recente prefixada por 3.0 é selecionada.

Se nenhum número de versão for especificado, a versão mais recente disponível será selecionada. Além disso, tal especificação pacote pode conter dois pontos, seguido pelo nome de uma das saídas do pacote, como em gcc:doc ou binutils@2.22:lib (veja Pacotes com múltiplas saídas).

Pacotes com um nome correspondente (e opcionalmente versão) são procurados entre os módulos de distribuição GNU (veja Módulos de pacote).

Alternativamente, um pacote pode especificar diretamente um nome de arquivo de armazém como /gnu/store/...-guile-3.0.7, conforme produzido por, por exemplo, guix build.

Às vezes, os pacotes têm propagated-inputs: são dependências que são instaladas automaticamente junto com o pacote necessário (veja propagated-inputs em package objetos, para obter informações sobre entradas propagadas em definições de pacote).

Um exemplo é a biblioteca GNU MPC: seus arquivos de cabeçalho C referem-se aos da biblioteca GNU MPFR, que por sua vez se refere aos da biblioteca GMP. Assim, ao instalar o MPC, as bibliotecas MPFR e GMP também são instaladas no perfil; a remoção do MPC também remove o MPFR e o GMP — a menos que eles também tenham sido explicitamente instalados pelo usuário.

Além disso, os pacotes às vezes dependem da definição de variáveis de ambiente para seus caminhos de pesquisa (veja a explicação de --search-paths abaixo). Quaisquer definições de variáveis ambientais ausentes ou possivelmente incorretas são relatadas aqui.

--install-from-expression=exp

-e exp

Instale o pacote avaliado por exp.

exp deve ser uma expressão de Scheme avaliada como um objeto <package>. Esta opção é particularmente útil para desambiguar variantes de um pacote com o mesmo nome, com expressões como (@(gnu packages commencement) guile-final).

Observe que esta opção instala a primeira saída do pacote especificado, o que pode ser insuficiente quando for necessária uma saída específica de um pacote de múltiplas saídas.

--install-from-file=arquivo

-f arquivo

Instale o pacote avaliado pelo código em arquivo.

Por exemplo, arquivo pode conter uma definição como esta (veja Definindo pacotes):

(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+))

Os desenvolvedores podem achar útil incluir um arquivo guix.scm na raiz da árvore de origem do projeto que pode ser usado para testar instantâneos de desenvolvimento e criar ambientes de desenvolvimento reproduzíveis (veja Invoking guix shell).

O arquivo também pode conter uma representação JSON de uma ou mais definições de pacote. Executar guix package -f em hello.json com o seguinte conteúdo resultaria na instalação do pacote greeter após construir myhello:

[
  {
    "name": "myhello",
    "version": "2.10",
    "source": "mirror://gnu/hello/hello-2.10.tar.gz",
    "build-system": "gnu",
    "arguments": {
      "tests?": false
    },
    "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": ["gettext"]
  },
  {
    "name": "greeter",
    "version": "1.0",
    "source": "mirror://gnu/hello/hello-2.10.tar.gz",
    "build-system": "gnu",
    "arguments": {
      "test-target": "foo",
      "parallel-build?": false
    },
    "home-page": "https://example.com/",
    "synopsis": "Greeter using GNU Hello",
    "description": "This is a wrapper around GNU Hello.",
    "license": "GPL-3.0+",
    "inputs": ["myhello", "hello"]
  }
]

--remove=pacote …

-r pacote …

Remova os pacotes especificados.

Quanto a --install, cada pacote pode especificar um número de versão e/ou nome de saída além do nome do pacote. Por exemplo, ‘-r glibc:debug’ removeria a saída de glibc.

--upgrade[=regexp …] ¶

-u [regexp …]

Atualize todos os pacotes instalados. Se um ou mais regexps forem especificados, atualize apenas os pacotes instalados cujo nome corresponda a um regexp. Veja também a opção --do-not-upgrade abaixo.

Note que isso atualiza o pacote para a versão mais recente dos pacotes encontrados na distribuição atualmente instalada. Para atualizar sua distribuição, você deve executar regularmente guix pull (veja Invocando guix pull).

Ao atualizar, as transformações de pacote que foram aplicadas originalmente ao criar o perfil são automaticamente reaplicadas (veja Opções de transformação de pacote). Por exemplo, suponha que você instalou o Emacs pela ponta do seu branch de desenvolvimento com:

guix install emacs-next --with-branch=emacs-next=master

Na próxima vez que você executar guix upgrade, o Guix puxará novamente a ponta do branch de desenvolvimento do Emacs e compilará emacs-next a partir desse checkout.

Observe que opções de transformação como --with-branch e --with-source dependem do estado externo; cabe a você garantir que elas funcionem conforme o esperado. Você também pode descartar transformações que se aplicam a um pacote executando:

guix install pacote

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

Quando usado junto com a opção --upgrade, não atualize nenhum pacote cujo nome corresponda a um regexp. Por exemplo, para atualizar todos os pacotes no perfil atual, exceto aqueles que contêm a substring "emacs”:

$ guix package --upgrade . --do-not-upgrade emacs

--manifest=arquivo ¶

-m arquivo

Crie uma nova geração do perfil a partir do objeto manifest retornado pelo código Scheme em arquivo. Esta opção pode ser repetida várias vezes, em cujo caso os manifestos são concatenados.

Isso permite que você declarando o conteúdo do perfil em vez de construí-lo por meio de uma sequência de --install e comandos similares. A vantagem é que arquivo pode ser colocado sob controle de versão, copiado para máquinas diferentes para reproduzir o mesmo perfil, e assim por diante.

arquivo deve retornar um objeto manifest, que é aproximadamente uma lista de pacotes:

(use-package-modules guile emacs)

(packages->manifest
 (list emacs
       guile-2.0
       ;; Usa uma saída de pacote específica.
       (list guile-2.0 "debug")))

Veja Escrevendo manifestos, para obter informações sobre como escrever um manifesto. Veja --export-manifest, para aprender como obter um arquivo de manifesto de um perfil existente.

--roll-back ¶

Reverta para a geração anterior do perfil, ou seja, desfaça a última transação.

Quando combinado com opções como --install, a reversão ocorre antes de qualquer outra ação.

Ao reverter da primeira geração que realmente contém pacotes instalados, o perfil é feito para apontar para a geração zero, que não contém arquivos além de seus próprios metadados.

Após ter revertido, instalar, remover ou atualizar pacotes sobrescreve gerações futuras anteriores. Assim, o histórico das gerações em um perfil é sempre linear.

--switch-generation=padrão ¶

-S padrão

Mude para uma geração específica definida por padrão.

padrão pode ser um número de geração ou um número prefixado com "+” ou "-”. O último significa: mover para frente/para trás por um número especificado de gerações. Por exemplo, se você quiser retornar para a última geração após --roll-back, use --switch-generation=+1.

A diferença entre --roll-back e --switch-generation=-1 é que --switch-generation não fará uma geração zero, então se uma geração especificada não existir, a geração atual não será alterada.

--search-paths[=tipo] ¶

Relata definições de variáveis de ambiente, na sintaxe Bash, que podem ser necessárias para usar o conjunto de pacotes instalados. Essas variáveis de ambiente são usadas para especificar caminhos de busca para arquivos usados por alguns dos pacotes instalados.

Por exemplo, o GCC precisa que as variáveis de ambiente CPATH e LIBRARY_PATH sejam definidas para que ele possa procurar cabeçalhos e bibliotecas no perfil do usuário (veja Environment Variables em Usando o GNU Compiler Collection (GCC)). Se o GCC e, digamos, a biblioteca C estiverem instalados no perfil, então --search-paths sugerirá definir essas variáveis como perfil/include e perfil/lib, respectivamente (veja Caminhos de pesquisa, para obter informações sobre especificações de caminho de pesquisa associadas a pacotes.)

O caso de uso típico é definir essas variáveis de ambiente no shell:

$ eval $(guix package --search-paths)

tipo pode ser um dos seguintes: exact, prefix ou suffix, o que significa que as definições de variáveis de ambiente retornadas serão configurações exatas ou prefixos ou sufixos do valor atual dessas variáveis. Quando omitido, tipo assume como padrão exact.

Esta opção também pode ser usada para calcular os caminhos de busca combinados de vários perfis. Considere este exemplo:

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

O último comando acima relata sobre a variável GUILE_LOAD_PATH, embora, considerados individualmente, nem foo nem bar levariam a essa recomendação.

--profile=perfil

-p perfil

Use perfil em vez do perfil padrão do usuário.

perfil deve ser o nome de um arquivo que será criado após a conclusão. Concretamente, perfil será um mero link simbólico ("symlink”) apontando para o perfil real onde os pacotes estão instalados:

$ guix install hello -p ~/code/my-profile
…
$ ~/code/my-profile/bin/hello
Olá, mundo!

Tudo o que é preciso para se livrar do perfil é remover este link simbólico e seus irmãos que apontam para gerações específicas:

$ rm ~/code/my-profile ~/code/my-profile-*-link

--list-profiles

Liste todos os perfis dos usuários:

$ guix package --list-profiles
/home/charlie/.guix-profile
/home/charlie/code/my-profile
/home/charlie/code/devel-profile
/home/charlie/tmp/test

Ao executar como root, liste todos os perfis de todos os usuários.

--allow-collisions

Permitir pacotes de colisão no novo perfil. Use por sua conta e risco!

Por padrão, guix package relata como um erro collisions no perfil. Colisões acontecem quando duas ou mais versões ou variantes diferentes de um determinado pacote acabam no perfil.

--bootstrap

Use o bootstrap Guile para construir o perfil. Esta opção é útil somente para desenvolvedores de distribuição.

Além dessas ações, guix package suporta as seguintes opções para consultar o estado atual de um perfil ou a disponibilidade de pacotes:

--search=regexp

-s regexp

Liste os pacotes disponíveis cujo nome, sinopse ou descrição correspondem a regexp (sem distinção entre maiúsculas e minúsculas), classificados por relevância. Imprima todos os metadados dos pacotes correspondentes no formato recutils (veja bancos de dados GNU recutils em manual GNU recutils).

Isso permite que campos específicos sejam extraídos usando o comando recsel, por exemplo:

$ 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

Da mesma forma, para mostrar o nome de todos os pacotes disponíveis sob os termos da GNU LGPL versão 3:

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

name: gmp
…

Também é possível refinar os resultados da pesquisa usando vários sinalizadores -s para guix package, ou vários argumentos para guix search. Por exemplo, o comando a seguir retorna uma lista de jogos de tabuleiro (desta vez usando o alias guix search):

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

Se omitissemos -s game, também teríamos pacotes de software que lidam com placas de circuito impresso; remover os colchetes angulares em torno de board adicionaria ainda mais pacotes relacionados a teclados.

E agora um exemplo mais elaborado. O comando a seguir procura bibliotecas criptográficas, filtra as bibliotecas Haskell, Perl, Python e Ruby e imprime o nome e a sinopse dos pacotes correspondentes:

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

Veja Selection Expressions em manual GNU recutils, para obter mais informações sobre expressões de seleção para recsel -e.

--show=pacote

Exibe detalhes sobre pacote, retirados da lista de pacotes disponíveis, no formato recutils (veja GNU Recutils Databases em GNU Recutils Manual).

$ guix package --show=guile | recsel -p name,version
name: guile
version: 3.0.5

name: guile
version: 3.0.2

name: guile
version: 2.2.7
…

Você também pode especificar o nome completo de um pacote para obter detalhes apenas sobre uma versão específica dele (desta vez usando o alias guix show):

$ guix show guile@3.0.5 | recsel -p name,version
name: guile
version: 3.0.5

--list-installed[=regexp]

-I [regexp]

Lista os pacotes instalados mais recentemente no perfil especificado, com os pacotes instalados mais recentemente mostrados por último. Quando regexp for especificado, liste apenas os pacotes instalados cujo nome corresponda a regexp.

Para cada pacote instalado, imprima os seguintes itens, separados por tabulações: o nome do pacote, sua string de versão e a parte do pacote que está instalada (por exemplo, out para a saída predefinida, include para os seus cabeçalhos, etc.) e o caminho deste pacote no armazém.

--list-available[=regexp]

-A [regexp]

Lista de pacotes atualmente disponíveis na distribuição para este sistema (veja Distribuição GNU). Quando regexp for especificado, liste apenas os pacotes disponíveis cujo nome corresponda a regexp.

Para cada pacote, imprima os seguintes itens separados por tabulações: seu nome, sua string de versão, as partes do pacote (veja Pacotes com múltiplas saídas) e o local de origem de sua definição.

--list-generations[=padrão] ¶

-l [padrão]

Retorne uma lista de gerações junto com suas datas de criação; para cada geração, exiba os pacotes instalados, com os pacotes instalados mais recentemente mostrados por último. Observe que a geração zero nunca é mostrada.

Para cada pacote instalado, mostre os seguintes itens, separados por tabulações: o nome de um pacote, sua string de versão, a parte do pacote que está instalada (veja Pacotes com múltiplas saídas) e a localização deste pacote em o armazém.

Quando padrão é usado, o comando retorna apenas gerações correspondentes. Os padrões válidos incluem:

• Inteiros e números inteiros separados por vírgula. Ambos os padrões denotam números de geração. Por exemplo, --list-generations=1 retorna o primeiro.

  E --list-generations=1,8,2 gera três gerações na ordem especificada. Não são permitidos espaços nem vírgulas finais.

• Intervalos. --list-generations=2..9 mostra o gerações especificadas e tudo mais. Observe que o início de um intervalo deve ser menor que o seu final.

  Também é possível omitir o ponto final. Por exemplo, --list-generations=2.. retorna todas as gerações começando pela segunda.

• Duração. Você também pode visitar os últimos N dias, semanas, ou meses passando um número inteiro junto com a primeira letra da duração. Por exemplo, --list-generations=20d lista gerações com até 20 dias.

--delete-generations[=padrão]

-d [padrão]

Quando padrão for omitido, exclua todas as gerações, exceto a atual.

Este comando aceita os mesmos padrões de --list-Generations. Quando pattern for especificado, exclua as gerações correspondentes. Quando padrão especifica uma duração, as gerações mais antigas que a duração especificada correspondem. Por exemplo, --delete-generations=1m exclui gerações com mais de um mês.

Se a geração atual corresponder, ela será não excluída. Além disso, a geração zero nunca é excluída.

Observe que a exclusão de gerações impede a reversão para elas. Conseqüentemente, este comando deve ser usado com cuidado.

--export-manifest

Escreva na saída padrão um manifesto adequado para --manifest correspondente ao(s) perfil(s) selecionado(s).

Esta opção destina-se a ajudá-lo a migrar do modo operacional "imperativo” — executando guix install, guix upgrade, etc.—para o modo declarativo que --manifest ofertas.

Observe que o manifesto resultante aproxima o que seu perfil realmente contém; por exemplo, dependendo de como seu perfil foi criado, ele pode se referir a pacotes ou versões de pacotes que não são exatamente o que você especificou.

Tenha em mente que um manifesto é puramente simbólico: ele contém apenas nomes de pacotes e possivelmente versões, e seu significado varia com o tempo. Se você quiser “fixar” canais nas revisões que foram usadas para construir o(s) perfil(es), veja --export-channels abaixo.

--export-channels

Escreva na saída padrão a lista de canais usados pelo(s) perfil(s) selecionado(s), em um formato adequado para guix pull --channels ou guix time-machine --channels (veja Canais) . .

Juntamente com --export-manifest, esta opção fornece informações que permitem replicar o perfil atual (veja Replicando Guix).

No entanto, observe que a saída deste comando aproxima o que foi realmente usado para construir este perfil. Em particular, um único perfil pode ter sido construído a partir de diversas revisões diferentes do mesmo canal. Nesse caso, --export-manifest escolhe a última e escreve a lista de outras revisões em um comentário. Se você realmente precisa escolher pacotes de análises de canais diferentes, você pode usar inferiores em seu manifesto para fazer isso (veja Inferiores).

Juntamente com --export-manifest, este é um bom ponto de partida se você estiver disposto a migrar do modelo "imperativo" para o modelo totalmente declarativo que consiste em um arquivo de manifesto junto com um arquivo de canais fixando o canal exato revisão(ões) que você deseja.

Finalmente, como guix package pode realmente iniciar processos de construção, ele suporta todas as opções de construção comuns (veja Opções de compilação comum). Ele também oferece suporte a opções de transformação de pacotes, como --with-source, e as preserva em atualizações (veja Opções de transformação de pacote).

5.3 Substitutos

Guix suporta implantação transparente de origem/binário, o que significa que ele pode construir coisas localmente ou baixar itens pré-construídos de um servidor, ou ambos. Chamamos esses itens pré-construídos de substitutos—eles são substitutos para resultados de construção local. Em muitos casos, baixar um substituto é muito mais rápido do que construir coisas localmente.

Substitutos podem ser qualquer coisa resultante de uma construção de derivação (veja Derivações). Claro, no caso comum, eles são binários de pacotes pré-construídos, mas tarballs de origem, por exemplo, que também resultam de construções de derivação, podem estar disponíveis como substitutos.

• Official Substitute Servers
• Autorização de servidor substituto
• Obtendo substitutos de outros servidores
• Autenticação de substituto
• Configurações de proxy
• Falha na substituição
• Confiança em binários

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

$ guix build emacs --dry-run
A seguinte derivações seriam compiladas:
   /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 seriam baixados:
   /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
…

(operating-system
 ;; …
 (services
  ;; Suponha que estamos começando com '%desktop-services'. Substitua-o
  ;; pela lista de serviços que você está realmente usando.
  (modify-services %desktop-services
    (guix-service-type config =>
                       (guix-configuration
                        (inherit config)
                        (substitute-urls
                         (append (list "https://guix.example.org")
                                 %default-substitute-urls))
                        (authorized-keys
                         (append (list (local-file "./key.pub"))
                                 %default-authorized-guix-keys)))))))

$ sudo guix system reconfigure /etc/config.scm
$ sudo herd restart guix-daemon

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

5.4 Pacotes com múltiplas saídas

Frequentemente, os pacotes definidos no Guix têm uma única saída — ou seja, o pacote fonte leva a exatamente um diretório no armazém. Ao executar guix install glibc, instala-se a saída padrão do pacote GNU libc; A saída padrão é chamada out, mas seu nome pode ser omitido conforme mostrado neste comando. Neste caso específico, a saída padrão de glibc contém todos os arquivos de cabeçalho C, bibliotecas compartilhadas, bibliotecas estáticas, documentação de informações e outros arquivos de suporte.

Às vezes é mais apropriado separar os vários tipos de arquivos produzidos a partir de um único pacote fonte em saídas separadas. Por exemplo, a biblioteca GLib C (usada pelo GTK+ e pacotes relacionados) instala mais de 20 MiB de documentação de referência como páginas HTML. Para economizar espaço para usuários que não precisam, a documentação vai para uma saída separada, chamada doc. Para instalar a saída principal do GLib, que contém tudo menos a documentação, seria executado:

guix install glib

O comando para instalar sua documentação é:

guix install glib:doc

Embora a sintaxe de dois pontos funcione para especificação de linha de comando de saídas de pacotes, ela não funcionará ao usar uma variável de pacote no código do Scheme. Por exemplo, para adicionar a documentação do glib aos pacotes instalados globalmente de um operating-system (veja operating-system Reference), uma lista de dois itens, sendo o primeiro a variável de pacote e o segundo o nome da saída a ser selecionada (uma string), devem ser usados:

(use-modules (gnu packages glib))
;; glib-with-documentation é o símbolo de Guile para o pacote glib
(operating-system
 ...
 (packages
  (append
   (list (list glib-with-documentation "doc"))
         %base-packages)))

Alguns pacotes instalam programas com diferentes "pegadas de dependência”. Por exemplo, o pacote WordNet instala ferramentas de linha de comando e interfaces gráficas de usuário (GUIs). Os primeiros dependem exclusivamente da biblioteca C, enquanto os últimos dependem apenas do Tcl/Tk e das bibliotecas X subjacentes. Nesse caso, deixamos as ferramentas de linha de comando na saída padrão, enquanto as GUIs ficam em uma saída separada. Isso permite que usuários que não precisam de GUIs economizem espaço. O comando guix size pode ajudar a descobrir tais situações (veja Invocando guix size). guix graph também pode ser útil (veja Invocando guix graph).

Existem vários desses pacotes de múltiplas saídas na distribuição GNU. Outros nomes de saída convencionais incluem lib para bibliotecas e possivelmente arquivos de cabeçalho, bin para programas independentes e debug para informações de depuração (veja Instalando arquivos de depuração). A saída de um pacote está listada na terceira coluna da saída de guix package --list-available (veja Invocando guix package).

5.5 Invocando guix locate

Há tantos softwares gratuitos por aí que, mais cedo ou mais tarde, você precisará procurar por pacotes. O comando guix search que vimos antes (veja Invocando guix package) permite pesquisar por palavras-chave:

guix search video editor

Às vezes, você deseja descobrir qual pacote fornece um determinado arquivo, e é aí que entra guix locate. Veja como você pode encontrar o comando ls:

$ guix locate ls
coreutils@9.1       /gnu/store/…-coreutils-9.1/bin/ls

É claro que o comando funciona para qualquer arquivo, não apenas para comandos:

$ guix locate unistr.h
icu4c@71.1          /gnu/store/…/include/unicode/unistr.h
libunistring@1.0    /gnu/store/…/include/unistr.h

Você também pode especificar padrões de globo com curingas. Por exemplo, aqui está como você procuraria pacotes que fornecem arquivos .service:

$ guix locate -g '*.service'
man-db@2.11.1        …/lib/systemd/system/man-db.service
wpa-supplicant@2.10  …/system-services/fi.w1.wpa_supplicant1.service

O comando guix locate depende de um banco de dados que mapeia nomes de arquivos para nomes de pacotes. Por padrão, ele cria automaticamente esse banco de dados, caso ele ainda não exista, percorrendo os pacotes disponíveis localmente, o que pode levar alguns minutos (dependendo do tamanho do seu armazém e da velocidade do seu dispositivo de armazenamento).

Nota: Por enquanto, guix locate constrói seu banco de dados baseado em conhecimento puramente local – o que significa que você não encontrará pacotes que nunca chegaram ao sue armazém. Eventualmente, ele suportará o download de um banco de dados pré-construído para que você possa encontrar mais pacotes.

Por padrão, guix locate primeiro tenta procurar um banco de dados de todo o sistema, geralmente em /var/cache/guix/locate; Se não existir ou for muito antigo, ele retornará ao banco de dados por usuário, por padrão em ~/.cache/guix/locate. Em um sistema multiusuário, os administradores podem querer atualizar periodicamente o banco de dados de todo o sistema para que todos os usuários possam se beneficiar dele, por exemplo, configurando package-database-service-type (veja package-database-service-type).

A sintaxe geral é:

guix locate [opções…] arquivo…

... onde arquivo é o nome de um arquivo a ser pesquisado (especificamente, o "nome base" do arquivo: arquivos cujos diretórios pais são chamados arquivo não são correspondidos).

As opções disponíveis são as seguintes:

--glob

-g

Interprete arquivo… como padrões de globo—padrões que podem incluir caracteres curinga, como ‘*.scm’ para denotar todos os arquivos que terminam em ‘.scm’.

--stats

Exibir estatísticas do banco de dados.

--update

-u

Atualize o banco de dados dos arquivos.

Por padrão, o banco de dados é atualizado automaticamente quando é muito antigo.

--clear

Limpe o banco de dados e preencha-o novamente.

Esta opção permite começar de novo, garantindo que os dados antigos sejam removidos do banco de dados, o que também evita ter um banco de dados em constante crescimento. Por padrão, guix locate faz isso automaticamente periodicamente, embora com pouca frequência.

--database=arquivo

Use arquivo como banco de dados, criando-o se necessário.

Por padrão, guix locate escolhe o banco de dados em ~/.cache/guix ou /var/cache/guix, o que for mais recente.

--method=método

-m método

Use método para selecionar o conjunto de pacotes a serem indexados. Os valores possíveis são:

manifests

Este é o método padrão: ele funciona percorrendo perfis na máquina e gravando os pacotes que encontra – pacotes instalados por você ou por outros usuários da máquina, direta ou indiretamente. É rápido mas você pode perder outros pacotes disponíveis no armazém mas não referenciados por nenhum perfil.

store

Este é um método mais lento, porém mais exaustivo: verifica entre todos os pacotes existentes aqueles que estão disponíveis no armazém e os registra.

5.6 Invocando guix gc

Pacotes instalados mas não usados podem ser garbage-collected. O comando guix gc permite que os usuários executem explicitamente o coletor de lixo para recuperar espaço do diretório /gnu/store. É a maneira única de remover arquivos de /gnu/store — remover arquivos ou diretórios manualmente pode quebrá-los sem possibilidade de reparo!

O coletor de lixo possui um conjunto de roots conhecidos: qualquer arquivo em /gnu/store acessível a partir de uma raiz é considerado live e não pode ser excluído; Qualquer outro arquivo é considerado dead e pode ser excluído. O conjunto de raízes do coletor de lixo (abreviadamente “Raízes GC”) inclui perfis de usuário padrão; por padrão, os links simbólicos em /var/guix/gcroots representam essas raízes do GC. Novas raízes de GC podem ser adicionadas com guix build --root, por exemplo (veja Invocando guix build). O comando guix gc --list-roots os lista.

Antes de executar guix gc --collect-garbage para liberar espaço, geralmente é útil remover gerações antigas dos perfis de usuário; dessa forma, compilações de pacotes antigos referenciadas por essas gerações podem ser recuperadas. Isso é conseguido executando guix package --delete-generations (veja Invocando guix package).

Nossa recomendação é executar uma coleta de lixo periodicamente ou quando houver pouco espaço em disco. Por exemplo, para garantir que pelo menos 5 GB estejam disponíveis no disco, basta executar:

guix gc -F 5G

É perfeitamente seguro executar como um trabalho periódico não interativo (veja Execução de trabalho agendado, para saber como configurar tal trabalho). Executar guix gc sem argumentos coletará o máximo de lixo possível, mas isso geralmente é inconveniente: você pode ter que reconstruir ou baixar novamente um software que está "morto" do ponto de vista do GC, mas que é necessário para construir outras peças de software - por exemplo, a cadeia de ferramentas do compilador.

O comando guix gc tem três modos de operação: pode ser usado para coletar o lixo de quaisquer arquivos mortos (o padrão), para excluir arquivos específicos (a opção --delete), para imprimir lixo- informações do coletor ou para consultas mais avançadas. As opções de coleta de lixo são as seguintes:

--collect-garbage[=min]

-C [min]

Colete lixo, ou seja, arquivos e subdiretórios /gnu/store inacessíveis. Esta é a operação padrão quando nenhuma opção é especificada.

Quando min for fornecido, pare quando min bytes forem coletados. min pode ser um número de bytes ou pode incluir uma unidade como sufixo, como MiB para mebibytes e GB para gigabytes (veja especificações de tamanho em GNU Coreutils).

Quando min for omitido, colete todo o lixo.

--free-space=free

-F free

Colete o lixo até que o espaço free esteja disponível em /gnu/store, se possível; free denota espaço de armazenamento, como 500MiB, conforme descrito acima.

Quando free ou mais já estiver disponível em /gnu/store, não faça nada e saia imediatamente.

--delete-generations[=duração]

-d [duração]

Antes de iniciar o processo de coleta de lixo, exclua todas as gerações anteriores a duração, para todos os perfis de usuário e gerações do ambiente pessoal. Quando executado como root, isso se aplica a todos os perfis de todos os usuários.

Por exemplo, este comando exclui todas as gerações de todos os seus perfis com mais de 2 meses (exceto as gerações atuais) e depois libera espaço até que pelo menos 10 GiB estejam disponíveis:

guix gc -d 2m -F 10G

--delete

-D

Tentativa de excluir todos os arquivos e diretórios de armazém especificados como argumentos. Isso falhará se alguns dos arquivos não estiverem no armazém ou se ainda estiverem ativos.

--list-failures

Listar itens de armazém correspondentes a falhas de compilação em cache.

Isso não imprime nada, a menos que o daemon tenha sido iniciado com --cache-failures (veja --cache-failures).

--list-roots

Listar as raízes do GC de propriedade do usuário; quando executado como root, listar todas as raízes do GC.

--list-busy

Listar itens de armazém em uso por processos em execução no momento. Esses itens de armazém são efetivamente considerados raízes GC: eles não podem ser excluídos.

--clear-failures

Remova os itens de armazém especificados do cache de compilação com falha.

Novamente, essa opção só faz sentido quando o daemon é iniciado com --cache-failures. Caso contrário, não faz nada.

--list-dead

Exibe a lista de arquivos e diretórios mortos ainda presentes no armazém, ou seja, arquivos e diretórios que não podem mais ser acessados de nenhuma raiz.

--list-live

Exibe a lista de arquivos e diretórios do armazém ativa.

Além disso, as referências entre arquivos de armazém existentes podem ser consultadas:

--references ¶

--referrers

Listar as referências (respectivamente, os referenciadores) dos arquivos de armazém fornecidos como argumentos.

--requisites ¶

-R

Liste os requisitos dos arquivos de armazém passados como argumentos. Os requisitos incluem os próprios arquivos de armazém, suas referências e as referências destes, recursivamente. Em outras palavras, a lista retornada é o fechamento transitivo dos arquivos de armazém.

Veja Invocando guix size, para uma ferramenta para criar o perfil do tamanho do fechamento de um elemento. Veja Invocando guix graph, para uma ferramenta para visualizar o grafo de referências.

--derivers ¶

Retorna a(s) derivação(ões) que levam aos itens de armazém fornecidos (veja Derivações).

Por exemplo, este comando:

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

retorna o(s) arquivo(s) .drv que levam ao pacote emacs instalado no seu perfil.

Note que pode haver zero arquivos .drv correspondentes, por exemplo porque esses arquivos foram coletados como lixo. Também pode haver mais de um .drv correspondente devido a derivações de saída fixa.

Por fim, as seguintes opções permitem que você verifique a integridade do armazém e controle o uso do disco.

--verify[=opções] ¶

Verifique a integridade do armazém.

Por padrão, certifique-se de que todos os itens de armazém marcados como válidos no banco de dados do daemon realmente existam em /gnu/store.

Quando fornecido, opções deve ser uma lista separada por vírgulas contendo um ou mais de contents e repair.

Ao passar --verify=contents, o daemon calcula o hash de conteúdo de cada item do armazém e o compara com seu hash no banco de dados. Incompatibilidades de hash são relatadas como corrupções de dados. Como ele percorre todos os arquivos no armazém, esse comando pode levar muito tempo, especialmente em sistemas com uma unidade de disco lenta.

Usar --verify=repair ou --verify=contents,repair faz com que o daemon tente reparar itens corrompidos do armazém buscando substitutos para eles (veja Substitutos). Como o reparo não é atômico e, portanto, potencialmente perigoso, ele está disponível apenas para o administrador do sistema. Uma alternativa leve, quando você sabe exatamente quais itens no armazém estão corrompidos, é guix build --repair (veja Invocando guix build).

--optimize ¶

Otimize o armazém vinculando fisicamente arquivos idênticos — isso é deduplication.

O daemon executa a desduplicação após cada importação bem-sucedida de build ou archive, a menos que tenha sido iniciado com --disable-deduplication (veja --disable-deduplication). Portanto, essa opção é útil principalmente quando o daemon estava em execução com --disable-deduplication.

--vacuum-database ¶

Guix uses an sqlite database to keep track of the items in (veja O armazém). Over time it is possible that the database may grow to a large size and become fragmented. As a result, one may wish to clear the freed space and join the partially used pages in the database left behind from removed packages or after running the garbage collector. Running sudo guix gc --vacuum-database will lock the database and VACUUM the store, defragmenting the database and purging freed pages, unlocking the database when it finishes.

5.7 Invocando guix pull

Packages are installed or upgraded to the latest version available in the distribution currently available on your local machine. To update that distribution, along with the Guix tools, you must run guix pull: the command downloads the latest Guix source code and package descriptions, and deploys it. Source code is downloaded from a Git repository, by default the official GNU Guix repository, though this can be customized. guix pull ensures that the code it downloads is authentic by verifying that commits are signed by Guix developers.

Specifically, guix pull downloads code from the channels (veja Canais) specified by one of the following, in this order:

1. the --channels option;
2. the user’s ~/.config/guix/channels.scm file, unless -q is passed;
3. the system-wide /etc/guix/channels.scm file, unless -q is passed (on Guix System, this file can be declared in the operating system configuration, veja channels field of guix-configuration);
4. the built-in default channels specified in the %default-channels variable.

On completion, guix package will use packages and package versions from this just-retrieved copy of Guix. Not only that, but all the Guix commands and Scheme modules will also be taken from that latest version. New guix sub-commands added by the update also become available.

Any user can update their Guix copy using guix pull, and the effect is limited to the user who ran guix pull. For instance, when user root runs guix pull, this has no effect on the version of Guix that user alice sees, and vice versa.

The result of running guix pull is a profile available under ~/.config/guix/current containing the latest Guix.

The --list-generations or -l option lists past generations produced by guix pull, along with details about their provenance:

$ 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

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

Veja guix describe, for other ways to describe the current status of Guix.

This ~/.config/guix/current profile works exactly like the profiles created by guix package (veja Invocando guix package). That is, you can list generations, roll back to the previous generation—i.e., the previous Guix—and so on:

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

You can also use guix package (veja Invocando guix package) to manage the profile by naming it explicitly:

$ 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

The guix pull command is usually invoked with no arguments, but it supports the following options:

--url=url

--commit=commit

--branch=ramo

Download code for the guix channel from the specified url, at the given commit (a valid Git commit ID represented as a hexadecimal string or the name of a tag), or branch.

These options are provided for convenience, but you can also specify your configuration in the ~/.config/guix/channels.scm file or using the --channels option (see below).

--channels=file

-C arquivo

Read the list of channels from file instead of ~/.config/guix/channels.scm or /etc/guix/channels.scm. file must contain Scheme code that evaluates to a list of channel objects. Veja Canais, for more information.

--no-channel-files

-q

Inhibit loading of the user and system channel files, ~/.config/guix/channels.scm and /etc/guix/channels.scm.

--news

-N

Display news written by channel authors for their users for changes made since the previous generation (veja Writing Channel News). When --details is passed, additionally display new and upgraded packages.

You can view that information for previous generations with guix pull -l.

--list-generations[=padrão]

-l [padrão]

List all the generations of ~/.config/guix/current or, if pattern is provided, the subset of generations that match pattern. The syntax of pattern is the same as with guix package --list-generations (veja Invocando guix package).

By default, this prints information about the channels used in each revision as well as the corresponding news entries. If you pass --details, it will also print the list of packages added and upgraded in each generation compared to the previous one.

--details

Instruct --list-generations or --news to display more information about the differences between subsequent generations—see above.

--roll-back ¶

Roll back to the previous generation of ~/.config/guix/current—i.e., undo the last transaction.

--switch-generation=padrão ¶

-S padrão

Mude para uma geração específica definida por padrão.

padrão pode ser um número de geração ou um número prefixado com "+” ou "-”. O último significa: mover para frente/para trás por um número especificado de gerações. Por exemplo, se você quiser retornar para a última geração após --roll-back, use --switch-generation=+1.

--delete-generations[=padrão]

-d [padrão]

Quando padrão for omitido, exclua todas as gerações, exceto a atual.

Este comando aceita os mesmos padrões de --list-Generations. Quando pattern for especificado, exclua as gerações correspondentes. Quando padrão especifica uma duração, as gerações mais antigas que a duração especificada correspondem. Por exemplo, --delete-generations=1m exclui gerações com mais de um mês.

If the current generation matches, it is not deleted.

Observe que a exclusão de gerações impede a reversão para elas. Conseqüentemente, este comando deve ser usado com cuidado.

Veja Invocando guix describe, for a way to display information about the current generation only.

--profile=perfil

-p perfil

Use profile instead of ~/.config/guix/current.

--dry-run

-n

Show which channel commit(s) would be used and what would be built or substituted but do not actually do it.

--allow-downgrades

Allow pulling older or unrelated revisions of channels than those currently in use.

By default, guix pull protects against so-called “downgrade attacks” whereby the Git repository of a channel would be reset to an earlier or unrelated revision of itself, potentially leading you to install older, known-vulnerable versions of software packages.

Nota: Make sure you understand its security implications before using --allow-downgrades.

--disable-authentication

Allow pulling channel code without authenticating it.

By default, guix pull authenticates code downloaded from channels by verifying that its commits are signed by authorized developers, and raises an error if this is not the case. This option instructs it to not perform any such verification.

Nota: Make sure you understand its security implications before using --disable-authentication.

--system=system

-s sistema

Attempt to build for system—e.g., i686-linux—instead of the system type of the build host.

--bootstrap

Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers.

The channel mechanism allows you to instruct guix pull which repository and branch to pull from, as well as additional repositories containing package modules that should be deployed. Veja Canais, for more information.

In addition, guix pull supports all the common build options (veja Opções de compilação comum).

5.8 Invoking guix time-machine

The guix time-machine command provides access to other revisions of Guix, for example to install older versions of packages, or to reproduce a computation in an identical environment. The revision of Guix to be used is defined by a commit or by a channel description file created by guix describe (veja Invocando guix describe).

Let’s assume that you want to travel to those days of November 2020 when version 1.2.0 of Guix was released and, once you’re there, run the guile of that time:

guix time-machine --commit=v1.2.0 -- \
  environment -C --ad-hoc guile -- guile

The command above fetches Guix 1.2.0 (and possibly other channels specified by your channels.scm configuration files—see below) and runs its guix environment command to spawn an environment in a container running guile (guix environment has since been subsumed by guix shell; veja Invoking guix shell). It’s like driving a DeLorean¹²! The first guix time-machine invocation can be expensive: it may have to download or even build a large number of packages; the result is cached though and subsequent commands targeting the same commit are almost instantaneous.

As for guix pull, in the absence of any options, time-machine fetches the latest commits of the channels specified in ~/.config/guix/channels.scm, /etc/guix/channels.scm, or the default channels; the -q option lets you ignore these configuration files. The command:

guix time-machine -q -- build hello

will thus build the package hello as defined in the main branch of Guix, without any additional channel, which is in general a newer revision of Guix than you have installed. Time travel works in both directions!

Nota: The history of Guix is immutable and guix time-machine provides the exact same software as they are in a specific Guix revision. Naturally, no security fixes are provided for old versions of Guix or its channels. A careless use of guix time-machine opens the door to security vulnerabilities. Veja --allow-downgrades.

guix time-machine raises an error when attempting to travel to commits older than “v0.16.0” (commit ‘4a0b87f0’), dated Dec. 2018. This is one of the oldest commits supporting the channel mechanism that makes “time travel” possible.

Nota: Although it should technically be possible to travel to such an old commit, the ease to do so will largely depend on the availability of binary substitutes. When traveling to a distant past, some packages may not easily build from source anymore. One such example are old versions of OpenSSL whose tests would fail after a certain date. This particular problem can be worked around by running a virtual build machine with its clock set to the right time (veja Virtual Build Machines).

A sintaxe geral é:

guix time-machine options… -- command arg…

where command and arg… are passed unmodified to the guix command of the specified revision. The options that define this revision are the same as for guix pull (veja Invocando guix pull):

--url=url

--commit=commit

--branch=ramo

Use the guix channel from the specified url, at the given commit (a valid Git commit ID represented as a hexadecimal string or the name of a tag), or branch.

--channels=file

-C arquivo

Read the list of channels from file. file must contain Scheme code that evaluates to a list of channel objects. Veja Canais for more information.

--no-channel-files

-q

Inhibit loading of the user and system channel files, ~/.config/guix/channels.scm and /etc/guix/channels.scm.

Thus, guix time-machine -q is equivalent to the following Bash command, using the “process substitution” syntax (veja Process Substitution em The GNU Bash Reference Manual):

guix time-machine -C <(echo %default-channels) …

Note that guix time-machine can trigger builds of channels and their dependencies, and these are controlled by the standard build options (veja Opções de compilação comum).

If guix time-machine is executed without any command, it prints the file name of the profile that would be used to execute the command. This is sometimes useful if you need to get store file name of the profile—e.g., when you want to guix copy it.

5.9 Inferiores

Nota: The functionality described here is a “technology preview” as of version 9b1de85. As such, the interface is subject to change.

Sometimes you might need to mix packages from the revision of Guix you’re currently running with packages available in a different revision of Guix. Guix inferiors allow you to achieve that by composing different Guix revisions in arbitrary ways.

Technically, an “inferior” is essentially a separate Guix process connected to your main Guix process through a REPL (veja Invocando guix repl). The (guix inferior) module allows you to create inferiors and to communicate with them. It also provides a high-level interface to browse and manipulate the packages that an inferior provides—inferior packages.

When combined with channels (veja Canais), inferiors provide a simple way to interact with a separate revision of Guix. For example, let’s assume you want to install in your profile the current guile package, along with the guile-json as it existed in an older revision of Guix—perhaps because the newer guile-json has an incompatible API and you want to run your code against the old API. To do that, you could write a manifest for use by guix package --manifest (veja Escrevendo manifestos); in that manifest, you would create an inferior for that old Guix revision you care about, and you would look up the guile-json package in the inferior:

(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")))

On its first run, guix package --manifest might have to build the channel you specified before it can create the inferior; subsequent runs will be much faster because the Guix revision will be cached.

The (guix inferior) module provides the following procedures to open an inferior:

Procedure: inferior-for-channels channels [#:cache-directory] [#:ttl]

Return an inferior for channels, a list of channels. Use the cache at cache-directory, where entries can be reclaimed after ttl seconds. This procedure opens a new connection to the build daemon.

As a side effect, this procedure may build or substitute binaries for channels, which can take time.

Procedure: open-inferior directory [#:command "bin/guix"]

Open the inferior Guix in directory, running directory/command repl or equivalent. Return #f if the inferior could not be launched.

The procedures listed below allow you to obtain and manipulate inferior packages.

Procedure: inferior-packages inferior

Return the list of packages known to inferior.

Procedure: lookup-inferior-packages inferior name [version]

Return the sorted list of inferior packages matching name in inferior, with highest version numbers first. If version is true, return only packages with a version number prefixed by version.

Procedure: inferior-package? obj

Return true if obj is an inferior package.

Procedure: inferior-package-name package

Procedure: inferior-package-version package

Procedure: inferior-package-synopsis package

Procedure: inferior-package-description package

Procedure: inferior-package-home-page package

Procedure: inferior-package-location package

Procedure: inferior-package-inputs package

Procedure: inferior-package-native-inputs package

Procedure: inferior-package-propagated-inputs package

Procedure: inferior-package-transitive-propagated-inputs package

Procedure: inferior-package-native-search-paths package

Procedure: inferior-package-transitive-native-search-paths package

Procedure: inferior-package-search-paths package

These procedures are the counterpart of package record accessors (veja package Reference). Most of them work by querying the inferior package comes from, so the inferior must still be live when you call these procedures.

Inferior packages can be used transparently like any other package or file-like object in G-expressions (veja Expressões-G). They are also transparently handled by the packages->manifest procedure, which is commonly used in manifests (veja the --manifest option of guix package). Thus you can insert an inferior package pretty much anywhere you would insert a regular package: in manifests, in the packages field of your operating-system declaration, and so on.

5.10 Invocando guix describe

Often you may want to answer questions like: “Which revision of Guix am I using?” or “Which channels am I using?” This is useful information in many situations: if you want to replicate an environment on a different machine or user account, if you want to report a bug or to determine what change in the channels you are using caused it, or if you want to record your system state for reproducibility purposes. The guix describe command answers these questions.

When run from a guix pulled guix, guix describe displays the channel(s) that it was built from, including their repository URL and commit IDs (veja Canais):

$ 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

If you’re familiar with the Git version control system, this is similar in spirit to git describe; the output is also similar to that of guix pull --list-generations, but limited to the current generation (veja the --list-generations option). Because the Git commit ID shown above unambiguously refers to a snapshot of Guix, this information is all it takes to describe the revision of Guix you’re using, and also to replicate it.

To make it easier to replicate Guix, guix describe can also be asked to return a list of channels instead of the human-readable description above:

$ guix describe -f channels
(list (channel
        (name 'guix)
        (url "https://git.savannah.gnu.org/git/guix.git")
        (commit
          "e0fa68c7718fffd33d81af415279d6ddb518f727")
        (introduction
          (make-channel-introduction
            "9edb3f66fd807b096b48283debdcddccfea34bad"
            (openpgp-fingerprint
              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))

You can save this to a file and feed it to guix pull -C on some other machine or at a later point in time, which will instantiate this exact Guix revision (veja the -C option). From there on, since you’re able to deploy the same revision of Guix, you can just as well replicate a complete software environment. We humbly think that this is awesome, and we hope you’ll like it too!

The details of the options supported by guix describe are as follows:

--format=format

-f format

Produce output in the specified format, one of:

human

produce human-readable output;

channels

produce a list of channel specifications that can be passed to guix pull -C or installed as ~/.config/guix/channels.scm (veja Invocando guix pull);

channels-sans-intro

like channels, but omit the introduction field; use it to produce a channel specification suitable for Guix version 1.1.0 or earlier—the introduction field has to do with channel authentication (veja Channel Authentication) and is not supported by these older versions;

json ¶

produce a list of channel specifications in JSON format;

recutils

produce a list of channel specifications in Recutils format.

--list-formats

Display available formats for --format option.

--profile=perfil

-p perfil

Display information about profile.

5.11 Invocando guix archive

The guix archive command allows users to export files from the store into a single archive, and to later import them on a machine that runs Guix. In particular, it allows store files to be transferred from one machine to the store on another machine.

Nota: If you’re looking for a way to produce archives in a format suitable for tools other than Guix, veja Invocando guix pack.

To export store files as an archive to standard output, run:

guix archive --export options specifications...

specifications may be either store file names or package specifications, as for guix package (veja Invocando guix package). For instance, the following command creates an archive containing the gui output of the git package and the main output of emacs:

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

If the specified packages are not built yet, guix archive automatically builds them. The build process may be controlled with the common build options (veja Opções de compilação comum).

To transfer the emacs package to a machine connected over SSH, one would run:

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

Similarly, a complete user profile may be transferred from one machine to another like this:

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

However, note that, in both examples, all of emacs and the profile as well as all of their dependencies are transferred (due to -r), regardless of what is already available in the store on the target machine. The --missing option can help figure out which items are missing from the target store. The guix copy command simplifies and optimizes this whole process, so this is probably what you should use in this case (veja Invocando guix copy).

Each store item is written in the normalized archive or nar format (described below), and the output of guix archive --export (and input of guix archive --import) is a nar bundle.

The nar format is comparable in spirit to ‘tar’, but with differences that make it more appropriate for our purposes. First, rather than recording all Unix metadata for each file, the nar format only mentions the file type (regular, directory, or symbolic link); Unix permissions and owner/group are dismissed. Second, the order in which directory entries are stored always follows the order of file names according to the C locale collation order. This makes archive production fully deterministic.

That nar bundle format is essentially the concatenation of zero or more nars along with metadata for each store item it contains: its file name, references, corresponding derivation, and a digital signature.

When exporting, the daemon digitally signs the contents of the archive, and that digital signature is appended. When importing, the daemon verifies the signature and rejects the import in case of an invalid signature or if the signing key is not authorized.

The main options are:

--export

Export the specified store files or packages (see below). Write the resulting archive to the standard output.

Dependencies are not included in the output, unless --recursive is passed.

-r

--recursive

When combined with --export, this instructs guix archive to include dependencies of the given items in the archive. Thus, the resulting archive is self-contained: it contains the closure of the exported store items.

--import

Read an archive from the standard input, and import the files listed therein into the store. Abort if the archive has an invalid digital signature, or if it is signed by a public key not among the authorized keys (see --authorize below).

--missing

Read a list of store file names from the standard input, one per line, and write on the standard output the subset of these files missing from the store.

--generate-key[=parameters] ¶

Generate a new key pair for the daemon. This is a prerequisite before archives can be exported with --export. This operation is usually instantaneous but it can take time if the system’s entropy pool needs to be refilled. On Guix System, guix-service-type takes care of generating this key pair the first boot.

The generated key pair is typically stored under /etc/guix, in signing-key.pub (public key) and signing-key.sec (private key, which must be kept secret). When parameters is omitted, an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt versions before 1.6.0, it is a 4096-bit RSA key. Alternatively, parameters can specify genkey parameters suitable for Libgcrypt (veja gcry_pk_genkey em The Libgcrypt Reference Manual).

--authorize ¶

Authorize imports signed by the public key passed on standard input. The public key must be in “s-expression advanced format”—i.e., the same format as the signing-key.pub file.

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

Read a single-item archive as served by substitute servers (veja Substitutos) and extract it to directory. This is a low-level operation needed in only very narrow use cases; see below.

For example, the following command extracts the substitute for Emacs served by bordeaux.guix.gnu.org to /tmp/emacs:

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

Single-item archives are different from multiple-item archives produced by guix archive --export; they contain a single store item, and they do not embed a signature. Thus this operation does no signature verification and its output should be considered unsafe.

The primary purpose of this operation is to facilitate inspection of archive contents coming from possibly untrusted substitute servers (veja Invocando guix challenge).

--list

-t

Read a single-item archive as served by substitute servers (veja Substitutos) and print the list of files it contains, as in this example:

$ wget -O - \
  https://bordeaux.guix.gnu.org/nar/lzip/…-emacs-26.3 \
  | lzip -d | guix archive -t

6.1 Especificando canais adicionais

You can specify additional channels to pull from. To use a channel, write ~/.config/guix/channels.scm to instruct guix pull to pull from it in addition to the default Guix channel(s):

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

Note that the snippet above is (as always!) Scheme code; we use cons to add a channel the list of channels that the variable %default-channels is bound to (veja cons and lists em GNU Guile Reference Manual). With this file in place, guix pull builds not only Guix but also the package modules from your own repository. The result in ~/.config/guix/current is the union of Guix with your own package modules:

$ guix describe
Generation 19	Aug 27 2018 16:20:48
  guix d894ab8
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  variant-packages dd3df5e
    repository URL: https://example.org/variant-packages.git
    branch: master
    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb

The output of guix describe above shows that we’re now running Generation 19 and that it includes both Guix and packages from the variant-packages channel (veja Invocando guix describe).

6.2 Usando um canal Guix personalizado

The channel called guix specifies where Guix itself—its command-line tools as well as its package collection—should be downloaded. For instance, suppose you want to update from another copy of the Guix repository at example.org, and specifically the super-hacks branch, you can write in ~/.config/guix/channels.scm this specification:

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

From there on, guix pull will fetch code from the super-hacks branch of the repository at example.org. The authentication concern is addressed below (veja Autenticação de canal).

Note that you can specify a local directory on the url field above if the channel that you intend to use resides on a local file system. However, in this case guix checks said directory for ownership before any further processing. This means that if the user is not the directory owner, but wants to use it as their default, they will then need to set it as a safe directory in their global git configuration file. Otherwise, guix will refuse to even read it. Supposing your system-wide local directory is at /src/guix.git, you would then create a git configuration file at ~/.gitconfig with the following contents:

[safe]
        directory = /src/guix.git

This also applies to the root user unless when called with sudo by the directory owner.

6.3 Replicando Guix

The guix describe command shows precisely which commits were used to build the instance of Guix we’re using (veja Invocando guix describe). We can replicate this instance on another machine or at a different point in time by providing a channel specification “pinned” to these commits that looks like this:

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

To obtain this pinned channel specification, the easiest way is to run guix describe and to save its output in the channels format in a file, like so:

guix describe -f channels > channels.scm

The resulting channels.scm file can be passed to the -C option of guix pull (veja Invocando guix pull) or guix time-machine (veja Invoking guix time-machine), as in this example:

guix time-machine -C channels.scm -- shell python -- python3

Given the channels.scm file, the command above will always fetch the exact same Guix instance, then use that instance to run the exact same Python (veja Invoking guix shell). On any machine, at any time, it ends up running the exact same binaries, bit for bit.

Pinned channels address a problem similar to “lock files” as implemented by some deployment tools—they let you pin and reproduce a set of packages. In the case of Guix though, you are effectively pinning the entire package set as defined at the given channel commits; in fact, you are pinning all of Guix, including its core modules and command-line tools. You’re also getting strong guarantees that you are, indeed, obtaining the exact same software.

This gives you super powers, allowing you to track the provenance of binary artifacts with very fine grain, and to reproduce software environments at will—some sort of “meta reproducibility” capabilities, if you will. Veja Inferiores, for another way to take advantage of these super powers.

6.4 Customizing the System-Wide Guix

If you’re running Guix System or building system images with it, maybe you will want to customize the system-wide guix it provides—specifically, /run/current-system/profile/bin/guix. For example, you might want to provide additional channels or to pin its revision.

This can be done using the guix-for-channels procedure, which returns a package for the given channels, and using it as part of your operating system configuration, as in this example:

(use-modules (gnu packages package-management)
             (guix channels))

(define my-channels
  ;; Channels that should be available to
  ;; /run/current-system/profile/bin/guix.
  (append
   (list (channel
          (name 'guix-science)
          (url "https://github.com/guix-science/guix-science")
          (branch "master")))
   %default-channels))

(operating-system
  ;; …
  (services
    ;; Change the package used by 'guix-service-type'.
    (modify-services %base-services
      (guix-service-type
       config => (guix-configuration
                  (inherit config)
                  (channels my-channels)
                  (guix (guix-for-channels my-channels)))))))

The resulting operating system will have both the guix and the guix-science channels visible by default. The channels field of guix-configuration above further ensures that /etc/guix/channels.scm, which is used by guix pull, specifies the same set of channels (veja channels field of guix-configuration).

The (gnu packages package-management) module exports the guix-for-channels procedure, described below.

Procedure: guix-for-channels channels

Return a package corresponding to channels.

The result is a “regular” package, which can be used in guix-configuration as shown above or in any other place that expects a package.

6.5 Autenticação de canal

The guix pull and guix time-machine commands authenticate the code retrieved from channels: they make sure each commit that is fetched is signed by an authorized developer. The goal is to protect from unauthorized modifications to the channel that would lead users to run malicious code.

As a user, you must provide a channel introduction in your channels file so that Guix knows how to authenticate its first commit. A channel specification, including its introduction, looks something along these lines:

(channel
  (name 'some-channel)
  (url "https://example.org/some-channel.git")
  (introduction
   (make-channel-introduction
    "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
    (openpgp-fingerprint
     "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))

The specification above shows the name and URL of the channel. The call to make-channel-introduction above specifies that authentication of this channel starts at commit 6f0d8cc…, which is signed by the OpenPGP key with fingerprint CABB A931….

For the main channel, called guix, you automatically get that information from your Guix installation. For other channels, include the channel introduction provided by the channel authors in your channels.scm file. Make sure you retrieve the channel introduction from a trusted source since that is the root of your trust.

If you’re curious about the authentication mechanics, read on!

6.6 Canais com substitutos

When running guix pull, Guix will first compile the definitions of every available package. This is an expensive operation for which substitutes (veja Substitutos) may be available. The following snippet in channels.scm will ensure that guix pull uses the latest commit with available substitutes for the package definitions: this is done by querying the continuous integration server at https://ci.guix.gnu.org.

(use-modules (guix ci))

(list (channel-with-substitutes-available
       %default-guix-channel
       "https://ci.guix.gnu.org"))

Note that this does not mean that all the packages that you will install after running guix pull will have available substitutes. It only ensures that guix pull will not try to compile package definitions. This is particularly useful when using machines with limited resources.

6.7 Criando um canal

Let’s say you have a bunch of custom package variants or personal packages that you think would make little sense to contribute to the Guix project, but would like to have these packages transparently available to you at the command line. By creating a channel, you can use and publish such a package collection. This involves the following steps:

1. A channel lives in a Git repository so the first step, when creating a channel, is to create its repository:

   mkdir my-channel
   cd my-channel
   git init
   

2. The next step is to create files containing package modules (veja Módulos de pacote), each of which will contain one or more package definitions (veja Definindo pacotes). A channel can provide things other than packages, such as build systems or services; we’re using packages as it’s the most common use case.

   For example, Alice might want to provide a module called (alice packages greetings) that will provide her favorite “hello world” implementations. To do that Alice will create a directory corresponding to that module name.

   mkdir -p alice/packages
   $EDITOR alice/packages/greetings.scm
   git add alice/packages/greetings.scm
   

   You can name your package modules however you like; the main constraint to keep in mind is to avoid name clashes with other package collections, which is why our hypothetical Alice wisely chose the (alice packages …) name space.

   Note that you can also place modules in a sub-directory of the repository; veja Módulos de pacote em um subdiretório, for more info on that.

3. With this first module in place, the next step is to test the packages it provides. This can be done with guix build, which needs to be told to look for modules in the Git checkout. For example, assuming (alice packages greetings) provides a package called hi-from-alice, Alice will run this command from the Git checkout:

   guix build -L. hi-from-alice
   

   ... where -L. adds the current directory to Guile’s load path (veja Load Paths em GNU Guile Reference Manual).

4. It might take Alice a few iterations to obtain satisfying package definitions. Eventually Alice will commit this file:

   git commit
   

   As a channel author, consider bundling authentication material with your channel so that users can authenticate it. Veja Autenticação de canal, and Especificando autorizações de canal, for info on how to do it.

5. To use Alice’s channel, anyone can now add it to their channel file (veja Especificando canais adicionais) and run guix pull (veja Invocando guix pull):

   $EDITOR ~/.config/guix/channels.scm
   guix pull
   

   Guix will now behave as if the root directory of that channel’s Git repository had been permanently added to the Guile load path. In this example, (alice packages greetings) will automatically be found by the guix command.

Voilà!

Aviso: Before you publish your channel, we would like to share a few words of caution:

• Before publishing a channel, please consider contributing your package definitions to Guix proper (veja Contribuindo). Guix as a project is open to free software of all sorts, and packages in Guix proper are readily available to all Guix users and benefit from the project’s quality assurance process.
• Package modules and package definitions are Scheme code that uses various programming interfaces (APIs). We, Guix developers, never change APIs gratuitously, but we do not commit to freezing APIs either. When you maintain package definitions outside Guix, we consider that the compatibility burden is on you.
• Corollary: if you’re using an external channel and that channel breaks, please report the issue to the channel authors, not to the Guix project.

You’ve been warned! Having said this, we believe external channels are a practical way to exert your freedom to augment Guix’ package collection and to share your improvements, which are basic tenets of free software. Please email us at guix-devel@gnu.org if you’d like to discuss this.

6.8 Módulos de pacote em um subdiretório

As a channel author, you may want to keep your channel modules in a sub-directory. If your modules are in the sub-directory guix, you must add a meta-data file .guix-channel that contains:

(channel
  (version 0)
  (directory "guix"))

The modules must be underneath the specified directory, as the directory changes Guile’s load-path. For example, if .guix-channel has (directory "base"), then a module defined as (define-module (gnu packages fun)) must be located at base/gnu/packages/fun.scm.

Doing this allows for only parts of a repository to be used as a channel, as Guix expects valid Guile modules when pulling. For instance, guix deploy machine configuration files are not valid Guile modules, and treating them as such would make guix pull fail.

6.9 Declarando dependências de canal

Channel authors may decide to augment a package collection provided by other channels. They can declare their channel to be dependent on other channels in a meta-data file .guix-channel, which is to be placed in the root of the channel repository.

The meta-data file should contain a simple S-expression like this:

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

   ;; The 'introduction' bit below is optional: you would
   ;; provide it for dependencies that can be authenticated.
   (introduction
    (channel-introduction
      (version 0)
      (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
      (signer "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
  (channel
   (name some-other-collection)
   (url "https://example.org/second-collection.git")
   (branch "testing"))))

In the above example this channel is declared to depend on two other channels, which will both be fetched automatically. The modules provided by the channel will be compiled in an environment where the modules of all these declared channels are available.

For the sake of reliability and maintainability, you should avoid dependencies on channels that you don’t control, and you should aim to keep the number of dependencies to a minimum.

6.10 Especificando autorizações de canal

As we saw above, Guix ensures the source code it pulls from channels comes from authorized developers. As a channel author, you need to specify the list of authorized developers in the .guix-authorizations file in the channel’s Git repository. The authentication rule is simple: each commit must be signed by a key listed in the .guix-authorizations file of its parent commit(s)¹³ The .guix-authorizations file looks like this:

;; Example '.guix-authorizations' file.

(authorizations
 (version 0)               ;current file format version

 (("AD17 A21E F8AE D8F1 CC02  DBD9 F8AE D8F1 765C 61E3"
   (name "alice"))
  ("2A39 3FFF 68F4 EF7A 3D29  12AF 68F4 EF7A 22FB B2D5"
   (name "bob"))
  ("CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"
   (name "charlie"))))

Each fingerprint is followed by optional key/value pairs, as in the example above. Currently these key/value pairs are ignored.

This authentication rule creates a chicken-and-egg issue: how do we authenticate the first commit? Related to that: how do we deal with channels whose repository history contains unsigned commits and lack .guix-authorizations? And how do we fork existing channels?

Channel introductions answer these questions by describing the first commit of a channel that should be authenticated. The first time a channel is fetched with guix pull or guix time-machine, the command looks up the introductory commit and verifies that it is signed by the specified OpenPGP key. From then on, it authenticates commits according to the rule above. Authentication fails if the target commit is neither a descendant nor an ancestor of the introductory commit.

Additionally, your channel must provide all the OpenPGP keys that were ever mentioned in .guix-authorizations, stored as .key files, which can be either binary or “ASCII-armored”. By default, those .key files are searched for in the branch named keyring but you can specify a different branch name in .guix-channel like so:

(channel
  (version 0)
  (keyring-reference "my-keyring-branch"))

To summarize, as the author of a channel, there are three things you have to do to allow users to authenticate your code:

1. Export the OpenPGP keys of past and present committers with gpg --export and store them in .key files, by default in a branch named keyring (we recommend making it an orphan branch).
2. Introduce an initial .guix-authorizations in the channel’s repository. Do that in a signed commit (veja Confirmar acesso, for information on how to sign Git commits.)
3. Advertise the channel introduction, for instance on your channel’s web page. The channel introduction, as we saw above, is the commit/key pair—i.e., the commit that introduced .guix-authorizations, and the fingerprint of the OpenPGP used to sign it.

Before pushing to your public Git repository, you can run guix git authenticate to verify that you did sign all the commits you are about to push with an authorized key:

guix git authenticate commit signer

where commit and signer are your channel introduction. Veja Invoking guix git authenticate, for details.

Publishing a signed channel requires discipline: any mistake, such as an unsigned commit or a commit signed by an unauthorized key, will prevent users from pulling from your channel—well, that’s the whole point of authentication! Pay attention to merges in particular: merge commits are considered authentic if and only if they are signed by a key present in the .guix-authorizations file of both branches.

6.11 URL principal

Channel authors can indicate the primary URL of their channel’s Git repository in the .guix-channel file, like so:

(channel
  (version 0)
  (url "https://example.org/guix.git"))

This allows guix pull to determine whether it is pulling code from a mirror of the channel; when that is the case, it warns the user that the mirror might be stale and displays the primary URL. That way, users cannot be tricked into fetching code from a stale mirror that does not receive security updates.

This feature only makes sense for authenticated repositories, such as the official guix channel, for which guix pull ensures the code it fetches is authentic.

6.12 Escrevendo notícias do canal

Channel authors may occasionally want to communicate to their users information about important changes in the channel. You’d send them all an email, but that’s not convenient.

Instead, channels can provide a news file; when the channel users run guix pull, that news file is automatically read and guix pull --news can display the announcements that correspond to the new commits that have been pulled, if any.

To do that, channel authors must first declare the name of the news file in their .guix-channel file:

(channel
  (version 0)
  (news-file "etc/news.txt"))

The news file itself, etc/news.txt in this example, must look something like this:

(channel-news
  (version 0)
  (entry (tag "the-bug-fix")
         (title (en "Fixed terrible bug")
                (fr "Oh la la"))
         (body (en "@emph{Good news}!  It's fixed!")
               (eo "Certe ĝi pli bone funkcias nun!")))
  (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
         (title (en "Added a great package")
                (ca "Què vol dir guix?"))
         (body (en "Don't miss the @code{hello} package!"))))

While the news file is using the Scheme syntax, avoid naming it with a .scm extension or else it will get picked up when building the channel and yield an error since it is not a valid module. Alternatively, you can move the channel module to a subdirectory and store the news file in another directory.

The file consists of a list of news entries. Each entry is associated with a commit or tag: it describes changes made in this commit, possibly in preceding commits as well. Users see entries only the first time they obtain the commit the entry refers to.

The title field should be a one-line summary while body can be arbitrarily long, and both can contain Texinfo markup (veja Overview em GNU Texinfo). Both the title and body are a list of language tag/message tuples, which allows guix pull to display news in the language that corresponds to the user’s locale.

If you want to translate news using a gettext-based workflow, you can extract translatable strings with xgettext (veja xgettext Invocation em GNU Gettext Utilities). For example, assuming you write news entries in English first, the command below creates a PO file containing the strings to translate:

xgettext -o news.po -l scheme -ken etc/news.txt

To sum up, yes, you could use your channel as a blog. But beware, this is not quite what your users might expect.

7.1 Invoking 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.

Nota: The guix shell command was recently introduced to supersede guix environment (veja Invocando guix environment). If you are familiar with guix environment, you will notice that it is similar but also—we hope!—more convenient.

A sintaxe geral é:

guix shell [options] [package…]

Sometimes an interactive shell session is not desired. An arbitrary command may be invoked by placing the -- token to separate the command from the rest of the arguments.

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.

Nota: 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 (veja Invocando 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 defines the GUIX_ENVIRONMENT variable in the shell it spawns; its value is the file name of the profile of this environment. This allows users to, say, define a specific prompt for development environments in their .bashrc (veja Bash Startup Files em The GNU Bash Reference Manual):

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

... or to browse the profile:

$ ls "$GUIX_ENVIRONMENT/bin"

The available options are summarized below.

--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. Veja Bash Startup Files em 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

Create an environment for the package or list of packages that expr evaluates to.

For example, running:

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

starts a shell with the environment for this specific variant of the PETSc package.

Running:

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

starts a shell with all the base system packages available.

The above commands only use the default output of the given packages. To select other outputs, two element tuples can be specified:

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

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

--file=file

-f arquivo

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

Por exemplo, arquivo pode conter uma definição como esta (veja Definindo pacotes):

(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=arquivo

-m arquivo

Create an environment for the packages contained in the manifest object returned by the Scheme code in file. This option can be repeated several times, in which case the manifests are concatenated.

This is similar to the same-named option in guix package (veja --manifest) and uses the same manifest files.

Veja Escrevendo manifestos, 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 (veja Opções de transformação de pacote) so it should be lossless.

--profile=perfil

-p perfil

Create an environment containing the packages installed in profile. Use guix package (veja Invocando guix package) to create and manage profiles.

--pure

Unset existing environment variables when building the new environment, except those specified with --preserve (see below). This has the effect of creating an environment in which search paths only contain package inputs.

--preserve=regexp

-E regexp

When used alongside --pure, preserve the environment variables matching regexp—in other words, put them on a “white list” of environment variables that must be preserved. This option can be repeated several times.

guix shell --pure --preserve=^SLURM openmpi … \
  -- mpirun …

This example runs mpirun in a context where the only environment variables defined are PATH, environment variables whose name starts with ‘SLURM’, as well as the usual “precious” variables (HOME, USER, etc.).

--search-paths

Display the environment variable definitions that make up the environment.

--system=system

-s sistema

Attempt to build for system—e.g., i686-linux.

--container ¶

-C

Run command within an isolated container. The current working directory outside the container is mapped inside the container. Additionally, unless overridden with --user, a dummy home directory is created that matches the current user’s home directory, and /etc/passwd is configured accordingly.

The spawned process runs as the current user outside the container. Inside the container, it has the same UID and GID as the current user, unless --user is passed (see below).

--network

-N

For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device.

--link-profile

-P

For containers, link the environment profile to ~/.guix-profile within the container and set GUIX_ENVIRONMENT to that. This is equivalent to making ~/.guix-profile a symlink to the actual profile within the container. Linking will fail and abort the environment if the directory already exists, which will certainly be the case if guix shell was invoked in the user’s home directory.

Certain packages are configured to look in ~/.guix-profile for configuration files and data;¹⁵ --link-profile allows these programs to behave as expected within the environment.

--user=user

-u usuário

For containers, use the username user in place of the current user. The generated /etc/passwd entry within the container will contain the name user, the home directory will be /home/user, and no user GECOS data will be copied. Furthermore, the UID and GID inside the container are 1000. user need not exist on the system.

Additionally, any shared or exposed path (see --share and --expose respectively) whose target is within the current user’s home directory will be remapped relative to /home/USER; this includes the automatic mapping of the current working directory.

# 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

While this will limit the leaking of user identity through home paths and each of the user fields, this is only one useful component of a broader privacy/anonymity solution—not one in and of itself.

--no-cwd

For containers, the default behavior is to share the current working directory with the isolated container and immediately change to that directory within the container. If this is undesirable, --no-cwd will cause the current working directory to not be automatically shared and will change to the user’s home directory within the container instead. See also --user.

--expose=fonte[=alvo]

--share=fonte[=alvo]

For containers, --expose (resp. --share) exposes the file system source from the host system as the read-only (resp. writable) file system target within the container. If target is not specified, source is used as the target mount point in the container.

The example below spawns a Guile REPL in a container in which the user’s home directory is accessible read-only via the /exchange directory:

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:

• mapeie o socket do daemon (por padrão, /var/guix/daemon-socket/socket) dentro do contêiner;
• 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=arquivo ¶

-r arquivo

Make file a symlink to the profile for this environment, and register it as a garbage collector root.

This is useful if you want to protect your environment from garbage collection, to make it “persistent”.

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.

Veja Invocando guix gc, for more on GC roots.

guix shell also supports all of the common build options that guix build supports (veja Opções de compilação comum) as well as package transformation options (veja Opções de transformação de pacote).

7.2 Invocando guix environment

The purpose of guix environment is to assist in creating development environments.

Deprecation warning: The guix environment command is deprecated in favor of guix shell, which performs similar functions but is more convenient to use. Veja Invoking guix shell.

Being deprecated, guix environment is slated for eventual removal, but the Guix project is committed to keeping it until May 1st, 2023. Please get in touch with us at guix-devel@gnu.org if you would like to discuss it.

A sintaxe geral é:

guix environment options package…

The following example spawns a new shell set up for the development of GNU Guile:

guix environment guile

If the needed dependencies are not built yet, guix environment automatically builds them. The environment of the new shell is an augmented version of the environment that guix environment was run in. It contains the necessary search paths for building the given package added to the existing environment variables. To create a “pure” environment, in which the original environment variables have been unset, use the --pure option¹⁶.

Exiting from a Guix environment is the same as exiting from the shell, and will place the user back in the old environment before guix environment was invoked. The next garbage collection (veja Invocando guix gc) will clean up packages that were installed from within the environment and are no longer used outside of it.

guix environment defines the GUIX_ENVIRONMENT variable in the shell it spawns; its value is the file name of the profile of this environment. This allows users to, say, define a specific prompt for development environments in their .bashrc (veja Bash Startup Files em The GNU Bash Reference Manual):

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

... or to browse the profile:

$ ls "$GUIX_ENVIRONMENT/bin"

Additionally, more than one package may be specified, in which case the union of the inputs for the given packages are used. For example, the command below spawns a shell where all of the dependencies of both Guile and Emacs are available:

guix environment guile emacs

Sometimes an interactive shell session is not desired. An arbitrary command may be invoked by placing the -- token to separate the command from the rest of the arguments:

guix environment guile -- make -j4

In other situations, it is more convenient to specify the list of packages needed in the environment. For example, the following command runs python from an environment containing Python 3 and NumPy:

guix environment --ad-hoc python-numpy python -- python3

Furthermore, one might want the dependencies of a package and also some additional packages that are not build-time or runtime dependencies, but are useful when developing nonetheless. Because of this, the --ad-hoc flag is positional. Packages appearing before --ad-hoc are interpreted as packages whose dependencies will be added to the environment. Packages appearing after are interpreted as packages that will be added to the environment directly. For example, the following command creates a Guix development environment that additionally includes Git and strace:

guix environment --pure guix --ad-hoc git strace

Sometimes it is desirable to isolate the environment as much as possible, for maximal purity and reproducibility. In particular, when using Guix on a host distro that is not Guix System, it is desirable to prevent access to /usr/bin and other system-wide resources from the development environment. For example, the following command spawns a Guile REPL in a “container” where only the store and the current working directory are mounted:

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

Nota: The --container option requires Linux-libre 3.19 or newer.

Another typical use case for containers is to run security-sensitive applications such as a web browser. To run Eolie, we must expose and share some files and directories; we include nss-certs and expose /etc/ssl/certs/ for HTTPS authentication; finally we preserve the DISPLAY environment variable since containerized graphical applications won’t display without it.

guix environment --preserve='^DISPLAY$' --container --network \
  --expose=/etc/machine-id \
  --expose=/etc/ssl/certs/ \
  --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
  --ad-hoc eolie nss-certs dbus --  eolie

The available options are summarized below.

--check

Set up the environment and check whether the shell would clobber environment variables. Veja --check, for more info.

--root=arquivo ¶

-r arquivo

Make file a symlink to the profile for this environment, and register it as a garbage collector root.

This is useful if you want to protect your environment from garbage collection, to make it “persistent”.

When this option is omitted, the environment is protected from garbage collection only for the duration of the guix environment session. This means that next time you recreate the same environment, you could have to rebuild or re-download packages. Veja Invocando guix gc, for more on GC roots.

--expression=expr

-e expr

Create an environment for the package or list of packages that expr evaluates to.

For example, running:

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

starts a shell with the environment for this specific variant of the PETSc package.

Running:

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

starts a shell with all the base system packages available.

The above commands only use the default output of the given packages. To select other outputs, two element tuples can be specified:

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

--load=arquivo

-l arquivo

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

Por exemplo, arquivo pode conter uma definição como esta (veja Definindo pacotes):

(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))))

--manifest=arquivo

-m arquivo

Create an environment for the packages contained in the manifest object returned by the Scheme code in file. This option can be repeated several times, in which case the manifests are concatenated.

This is similar to the same-named option in guix package (veja --manifest) and uses the same manifest files.

Veja guix shell --export-manifest, for information on how to “convert” command-line options into a manifest.

--ad-hoc

Include all specified packages in the resulting environment, as if an ad hoc package were defined with them as inputs. This option is useful for quickly creating an environment without having to write a package expression to contain the desired inputs.

For instance, the command:

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

runs guile in an environment where Guile and Guile-SDL are available.

Note that this example implicitly asks for the default output of guile and guile-sdl, but it is possible to ask for a specific output—e.g., glib:bin asks for the bin output of glib (veja Pacotes com múltiplas saídas).

This option may be composed with the default behavior of guix environment. Packages appearing before --ad-hoc are interpreted as packages whose dependencies will be added to the environment, the default behavior. Packages appearing after are interpreted as packages that will be added to the environment directly.

--profile=perfil

-p perfil

Create an environment containing the packages installed in profile. Use guix package (veja Invocando guix package) to create and manage profiles.

--pure

Unset existing environment variables when building the new environment, except those specified with --preserve (see below). This has the effect of creating an environment in which search paths only contain package inputs.

--preserve=regexp

-E regexp

When used alongside --pure, preserve the environment variables matching regexp—in other words, put them on a “white list” of environment variables that must be preserved. This option can be repeated several times.

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

This example runs mpirun in a context where the only environment variables defined are PATH, environment variables whose name starts with ‘SLURM’, as well as the usual “precious” variables (HOME, USER, etc.).

--search-paths

Display the environment variable definitions that make up the environment.

--system=system

-s sistema

Attempt to build for system—e.g., i686-linux.

--container ¶

-C

Run command within an isolated container. The current working directory outside the container is mapped inside the container. Additionally, unless overridden with --user, a dummy home directory is created that matches the current user’s home directory, and /etc/passwd is configured accordingly.

The spawned process runs as the current user outside the container. Inside the container, it has the same UID and GID as the current user, unless --user is passed (see below).

--network

-N

For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device.

--link-profile

-P

For containers, link the environment profile to ~/.guix-profile within the container and set GUIX_ENVIRONMENT to that. This is equivalent to making ~/.guix-profile a symlink to the actual profile within the container. Linking will fail and abort the environment if the directory already exists, which will certainly be the case if guix environment was invoked in the user’s home directory.

Certain packages are configured to look in ~/.guix-profile for configuration files and data;¹⁷ --link-profile allows these programs to behave as expected within the environment.

--user=user

-u usuário

For containers, use the username user in place of the current user. The generated /etc/passwd entry within the container will contain the name user, the home directory will be /home/user, and no user GECOS data will be copied. Furthermore, the UID and GID inside the container are 1000. user need not exist on the system.

Additionally, any shared or exposed path (see --share and --expose respectively) whose target is within the current user’s home directory will be remapped relative to /home/USER; this includes the automatic mapping of the current working directory.

# 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

While this will limit the leaking of user identity through home paths and each of the user fields, this is only one useful component of a broader privacy/anonymity solution—not one in and of itself.

--no-cwd

For containers, the default behavior is to share the current working directory with the isolated container and immediately change to that directory within the container. If this is undesirable, --no-cwd will cause the current working directory to not be automatically shared and will change to the user’s home directory within the container instead. See also --user.

--expose=fonte[=alvo]

--share=fonte[=alvo]

For containers, --expose (resp. --share) exposes the file system source from the host system as the read-only (resp. writable) file system target within the container. If target is not specified, source is used as the target mount point in the container.

The example below spawns a Guile REPL in a container in which the user’s home directory is accessible read-only via the /exchange directory:

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

--emulate-fhs

-F

For containers, emulate a Filesystem Hierarchy Standard (FHS) configuration within the container, see the official specification. 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 which 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.

guix environment also supports all of the common build options that guix build supports (veja Opções de compilação comum) as well as package transformation options (veja Opções de transformação de pacote).

7.3 Invocando guix pack

Occasionally you want to pass software to people who are not (yet!) lucky enough to be using Guix. You’d tell them to run guix package -i something, but that’s not possible in this case. This is where guix pack comes in.

Nota: If you are looking for ways to exchange binaries among machines that already run Guix, veja Invocando guix copy, Invocando guix publish, and Invocando guix archive.

The guix pack command creates a shrink-wrapped pack or software bundle: it creates a tarball or some other archive containing the binaries of the software you’re interested in, and all its dependencies. The resulting archive can be used on any machine that does not have Guix, and people can run the exact same binaries as those you have with Guix. The pack itself is created in a bit-reproducible fashion, so anyone can verify that it really contains the build results that you pretend to be shipping.

For example, to create a bundle containing Guile, Emacs, Geiser, and all their dependencies, you can run:

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

The result here is a tarball containing a /gnu/store directory with all the relevant packages. The resulting tarball contains a profile with the three packages of interest; the profile is the same as would be created by guix package -i. It is this mechanism that is used to create Guix’s own standalone binary tarball (veja Instalação de binários).

Users of this pack would have to run /gnu/store/…-profile/bin/guile to run Guile, which you may find inconvenient. To work around it, you can create, say, a /opt/gnu/bin symlink to the profile:

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

That way, users can happily type /opt/gnu/bin/guile and enjoy.

What if the recipient of your pack does not have root privileges on their machine, and thus cannot unpack it in the root file system? In that case, you will want to use the --relocatable option (see below). This option produces relocatable binaries, meaning they can be placed anywhere in the file system hierarchy: in the example above, users can unpack your tarball in their home directory and directly run ./opt/gnu/bin/guile.

Alternatively, you can produce a pack in the Docker image format using the following command:

guix pack -f docker -S /bin=bin guile guile-readline

The result is a tarball that can be passed to the docker load command, followed by docker run:

docker load < file
docker run -ti guile-guile-readline /bin/guile

where file is the image returned by guix pack, and guile-guile-readline is its “image tag”. See the Docker documentation for more information.

Yet another option is to produce a SquashFS image with the following command:

guix pack -f squashfs bash guile emacs 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.

Several command-line options allow you to customize your pack:

--format=format

-f format

Produce a pack in the given format.

The available formats are:

tarball

This is the default format. It produces a tarball containing all the specified binaries and symlinks.

docker

This produces a tarball that follows the Docker Image Specification. By default, the “repository name” as it appears in the output of the docker images command is computed from package names passed on the command line or in the manifest file. Alternatively, the “repository name” can also be configured via the --image-tag option. Refer to --help-docker-format for more information on such advanced options.

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.

Nota: Singularity requires you to provide /bin/sh in the image. For that reason, guix pack -f squashfs always implies -S /bin=bin. Thus, your guix pack invocation must always start with something like:

guix pack -f squashfs bash …

If you forget the bash (or similar) package, singularity run and singularity exec will fail with an unhelpful “no such file or directory” message.

deb ¶

This produces a Debian archive (a package with the ‘.deb’ file extension) containing all the specified binaries and symbolic links, that can be installed on top of any dpkg-based GNU(/Linux) distribution. Advanced options can be revealed via the --help-deb-format option. They allow embedding control files for more fine-grained control, such as activating specific triggers or providing a maintainer configure script to run arbitrary setup code upon installation.

guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello

Nota: Because archives produced with guix pack contain a collection of store items and because each dpkg package must not have conflicting files, in practice that means you likely won’t be able to install more than one such archive on a given system. You can nonetheless pack as many Guix packages as you want in one such archive.

Aviso: dpkg will assume ownership of any files contained in the pack that it does not know about. It is unwise to install Guix-produced ‘.deb’ files on a system where /gnu/store is shared by other software, such as a Guix installation or other, non-deb packs.

rpm ¶

This produces an RPM archive (a package with the ‘.rpm’ file extension) containing all the specified binaries and symbolic links, that can be installed on top of any RPM-based GNU/Linux distribution. The RPM format embeds checksums for every file it contains, which the rpm command uses to validate the integrity of the archive.

Advanced RPM-related options are revealed via the --help-rpm-format option. These options allow embedding maintainer scripts that can run before or after the installation of the RPM archive, for example.

The RPM format supports relocatable packages via the --prefix option of the rpm command, which can be handy to install an RPM package to a specific prefix.

guix pack -f rpm -R -C xz -S /usr/bin/hello=bin/hello hello

sudo rpm --install --prefix=/opt /gnu/store/...-hello.rpm

Nota: Contrary to Debian packages, conflicting but identical files in RPM packages can be installed simultaneously, which means multiple guix pack-produced RPM packages can usually be installed side by side without any problem.

Aviso: rpm assumes ownership of any files contained in the pack, which means it will remove /gnu/store upon uninstalling a Guix-generated RPM package, unless the RPM package was installed with the --prefix option of the rpm command. It is unwise to install Guix-produced ‘.rpm’ packages on a system where /gnu/store is shared by other software, such as a Guix installation or other, non-rpm packs.

--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 twice¹⁸, relocatable binaries fall to back to other techniques 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.

Nota: 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 another execution engine if user namespaces are not supported. The following execution engines are supported:

default

Try user namespaces and fall back to PRoot if user namespaces are not supported (see below).

performance

Try user namespaces and fall back to Fakechroot if user namespaces are not supported (see below).

userns

Run the program through user namespaces and abort if they are not supported.

proot

Run through PRoot. 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.

fakechroot

Run through Fakechroot. Fakechroot virtualizes file system accesses by intercepting calls to C library functions such as open, stat, exec, and so on. Unlike PRoot, it incurs very little overhead. However, it does not always work: for example, some file system accesses made from within the C library are not intercepted, and file system accesses made via direct syscalls are not intercepted either, leading to erratic behavior.

When running a wrapped program, you can explicitly request one of the execution engines listed above by setting the GUIX_EXECUTION_ENGINE environment variable accordingly.

--entry-point=command

Use command as the entry point of the resulting pack, if the pack format supports it—currently docker and squashfs (Singularity) support it. command must be relative to the profile contained in the pack.

The entry point specifies the command that tools like docker run or singularity run automatically start by default. For example, you can do:

guix pack -f docker --entry-point=bin/guile guile

The resulting pack can easily be loaded and docker run with no extra arguments will spawn bin/guile:

docker load -i pack.tar.gz
docker run image-id

--entry-point-argument=command

-A command

Use command as an argument to entry point of the resulting pack. This option is only valid in conjunction with --entry-point and can appear multiple times on the command line.

guix pack -f docker --entry-point=bin/guile --entry-point-argument="--help" guile

--max-layers=n

Specifies the maximum number of Docker image layers allowed when building an image.

guix pack -f docker --max-layers=100 guile

This option allows you to limit the number of layers in a Docker image. Docker images are comprised of multiple layers, and each layer adds to the overall size and complexity of the image. By setting a maximum number of layers, you can control the following effects:

• Disk Usage: Increasing the number of layers can help optimize the disk space required to store multiple images built with a similar package graph.
• Pulling: When transferring images between different nodes or systems, having more layers can reduce the time required to pull the image.

--expression=expr

-e expr

Consider the package expr evaluates to.

This has the same purpose as the same-named option in guix build (veja --expression in guix build).

--manifest=arquivo

-m arquivo

Use the packages contained in the manifest object returned by the Scheme code in file. This option can be repeated several times, in which case the manifests are concatenated.

This has a similar purpose as the same-named option in guix package (veja --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.

Veja Escrevendo manifestos, for information on how to write a manifest. Veja guix shell --export-manifest, for information on how to “convert” command-line options into a manifest.

--system=system

-s sistema

Attempt to build for system—e.g., i686-linux—instead of the system type of the build host.

--target=triplet ¶

Cross-build for triplet, which must be a valid GNU triplet, such as "aarch64-linux-gnu" (veja GNU configuration triplets em Autoconf).

--compression=tool

-C tool

Compress the resulting tarball using tool—one of gzip, zstd, 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 (veja Canais).

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.

--root=arquivo ¶

-r arquivo

Make file a symlink to the resulting pack, and register it as a garbage collector root.

--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 (veja O armazém) as well as garbage-collector roots (veja Invocando 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 (veja Instalação de binários).

--derivation

-d

Print the name of the derivation that builds the pack.

--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 (veja Opções de compilação comum) and all the package transformation options (veja Opções de transformação de pacote).

7.4 A cadeia de ferramentas do GCC

If you need a complete toolchain for compiling and linking C or C++ source code, use the gcc-toolchain package. This package provides a complete GCC toolchain for C/C++ development, including GCC itself, the GNU C Library (headers and binaries, plus debugging symbols in the debug output), Binutils, and a linker wrapper.

The wrapper’s purpose is to inspect the -L and -l switches passed to the linker, add corresponding -rpath arguments, and invoke the actual linker with this new set of arguments. You can instruct the wrapper to refuse to link against libraries not in the store by setting the GUIX_LD_WRAPPER_ALLOW_IMPURITIES environment variable to no.

The package gfortran-toolchain provides a complete GCC toolchain for Fortran development. For other languages, please use ‘guix search gcc toolchain’ (veja Invoking guix package).

7.5 Invoking guix git authenticate

The guix git authenticate command authenticates a Git checkout following the same rule as for channels (veja channel authentication). That is, starting from a given commit, it ensures that all subsequent commits are signed by an OpenPGP key whose fingerprint appears in the .guix-authorizations file of its parent commit(s).

You will find this command useful if you maintain a channel. But in fact, this authentication mechanism is useful in a broader context, so you might want to use it for Git repositories that have nothing to do with Guix.

A sintaxe geral é:

guix git authenticate commit signer [options…]

By default, this command authenticates the Git checkout in the current directory; it outputs nothing and exits with exit code zero on success and non-zero on failure. commit above denotes the first commit where authentication takes place, and signer is the OpenPGP fingerprint of public key used to sign commit. Together, they form a channel introduction (veja channel introduction). On your first successful run, the introduction is recorded in the .git/config file of your checkout, allowing you to omit them from subsequent invocations:

guix git authenticate [options…]

Should you have branches that require different introductions, you can specify them directly in .git/config. For example, if the branch called personal-fork has a different introduction than other branches, you can extend .git/config along these lines:

[guix "authentication-personal-fork"]
	introduction-commit = cabba936fd807b096b48283debdcddccfea3900d
	introduction-signer = C0FF EECA BBA9 E6A8 0D1D  E643 A2A0 6DF2 A33A 54FA
	keyring = keyring

The first run also attempts to install pre-push and post-merge hooks, such that guix git authenticate is invoked as soon as you run git push, git pull, and related commands; it does not overwrite preexisting hooks though.

The command-line options described below allow you to fine-tune the process.

--repository=directory

-r directory

Open the Git repository in directory instead of the current directory.

--keyring=reference

-k reference

Load OpenPGP keyring from reference, the reference of a branch such as origin/keyring or my-keyring. The branch must contain OpenPGP public keys in .key files, either in binary form or “ASCII-armored”. By default the keyring is loaded from the branch named keyring.

--end=commit

Authenticate revisions up to commit.

--stats

Display commit signing statistics upon completion.

--cache-key=key

Previously-authenticated commits are cached in a file under ~/.cache/guix/authentication. This option forces the cache to be stored in file key in that directory.

--historical-authorizations=file

By default, any commit whose parent commit(s) lack the .guix-authorizations file is considered inauthentic. In contrast, this option considers the authorizations in file for any commit that lacks .guix-authorizations. The format of file is the same as that of .guix-authorizations (veja .guix-authorizations format).

8.1 Módulos de pacote

From a programming viewpoint, the package definitions of the GNU distribution are provided by Guile modules in the (gnu packages …) name space¹⁹ (veja Guile modules em GNU Guile Reference Manual). For instance, the (gnu packages emacs) module exports a variable named emacs, which is bound to a <package> object (veja Definindo pacotes).

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)²⁰. 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 (veja Opções de compilação comum), 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. Veja Canais, 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, veja Inicializando.

8.2 Definindo pacotes

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 (list 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 (veja Scheme records em 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 (veja Invoking 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 (veja Módulos de pacote).

There are a few points worth noting in the above package definition:

• The source field of the package is an <origin> object (veja origin Reference, for the complete reference). Here, the url-fetch method from (guix download) is used, meaning that the source is a file to be downloaded over FTP or HTTP.

  The mirror://gnu prefix instructs url-fetch to use one of the GNU mirrors defined in (guix download).

  The sha256 field specifies the expected SHA256 hash of the file being downloaded. It is mandatory, and allows Guix to check the integrity of the file. The (base32 …) form introduces the base32 representation of the hash. You can obtain this information with guix download (veja Invocando guix download) and guix hash (veja Invocando guix hash).

  When needed, the origin form can also have a patches field listing patches to be applied, and a snippet field giving a Scheme expression to modify the source code.

• The build-system field specifies the procedure to build the package (veja Sistemas de compilação). Here, gnu-build-system represents the familiar GNU Build System, where packages may be configured, built, and installed with the usual ./configure && make && make check && make install command sequence.

  When you start packaging non-trivial software, you may need tools to manipulate those build phases, manipulate files, and so on. Veja Construir utilitários, for more on this.

• The arguments field specifies options for the build system (veja Sistemas de compilação). Here it is interpreted by gnu-build-system as a request run configure with the --enable-silent-rules flag.

  What about these quote (') characters? They are Scheme syntax to introduce a literal list; ' is synonymous with quote. Sometimes you’ll also see ` (a backquote, synonymous with quasiquote) and , (a comma, synonymous with unquote). Veja quoting em GNU Guile Reference Manual, for details. Here the value of the arguments field is a list of arguments passed to the build system down the road, as with apply (veja apply em GNU Guile Reference Manual).

  The hash-colon (#:) sequence defines a Scheme keyword (veja Keywords em GNU Guile Reference Manual), and #:configure-flags is a keyword used to pass a keyword argument to the build system (veja Coding With Keywords em GNU Guile Reference Manual).

• The inputs field specifies inputs to the build process—i.e., build-time or run-time dependencies of the package. Here, we add an input, a reference to the gawk variable; gawk is itself bound to a <package> object.

  Note that GCC, Coreutils, Bash, and other essential tools do not need to be specified as inputs here. Instead, gnu-build-system takes care of ensuring that they are present (veja Sistemas de compilação).

  However, any other dependencies need to be specified in the inputs field. Any dependency not specified here will simply be unavailable to the build process, possibly leading to a build failure.

Veja package Reference, for a full description of possible fields.

Indo além: Intimidated by the Scheme language or curious about it? The Cookbook has a short section to get started that recaps some of the things shown above and explains the fundamentals. Veja A Scheme Crash Course em GNU Guix Cookbook, for more information.

Once a package definition is in place, the package may actually be built using the guix build command-line tool (veja Invocando guix build), troubleshooting any build failures you encounter (veja Depurando falhas de compilação). You can easily jump back to the package definition using the guix edit command (veja Invocando guix edit). Veja Diretrizes de empacotamento, for more information on how to test package definitions, and Invocando guix lint, for information on how to check a definition for style conformance. Lastly, veja Canais, 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 (veja Invocando 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 (veja O armazém).

Procedure: package-derivation store package [system]

Return the <derivation> object of package for system (veja Derivações).

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 (veja O armazém).

Similarly, it is possible to compute a derivation that cross-builds a package for some other system:

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 "aarch64-linux-gnu" (veja Specifying Target Triplets em Autoconf).

Once you have package definitions, you can easily define variants of those packages. Veja Definindo variantes de pacote, for more on that.

• package Reference
• origin Reference