Procedimentos para Construção de Pacotes

Com o objetivo de disponibilizar binários pré-compilados de aplicações de terceiros para o FreeBSD, a Coleção de Ports é regularmente compilada em um dos “Clusters de Compilação de Pacotes”. Atualmente o principal cluster em uso é o http://pointyhat.FreeBSD.org.

Este artigo documenta os trabalhos internos do cluster

Os clientes i386™ localizados conjuntamente com o pointyhat, efetuam o boot via rede a partir dele (nós conectados); todos os outros clientes (nós desconectados) ou são auto-hospedados ou efetuam boot via rede a partir de outro host pxe. Em todos os casos eles se auto configuram durante o boot preparando-se para compilar pacotes.

O cluster principal copia, através do rsync, os dados necessários (a árvore de ports e dos fontes, bindist tarballs, scripts, etc.) para os nós desconectados durante a fase de configuração dos nós. Em seguida, o diretório portbuild desconectado é montado como nullfs para compilações sob chroot.

O usuário ports-${arch} pode acessar os nós clientes através do ssh(1) para monitorá-los. Use o sudo e verifique o portbuild.hostname.conf para o usuário e detalhes do acesso.

O script scripts/allgohans pode ser usado para executar um comando em todos os clientes ${arch}.

O script scripts/checkmachines é usado para monitorar a carga em todos os nós do cluster de compilação, e agendar quais nós compilarão quais ports. Este script não é muito robusto e tem uma tendência a morrer. É melhor iniciar este script no nó principal (por exemplo, pointyhat) depois do boot usando um loop com while(1).

A compilação de pacotes é realizada em um ambiente chroot, configurado pelo script portbuild usando o arquivo ${arch}/${branch}/builds/${buildid}/bindist.tar.

O seguinte comando faz o build world a partir da árvore de diretórios em ${arch}/${branch}/builds/${buildid}/src/ e o instala em ${worlddir}. A árvore de diretórios será atualizada primeiro, a menos que a opção -nocvs seja especificada.

/var/portbuild# scripts/makeworld ${arch} ${branch} ${buildid} [-nocvs]

O arquivo bindist.tar é criado a partir do world, instalado previamente, pelo script mkbindist. Este deve ser executado como root com o seguinte comando:

/var/portbuild# scripts/mkbindist ${arch} ${branch} ${buildid}

Os tarballs de cada máquina estão localizados em ${arch}/clients.

O arquivo bindist.tar é extraído para cada cliente durante a inicialização dos mesmos, e no início de cada passagem do script dopackages.

(O trecho a seguir aplica-se apenas ao novo código base.)

Você pode customizar sua compilação providenciando versões locais do make.conf e/ou src.conf, localizados em ${arch}/${branch}/builds/${buildid}/make.conf.server e ${arch}/${branch}/builds/${buildid}/src.conf.server, respectivamente. Estes serão usados, em vez dos arquivos padrões que estão no lado do servidor.

Da mesma forma, se você também quiser afetar o make.conf no lado do cliente, você pode usar o ${arch}/${branch}/builds/${buildid}/make.conf.client.

RUBY_DEFAULT_VER= 1.9

.if !defined(CC) || ${CC} == "cc"
CC=clang
.endif
.if !defined(CXX) || ${CXX} == "c++"
CXX=clang++
.endif
.if !defined(CPP) || ${CPP} == "cpp"
CPP=clang-cpp
.endif
# Don't die on warnings
NO_WERROR=
WERROR=

WITH_PKGNG=yes
PKG_BIN=/usr/local/sbin/pkg

WITH_PKGNG=yes

WITH_BSD_SORT=yes

Várias compilações separadas para cada arquitetura - a combinação de branchs é suportada. Todos os dados privados para uma compilação (árvore de ports, árvore do src, pacotes, distfiles, arquivos de log, bindist, Makefile, etc) estão localizados sob ${arch}/${branch}/builds/${buildid}. Alternativamente, a última compilação pode ser referenciada sob o buildid latest, e a anterior a esta é chamada previous.

Novas compilações são clonadas a partir da latest, o que é rápido, uma vez que ele usa ZFS.

dopackages.7 ${arch} ${buildid} [-options]

dopackages.wrapper ${arch} ${branch} ${buildid} [-options]

don't know how to make dns-all(continuing)

Uma compilação completa, sem qualquer opção -no que desabilite as opções padrões, executa as seguintes operações na ordem especificada:

[*] O status destes passos pode ser encontrado em ${arch}/${branch}/build.log, bem como no stderr do tty onde o comando dopackages está rodando.

[+] Se qualquer destes passos falhar, a compilação será encerrada.

[++] O status destes passos pode ser encontrado em ${arch}/${branch}/make (antigo código base) ou ${arch}/${branch}/journal (novo código base). Ports individuais irão escrever seus logs de compilação em ${arch}/${branch}/logs e os seus logs de erros em ${arch}/${branch}/errors.

Anteriormente, a árvore docs também era verificada, no entanto, isso se mostrou desnecessário.

Existem vários casos onde você precisará limpar manualmente uma compilação:

% /var/portbuild/scripts/build cleanup i386 8-exp 20080714120411 -full

ssh -l root gohan24 df

allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports"
allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/src"

umount: pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports: statfs: No such file or directory
umount: pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports: unknown file system
umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
/x/tmp/8-exp/chroot/53837/compat/linux/proc: not a file system root directory

Você pode usar o comando qclient para monitorar o status dos nós de compilação, e para listar as tarefas de compilação agendadas para execução:

python path/qmanager/qclient jobs

python path/qmanager/qclient status

O comando scripts/stats ${branch} mostra o número de pacotes cuja compilação já finalizou.

