dgit-user(7)

NOME
dgit-user - fazer e partilhar alterações a pacotes Debian, com o git

INTRODUÇÃO
git permite-lhe obter o código fonte para cada pacote no seu sistema como se a sua distribuição usasse git para os manter todos lá.

Você pode depois edita-los, compilar pacotes binários actualizados (.debs) e instala-los e corre-os. Você pode também partilhar o seu trabalho com outros.

Este tutorial fornece algumas receitas e dicas para isto. Ele assume que você está basicamente familiarizado com o git. Não assume nenhuma familiarização inicial com os processos de empacotamento de Debian.

Se você é um maintainer de pacotes com Debian; um DM ou DD; e/ou um apadrinhado: este tutorial não é para si. Tente dgit-nmu-simple(7), dgit-maint-*(7), ou dgit(1) e dgit(7).

SUMÁRIO
(Estas runas serão discutidas mais tarde.)

    % dgit clone glibc bookworm,-security
    % cd glibc
    % curl 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
    % git commit -a -m 'Fix libc lost output bug'
    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
    % sudo apt-get build-dep .
    % dpkg-buildpackage -uc -b
    % sudo dpkg -i ../libc6_*.deb

Ocasionalmente:

    % git clean -xdf
    % git reset --hard

Depois:

    % cd glibc
    % dgit pull bookworm,-security
    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
    % dpkg-buildpackage -uc -b
    % sudo dpkg -i ../libc6_*.deb

ENCONTRAR O CÓDIGO FONTE CERTO - CLONE DO DGIT
    % dgit clone glibc bookworm,-security
    % cd glibc

o clone do dgit precisa que lhe digam o nome do pacote fonte (que pode ser diferente do nome do pacote binário, o qual foi o nome que você passou ao "apt-get install") e o nome de código ou nome alternativo do lançamento Debian (isto é chamado a "suite").

  Encontrar o nome do pacote fonte
Para muitos pacotes, o nome de pacote fonte é óbvio. Caso contrário, se você souber de um ficheiro que está no pacote, você pode procura-lo com o dpkg:

    % dpkg -S /lib/i386-linux-gnu/libc.so.6
    libc6:i386: /lib/i386-linux-gnu/libc.so.6
    % dpkg -s libc6:i386
    Package: libc6
    Status: install ok installed
    ...
    Source: glibc

(Neste exemplo, libc6 é um pacote "multi-arch: allowed", o que significa que ele existe em várias compilações diferentes para arquitecturas diferentes. É daí que ":i386" vem.)

  Encontrar o lançamento Debian (a "suite")
Internamente, as distribuições Debian (e derivadas) normalmente referem os seus lançamentos por nomes de código. Debian também tem nomes alternativos que referem o lançamento estável actual, etc. Assim por exemplo, na altura da escrita de Debian "bookworm" (Debian 12) é Debian "stable"; e a versão atual de Ubuntu é "plucky" (Plucky Puffin, 25.04). Você pode especificar seja o nome de código "bookworm" ou o nome alternativo "stable". Se você não o disser, vai obter "sid", o que é Debian "unstable" - o principal ramo de trabalho em progresso.

Se você não sabe o que está a usar, por favor consulte a sua configuração do apt em /etc/apt/sources* ou em /etc/debian_version

Para Debian, você deve adicionar ",-security" ao final do nome de suite , a menos que esteja em unstable ou testing. Assim, no seu exemplo "bookworm" torna-se "bookworm,-security". (Sim, com uma vírgula.)

O QUE O CLONE DO DGIT PRODUZ

  Que ramos existem
dgit clone irá dar-lhe uma nova árvore de trabalho, e arrumar para si para ficar num ramo chamado algo como "dgit/bookworm,-security" (sim, com uma vírgula no nome de ramo).

Para cada lançamento (como "bookworm") existe um ramo de acompanhamento para os conteúdos do arquivo, chamado "remotes/dgit/dgit/bookworm" (e semelhante para outras suites). Isto pode ser atualizado com "dgit fetch bookworm". Isto, o remote suite branch, é sintetizado pela sua cópia local do dgit. É um avanço rápido.

Debian separa as atualizações de segurança, em "*-security". Dizer ao dgit "bookworm,-security" significa que deve incluir quaisquer atualizações disponíveis em "bookworm-security". A notação com a vírgula é um pedido ao dgit para acompanhar bookworm, ou bookworm-security para ver se há atualização para o pacote lá.

(Você também pode fazer o dgit procurar numa árvore que não foi feita pelo dgit clone. Se não existir um "debian/changelog" você tem de fornecer uma opção "-p"pacote para o dgit procurar.)

  Que tipo de árvore fonte você obtém
