10.5. Poudriere

Para um contribuidor de ports, o Poudriere é uma das mais importantes e úteis ferramentas de teste e compilação. Suas principais características incluem:

Porque o Poudriere realiza a sua compilação em um ambiente de jail(8) limpo e usa características do zfs(8), ele tem várias vantagens sobre os testes tradicionais no sistema host:

Ele também é muito simples de configurar e usar, não tem dependências e será executado em qualquer versão suportada do FreeBSD. Esta seção mostra como instalar, configurar e executar o Poudriere como parte do fluxo de trabalho normal de um contribuidor de ports.

Os exemplos nesta seção mostram um layout de arquivo padrão, como padrão no FreeBSD. Substitua quaisquer alterações locais de acordo. A árvore de ports, representada por ${PORTSDIR}, está localizada em /usr/ports. Ambos ${LOCALBASE} e ${PREFIX} são /usr/local por padrão.

10.5.1. Instalando o Poudriere

O Poudriere está disponível na árvore de ports em ports-mgmt/poudriere. Ele pode ser instalado usando o pkg(8) ou a partir do ports:

# pkg install poudriere

ou

# make -C /usr/ports/ports-mgmt/poudriere install clean

Há também uma versão de trabalho em andamento do Poudriere que acabará por se tornar o próximo release. Ele está disponível em ports-mgmt/poudriere-devel. Esta versão de desenvolvimento é usada para as compilações oficiais de pacotes do FreeBSD, então é bem testada. Muitas vezes tem novos recursos interessantes. Um committer de ports desejará usar a versão de desenvolvimento porque é o que é usado na produção e possui todos os novos recursos que farão com que tudo esteja exatamente correto. Um colaborador não precisará necessariamente deles, pois as correções mais importantes são sempre incorporadas na versão release. A principal razão para o uso da versão de desenvolvimento para compilar os pacotes oficiais é porque é mais rápido, de uma forma que encurtará uma compilação completa de 18 horas para 17 horas ao usar um servidor de 32 CPUs high-end com 128GB de RAM. Essas otimizações não terão muita importância ao compilar ports em uma máquina desktop.

10.5.2. Configurando o Poudriere

O port instala um arquivo de configuração padrão, o /usr/local/etc/poudriere.conf. Cada parâmetro é documentado no arquivo de configuração em poudriere(8). Aqui está um arquivo de configuração mínimo de exemplo:

ZPOOL=tank
ZROOTFS=/poudriere
BASEFS=/poudriere
DISTFILES_CACHE=/usr/ports/distfiles
RESOLV_CONF=/etc/resolv.conf
FREEBSD_HOST=ftp://ftp.freebsd.org
SVN_HOST=svn.FreeBSD.org
ZPOOL

O nome do pool de armazenamento do ZFS que o Poudriere deve usar. Deve ser listado na saída de zpool status.

ZROOTFS

A raiz dos sistemas de arquivos gerenciados do Poudriere. Esta entrada fará com que o Poudriere crie o sistema de arquivo zfs(8) sob tank/poudriere.

BASEFS

O ponto de montagem da raiz do sistema de arquivo Poudriere. Esta entrada fará com que o Poudriere monte o tank/poudriere no /poudriere.

DISTFILES_CACHE

Define onde os distfiles são armazenados. Neste exemplo, o Poudriere e o host compartilham o diretório de armazenamento dos distfiles. Isso evita o download de tarballs que já estão presentes no sistema.

RESOLV_CONF

Utiliza o /etc/resolv.conf do host dentro do jails para a resolução de DNS. Isso é necessário para que as jails possam resolver as URLs dos distfiles durante o download. Não é necessário ao usar um proxy. Consulte o arquivo de configuração padrão para a configuração de proxy.

FREEBSD_HOST

O servidor FTP/HTTP a ser usado quando as jails são instaladas a partir de versões do FreeBSD e atualizadas com o freebsd-update(8). Escolha um servidor cuja localização esteja próxima, por exemplo, se a máquina estiver localizada na Austrália, use ftp.au.freebsd.org.

SVN_HOST

O servidor de onde as jails são instaladas e atualizadas ao usar o Subversion. Também usado para a árvore de ports quando não estiver usando o portsnap(8). Mais uma vez, escolha um local próximo. Uma lista de espelhos oficiais do Subversion podem ser encontrados na seção sobre Subversion do Handbook do FreeBSD.

10.5.3. Criando Poudriere Jails

Crie as jails de base que serão usadas pelo Poudriere para as compilações:

# poudriere jail -c -j 111Ramd64 -v 11.1-RELEASE -a amd64

Busca a versão 11.1-RELEASE para amd64 do servidor FTP dado por FREEBSD_HOST dentro do poudriere.conf, crie o sistema de arquivos com zfs em tank/poudriere/jails/111Ramd64, monta-o em /poudriere/jails/111Ramd64 e extrai os tarballs 11.1-RELEASE neste sistema de arquivos.