A execução de um cat /var/portbuild/*/loads/* irá mostrar o load nos clientes e o número de compilações simultâneas em andamento. Os arquivos que foram atualizados recentemente correspondem aos clientes que estão online; os demais arquivos são dos clientes que estão offline.

Executar tail -f ${arch}/${branch}/build.log irá mostrar o progresso geral da compilação.

Se a compilação do port falhar, e o motivo não ficar imediatamente óbvio a partir da análise do log, você pode preservar o WRKDIR para uma análise mais aprofundada. Para fazer isso, crie um arquivo vazio chamado .keep no diretório do port, isso vai arquivar, comprimir, e copiar o WRKDIR para ${arch}/${branch}/wrkdirs.

Se você verificar que o sistema está compilando o mesmo pacote de forma ciclica, repetindo o processo indefinidamente, você pode ser capaz de corrigir o problema reconstruindo manualmente o pacote ofensor.

Se todas as compilações iniciam reclamando de que não pode carregar os pacotes dos quais ela depende, verifique se o httpd ainda está rodando, e o i reinicie se não estiver.

Mantenha o olho na saída do df(1). Se o sistema de arquivos do /var/portbuild ficar cheio, coisas ruins acontecem.

O status de todas as compilações é gerado duas vezes por hora e postado em http://pointyhat.FreeBSD.org/errorlogs/packagestats.html. Para cada buildenv é apresentado o seguinte:

A maneira mais fácil de rastrear falhas na compilação é receber os logs enviados por e-mail e organizá-los em uma pasta, assim você pode manter uma lista com as falhas atuais e detectar facilmente as novas. Para fazer isto, adicione um endereço de e-mail ao ${branch}/portbuild.conf. Você pode encaminhar facilmente os novos erros para os mantenedores.

Quando um port passa a não compilar corretamente durante varios ciclos de compilação seguidos, é hora de marcá-lo como quebrado (BROKEN). Recomenda-se notificar os mantenedores durante duas semanas, antes de fazê-lo.

Ao compilar pacotes para uma versão específica do FreeBSD, pode ser necessário atualizar manualmente as árvores do ports e do src para a tag da versão desejada e usar as opções -nocvs e -noportscvs.

Para compilar conjuntos de pacotes que serão usados em um CD-ROM, use a opção -cdrom para o comando dopackages.

Se não houver espaço em disco disponível no cluster, use -nodistfiles para que os distfiles não sejam baixados.

Após completar a compilação inicial, reinicie a compilação com -restart -fetch-original para baixar os distfiles atualizados. Então, uma vez que a compilação tiver sido pós-processada, faça um inventário da lista de arquivos baixados:

% cd ${arch}/${branch}
% find distfiles > distfiles-${release}

Este arquivo de inventário normalmente fica localizado em i386/${branch} no nó principal do cluster.

Isto é útil para ajudar na limpeza periódica dos distfiles do ftp-master. Quando o espaço se torna escasso, os distfiles das versões recentes podem ser mantidos, enquanto outros podem ser jogados fora.

Uma vez que o upload dos distfiles tenha sido feito (veja abaixo), o conjunto de pacotes da versão final deve ser criado. Para se assegurar, execute manualmente o script ${arch}/${branch}/cdrom.sh para certificar-se de que todos os pacotes com distribuição restrita via CD-ROM e todos os distfiles foram removidos. Então, copie o diretório ${arch}/${branch}/packages para ${arch}/${branch}/packages-${release}. Uma vez que os pacotes tenham sido movidos com segurança, contate o Time de engenharia de Lançamento <re@FreeBSD.org> e informe-os da localização dos pacotes do release.

Lembre-se de coordenar com o Time de engenharia de Lançamento <re@FreeBSD.org> sobre o timing e o status das compilações do release.

Uma vez que a compilação tenha terminado, os pacotes e/ou distfiles podem ser transferidos para o ftp-master para serem propagados para a rede de espelhos FTP. Se a compilação foi executada com a opção -nofinish, então certifique-se de executar em seguida o comando dopackages -finish para realizar o pós-processamento dos pacotes (remover pacotes marcados como RESTRICTED ou como NO_CDROM onde for apropriado, remover pacotes não listados no INDEX, remover do INDEX as referências para pacotes não compilados, e gerar um sumário CHECKSUM.MD5); e dos distfiles (movê-los do diretório temporário distfiles/.pbtmp para o diretório distfiles/ e remover os distfiles marcados como RESTRICTED e NO_CDROM).

É recomendado que se execute manualmente os scripts restricted.sh e/ou cdrom.sh após a finalização do dopackages, apenas por segurança. Execute o script restricted.sh antes de fazer o upload para o ftp-master, em seguida, execute cdrom.sh antes de preparar o conjunto final de pacotes para um release.

Os subdiretórios de pacotes são nomeados de acordo com a versão e branch ao qual se destinam. Por exemplo:

Se você está preparando um conjunto de pacotes completamente novo (por exemplo, para um novo release), copie os pacotes para a área de teste do ftp-master executando algo como mostrado abaixo:

# cd /var/portbuild/${arch}/${branch}
# tar cfv - packages/ | ssh portmgr@ftp-master tar xfC - w/ports/${arch}/tmp/${subdir}

Em seguida, entre no ftp-master e verifique se o conjunto de pacotes foi transferido com sucesso, remova o conjunto de pacotes que o novo conjunto vai substituir (em ~/w/ports/${arch}), e mova o novo conjunto para o local. (w/ é apenas um atalho.)

Para compilações incrementais, o upload deve ser feito usando o rsync para não colocar muita pressão nos espelhos.

SEMPRE use o rsync primeiro com a opção -n e verifique a saída do comando para assegurar-se que não existem problemas. Se parece estar tudo bem, execute novamente o rsync sem a opção -n.

Exemplo de sintaxe do comando rsync para o upload incremental de pacotes:

# rsync -n -r -v -l -t -p --delete packages/ portmgr@ftp-master:w/ports/${arch}/${subdir}/ | tee log

Os distfiles devem ser transferidos utilizando-se o script cpdistfiles:

# /var/portbuild/scripts/cpdistfiles ${arch} ${branch} ${buildid} [-yesreally] | tee log2

A execução manual deste processo é um procedimento obsoleto.

Compilações de patches experimentais são executadas de tempos em tempos para novas funções ou correções de defeitos na infraestrutura do ports (isto é, bsd.port.mk), ou para testar atualizações em grande escala. A qualquer momento podem haver vários patches de branchs experimentais simultâneos, como o 8-exp na arquitetura amd64.

Geralmente, a compilação de patches experimentais é executada da mesma forma que qualquer outra compilação, exceto que você deve primeiro atualizar a árvore de ports para a última versão e, em seguida, aplicar os seus patches. Para fazer o primeiro, você pode usar o seguinte:

% cvs -R update -dP > update.out
% date > cvsdone

Essa é a simulação mais próxima do que o script dopackages faz. (Embora o cvsdone seja meramente informativo, ele pode ser útil.)

Você precisará editar o update.out para procurar por linhas que comecem com ^M, ^C, ou ^? para que possa corrigi-las.

É sempre uma boa idéia salvar cópias do original de todos os arquivos modificados, bem como uma lista do que você está modificando. Você pode consultar a lista ao fazer o commit final, para se certificar de que você está realizando o commit exatamente daquilo que testou.

Pelo fato da máquina ser compartilhada, alguém pode excluir suas alterações por engano, então mantenha cópias destas, por exemplo, no seu diretório home freefall freefall. Não use o tmp/; pois a pointyhat executa ele mesmo alguma versão do -CURRENT, você pode esperar por reinicializações (no mínimo para atualizações).

Para que você tenha uma compilação de controle com a qual possa comparar eventuais falhas, você deve primeiro executar a compilação de pacote no branch em que os patches experimentais foram baseados para a arquitetura i386™ (atualmente esta é o 8). Quando estiver preparando a compilação dos patches experimentais, faça o checkout da árvore do ports e do src com a mesma data da que foi usada para a compilação de controle. Isso vai garantir uma comparação válida entre as compilações depois.

Uma vez terminada a compilação, compare as falhas da compilação de controle com as da compilação dos patches experimentais. Para facilitar, use os seguintes comandos (assumindo o branch 8 como branch de controle, e o 8-exp como branch experimental):

% cd /var/portbuild/i386/8-exp/errors
% find . -name \*.log\* | sort > /tmp/8-exp-errs
% cd /var/portbuild/i386/8/errors
% find . -name \*.log\* | sort > /tmp/8-errs

% comm -3 /tmp/8-errs /tmp/8-exp-errs | less

Este último comando vai gerar um relatório com duas colunas. A primeira coluna contém os ports que falharam na compilação de controle, mas não na compilação com patches experimentais; a segunda é o inverso As razões para o port estar na primeira coluna incluem:

Razões para o port aparecer na segunda coluna incluem:

Ambas as colunas devem ser investigadas e as razões para os erros entendidas antes do commit do conjunto de patches experimentais. Para diferenciar entre o [1] e o [2] acima, você pode recompilar os pacotes afetados sob o branch de controle:

% cd /var/portbuild/i386/8/ports

O seguinte comando vai configurar o branch de controle para a compilação parcial (antigo código base):

% /var/portbuild/scripts/dopackages.8 -noportscvs -nobuild -nocvs -nofinish

As compilações devem ser executadas a partir do diretório packages/All. Este diretório deve estar vazio inicialmente, exceto pelo link simbólico do Makefile. Se este link simbólico não existir, ele deve ser criado:

% cd /var/portbuild/i386/8/packages/All
% ln -sf ../../Makefile .
% make -k -j<#> <list of packages to build>

Isto vai compilar apenas os pacotes listados, bem como todas as suas dependências.

Você pode verificar o progresso da compilação parcial da mesma forma que você faria com uma compilação normal.

Uma vez que todos os erros tenham sido resolvidos, você pode efetuar o commit do conjunto de pacotes. Após efetuar o commit, é de costume enviar um e-mail para ports@FreeBSD.org e com cópia para ports-developers@FreeBSD.org, informando as pessoas sobre as mudanças. Um resumo de todas as mudanças também deve registrado no arquivo /usr/ports/CHANGES.

Antes de seguir estes passos, por favor, converse com o portmgr.

Quando um novo branch é criado, é necessário efetuar alguns ajustes no sistema para especificar que o branch anterior não mais corresponde ao HEAD. As seguintes instruções se aplicam ao número do branch anterior:

Quando um branch antigo deixa de ser suportado, existem algumas coisas a serem feitas para que não fique sujeira para trás.

Desde 2011 a filosofia da compilação de pacotes diz que devemos compilá-los baseados na versão mais antiga suportada de cada branch. Por exemplo: se no RELENG-8 as seguintes versões são suportadas: 8.1, 8.2, 8.3; então o packages-8-stable deve ser compilado a partir da versão 8.1.

Quando uma versão chega ao fim de sua vida (End-Of-Life, veja o quadro), uma compilação completa (não incremental!) dos pacotes deve ser realizada e enviada para os servidores de distribuição.

Os procedimentos para o novo código base são os que seguem abaixo:

O procedimento para o antigo código base fica como um exercício para o leitor.

Esta seção está em progresso.

Por favor, consulte o Mark Linimon antes de efetuar qualquer mudança.

Quando uma máquina tem uma falha de disco (por exemplo, um panic devido a erros de leitura, etc.), devemos executar os seguintes procedimentos:

Quando um disco falhar, por favor, informe os administradores do cluster, para que possamos substituí-lo.