Sintaxe de arquivo de coleção de módulos

JHBuild usa arquivos XML para descrever as dependências entre módulo. Um esquema de RELAX-NG e uma definição de tipo de documento são incluídos ao JHBuild no diretório modulesets/. O esquema de RELAX-NG pode ser usado para editar arquivos de coleção de módulos usando nxml-mode no Emacs.

O elemento primário em um arquivo da coleção de módulos é o elemento moduleset. Nenhum espaço de nomes XML é usado. Os elementos embaixo deste vem em três tipos: fontes de módulos, declarações de inclusões (include) e definições de módulo.

O conteúdo no arquivo de coleção de módulos pode ser incluído condicionalmente usando a tag <if> para cobrir o conteúdo condicional. Ele é atualmente possível apenas predicar a inclusão se uma opção de condição em particular estiver definida ou não, usando <if condition-set='cond'> ou <se condition-unset='cond'>. Condições são definidas por padrão com base no SO, mas pode ser influenciado por meio da variável conditions em jhbuildrc ou o argumento de linha de comando --conditions=.

7.1. Fontes de módulo

Em vez de listar a localidade completa de cada módulo, um número de "fontes de módulo" está listado na coleção de módulos e, então, referenciada pelo nome nas definições de módulo. Além de reduzir a quantidade de informação redundante na coleção de módulos, isso deixa mais fácil para o usuário especificar uma fonte alternativa para aqueles módulos (para CVS e Subversion, é comum para desenvolvedores e usuários usarem diferentes métodos de acesso a repositório).

O elemento repository é usado para descrever todos os tipos de repositórios. O elemento branch é usado dentro da definição do módulo para especificar configurações adicionais.

<repository name="nome"
  type="tipo"
  [ default="padrão" ]
  [ password="senha" ]
  [ cvsroot="raiz-cvs" ]
  [ archive="arquivo" ]
  [ href="href" ]
  [ server="servidor" ]
  [ database="banco de dados" ]
  [ defbranch="ramo" ]
  [ trunk-template="modelo-trunk" ]
  [ branches-template="modelo-branches" ]
  [ tags-template="modelo-tags" ]
  [ developer-href-example="exemplo-href-desenvolvedor" ] />

O atributo name é um identificador único do repositório.

O atributo default especifica este repositório no fonte padrão desta coleção de módulos.

O atributo type especifica o tipo de repositório. Ele pode ser: bzr, cvs, darcs, fossil, git, hg, mnt, svn ou tarball. Outros atributos dependem do type, além do branch usado dentro das definições de módulo. Aqueles descritos embaixo das subseções de tipos de repositório.

O atributo developer-href-example é usado para especificar o formato da URL do repositório usado por desenvolvedores. Serve apenas como informação.

O elemento branch é usado dentro das definições de módulo.

<branch
  [ repo="repositório" ]
  [ module="nome-do-módulo" ]
  [ checkoutdir="diretório-de-checkout" ]
  [ revision="revisão" ]
  [ tag="tag" ]
  [ update-new-dirs="atualiza-direstpiruis-novos" ]
  [ override-checkoutdir="sobrescreve-checkoutdir" ]
  [ subdir="subdiretório" ]
  [ branch="ramo" ]
  [ version="versão" ]
  [ size="tamanho" ]
  [ source-subdir="subdiretório-fonte" ]
  [ hash="hash" ]/>

Todos os atributos possuem padrões sensíveis e dependem das definições do módulo e repositório. Atributos comuns são descritos aqui.

O atributo repo é usado para especificar um nome de repositório não padronizado.

O atributo module é usado para especificar um nome de módulo para baixar do repositório. Padrão é a identificação (id) do módulo.

O atributo checkoutdir é usado para especificar o nome do diretório no qual será realizado checkout. Padrão é a identificação (id) do módulo.

Outros atributos são descritos abaixo.

7.1.1. Bazaar

Este tipo de repositório é usado para definir um repositório Bazaar. É recomendado ter Bazaar 1.16 ou outra versão mais nova.

<repository type="bzr" name="launchpad.net"
      href="lp:"/>
        

São atributos adicionais: trunk-template (padrão é "%(module)s") e branches-template (padrão é "%(module)s/%(branch)s"). Estes atributos são usados para especificar modelos para construção de URL. Um elemento branch nas definições do módulo pode especificar atributos branch e user. Estes valores serão substituídos nos modelos. Se um deles for definido, branches-template é usado. Do contrário, trunk-template é usado. Desta forma, você pode sobrescrever um repositório para compilar módulos do seu ramo pessoal ou compilar muitos módulos de um repositório com uma disposição não padronizada.