# poudriere jail -c -j 11i386 -v stable/11 -a i386 -m svn+https

Criado o tank/poudriere/jaulas/11i386 monte-o em /poudriere/jails/11i386, então confira a dica do Subversion branch do FreeBSD-11-STABLE a partir do SVN_HOST dentro do poudriere.conf para dentro de /poudriere/jails/11i386/usr/src, e então complete um buildworld e instale-o em /poudriere/jails/11i386.

Dica:

Se uma determinada revisão do Subversion é necessária, anexe ela à string de versão. Por exemplo:

# poudriere jail -c -j 11i386 -v stable/11@123456 -a i386 -m svn+https

Nota:

Embora seja possível compilar uma versão mais nova do FreeBSD em uma versão mais antiga, na maioria das vezes ela não irá executar. Por exemplo, se uma jail stable/11 é necessária, o host terá que rodar stable/11 também. Rodar 11.0-RELEASE não é o suficiente.

Nota:

Para criar uma jail Poudriere para o 13.0-CURRENT:

# poudriere jail -c -j 12amd64 -v head -a amd64 -m svn+https

Para executar uma jail 13.0-CURRENT no Poudriere você deve estar rodando o 13.0-CURRENT. Em geral, novos kernels podem ser compilados e executar jails mais antigas. Por exemplo, um kernel 13.0-CURRENT pode compilar e executar uma jail 11.1-STABLE no Poudriere se a opção de kernel COMPAT_FREEBSD11 tiver sido compilada (habilitada por padrão na configuração do kernel GENERIC do 13.0-CURRENT).

Cuidado:

O protocolo padrão svn funciona normalmente, mas não é muito seguro. Usar svn+https juntamente com a verificação do fingerpprint SSL do servidor remoto é aconselhável. Isso garantirá que os arquivos usados para compilar a jail sejam de uma fonte confiável.

Uma lista de jails atualmente conhecidas pelo Poudriere podem ser mostradas com poudriere jail -l:

# poudriere jail -l
JAILNAME             VERSION              ARCH    METHOD
111Ramd64             11.1-RELEASE          amd64   ftp
11i386               11.0-STABLE          i386    svn+https

10.5.4. Mantendo as Jails do Poudriere Atualizadas

Gerenciar atualizações é muito simples. O comando:

# poudriere jail -u -j JAILNAME

atualiza a jail especificada para a versão mais recente disponível. Para releases do FreeBSD, atualiza para o patchlevel mais recente com o freebsd-update(8). Para versões do FreeBSD compiladas a partir do código fonte, atualiza para a revisão mais recente na branch do Subversion.

Dica:

Para jails que empregam um método svn+*, é útil adicionar -J NumberOfParallelBuildJobs para acelerar a compilação aumentando o número de trabalhos de compilação paralelos utilizados. Por exemplo, se a máquina de compilação tiver 6 CPUs, use:

# poudriere jail -u -J 6 -j JAILNAME

10.5.5. Configurando a Árvores de Ports para Uso com o Poudriere

Existem várias maneiras de usar árvores de ports no Poudriere. A maneira mais direta é o Poudriere criar uma árvore de ports padrão para si mesmo:

# poudriere ports -c

Este comando cria o tank/poudriere/ports/default, monta-o em /poudriere/ports/default e o povoa usando o portsnap(8). Depois disso, ele é incluído na lista de árvores de ports conhecidas:

# poudriere ports -l
PORTSTREE      METHOD     PATH
default        portsnap   /poudriere/ports/default

Nota:

Note que a árvore de ports default é especial. Cada um dos comandos de compilação explicados posteriormente usará implicitamente essa árvore de ports, a menos que seja especificamente especificado de outra forma. Para usar outra árvore, adicione -p treename aos comandos.

Embora seja útil para compilações em massa regulares, ter esta árvore de ports padrão com o método portsnap(8) pode não ser a melhor maneira de lidar com modificações locais para um contribuidor de ports. Assim como na criação dos jails, é possível usar um método diferente para criar a árvore de ports. Para adicionar uma árvore de ports adicional para testar modificações locais e para o desenvolvimento de ports, é possível baixar a árvore via Subversion:

# poudriere ports -c -m svn+https -p subversive

Nota:

Os métodos http e https precisam que o devel/subversion seja compilado com a opção SERF ativada. Ela vem habilitada por padrão.

Cria tank/poudriere/ports/subversive e o monta em /poudriere/ports/subversive. Em seguida, ele é povoado usando Subversion. Finalmente, ele é adicionado à lista de árvores de ports conhecidas:

# poudriere ports -l
PORTSTREE            METHOD     PATH
default              portsnap   /poudriere/ports/default
subversive           svn+https  /poudriere/ports/subversive

