Scroll to navigation

dgit-downstream-dsc(7) dgit dgit-downstream-dsc(7)

NOME

dgit-downstream-dsc - definir o dgit push para uma nova distribuição

INTRODUÇÃO

Este documento destina-se a fluxos abaixo de Debian. Explica como você pode publicar o código fonte dos seus pacotes ambos como pacotes fonte tradicionais Debian, e como ramos git, usando dgit push. Os seus utilizadores serão capazes de obter a fonte com dgit clone, ou com ferramentas tradicionais como apt-get source.

Note que geralmente é desnecessário publicar pacotes fonte tradicionais. Os pacotes fonte de formato Debian conseguem ser complexos, idiossincráticos e difíceis de trabalhar com eles. Você deve evita-los de puder. Se você não precisar publicar pacotes fonte, você pode trabalhar num fluxo abaixo de Debian usando puramente ramos git, (usando o dgit para obter a fonte de Debian em formato git). Você pode compilar binários diretamente de git, e enviar o código fonte do pacote como um ramo git para um servidor git normal. Veja dgit-user(7).

Nem todas as opções são cobertas aqui. dgit(1) tem uma lista muito completa de opções de configuração, apesar de nem sempre com descrições úteis.

NOMES

Você precisa de escolher alguns nomes.

O dgit compreende tudo o que interage como uma distribuição. Assim em termos do dgit, você está a configurar uma distribuição.

Você precisa dum nome para si (isto é, para a sua distribuição). O nome irá aparecer nas etiquetas git feitas pelas suas ferramentas, e nas definições de configuração. Tem de ser único globalmente entre todas as pessoas e instituições que usem o dgit,

Você pode escolher o nome de domínio da sua organização, ou parte dele se achar que vai ser muito único.

O nome da distribuição pode conter alfanuméricos ascii e . + -, apesar de - poder criar confusão e provavelmente o melhor é evita-lo. Tente evitar letras maiúsculas (e underscore): você vai teclar este nome muitas vezes.

Por exemplo, se você for a Free Software Foundation Europe (fsfe.org) você poderá chamar a sua distribuição fsfe ou fsfe.org. No resto deste documento nós vamos só escrever distro para o seu nome de distribuição.

Em dgit e terminologia de arquivo Debian, uma suite é uma linha de desenvolvimento e/ou um lançamento Debian. Por exemplo, à data desta escrita, Debian tem suites como sid aka unstable, trixie aka testing, e bookworm aka stable. Existem também suites auxiliares como a bookworm-security.

Se os seus lançamentos alinharem com lançamentos de Debian, então as suas suites devem conter os nomes de suites Debian. Não use apenas os nomes de Debian. Isso vai criar confusão. Em vez disso, anteceda com o nome da sua organização e um hífen. Por exemplo, FSFE poderia ficar com suites como fsfe-trixie.

Os nomes de suite acabam em referências git e nomes de ramo, e nas linhas de comando do dgit. Os nomes de suite pode conter alfanuméricos e "-". Outros caracteres podem funcionar mas não são recomendados.

SERVIÇOS

Você vai precisar de correr dois serviços paralelos:

Isto vai manter os ramos git acedidos pelo dgit.

Qualquer pessoa que irá usar dgit push precisa de ser capaz de atualizar refs/dgit/suite (nota, não refs/heads/dgit/suite) nesse servidor, e para criar etiquetas distro/version e archive/distro/version. Normalmente isto deve ser feito sobre ssh.

O servidor também pode hospedar outros ramos e etiquetas. Assim este pode ser o seu servidor git normal, ou uma instância de um sistema de hospedagem git.

Qualquer pessoa que obtenha um dos seus pacotes fonte, ou quem irá correr dgit clone e dgit fetch, precisa de ter pelo menos acesso de leitura ao servidor git. Idealmente tudo seria publicado via protocolo https inteligente do git.