Um elemento branch adicional aceita um atributo revspec para ancorar em uma revisão em particular. Qualquer bzr revspec válido é aceito. Por exemplo, use date:yesterday, -5, tag:0.1 para obter a primeira revisão a partir de ontem, 5 commits atrás da tip ou tag "0.1". Veja bzr help revisionspec para todos os valores possíveis.

Por exemplo, um repositório com atributos template definidos:

<repository type="bzr" name="launchpad.net"
      href="lp:"
      trunk-template="~bzr-pqm/%(module)s/bzr.dev"
      branches-template="~bzr-pqm/%(module)s/%(branch)s"/>
        

Exemplo de elementos branch para o repositório acima:

<branch repo="launchpad.net"
      module="bzr"
      checkoutdir="bzr-next"/>
        
<branch repo="launchpad.net"
      module="bzr"
      branch="2.2"
      checkoutdir="bzr-beta"/>
        

7.1.2. CVS

Este tipo de repositório é usado para definir um repositório CVS.

O atributo password é usado para especificar a senha do repositório.

O atributo cvsroot é usado para especificar a raiz do repositório.

<repository type="cvs" name="tango.freedesktop.org"
    cvsroot=":pserver:anoncvs@anoncvs.freedesktop.org:/cvs/tango"
    password=""/>
        

São atributos adicionais: revision, update-new-dirs e override-checkoutdir.

7.1.3. Darcs

Este tipo de repositório é usado para definir um repositório Darcs.

<repository type="darcs" name="telepathy.freedesktop.org"
      href="http://projects.collabora.co.uk/darcs/telepathy/"/>

7.1.4. Git

Este tipo de repositório é usado para definir um repositório Git.

<repository type="git" name="git.freedesktop.org"
    href="git://anongit.freedesktop.org/git/"/>
        

Ele permite os seguintes atributos no elemento branch:

O atributo revision é usado para especificar um ramo local ou remoto que pode ser selecionado na fase de atualização. Padrão é "master". É possível sobrescrever este atributo com a variável de configuração branches. A seleção será realizada apenas se o ramo atual estiver seguindo um ramo remoto, para não atrapalhar o seu próprio trabalho.

O atributo tag é usado para especificar uma revisão para baixar incondicionalmente na fase de atualização. Ele substitui o atributo revision.

<branch repo="git.freedesktop.org" module="swfdec/swfdec"
        checkoutdir="swfdec"
        revision="ramo-local-ou-remoto"
        tag="tag"/>
        

7.1.5. Mercurial

Este tipo de repositório é usado para definir um repositório Mercurial.

<repository type="hg" name="hg.gtk-vnc"
    href="http://gtk-vnc.codemonkey.ws/hg/" />
<branch repo="hg.gtk-vnc" module="outgoing.hg" checkoutdir="gtk-vnc"/>

7.1.6. Monotone

Este tipo de repositório é usado para definir um repositório Monotone.

O atributo server é usado para especificar o servidor do repositório.

O atributo database é usado para especificar o banco de dados a ser usado pelo repositório.

O atributo defbranch é usado para especificar o ramo do repositório a ser usado.

<repository type="mtn" name="pidgin.im"
    server="pidgin.im" database="pidgin.im.mtn"
    defbranch="im.pidgin.pidgin"/>

7.1.7. Subversion

Este tipo de repositório é usado para definir um repositório.

<repository type="svn" name="svn.gnome.org" default="yes"
    href="http://svn.gnome.org/svn/"/>
        

Ele permite uma revision no elemento branch. Este atributo define o ramo para fazer checkout ou, se for um número, uma revisão específica para fazer checkout.

<branch revision="gnome-2-20"/>
        

É possível especificar uma disposição svn diferente usando trunk-template (padrão é "%(module)s/trunk"), branches-template (padrão é "%(module)s/branches/%(branch)s") and tags-template (padrão é "%(module)s/tags/%(tag)s")

7.1.8. Sistema

Este tipo de repositório é usado para definir um repositório de sistema falso. Um repositório de sistema é necessário para criar systemmodules.

<repository type="system" name="sistema"/>

7.1.9. Tarballs

Este tipo de repositório é usado para definir um respositório de tarball.

<repository type="tarball" name="dbus/dbus-python"
    href="http://dbus.freedesktop.org/releases/dbus-python/"/>

Ele permite os seguintes atributos no elemento branch:

O atributo module especifica o arquivo para baixar e compilar, o atributo version especifica a versão do módulo.

Os elementos size e hash, assim como o obsoleto md5sum, são opcionais. Se esses atributos estiverem presentes, eles são usados para verificar se o pacote de fontes foi baixado corretamente.

Qualquer número de elementos de patch pode ser acrescentado dentro do elemento branch. Esses patches são aplicados, em ordem, na árvore de fontes após o desempacotamento. O atributo file fornece o nome do arquivo de patch e o atributo strip informa quantos níveis devem ser suprimidos ao aplicar o patch.

Para coleções de módulos disponibilizados com o JHBuild, os arquivos de patch são buscados no diretório jhbuild/patches/; para coleções de módulos relacionados por URI, os arquivos de patch são obtidos no mesmo diretório do arquivo de coleção de módulos ou em seu subdiretório patches/. Também é possível que o atributo file especifique uma URI, caso em que o patch será baixado desta localização.

<branch module="dbus-python-0.80.2.tar.gz" version="0.80.2"
    repo="dbus/dbus-python"
    hash="md5:2807bc85215c995bd595e01edd9d2077" size="453499">
  <patch file="dbus-glib-build.patch" strip="1" />
</branch>

Um elemento branch de tarball também pode conter elementos quilt, que especificam branch aninhados para importar.

7.2. Incluindo outras coleções de módulos

JHBuild permite que uma coleção de módulos inclua os conteúdos de outra por referência usando o elemento include.

<include href="uri"/>

O href é uma referência de URI à coleção de módulos a serem incluídos, relativo ao arquivo contendo o elemento include.

Apenas definições de módulos são importadas da coleção de módulos referenciada - fontes de módulos não são. Múltiplos níveis de inclusões são permitidas, mas loops de inclusão não são (não código algum para lidar com loops no presente momento).

7.3. Definições de módulo

Há vários tipos de definições de módulos que podem ser usados em um arquivo de coleção de módulos, e a lista pode ser facilmente estendida. Apenas aqueles mais comuns que são mencionados aqui.

As definições são basicamente todas compostas de um elemento branch descrevendo como obter o módulo e elementos dependencies, suggests e after para declarar as dependências do módulo.

Quaisquer módulos listados no elemento dependencies serão adicionados à lista de módulos de jhbuild build, se eles já não estiverem inclusos, e confirmados de que módulos dependentes serão compilados primeiro.

Após gerar a lista de módulos, os módulos listados no elemento suggests serão usados para posterior organização da lista de módulos (apesar de que ela não vai obter nenhum módulos adicionais). Isso não foi destinado para casos em que um módulo possui uma dependência opcional em outro módulo.

7.3.1. autotools

O elemento autotools é usado para definir um módulo que é compilado usando o sistema de compilação do GNU Autotools.

<autotools id="id"
	      [ autogenargs="argumentos-autogen" ]
	      [ makeargs="argumentos-make" ]
	      [ makeinstallargs="argumentos-make-install" ]
	      [ autogen-sh="autogen-sh" ]
	      [ makefile="makefile" ]
	      [ skip-autogen="ignora-autogen" ]
	      [ skip-install="ignora-install" ]
	      [ autogen-template="modelo-de-autogen" ]
	      [ check-target="verifica-alvo" ]
	      [ supports-non-srcdir-builds="suporte-a-compilações-fora-do-srcdir" ]>

  <branch [ ... ] >
    [...]
  </branch>

  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <after>
    <dep package="nome-do-módulo"/>
    ...
  </after>

</autotools>

Os atributos autogenargs, makeargs e makeinstallargs são usados para especificar argumentos adicionais a serem passados para o autogen.sh, make e make install, respectivamente.

O atributo autogen-sh especifica o nome do script autogen.sh a ser executado. O valor autoreconf pode ser usado se seu módulo não possuir um script autogen.sh equivalente. Nesse caso, JHBuild vai executar autoreconf -fi, seguido pelo configure apropriado. skip-autogen escolhe executar ou não o autogen.sh, sendo ele um boolean com um valor never extra para informar o JHBuild para nunca pular a execução do autogen.sh. skip-install é um atributo boolean especificando pular ou não o comando make install no módulo. makefile especifica o nome de arquivo do makefile a ser usado.

O atributo supports-non-srcdir-builds é usado para marcar módulos que não pode ser compilados do zero usando um diretório de fontes separados.