Dica:

O método svn permite qualificadores extras para dizer ao Subversion exatamente como buscar os dados. Isso é explicado em poudriere(8). Por exemplo, poudriere ports -c -m svn+ssh -p subversive usa o SSH para o checkout.

10.5.6. Usando Árvores de Ports Gerenciadas Manualmente com o Poudriere

Dependendo do fluxo de trabalho, pode ser extremamente útil usar árvores de ports que são mantidas manualmente. Por exemplo, se houver uma cópia local da árvore de ports em /work/ports, aponte o Poudriere para o local:

# poudriere ports -c -F -f none -M /work/ports -p development

Isto será listado na tabela de árvores conhecidas:

# poudriere ports -l
PORTSTREE    METHOD   PATH
development  -        /work/ports

Nota:

O traço na coluna METHOD significa que o Poudriere nunca irá atualizar ou alterar esta árvore de ports. É de responsabilidade total do usuário a manutenção desta árvore, incluindo todas as modificações locais que podem ser usadas para testar novos ports e enviar patches.

10.5.7. Mantendo as Árvores de Ports do Poudriere Atualizadas

Tão simples quanto com as jails descritas anteriormente:

# poudriere ports -u -p PORTSTREE

Vai atualizar a PORTSTREE, uma árvore dada pela saída de poudriere -l, para a última revisão disponível nos servidores oficiais.

Nota:

As arvores de ports sem um método, veja Seção 10.5.6, “Usando Árvores de Ports Gerenciadas Manualmente com o Poudriere”, não podem ser atualizadas assim. Elas devem ser atualizadas manualmente pelo mantenedor de ports.

10.5.8. Testando Ports

Depois que as jails e as árvores de ports foram configuradas, o resultado das modificações de um colaborador na árvore de ports pode ser testado.

Por exemplo, modificações locais no port www/firefox localizado em /work/ports/www/firefox pode ser testado na jail 11.1-RELEASE criada anteriormente:

# poudriere testport -j 111Ramd64 -p development -o www/firefox

Isso irá compilar todas as dependências do firefox. Se uma dependência foi criada anteriormente e ainda está atualizada, o pacote pré-criado é instalado. Se uma dependência não tiver um pacote atualizado, ela será compilada com opções padrão em uma jail. Depois disso o firefox será compilado.

A compilação completa de cada port será registrada em /poudriere/data/logs/bulk/111Ri386-development/build-time/logs.

O nome do diretório 111Ri386-development é derivado dos argumentos para -j e -p, respectivamente. Por conveniência, um link simbólico /poudriere/data/logs/bulk/111Ri386-development/latest também é mantido. O link aponta para o mais recente diretório build-time. Neste diretório também se encontra um index.html para que possa ser possível observar o processo de compilação com um navegador web.

Por padrão, o Poudriere limpa as jails e deixa os arquivos de log nos diretórios mencionados acima. Para facilitar a investigação, as jails podem ser mantidas em execução após a compilação, adicionando a opção -i ao testport:

# poudriere testport -j 111Ramd64 -p development -i -o www/firefox

Depois que a compilação é concluída, e independentemente de ter sido bem-sucedida, um shell é fornecido dentro da jail. O shell é usado para investigações adicionais. O Poudriere pode ser dito para deixar a jail em execução após a conclusão da compilação com -i. O Poudriere mostrará o comando para ser executado quando a jail não for mais necessária. E então é possível fazer um jexec(8) para dentro dele:

# poudriere testport -j 111Ramd64 -p development -I -o www/firefox
[...]
====>> Installing local Pkg repository to /usr/local/etc/pkg/repos
====>> Leaving jail 111Ramd64-development-n running, mounted at /poudriere/data/.m/111Ramd64-development/ref for interactive run testing
====>> To enter jail: jexec 111Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root
====>> To stop jail: poudriere jail -k -j 111Ramd64 -p development
# jexec 111Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root
# [do some stuff in the jail]
# exit
# poudriere jail -k -j 111Ramd64 -p development
====>> Umounting file systems

Uma parte integral da infraestrutura de compilação de ports do FreeBSD é a capacidade de ajustar os ports as preferências pessoais por meio de opções. Elas podem ser testadas com o Poudriere também. Adicionando a opção -c:

# poudriere testport -c -o www/firefox

Apresenta o diálogo de configuração do port antes que o port seja compilado. Os ports informados após o -o no formato category/portname usará as opções especificadas, todas as dependências usarão as opções padrão. O teste de ports dependentes com opções não padrão pode ser realizado usando conjuntos, consulte Seção 10.5.9, “Usando Conjuntos”.

Dica:

Ao testar ports nos quais o pkg-plist é alterado durante a compilação, dependendo das opções selecionadas, é recomendável executar um teste com todas as opções selecionadas e um com todas as opções desmarcadas.