O nome do servidor git, e a estrutura de url de git público, devem ser escolhidos de modo que não precisem ser alterados no futuro. O melhor é dar ao servidor git um nome DNS dele próprio.

O servidor git dgit de Debian tem regras de controlo de acesso especiais, implementadas em dgit-repos-server e dgit-repos-policy-debian no pacote dgit-infrastructure. Mas na maioria das instalações isto não é necessário. Se não existir distinção, ou for pequena, entre (i) desenvolvedores que têm direito a enviar (push) e (ii) administradores do repositório, então é suficiente fornecer um servidor git com uma conta unix para cada utilizador que irá enviar, talvez usando comandos restritos de ssh.

Isto detém os pacotes fonte. Você irá provavelmente usar o mesmo arquivo para hospedar os seus binários, e apontar o seu apt a ele.

O dgit usa o termo arquivo para isto.

Existe uma variedade de ferramentas para criar e gerir um arquivo de formato Debian. Neste documento vamos assumir que você está a usar o reprepro.

Configurar o reprepro não está coberto por este tutorial. Em vez disso, assumimos que você já tem o reprepro a funcionar.

Você deve também escrever uma configuração apropriada do dput, pois o dgit usa o dput para enviar pacotes para o arquivo. Isto irá envolver escolher um nome de máquina do dput. Isso será provavelmente o seu nome de distribuição, distro.

CONFIGURAÇÃO

Quando você tiver tudo que foi dito em cima configurado, está pronto para explicar ao dgit como aceder aos seus sistemas.

O dgit é configurado via sistema de configuração do git, assim isto é feito com a configuração do git. Veja git-config(1).

Em baixo, cada título é uma ou mais chaves de configuração do git. negrito é texto literal e itálico são coisas que variam. Nas descrições dos efeitos das definições de configuração, nós referimos os valores de configuração "assim".

Especifica os URLs git de acesso público para o seu servidor git dgit. Os urls gerados são "git-url"/pacote"git-url-sufixo"

O url deve ser estável, e acessível publicamente, porque o seu nome é publicado em ficheiros .dsc. (Note que você fez versões modificadas dos pacotes a partir de Debian, as licenças de cópia usadas para Software Livre geralmente requerem que você permita aos seus utilizadores, empregados, e outros fluxos abaixo do seu, que continuem a distribuir o seu código fonte modificado.)

O nome de domínio da sua interface ssh do servidor git.
Alguns sistemas de hospedagem git esperam que todos se liguem por ssh como o mesmo utilizador, geralmente git. Se este for o caso, defina "git-user-force" para esse utilizador.

Se você tiver um acordo de git sobre ssh normal, onde as pessoas usam ssh como elas próprias, deixe "git-user-force" por definir. Se um utilizador desejar sobrepor o nome de utilizador (por exemplo, se o seu nome de utilizador local não for o mesmo que no servidor) ele pode definir "username".

Defina isto para string vazia. Isto vai fazer com que os acessos de envio (push) ao servidor ssh irão usar "/push.git-host", etc.
ssh://
"dgit-distro."distro/push.git-path
O caminho para os seus repositórios. O dgit push irá tentar enviar para "git-proto"["git-user-force"|"nome-utilizador"@]"caminho-git"/pacote.git
O dgit clone precisa de ser capaz de perceber se ainda existe um repositório git para um pacote particular.

Se você tiver sempre um repositório git para cada pacote no seu arquivo, talvez porque nunca usou o dput/dupload, e sempre o dgit push, defina "git-check" para true.

Caso contrário, defina "git-check" para um prefixo de url - idealmente, https. O dgit clone irá tentar obter "git-check"/pacote"git-check-suffix" e esperar obter ou algum sucesso na obtenção (não interessa qual) ou um erro de ficheiro não encontrado (código de estado 404 do http). Os outros resultados são erros fatais.

Se o seu servidor git correr cgit, então você pode definir "git-check" para o mesmo que "git-url", e "git-check-suffix" para /info/refs.