Se o pacote Debian for baseado em algum lançamento do autor, a disposição do código estará parecida com a versão do autor. Você vai achar "git grep" uma boa ajuda para descobrir onde editar.

Os metadados do pacote Debian e os scripts para compilar pacotes binário estão sob "debian/". "debian/control", "debian/changelog" e "debian/rules" são os pontos de partida. O Manual de Política Debian tem a maioria dos detalhes mais profundos.

Para a maioria dos pacotes, vão estar também algumas coisas em "debian/patches/". É melhor ignorar estas. Na medida que são relevantes nas alterações que vão ser aplicadas aos ficheiros, provavelmente por meio de coisas cometidas no histórico do git. O conteúdo debian/patches é ignorado quando se compila binários a partir de ramos git feitos à dgit.

(Para os aficionados de Debian: as árvores git que saem do dgit são "ramos de empacotamento com patches-aplicada sem um directório .pc".)

  Que tipo de história você obtém
Se estiver com sorte, o histórico será uma versão de, ou baseada em, do histórico git do próprio maintainer Debian, ou do histórico git do autor.

Mas para muitos pacotes o histórico git real não existe, ou não foi publicado num formato à dgit. Assim você pode descobrir que o histórico é um histórico bastante curto inventado pelo dgit.

os históricos do dgit muitas vezes contém commits gerados automaticamente, incluindo commits que não fizeram nenhumas alterações mas serviram para criar um ramo re-baseado de avanço rápido. Isto é particularmente verdade de se combinar ramos como "bookworm,-security".

Se o maintainer do pacote está a usar git após dgit clone você pode descobrir que existe um "vcs-git" remoto útil que refere ao repositório do maintainer do pacote Debian. Você pode ver o que lá está com "git fetch vcs-git". Mas use o que lá encontrar com cuidado: os repositórios de maintainers Debian muitas vezes têm conteúdos que são muito confusos e idiossincráticos. Em particular, você pode precisar de aplicar manualmente as patches que estão em debian/patches antes de fazer qualquer outra coisa.

COMPILAÇÃO

  Cometa sempre antes de compilar
    % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
    % git commit -a -m 'Fix libc lost output bug'

Compilações de pacote Debian são muitas vezes bastantes desarrumadas: elas podem modificar ficheiros que são também cometidos para o git, ou deixar resultados e ficheiros temporários não cobertos pelo ".gitignore".

Se você cometer sempre, você pode usar

    % git clean -xdf
    % git reset --hard

para arrumar tudo após um compilação. (Se você se esqueceu de cometer, não use esses comandos; em vez disso, saiba que pode usar "git add -p" para ajudar a cometer aquilo que realmente quer manter.)

Estes são comandos destrutivos que apagam todos os novos ficheiros (assim você tem de se lembrar de dizer "git add") e deitam fora as edições de cada ficheiro (assim você tem de se lembrar de cometer).

  Atualize o changelog (pelo menos uma vez) antes de compilar
    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit

Os binários que você compilar irão ter um número de versão que em última análise vem de "debian/changelog". Você vai querer ser capaz de distinguir os seus binários dos da sua distribuição.

Assim você deve atualizar "debian/changelog" para adicionar uma nova estrofe no topo, para a sua compilação.

Esta runa fornece uma maneira fácil de fazer isto. Adiciona uma nova entrada no changelog com uma mensagem pouco informativa e um número de versão plausível (contendo um bocadinho do seu id de cometido ao git).

Se desejar ser mais sofisticado, o pacote "dpkg-dev-el" tem um bom modo Emacs para editar changelogs. Em alternativa, você pode editar o changelog com outro editor de texto, ou correr "dch" ou "gbp dch" com opções diferentes. Escolher um bom número de versão é um pouco complicado e um tratamento completo está para lá do escopo deste tutorial.

  Realmente compilar
    % sudo apt-get build-dep .
    % dpkg-buildpackage -uc -b

dpkg-buildpackage é a ferramenta principal para compilar um pacote fonte Debian. "-uc" significa não assinar com pgp os resultados. "-b" significa compilar todos os pacotes binário, mas não compilar um pacote fonte.

  Usar o sbuild
Você pode compilar numa chroot de schroot, com o sbuild, em vez de o fazer no seu ambiente principal. (sbuild é usado pelos daemons de compilação de Debian.)

    % git clean -xdf
    % sbuild -d trixie -A --no-clean-source \
             --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'

Note que isto vai parecer deixar um "pacote fonte" (.dsc e .tar.gz) no directório pai, mas esse pacote fonte não deve ser usado. Estará provavelmente estragado. Para mais informação veja bug Debian #868527.