10.5.9. Usando Conjuntos

Para todas as ações envolvendo builds, um então chamado conjunto pode ser especificado usando -z setname. Um conjunto se refere a uma compilação totalmente independente. Isso permite, por exemplo, o uso de testport com opções não padrão para os ports dependentes.

Para usar sets, o Poudriere espera uma estrutura de diretórios existente semelhante a PORT_DBDIR, o padrão é /var/db/ports no seu diretório de configuração. Este diretório é então nullfs(5)-montado nas jails onde os ports e suas dependências são compilados. Normalmente, um ponto de partida adequado pode ser obtido copiando de forma recursiva o PORT_DBDIR para /usr/local/etc/poudriere.d/jailname-portname-setname-options. Isso é descrito em detalhes em poudriere(8). Por exemplo, para testar o www/firefox em um conjunto específico chamado devset, adicione o parâmetro -z devset ao comando testport:

# poudriere testport -j 111Ramd64 -p development -z devset -o www/firefox

Isso irá procurar pela existência desses diretórios nesta ordem:

  • /usr/local/etc/poudriere.d/111Ramd64-development-devset-options

  • /usr/local/etc/poudriere.d/111Ramd64-devset-options

  • /usr/local/etc/poudriere.d/111Ramd64-development-options

  • /usr/local/etc/poudriere.d/devset-options

  • /usr/local/etc/poudriere.d/development-options

  • /usr/local/etc/poudriere.d/111Ramd64-options

  • /usr/local/etc/poudriere.d/options

Desta lista, o Poudriere nullfs(5)-monta a primeira árvore existente de diretório para o diretório /var/db/ports das jails de compilação. Portanto, todas as opções personalizadas são usadas para todos os ports durante essa execução do testport.

Depois que a estrutura de diretório para um conjunto é fornecida, as opções para um port específico podem ser alteradas. Por exemplo:

# poudriere options -c www/firefox -z devset

O diálogo de configuração para o www/firefox é mostrado e as opções podem ser editadas. As opções selecionadas são salvas no set devset.

Nota:

Poudriere é muito flexível na configuração das opções. Elas podem ser configuradas para jails específicas, árvores de ports e para vários ports por um comando. Veja poudriere(8) para detalhes.

10.5.10. Fornecendo um Arquivo make.conf Customizado

Semelhante ao uso de conjuntos (sets), o Poudriere também usará um make.conf personalizado se for fornecido. Nenhum argumento de linha de comando especial é necessário. Em vez disso, o Poudriere procura por arquivos existentes que correspondam a um esquema de nomes derivado da linha de comando. Por exemplo:

# poudriere testport -j 111Ramd64 -p development -z devset -o www/firefox

faz o Poudriere verificar a existência desses arquivos nesta ordem:

  • /usr/local/etc/poudriere.d/make.conf

  • /usr/local/etc/poudriere.d/devset-make.conf

  • /usr/local/etc/poudriere.d/development-make.conf

  • /usr/local/etc/poudriere.d/111Ramd64-make.conf

  • /usr/local/etc/poudriere.d/111Ramd64-development-make.conf

  • /usr/local/etc/poudriere.d/111Ramd64-devset-make.conf

  • /usr/local/etc/poudriere.d/111Ramd64-development-devset-make.conf

Ao contrário dos conjuntos, todos os arquivos encontrados serão anexados, naquela ordem, em um make.conf dentro das jails de compilação. Assim, é possível ter variáveis ​​gerais, destinadas a afetar todas as compilações /usr/local/etc/poudriere.d/make.conf. Variáveis ​​especiais, destinadas a afetar apenas determinadas jails ou conjuntos, podem ser setadas em arquivos especiais como make.conf, assim como /usr/local/etc/poudriere.d/111Ramd64-development-devset-make.conf.

Exemplo 10.1. Usando make.conf para Alterar o Perl Padrão

Para compilar um conjunto com uma versão não padrão do Perl, por exemplo, 5.20, usando um conjunto chamado perl5-20, crie um perl5-20-make.conf com esta entrada:

DEFAULT_VERSIONS+= perl=5.20

Nota:

Observe o uso de += de modo que, se a variável já estiver definida no make.conf padrão, seu conteúdo não será sobrescrito.


10.5.11. Remoção de Distfiles Não Mais Necessários

Poudriere vem com um mecanismo embutido para remover distfiles desatualizados que não são mais usados ​​por qualquer port de uma determinada árvore. O comando

# poudriere distclean -p portstree

irá escanear a pasta distfiles, DISTFILES_CACHE dentro do poudriere.conf, contra a árvore de ports dada pelo argumento -p portstree e solicitar a remoção desses distfiles. Para pular o prompt e remover incondicionalmente todos os arquivos não utilizados, o argumento -y pode ser adicionado:

# poudriere distclean -p portstree -y

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.