dpkg-source(1) | dpkg suite | dpkg-source(1) |
dpkg-source - ferramenta de manipulação de pacotes fonte Debian (.dsc)
dpkg-source [option...] command
dpkg-source empacote e desempacota arquivos de fonte Debian.
Nenhum destes comandos permite que várias acções sejam combinadas em uma, e eles não permitem que o valor para uma opção seja especificado num argumento separado.
O dpkg-source irá ler os nomes dos outros ficheiros que fazem o pacote fonte a partir do ficheiro de controle; assume-se que eles estejam no mesmo directório que o .dsc.
Os ficheiros no pacote extraído irão ter as suas permissões e propriedades definidas para aquelas que seriam as esperadas caso os ficheiros e directórios tivessem simplesmente sido criados - os directórios e ficheiros executáveis irão ficar com 0777 e ficheiros simples irão ficar com 0666, ambos modificados pelo umask do extractor; se o directório pai está com setgid então os directórios extraídos estarão também, e todos os ficheiros e directórios irão herdar a propriedade do seu grupo.
Se o pacote fonte usar um formato não-standard (actualmente isto significa todos os formatos excepto “1.0”), o seu nome será armazenado em debian/source/format para que as compilações seguintes do pacote fonte usem o mesmo formato por predefinição.
dpkg-source irá compilado o pacote fonte com o primeiro formato encontrado nesta lista por esta ordem: o formato indicado com a opção de linha de comando --format, o formato indicado em debian/source/format, “1.0”. O cair para “1.0” está descontinuado e será removido em algum ponto no futuro, você deve sempre documentar o formato de fonte desejado em debian/source/format.Veja a secção SOURCE PACKAGE FORMATS para uma descrição extensiva dos vários formatos de pacote fonte.
A opção -i por si só activa esta definição com uma regex predefinida (preservando qualquer modificação ao regex predefinido feito por uma utilização anterior de --extend-diff-ignore) que irá filtrar fora ficheiros de controle e directórios dos sistemas de controlo de revisão mais comuns, salvaguardas e ficheiros swap, e directórios de resultados de compilação de Libtool. Só pode existir um regex activo, das várias opções -i apenas a última irá ter efeito.
Isto é uma grande ajuda para cortar ficheiros alheios que foram incluídos no diff, por exemplo se você mantêm a sua fonte num sistema de controle de revisão e deseja usar um checkout para compilar um pacote fonte sem incluir os ficheiros adicionais e os directórios que geralmente contém (ex. CVS/, .cvsignore, .svn/). O regex predefinido já é bastante exaustivo, mas se precisar de o substituir, por favor note que por predefinição ele consegue corresponder a qualquer parte de um caminho, portanto se você quer corresponder ao inicio de um nome de ficheiro, ou apenas nomes completos de ficheiros, precisa ser você próprio a fornecer as âncoras necessárias (ex, ‘(^|/)’, ‘($|/)’).
-I por si próprio adiciona opções --exclude predefinidas que irão filtrar ficheiros de controle e directórios dos sistemas de controlo de revisão mais comuns, ol systems, salvaguarda e permutar ficheiros e directórios de saída de compilação de Libtool.
Nota: Apesar de terem objectivos semelhantes, -i e -I têm muitas diferenças na sintaxe e semântica. -i só pode ser especificado uma vez e e recebe uma expressão regular compatível com perl que é correspondida ao caminho relativo completo de cada ficheiro. -I pode se especificado várias vezes e recebe um padrão de nome de ficheiro com wildcards de shell. O padrão é aplicado ao caminho relativo completo mas também a cada parte do caminho individualmente. A semântica exacta da opção --exclude do tar é um tanto complicada, veja <https://www.gnu.org/software/tar/manual/tar.html#wildcards> para a documentação completa.
A regex e padrões predefinidos para ambas opções podem ser vistos no resultado do comando --help.
Se você não sabe que formato de fonte usar, deve provavelmente escolher entre “3.0 (quilt)” ou “3.0 (native)”. Veja <https://wiki.debian.org/Projects/DebSrc3.0> para informação sobre o desenvolvimento desses formatos em Debian.
Um pacote fonte neste formato consiste ou de um .orig.tar.gz associado a um .diff.gz ou de um único .tar.gz (nesse caso diz-se que o pacote é nativo). Opcionalmente o tarball origina pode estar acompanhado de uma assinatura separada do autor .orig.tar.gz.asc, extração suportada desde dpkg 1.18.5.
Extracting
Extrair um pacote nativo é uma simples extração do único tarball no directório alvo. Extrair um pacote não-nativo é feito ao primeiro desempacotar o .orig.tar.gz e depois aplicar a patch contida no ficheiro .diff.gz. O carimbo temporal de todos os ficheiros que receberam patch é reposto à hora de extração do pacote fonte (isto evita confusões com carimbos temporais que levam a problemas quando se aplicam patch a ficheiros auto-gerados). O diff pode criar novos ficheiros (todo o directório debian é criado deste modo) mas não pode remover ficheiros (ficheiros vazios serão deixados) e não pode criar ou modificar links simbólicos.
Building
Compilar um pacote nativo é apenas criar um único tarball com o directório fonte. Compilar um pacote não-nativo involve extrair o tarball original num directório “.orig” separado e regenerar o .diff.gz ao comparar o directory do pacote fonte com o directório .orig.
Build options (with --build):
Se um segundo argumento não-opção for fornecido este deve ser o nome do directório fonte original ou ficheiro tar ou uma string vazia se o pacote é um específico de Debian, e assim não tem diffs de debianização. Se não for fornecido um segundo argumento, então dpkg-source irá procurar o ficheiro tar fonte original package_upstream-version.orig.tar.gz ou o directório fonte original directory.orig dependendo dos argumentos -sX.
-sa, -sp, -sk, -su e -sr não irão sobrescrever ficheiros tar ou directórios existentes. Se isto for desejado então devem antes ser usados -sA, -sP, -sK, -sU e -sR.
Opções de extração (com --extract):
Em todos os casos qualquer árvore de fonte original existente será removida.
Todas as opções -sX são mutuamente exclusivas. Se você especificar mais do que uma, apenas será usada a última.
Extração suportada desde dpkg 1.13.9, compilação suportada desde dpkg 1.14.8. Também conhecido como wig&pen. Este formato não é recomendado para utilização em massa, o formato "3.0 (quilt)" substitui este. Wig&pen foi a primeira especificação de um formato de pacote fonte da nova geração.
O comportamento deste formato é o mesmo que o do formato "3.0 (quilt)" com a excepção de que não usa uma lista de patches explicita. Todos os ficheiros em debian/patches/ que correspondem à expressão regular perl [\w-]+ têm de ser patches válidas: elas são aplicadas durante a extração.
Quando se constrói um novo pacote fonte, qualquer alteração na fonte do autor é armazenada numa patch chamada zz_debian-diff-auto.
Suportado desde dpkg 1.14.17. Este formato é uma extensão do formato de pacote nativo como definido no formato 1.0. Suporta todos os métodos de compressão e irá ignorar por predefinição quaisquer ficheiros específicos de VCS e directórios também assim como muitos ficheiros temporários (veja valor predefinido associado à opção -I no resultado de --help).
Suportado desde dpkg 1.14.17. Um pacote fonte neste formato contém pelo menos um tarball original (.orig.tar.ext onde ext pode ser gz, bz2, lzma e xz) e um tarball debian (.debian.tar.ext). Também pode conter tarballs originais adicionais (.orig-component.tar.ext). component pode apenas conter caracteres alfanuméricos (‘a-zA-Z0-9’) e hífens (‘-’). Opcionalmente cada tarball original pode ser acompanhado por uma assinatura em separado do autor (.orig.tar.ext.asc e .orig-component.tar.ext.asc), extração suportada desde dpkg 1.17.20, compilação suportada desde dpkg 1.18.5.
Extracting
O tarball original principal é extraído primeiro, depois todos os tarballs originais adicionais são extraídos em sub-directórios nomeados após a parte component do seu nome de ficheiro (qualquer directório pré-existente é substituído). O tarball debian é extraído no topo do directório fonte após a pré remoção de qualquer directório debian pré-existente mas pode também conter ficheiros binários fora desse directório (veja a opção --include-binaries).
Todas as patches listadas em debian/patches/vendor.series ou debian/patches/series são então aplicadas, onde vendor será o nome em minúsculas do fornecedor actual, ou debian se não existir um fornecedor definido. Se o ficheiro anterior for usado e o posterior não existir (ou for um link simbólico), então o posterior é substituído por um link simbólico para o antigo. Isto destina-se a simplificar a utilização de quilt para gerir o conjunto de patches. Ficheiros de séries especificas-de-fornecedor destinam-se a tornar possível a criação de séries de múltiplos ramos de desenvolvimento baseados no fornecedor, num modo declarativo, dando preferência a codificação-aberta deste manuseamento em debian/rules. Isto é particularmente útil quando a fonte precisa de receber uma patch condicionalmente porque os ficheiros afectados não possuem suporte a oclusão condicional embutido. Note no entanto que enquanto dpkg-source analisa correctamente ficheiros de séries com opções explícitas usadas para aplicar patch a aplicação (armazenada em cada linha antes do nome de ficheiro de patch e um ou mais espaços), ele ignora essas opções e espera sempre que as patches possam ser aplicadas com a opção -p1 ou patch. Irá portanto emitir um aviso quando encontra tais opções, e é provável que a compilação falhe.
Note que lintian(1) irá emitir avisos incondicionais quando usa séries de fornecedor devido a regulamento controverso específico de Debian, o qual não deve afectar nenhuma utilização externa; para silenciar isto, o perfil lintian do dpkg pode ser usado ao passar «--profile dpkg» a lintian(1).
O carimbo temporal de todos os ficheiros com patch é reposto para a hora da extração do pacote fonte (isto evita inclinações do carimbo temporal que levam a problemas quando aplica patch a ficheiros auto-gerados).
Contrariamente ao comportamento predefinido de quilt, espera-se que as patches sejam aplicadas sem confusões. Quando esse não é o caso, você deve refrescar tais patches com quilt, ou dpkg-source irá terminar em erro ao tentar aplica-las.
Semelhante ao comportamento predefinido de quilt. as patches também podem remover ficheiros.
O ficheiro .pc/applied-patches é criado se algumas patches foram aplicadas durante a extração.
Building
Todos os tarballs originais encontrados no directório actual são extraídos num directório temporário seguindo a mesma lógica que para o desempacotar, o directório debian é copiado sobre o directório temporário, e todas as são aplicadas, excepto a patch automática (debian-changes-version ou debian-changes, dependendo de --single-debian-patch). O directório temporário é comparado com o directório do pacote fonte. Quando o diff é não-vazio, a compilação falha a menos que tenham sido usados --single-debian-patch ou --auto-commit, que neste caso o diff é guardado na patch automática. Se a patch automática for criada/apagada, é adicionada/removida do ficheiro de séries e dos meta-dados quilt.
Qualquer alteração num ficheiro binário não é representável num diff e irá assim levar a uma falha a menos que o maintainer tenha decidido deliberadamente incluir esse ficheiro binário modificado no tarball debian (ao lista-lo em debian/source/include-binaries). A compilação irá também falhar se encontrar ficheiros binários no sub-directório debian a menos que estes tenham sido autorizados através de debian/source/include-binaries.
O directório debian actualizado e a lista de binários modificados são então usados para gerar o tarball debian.
O diff gerado automaticamente não inclui alterações em ficheiros específicos de VCS assim como em muitos ficheiro temporários (veja valor predefinido associado à opção -i no resultado de --help). Em particular, o directório .pc usado por quilt é ignorado durante a geração da patch automática.
Nota: dpkg-source --before-build (e --build) irão assegurar que todas as patches listadas no ficheiro series são aplicadas para que uma compilação do pacote tenha sempre todas as patches aplicadas. Faz isto ao encontrar patches não aplicadas (elas estão listadas no ficheiro series mas não em .pc/applied-patches), e se a primeira patch nesse conjunto puder ser aplicada sem erros, irá aplica-las todas. A opção --no-preparation pode ser usada para desactivar este comportamento.
Gravar alterações
Passar patch-file é principalmente útil após uma falha de compilação que pré-gerou este ficheiro, e por esse motivo o ficheiro fornecido é removido após integração. Note também que as alterações contidas no ficheiro patch têm de já estar aplicadas na árvore e que os ficheiros modificados pela patch não podem ter alterações suplementares por gravar.
Se a geração da patch detectar ficheiros binários modificados, eles serão adicionados automaticamente a debian/source/include-binaries para que eles acabem no tarbal debian (exactamente como dpkg-source --include-binaries --build faria).
Opções de compilação
Opções de extração
Suportado desde dpkg 1.14.17. Este formato é especial. Não representa o formato real do pacote fonte mas pode ser usado para criar pacotes fonte com ficheiros arbitrários.
Opções de compilação
Todos os argumentos não-opção são tomados como ficheiros para integrar no pacote fonte gerado. Estes têm de existir e estão preferencialmente no directório actual. Pelo menos um ficheiro tem de ser fornecido.
Suportado desde dpkg 1.14.17. Este formato é experimental.
Um pacote fonte neste formato consiste de um único bolo de repositório git .git para manter a fonte de um pacote. Também pode existir um ficheiro .gitshallow listando revisões para um clone git shallow.
Extracting
O bolo é clonado como um repositório git para o directório alvo. Se existir um ficheiro gitshallow, é instalado como .git/shallow dentro do repositório git clonado.
Note que por predefinição o novo repositório irá ter o mesmo ramo "checked out" como era "checked out" na fonte original. (Tipicamente “main”, mas pode ser qualquer coisa.) Quaisquer outros ramos irão estar disponíveis sob remotes/origin/.
Building
Antes de avançar-mos, são feitas algumas verificações para assegurar que não temos nenhumas alterações não ignoradas por submeter.
git-bundle(1) é usado para gerar um bolo do repositório git. Por predefinição, todos os ramos e etiquetas no repositório são incluídos no bolo.
Opções de compilação
Suportado desde dpkg 1.14.17. Este formato é experimental. Gera um único tarball que contem o repositório bzr.
Extracting
O tarball é desempacotado e depois é usado o bzr para fazer "checkout" ao ramo actual.
Building
Antes de avançar-mos, são feitas algumas verificações para assegurar que não temos nenhumas alterações não ignoradas por submeter.
Depois a parte específica de VCS do directório fonte é copiada para um directório temporário. Antes deste directório temporário ser empacotado num tarball, são feitas várias limpezas para libertar espaço.
O ficheiro debian/source/format deve sempre existir e indicar o formato de fonte desejado. Para compatibilidade com software anterior, o formato “1.0” é assumido quando o ficheiro não existe mas você não deve confiar nisto: algures no futuro, dpkg-source será modificado para falhar quando esse ficheiro não existe.
A lógica é que o formato “1.0”não é mais o formato recomendado, você deve geralmente escolher um dos formatos mais recentes (“3.0 (quilt)”, “3.0 (native)”) mas o dpkg-source não vai fazer isto automaticamente por si. Se você deseja continuar a usar o formato antigo, você deve ser explícito acerca disso a colocar "1.0” em debian/source/format.
Quando se usar o formato de fonte “1.0” é geralmente uma má ideia modificar ficheiros do autor directamente pois as alterações acabam escondidas e maioritariamente não documentadas no ficheiro .diff.gz. Em vez disso você deve guardar as suas alterações em patches no directório debian e aplica-las durante a compilação. Para evitar esta complexidade você pode também usar o formato "3.0 (quilt)” que oferece isto nativamente.
As alterações às fontes originais são geralmente guardadas com ficheiros patch, mas nem todas as alterações podem ser representadas com patches: elas apenas podem alterar o conteúdo de ficheiros de texto simples. Se você tentar substituir um ficheiro por algo de diferente tipo (por exemplo, substituir um ficheiro simples por um link simbólico ou directório), você vai receber esta mensagem de erro.
Ficheiros vazios não podem ser criados com ficheiros patch. Assim esta alteração não é gravada no pacote fonte e você é avisado acerca disso.
Os ficheiros patch não gravam permissões dos ficheiro e assim as permissões de executável não são guardadas no pacote fonte. Este aviso lembra-o desse facto.
Os ficheiros patch não gravam permissões dos ficheiro e assim as permissões modificadas não são guardadas no pacote fonte. Este aviso lembra-o desse facto.
Este ficheiro contém numa linha única o formato que deve ser usado para compilar o pacote fonte (os formatos possíveis estão descritos acima). Não são permitidos espaços a anteceder ou a preceder.
Este ficheiro contém uma lista nomes de caminhos de ficheiros binários (um por cada linha) relativos ao directório raiz da fonte que devem ser incluídos no tarball de debian. Os espaços que antecedem e precedem são removidos. As linhas que começam com ‘#’ são comentários e são saltadas. Linhas vazias são ignoradas.
Este ficheiro contem uma lista de opções longas que devem ser automaticamente anexadas ao conjunto de opções de linha de comandos de uma chamada dpkg-source --build ou dpkg-source --print-format. Opções como --compression e --compression-level são bem apropriadas para este ficheiro.
Cada opção deve ser posta numa linha separada. AS linhas vazias e linhas começadas com ‘#’ são ignoradas. O ‘--’ inicial deve ser cortado e as opções curtas não são permitidas. São permitidos espaços opcionais a contornar o símbolo '=’ e são permitidas citações opcionais a envolver o valor. Aqui está um exemplo de tal ficheiro:
# let dpkg-source create a debian.tar.bz2 with maximal compression compression = "bzip2" compression-level = 9 # use debian/patches/debian-changes as automatic patch single-debian-patch # ignore changes on config.{sub,guess} extend-diff-ignore = "(^|/)(config.sub|config.guess)$"
Nota: As opções format não são aceites neste ficheiro, em vez disso você deve usar debian/source/format.
Exactamente como debian/source/options excepto que o ficheiro não é incluído no pacote fonte gerado. Pode ser útil para guardar uma preferência amarrada ao maintainer ou ao repositório VCS onde o pacote fonte é mantido.
Texto de formato livre que é colocado no topo da patch automática gerada em formatos “2.0” ou “3.0 (quilt)”. local-patch-header não é incluído no pacote fonte gerado enquanto patch-header o é.
Este ficheiro lista todas as patches que têm de ser aplicadas (na ordem dada) no topo do pacote fonte do autor original. Os espaços iniciais e finais são retirados. O vendor será o nome em minúsculas do fornecedor actual, ou debian se não existir um fornecedor definido. Se o ficheiro series especifico-do-fornecedor não existir, será usado o ficheiro series sem-fornecedor. As linha começadas com ‘#’ são comentários e são retiradas. Linhas vazias são ignoradas. As linhas restantes começam com um nome de ficheiro patch (relativo ao directório debian/patches/) até ap primeiro caractere de espaço ou ao fim da linha. Opções quilt opcionais podem seguir até ao fim da linha ou ao primeiro ‘#’ precedido por um ou mais espaços (o que marca o começo de um comentário até ao fim da linha).
O ponto no qual cada sobreposição de campo ocorre comparado com certas definições de campos de saídas standard é bastante confuso.
deb-src-control(5), deb-changelog(5), deb-substvars(5), dsc(5).
Américo Monteiro
Se encontrar algum erro na tradução deste documento, por favor comunique para Américo Monteiro <a_monteiro@gmx.com>.
2023-05-11 | 1.21.22 |