INSTALAÇÃO
    % sudo apt install ../libc6_*.deb

Você pode usar "dpkg -i" para instalar os .debs que saíram do seu pacote.

Se as dependências não estiverem instaladas, vai receber um erro, o que pode ser geralmente corrigido com "apt-get -f install".

Multi-arquitectura
Se você está a trabalhar num pacote biblioteca e o seu sistema tem várias arquitecturas activas, você pode ver algo como isto:

    dpkg: error processing package libpcre3-dev:amd64 (--configure):
     package libpcre3-dev:amd64 2:8.39-3~3.gbp8f25f5 cannot be configured because libpcre3-dev:i386 is at a different version (2:8.39-2)

O sistema de multi-arquitectura usado por Debian requer que cada pacote que esteja presente para múltiplas arquitecturas seja exatamente o mesmo entre todas as arquitecturas para quais está instalado.

A solução apropriada é compilar o pacote para todas as arquitecturas que tem activas. Você vai precisar duma chroot para cada uma das arquitecturas secundárias. Isto é um pouco cansativo, mesmo apesar de Debian ter ferramentas excelentes para gerir chroots. "sbuild-debian-developer-setup" do pacote com o mesmo nome e "sbuild-createchroot" do pacote "sbuild" são bons pontos de partida.

Caso contrário você pode desinstalar os pacotes que interessam para as outras arquitecturas com algo como "dpkg --remove libpcre3:i386".

Se nenhuma destas for opção, o seu último recurso desesperado é tentar usar o mesmo número de versão que o pacote oficial para o seu próprio pacote. (A versão é controlada por "debian/changelog" -veja em cima.) Isto não é ideal porque torna difícil de perceber o que está instalado, e porque irá confundir e induzir em erro o apt.

Com a abordagem "mesmo número" ainda pode ter erros do tipo

    a tentar sobrescreve '/usr/include/pcreposix.h' partilhado, o qual é diferente de outras instâncias do pacote libpcre3-dev

mas passar "--force-overwrite" ao dpkg vai ajudar - assumindo que você sabe o que faz.

PARTILHAR O SEU TRABALHO
O ramo "dgit/bookworm,-security" (ou qualquer outra coisa) é um ramo git normal. Você pode usar "git push" para o publicar em qualquer servidor git apropriado.

Qualquer pessoa que obtenha esse ramo git de si será capaz de compilar pacotes (.deb) binário tal como você fez.

Se você deseja contribuir as suas alterações de volta para Debian, deve provavelmente envia-las com o anexos em um email para o Debian Bug System <https://bugs.debian.org/> (seja no seguimento de um bug existente, ou num novo bug). Patches em formato "git-format-patch" são geralmente bem recebidas.

  Pacotes fonte
O ramo git não é suficiente para compilar um pacote fonte da maneira que Debian faz. Os pacotes fonte são um pouco desajeitados para se trabalhar. Na verdade muitos históricos git plausíveis ou árvores git não podem ser convertidos num pacote fonte apropriado. Assim Eu recomendo que você partilhe o seu ramo git em vez disto.

Se um ramo git não for suficiente, e precisar de fornecer um pacote fonte mas não se interessa pelo seu formato/disposição (por exemplo porque algum software que tem consome pacotes fonte, e não históricos git) você pode usar esta receita para gerar um pacote fonte "3.0 (nativo)", o que é apenas um tarball com acompanhado dum ficheiro de metadados .dsc:

    % echo '3.0 (native)' >debian/source/format
    % git commit -m 'switch to native source format' debian/source/format
    % dgit -wgf build-source

Se você precisar de fornecer um pacote fonte bonito, esteja preparado para muito mais trabalho. Vai precisar de ler muito mais, talvez começando com dgit-nmu-simple(7), dgit-sponsorship(7) ou dgit-maint-*(7)

INSTALAR O NOVO DGIT EM DISTRIBUIÇÕES ANTIGAS
Se o dgit quebrar com o pacote fonte em que está a trabalhar, isto pode ser devido a um bug que deveria ser corrigido por uma atualização.

Você pode provavelmente "apt install" diretamente a versão mais recente do dgit.deb de Debian stable, ou Debian testing.

Versões do dgit a partir de Debian 13 (trixie) daqui em diante documentam a sua instabilidade dos lançamentos antigos no manual. Por exemplo, para Debian testing atual, veja <https://manpages.debian.org/testing/dgit/dgit.1.en.html>, e consulte a secção SUPORTE EM DISTRIBUIÇÕES ANTIGAS.

VEJA TAMBÉM
dgit(1), dgit(7)