O dgit push também precisa de ser capaz de verificar se o repositório existe.

Você pode definir ambos estes para ssh-cmd, o que irá usar um comando shell ssh para testar a existência do repositório. Ou deixa-los por definir, e o dgit push irá usar os detalhes de apenas-leitura. Se os repositórios forem, de alguma forma, criados automaticamente no envio, você pode definir "git-create" para true.

Que valor de host passar ao dput, para o envio.

Isto é um nome alcunha, não o nome de máquina real. Você precisa de fornecer a todos os que vão enviar uma configuração dput apropriada. Veja dput.cf(5).

Um bom nome alcunha para a sua máquina de envio é o seu nome de distribuição distro.

Defina isto para o url do seu arquivo de pacote fonte. Esta é a mesma string como aparece no 2º campo de cada entrada do sources.list.
Se você tem uma distribuição pequenina, defina "archive-query" para aptget: (com os dois-pontos).

Se a sua distribuição é grande (ex, se conter uma fração substancial de Debian) então isto não vai ser muito eficiente: com esta definição, o dgit precisa muitas vezes de descarregar e atualizar os ficheiros Sources.

Para distribuições grandes, é melhor implementar a API ftpmaster do arquivo Debian. Veja <https://api.ftp-master.debian.org/>, e defina "archive-query" para ftpmasterapi: (com o :) e "archive-query-url" para o seu URL base da API. O dgit usa estas consultas: suites, dsc_in_suite/isuite/pacote e file_in_archive/pat (assim não precisa de implementar mais nada).

Em alternativa, se o seu sistema suportar o protocolo rmadison, você pode definir "archive-query" para madison:[madison-distro]. O dgit irá invocar rmadison -umadison-distro.

Defina isto para cada uma das suas suites. Você terá de atualizar isto quando forem criadas novas suites. Se você se esquecer, os seus utilizadores podem especificar explicitamente -d distro ao dgit.

REPOSITÓRIO GIT DE MODELOS

Quando o dgit push é usado para pacote na primeira vez, tem de criar um repositório git no servidor git.

Se "git-create" for definido para ssh-cmd, o dgit irá usar o acesso de shell do utilizador ao servidor para cp -a _template.git pacote.git. Assim você deve criar _template.git com conteúdo apropriado.

Note que a runa ssh invocada pelo dgit não faz nenhuma tranca. Assim se duas pessoas usarem dgit push no mesmo pacote ao mesmo tempo, vai haver perdas. Ou nunca façam isso, ou configure dgit-repos-server.

COMANDOS SSH

Quando um utilizador que pode enviar usa o dgit, o dgit usa ssh para aceder ao servidor git.

Para facilitar o uso de comandos restritos do ssh, e para o beneficio de dgit-repos-server, cada comando ssh do dgit começa com uma runa de comentários analisáveis.

Os comandos ssh usados pelo dgit são estes:

: dgit distro git-check pacote ;...
Testa se o pacote já tem um repositório git no servidor. Deve escrever 0 ou 1 e uma nova linha, e termina com estado zero em qualquer caso. O resto do comando, após ;, é uma implementação de shell para este teste. Usado quando "git-check" é definido para ssh-cmd.
: dgit distro git-create pacote ;...
Cria o repositório git para o pacote no servidor. Veja "REPOSITÓRIO GIT DE MODELOS", em cima. O resto do comando é uma invocação apropriada de cd e cp. Usado quando "git-create" é definido para ssh-cmd.
O dgit invoca git para aceder ao repositório; o git depois corre estes comandos. Note que o dgit push irá primeiro fazer uma busca git sobre ssh, assim você tem de fornecer upload-pack assim como receive-pack.

(Existem também outros comandos ssh que são históricos ou obscuros.)

VEJA TAMBÉM

dgit(1)

dgit+tag2upload team Debian Project