O atributo autogen-template pode ser usado se você precisar um controle melhor da linha de comando do autogen. Ele é uma string no formato python, que será substituída pelas seguintes variáveis: srcdir, autogen-sh, prefix, libdir e autogenargs. Por exemplo, aqui está o autogen-template padrão:

%(srcdir)s/%(autogen-sh)s --prefix %(prefix)s --libdir %(libdir)s %(autogenargs)s

O atributo check-target deve ser especificado (com valor sendo falso) para módulos que não possuem um alvo para make check.

7.3.2. cmake

O elemento cmake é usado para definir um módulo que é compilado usando o sistema de compilação do CMake.

<cmake id="nome-do-módulo">
  <branch [ ... ] >
    [...]
  </branch>

  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <after>
    <dep package="nome-do-módulo"/>
    ...
  </after>
</cmake>

7.3.3. distutils

O elemento distutils é usado para definir um módulo que é compilado usando distutils do python.

<distutils id="nome-do-módulo"
            [ supports-non-srcdir-builds="sim|no" ]>
  <branch [ ... ] >
    [...]
  </branch>

  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <after>
    <dep package="nome-do-módulo"/>
    ...
  </after>
</distutils>

7.3.4. linux

O elemento linux define um módulo usado para compilar um kernel do linux. Além disso, uma configuração de kernel separada pode ser escolhida usando o subelemento kconfig.

<linux id="id"
	  [ makeargs="argumentos-make" ]>

  <branch [ ... ] >
    [...]
  </branch>

  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <after>
    <dep package="nome-do-módulo"/>
    ...
  </after>

  <kconfig [ repo="repositório" ]
	    version="versão"
	    [ module="módulo" ]
	    [ config="configuração" ] />

</linux>

7.3.5. perl

O elemento perl é usado para compilar módulos de perl.

O atributo makeargs é usado para especificar argumentos adicionais a ser passados para o make.

<perl id="nome-do-módulo"
	 [ makeargs="argumentos-make" ]>

  <branch [ ... ] >
    [...]
  </branch>

  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <after>
    <dep package="nome-do-módulo"/>
    ...
  </after>

</perl>

7.3.6. systemmodule

O elemento systemmodule é usado para especificar os módulos que deve ser fornecidos pelo sistema. O módulo deveria ser instalado pelo sistema de gerenciamento de pacotes da sua distribuição.

<systemmodule id="nome-do-módulo">
  <pkg-config>pkg-config.pc</pkg-config>

  <branch repo="sistema" version="versão" />
</systemmodule>

Se o módulo do sistema não fornecer um arquivo de pkg-config, a tag systemdependencies pode ser usada para identificar as dependências. Há suporte a dois valores no atributo type da tag dep:

  1. Valor path. O caminho é pesquisado por um nome de programa correspondente.

  2. Valor c_include. O caminho de include C é pesquisado pelo nome de header correspondente. name pode incluir um subdiretório. O caminho de pesquisa de includes C podem ser modificados pela configuração CPPFLAGS dentro das variáveis de configuração cflags ou module_autogenargs.

<systemmodule id="nome-do-módulo">
  <branch repo="sistema" version="versão" />
  <systemdependencies>
    <dep type="path" name="nome-executável" />
  </systemdependencies>
</systemmodule>

<systemmodule id="nome-do-módulo">
  <branch repo="sistema" version="versão" />
  <systemdependencies>
    <dep type="c_include" name="nome-do-header" />
  </systemdependencies>
</systemmodule>

7.3.7. waf

O elemento waf é usado para definir um módulo que é compilado usando o sistema de compilação do Waf.

O atributo waf-command é usado para especificar o script do comando waf a ser usado. Padrão é waf.

O atributo python-command é usado para especificar o executável do Python a ser usado. Padrão é python. Isso é útil para compilar módulos com a versão 3 do Python.

<waf id="nome-do-módulo">
	 [ python-command="comando-python" ]
	 [ waf-command="comando-waf" ]>
  <branch [ ... ] >
    [...]
  </branch>

  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <after>
    <dep package="nome-do-módulo"/>
    ...
  </after>
</waf>

7.3.8. testmodule

O elemento testmodule é usado para criar um módulo que executa uma suíte de testes usando LDTP ou Dogtail.

<testmodule id="id"
	       type="tipo">

  <branch [ ... ] >
    [...]
  </branch>

  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <after>
    <dep package="nome-do-módulo"/>
    ...
  </after>

  <testedmodules>
    <tested package="pacote" />
  </testedmodules>

</testmodule>

