8.4 Escrevendo manifestos

Os comandos guix permitem que você especifique listas de pacotes na linha de comando. Isso é conveniente, mas conforme a linha de comando se torna mais longa e menos trivial, rapidamente se torna mais conveniente ter essa lista de pacotes no que chamamos de manifesto. Um manifesto é algum tipo de “lista de materiais” que define um conjunto de pacotes. Você normalmente criaria um trecho de código que constrói o manifesto, o armazenaria em um arquivo, digamos manifest.scm, e então passaria esse arquivo para a opção -m (ou --manifest) que muitos comandos guix suportam. Por exemplo, aqui está como um manifesto para um conjunto de pacotes simples pode se parecer:

;; Manifesto para três pacotes.
(specifications->manifest '("gcc-toolchain" "make" "git"))

Depois de ter esse manifesto, você pode passá-lo, por exemplo, para guix package para instalar apenas esses três pacotes no seu perfil (veja -m opção de guix package):

guix package -m manifest.scm

... ou você pode passá-lo para guix shell (veja -m opção de guix shell) para gerar um ambiente efêmero:

guix shell -m manifest.scm

... ou você pode passá-lo para guix pack praticamente da mesma forma (veja -m opção de guix pack). Você pode armazenar o manifesto sob controle de versão, compartilhá-lo com outros para que eles possam facilmente configurar, etc.

Mas como você escreve seu primeiro manifesto? Para começar, talvez você queira escrever um manifesto que espelhe o que você já tem em um perfil. Em vez de começar do zero, guix package pode gerar um manifesto para você (veja guix package --export-manifest):

# Escreva em 'manifest.scm' um manifesto correspondente ao
# perfil padrão, ~/.guix-profile.
guix package --export-manifest > manifest.scm

Ou talvez você queira “traduzir” argumentos de linha de comando em um manifesto. Nesse caso, guix shell pode ajudar (veja guix shell --export-manifest):

# Write a manifest for the packages specified on the command line.
guix shell --export-manifest gcc-toolchain make git > manifest.scm

Em ambos os casos, a opção --export-manifest tenta arduamente gerar um manifesto fiel; em particular, ela leva em consideração as opções de transformação de pacotes (veja Opções de transformação de pacote).

Nota: Manifestos são simbólicos: eles se referem a pacotes dos canais atualmente em uso (veja Canais). No exemplo acima, gcc-toolchain pode se referir à versão 14 hoje, mas pode se referir à versão 16 daqui a dois anos.

Se você quiser “fixar” seu ambiente de software em versões e variantes de pacotes específicos, precisará de uma informação adicional: a lista de revisões de canal em uso, conforme retornado por guix describe. Veja Replicando Guix, para mais informações.

Depois de obter seu primeiro manifesto, talvez você queira personalizá-lo. Como seu manifesto é código, agora você tem acesso a todas as interfaces de programação Guix!

Vamos supor que você queira um manifesto para implantar uma variante personalizada do GDB, o GNU Debugger, que não depende do Guile, junto com outro pacote. Com base no exemplo visto na seção anterior (veja Definindo variantes de pacote), você pode escrever um manifesto seguindo estas linhas:

(use-modules (guix packages)
             (gnu packages gdb)               ;para 'gdb'
             (gnu packages version-control))  ;para 'git'

;; Define a variant of GDB without a dependency on Guile.
(define gdb-sans-guile
  (package
    (inherit gdb)
    (inputs (modify-inputs (package-inputs gdb)
              (delete "guile")))))

;; Return a manifest containing that one package plus Git.
(packages->manifest (list gdb-sans-guile git))

Observe que neste exemplo, o manifesto se refere diretamente às variáveis gdb e git, que são vinculadas a um objeto package (veja Referência do package), em vez de chamar specifications->manifest para procurar pacotes por nome, como fizemos antes. O formulário use-modules no topo nos permite acessar a interface do pacote principal (veja Definindo pacotes) e os módulos que definem gdb e git (veja Módulos de pacote). Sem problemas, estamos entrelaçando tudo isso — as possibilidades são infinitas, libere sua criatividade!

O tipo de dados para manifestos, bem como procedimentos de suporte, são definidos no módulo (guix profiles), que está automaticamente disponível para o código passado para -m. A referência segue.

Tipo de dados: manifest

Data type representing a manifest.

Atualmente possui um campo:

entries

Esta deve ser uma lista de registros manifest-entry — veja abaixo.

Tipo de dados: manifest-entry

Tipo de dado que representa uma entrada de manifesto. Uma entrada de manifesto contém metadados essenciais: uma string de nome e versão, o objeto (geralmente um pacote) para essa entrada, a saída desejada (veja Pacotes com múltiplas saídas) e uma série de informações opcionais detalhadas abaixo.

Na maioria das vezes, você não construirá uma entrada de manifesto diretamente; em vez disso, você passará um pacote para package->manifest-entry, descrito abaixo. Em alguns casos incomuns, no entanto, você pode querer criar entradas de manifesto para coisas que são não pacotes, como neste exemplo:

;; Manually build a single manifest entry for a non-package object.
(let ((hello (program-file "hello" #~(display "Hi!"))))
  (manifest-entry
    (name "foo")
    (version "42")
    (item
     (computed-file "hello-directory"
                     #~(let ((bin (string-append #$output "/bin")))
                         (mkdir #$output) (mkdir bin)
                          (symlink #$hello
                                   (string-append bin "/hello")))))))

The available fields are the following:

name

version

Nome e sequência de versão para esta entrada.

item

Um pacote ou outro objeto tipo arquivo (veja objetos tipo arquivo).

output (padrão: "out")

Saída de item a ser usada, caso item tenha múltiplas saídas (veja Pacotes com múltiplas saídas).

dependencies (padrão: '())

Lista de entradas de manifesto das quais esta entrada depende. Ao construir um perfil, dependências são adicionadas ao perfil.

Normalmente, as entradas propagadas de um pacote (veja propagated-inputs) acabam tendo uma entrada de manifesto correspondente entre as dependências da própria entrada de manifesto do pacote.

search-paths (padrão: '())

A lista de especificações de caminhos de pesquisa respeitadas por esta entrada (veja Caminhos de pesquisa).

properties (padrão: '())

Lista de pares de símbolo/valor. Ao construir um perfil, essas propriedades são serializadas.

Isso pode ser usado para adicionar metadados adicionais, por exemplo, as transformações aplicadas a um pacote (veja Opções de transformação de pacote).

parent (padrão: (delay #f))

Uma promessa apontando para a entrada do manifesto “pai”.

This is used as a hint to provide context when reporting an error related to a manifest entry coming from a dependencies field.

Procedure: concatenate-manifests lst

Concatenate the manifests listed in lst and return the resulting manifest.

Procedure: package->manifest-entry package [output] [#:properties]

Return a manifest entry for the output of package package, where output defaults to "out", and with the given properties. By default properties is the empty list or, if one or more package transformations were applied to package, it is an association list representing those transformations, suitable as an argument to options->transformation (veja options->transformation).

The code snippet below builds a manifest with an entry for the default output and the send-email output of the git package:

(use-modules (gnu packages version-control))

(manifest (list (package->manifest-entry git)
                (package->manifest-entry git "send-email")))

Procedure: packages->manifest packages

Return a list of manifest entries, one for each item listed in packages. Elements of packages can be either package objects or package/string tuples denoting a specific output of a package.

Using this procedure, the manifest above may be rewritten more concisely:

(use-modules (gnu packages version-control))

(packages->manifest (list git `(,git "send-email")))

Procedure: package->development-manifest package [system] [#:target]

Return a manifest for the development inputs of package for system, optionally when cross-compiling to target. Development inputs include both explicit and implicit inputs of package.

Like the -D option of guix shell (veja guix shell -D), the resulting manifest describes the environment in which one can develop package. For example, suppose you’re willing to set up a development environment for Inkscape, with the addition of Git for version control; you can describe that “bill of materials” with the following manifest:

(use-modules (gnu packages inkscape)          ;for 'inkscape'
             (gnu packages version-control))  ;for 'git'

(concatenate-manifests
 (list (package->development-manifest inkscape)
       (packages->manifest (list git))))

In this example, the development manifest that package->development-manifest returns includes the compiler (GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and a couple of additional development tools—these are the dependencies guix show inkscape lists.

Last, the (gnu packages) module provides higher-level facilities to build manifests. In particular, it lets you look up packages by name—see below.

Procedure: specifications->manifest specs

Given specs, a list of specifications such as "emacs@25.2" or "guile:debug", return a manifest. Specs have the format that command-line tools such as guix install and guix package understand (veja Invocando guix package).

As an example, it lets you rewrite the Git manifest that we saw earlier like this:

(specifications->manifest '("git" "git:send-email"))

Notice that we do not need to worry about use-modules, importing the right set of modules, and referring to the right variables. Instead, we directly refer to packages in the same way as on the command line, which can often be more convenient.