O atributo type fornece um tipo de testes para ser executado no módulo. "dogtail" usa python para chamar todos os arquivos .py. "ldtp" chama 'ldtprunner run.xml'.

A menos que a opção de configuração noxvfb esteja definida, um servidor Xvfb começa a executar os testes.

7.3.9. metamodule

O elemento metamodule define um módulo que, na verdade, nada faz. O único propósito de um módulo deste tipo é suas dependências.

Por exemplo, meta-gnome-desktop depende de todos os componentes chave do ambiente GNOME e, portanto, ao dizer ao JHBuild para instalá-lo, na verdade instala o ambiente inteiro.

<metamodule id="nome-do-módulo">
  <dependencies>
    <dep package="nome-do-módulo"/>
    ...
  </dependencies>
  <suggests>
    <dep package="nome-do-módulo"/>
    ...
  </suggests>
</metamodule>

O atributo id fornece o nome do módulo. Os elementos filhos são lidados como sendo de autotools.

7.4. Elementos obsoletos

7.4.1. Fontes de módulo

7.4.1.1. cvsroot

O elemento cvsroot está agora obsoleto - o elemento repository deveria ser usado em seu lugar.

O elemento cvsroot é usado para descrever um repositório CVS.

  <cvsroot name="nome-raiz"
           [ default="yes|no" ]
           root="cvsroot-anônimo"
           password="senha-anônimo"/>

O atributo name deveria ser um identificador único do repositório CVS.

O atributo default informa se este é ou não a fonte padrão do módulo deste arquivo de coleção de módulos.

O atributo root lista a raiz CVS usada para um acesso anônimo a este repositório e o atributo password informa a senha usada para um acesso anônimo.

7.4.1.2. svnroot

O elemento svnroot está agora obsoleto - o elemento repository deveria ser usado em seu lugar.

O elemento svnroot é usado para descrever um repositório Subversion.

  <svnroot name="nome-raiz"
           [ default="yes|no" ]
           href="svnroot-anônimo"/>

O atributo name deveria ser um identificador único do repositório Subversion.

O atributo default informa se este é ou não a fonte padrão do módulo deste arquivo de coleção de módulos.

O atributo href lista a URL base do repositório. Provavelmente será uma URL de http, https ou svn.

7.4.2. Tipos de módulos obsoletos

Esta seção descreve elementos obsoletos. Eles podem estar sendo usados em coleções de módulos existentes, mas é aconselhado não mais usá-los.

7.4.2.1. tarball

Este elemento obsoleto é apenas uma interface dos tipos de módulo autotools e de repositório tarball.

O elemento tarball é usado para definir um módulo que está para ser compilado a partir de um tarball.

  <tarball id="nome-do-módulo"
              [ version="versão" ]
              [ checkourdir="diretório-checkout" ]
              [ autogenargs="argumentos-autogen" ]
              [ makeargs="argumentos-make" ]
              [ autogen-sh="autogen-sh" ]
              [ supports-non-srcdir-builds="yes|no" ]>
    <source href="url-fonte"
            [ size="tamanho-fonte" ]
            [ hash="algoritmo-fonte:hash-fonte" ]
            [ md5sum="md5sum-fonte" ]/>
    <patches>
      <patch file="nome-de-arquivo" strip="nível"/>
      ...
    </patches>
    <dependencies>
      <dep package="nome-do-módulo"/>
      ...
    </dependencies>
    <suggests>
      <dep package="nome-do-módulo"/>
      ...
    </suggests>
  </tarball>

Os atributos id e version são usados para identificar o módulo.

O elemento source especifica o arquivo para baixar e compilar. O atributo href é obrigatório, enquanto os atributos size e hash, assim como o obsoleto md5sum, são opcionais. Se esses últimos dois atributos estiverem presentes, eles são usados para verificar se o pacote de fontes foi baixado corretamente.

O elemento patches é usado para especificar um ou mais patches a serem aplicados na árvore de fontes para aplicar na árvore de fontes após descompactar, o atributo file fornece o nome de arquivo do patch e o atributo strip informa quantos níveis devem ser suprimidos ao aplicar o patch.

Para coleções de módulos disponibilizados com o JHBuild, os arquivos de patch são buscados no diretório jhbuild/patches/; para coleções de módulos relacionados por URI, os arquivos de patch são obtidos no mesmo diretório do arquivo de coleção de módulos ou em seu subdiretório patches/. Também é possível que o atributo file especifique uma URI, caso em que o patch será baixado desta localização.

Os outros atributos e os elementos dependencies, suggests e after são processados como sendo de autotools.