build2-community/build2-package

O que build2-package faz?

Resolver ROOT

Seja HERE o diretório que contém este SKILL.md (caminho absoluto a partir do contexto do sistema).

ROOT é a árvore de skills build2. Use o primeiro candidato cujo guides/packaging-guide-summary.md exista:

1. HERE/../build2 (layout lado a lado: este diretório ao lado de uma skill build2, incluindo uma cópia em um diretório de skills do usuário)
2. HERE/../.. (layout aninhado: este diretório sob o subdiretório skills/ da skill build2)

Se nenhum existir, pare.

Todos os caminhos read_file posteriores são ${ROOT}/....

Este arquivo é o procedimento. Os guias de empacotamento em ${ROOT}/guides/ e ${ROOT}/HOWTO/ são a fonte da verdade para como cada etapa é feita. Não invente um layout, uma invocação de bdep new, um nome de branch ou uma sequência de publicação.

Ações externas exigem aprovação explícita

Esta skill cria um pacote real e publicamente visível e eventualmente o publica. Nada que se torne visível fora da sua árvore de trabalho local acontece automaticamente. Isso abrange: criar um repositório no GitHub, qualquer git push (um branch ou uma tag), transferir ou renomear um repositório no GitHub, abrir ou mesclar um pull request, executar bdep ci e executar bdep publish.

Executar /build2-package (ou /build2 package) não é aprovação para nenhuma dessas ações, nem chegar ao portão onde uma delas acontece. Antes de realizar uma delas pela primeira vez nesta execução, pare, declare exatamente o que está prestes a acontecer (o comando e o que ele torna visível externamente) e aguarde a autorização explícita do usuário para essa ação específica. A aprovação para uma ação não se aplica a outra posterior; pergunte novamente a cada vez. Suposição padrão: nenhuma dessas ações acontece, a menos que o usuário peça explicitamente por essa etapa.

Todo o resto – commits locais, criação de branches, edição de arquivos, builds e testes locais, clonagem ou fetch somente leitura – prossegue sem necessidade de permissão.

Regras rígidas

Estas não são opcionais. Violar qualquer uma resulta em falha na execução.

1. Nunca escreva buildfiles do zero. Sempre comece com bdep new. Não use ${ROOT}/scripts/new-package.sh para este fluxo de trabalho.
2. Nunca toque em main após o primeiro commit de bdep new --type empty,third-party até o merge fast-forward de review no momento da publicação.
3. Nunca agrupe (vende) dependências. Desagrupe-as como depends.
4. Nunca coloque alvos principais lib{} / exe{} no buildfile raiz.
5. Nunca faça uma biblioteca ser apenas de cabeçalhos se o upstream distribuir um modo compilado.
6. Nunca pule a receita de distribuição de código-fonte (b dist, depois configure, update, test, clean no arquivo descompactado). bdep ci verde não é suficiente.
7. Nunca rebaixe as linhas geradas depends: * build2 / depends: * bpkg.
8. Nunca adivinhe uma tag upstream, licença ou esquema de inclusão de cabeçalho público. Se não estiver na árvore ou em uma página obtida, pare e pergunte.
9. Um commit git por etapa lógica de empacotamento (ou um grupo estritamente relacionado). Um commit cuja árvore é exatamente uma invocação de bdep new usa essa linha de comando como mensagem de commit, nada mais. Um commit que cria um par de overlay .orig/.patch para um arquivo upstream usa Patch <nome_do_arquivo>: <motivo> (corpo opcional <detalhes> para um patch não trivial) como mensagem, veja packaging-guide-antipatterns.md.
10. Não mescle review em main, não execute bdep release e não execute bdep publish até que os testes locais, testes de caso instalado, testes de distribuição e CI estejam verdes.
11. Todo link simbólico de diretório (não um link simbólico de arquivo comum) precisa de uma entrada symlink=dir correspondente no <pkg>/.gitattributes do próprio pacote (um novo arquivo, bdep new --package não gera um), no mesmo commit que adiciona o link simbólico. Verifique com find <pkg>/ -type l -exec test -d {} \; -print e cruze cada resultado com <pkg>/.gitattributes. O git não registra o tipo de link simbólico e sempre recria um link simbólico de arquivo no checkout, portanto pular isso quebra o pacote em um checkout no Windows.
12. Nunca deixe um comentário ou nota README que narre o processo de empacotamento em si, uma abordagem anterior que não funcionou ou um contratempo ao longo do caminho. Comentários e READMEs refletem apenas o estado final (veja packaging-guide-antipatterns.md, "Não deixe comentários ou notas estilo diário").
13. Nunca crie um repositório, faça push, transfira ou renomeie um repositório no GitHub, abra ou mescle um pull request, execute bdep ci ou execute bdep publish sem a aprovação explícita do usuário para essa ação específica, fornecida no momento (veja "Ações externas exigem aprovação explícita" acima). O padrão é que nenhuma dessas ações aconteça.

Leituras obrigatórias (nesta execução, antes de qualquer escrita)

Leia estes arquivos na íntegra com read_file antes de criar um repositório, editar um buildfile ou publicar. Não leia superficialmente.

1. ${ROOT}/guides/packaging-guide-summary.md
2. ${ROOT}/guides/packaging-guide-testing.md
3. ${ROOT}/guides/packaging-guide-antipatterns.md
4. ${ROOT}/HOWTO/package-naming.md

Em seguida, carregue sob demanda a partir do mapa no final deste arquivo. Nunca substitua a memória por um guia que este arquivo nomeia.

Re-verifique com os documentos de lista de verificação à medida que avança

Uma sequência completa de empacotamento (Portões A-K, ou uma execução new-version/revision) pode abranger muito mais turnos do que uma única janela de contexto comporta. Os turnos anteriores, incluindo as leituras obrigatórias acima, podem já ter sido resumidos quando você chegar a um portão posterior. Ter lido um guia uma vez no início não significa que suas regras ainda estão no contexto; não confie na memória da conversa para elas.

Reabra e re-verifique o estado atual da árvore em relação a estes documentos estilo lista de verificação pelo menos uma vez por portão, e novamente antes do Portão K (momento da publicação):

• ${ROOT}/guides/packaging-guide-antipatterns.md: o que não fazer (buildfiles escritos à mão, correção de upstream no pacote, layout upstream alterado, apenas cabeçalhos apesar de um modo compilado, dependências agrupadas, alvos principais no buildfile raiz, uma revisão muito ampla, inclusão de cabeçalho incorreta, aplicação de patch ad hoc, comentários ou notas estilo diário).
• ${ROOT}/guides/packaging-guide-review.md: a mesma lista de verificação que um revisor do cppget.org aplica. Verifique a árvore em relação a ela antes de publicar, em vez de descobrir durante a revisão real.
• ${ROOT}/HOWTO/third-party-private-headers.md: cabeçalhos privados não devem chegar à árvore de instalação.
• ${ROOT}/HOWTO/buildfile-compile-options.md: quais opções de compilação/link são locais vs exportadas.
• ${ROOT}/HOWTO/package-naming.md: as decisões de nomenclatura tomadas no Portão E; uma renomeação descoberta tarde é cara.
• ${ROOT}/guides/packaging-guide-summary.md Passo 5: todo link simbólico de diretório em cada pacote tem uma entrada symlink=dir no <pkg>/.gitattributes do próprio pacote (Regra rígida 11).

Se a árvore não corresponder mais a um deles, corrija antes de passar para o próximo portão, em vez de carregar o desvio adiante.

Argumentos

$ARGUMENTS é o texto de invocação após /build2-package (ou após /build2 package). Analise-o em ordem. A primeira regra correspondente vence.

Primeiro token	Modo
vazio / omitido	new se o diretório atual já não for um repositório de empacotamento, senão continue
new	sequência de empacotamento inicial
new-version	nova versão upstream após a primeira publicação
revision	revisão de empacotamento (X.Y.Z+R)
continue	retomar a sequência em andamento no diretório atual
qualquer outra coisa	se parecer uma URL git ou owner/repo, trate como new com esse upstream. Caso contrário, pergunte.

Tokens restantes: <upstream-url> opcional e <tag-or-version> opcional. Se algum estiver faltando e for necessário para o modo, pergunte. Não os invente.

Informe o modo escolhido ao usuário antes da primeira escrita.

Modo: continue

Inspecione o diretório atual (e seu histórico git) e retome no primeiro portão incompleto no modo correspondente abaixo. Evidência vence resumo de conversa.

Evidência	Retomar em
Sem .git, ou sem o primeiro commit bdep new --type empty,third-party	new do início
Primeiro commit existe, sem branch review	criar review e continuar new
Em review, sem submódulo upstream/	adicionar upstream
upstream/ presente, sem diretório de pacote / sem bdep new --package	estrutura do pacote
Scaffold do pacote presente, testes ou CI não verdes	testagem
Testes verdes, review não mesclado em main	merge no momento da publicação
Em main após merge, sem tag vX.Y.Z	release e depois publicar
Já publicado, usuário solicitou um novo upstream	new-version
Já publicado, usuário solicitou uma correção de empacotamento	revision

Se o repositório estiver em main com commits de empacotamento que deveriam estar em review, pare. Isso é um erro de processo. Não reescreva histórico publicado. Pergunte ao usuário como recuperar.

Modo: new (sequência inicial)

Siga a lista de verificação em ${ROOT}/guides/packaging-guide-summary.md e as etapas 8-10 em ${ROOT}/guides/packaging-guide-testing.md. Os portões numerados abaixo são aqueles que não devem ser pulados ou reordenados.

Portão A: trabalho existente

Pesquise todos os quatro, nesta ordem, e relate os resultados:

1. https://cppget.org/?advanced-search
2. https://queue.cppget.org
3. https://github.com/build2-packaging
4. https://github.com/build2-packaging/WISHLIST

Se um repositório ou pacote publicado já existir, pare e pergunte se deve juntar-se a esse trabalho (continue / new-version / revision) em vez de iniciar uma duplicata.

Portão B: repositório vazio e primeiro commit

Pare e obtenha aprovação explícita antes das ações externas deste portão: criar o repositório GitHub e enviar o commit inicial para ele. Faça o scaffold local (bdep new, git add, git commit) primeiro se isso ajudar a mostrar o que está prestes a ser enviado, mas não crie o repositório remoto nem execute git push até que o usuário tenha dito para prosseguir.

Crie um repositório git público vazio no espaço de trabalho pessoal do usuário. Descrição: build2 package for <nome>. Clone com SSH. Sem README, sem licença, sem arquivos gerados pelo GitHub.

bdep new --type empty,third-party
git add .
git commit -m "bdep new --type empty,third-party"
git push -u origin main

Verifique antes de continuar:

• git rev-list --max-parents=0 HEAD é este commit.
• git show --stat --format=%s HEAD a mensagem é exatamente bdep new --type empty,third-party.
• A árvore contém apenas arquivos gerados por esse comando.

Se qualquer arquivo extra ou edição manual estiver nesse commit, reset e refaça. O processo de revisão depende disso.

Portão C: branch review

git checkout -b review

Permaneça em review para todos os commits posteriores nesta sequência. Não execute git checkout main. Não mescle. Não faça release. Não publique.

Portão D: submódulo upstream

git submodule add https://github.com/<upstream>/<repo>.git upstream

Use apenas https://. Faça checkout do commit de release (tag). Commit: Add upstream submodule, <tag>.

Portão E: nomes e layout

Leia ${ROOT}/HOWTO/package-naming.md novamente se necessário. Decida e escreva as decisões antes de gerar o pacote:

• Nome do repositório Git: maiúsculas/minúsculas do upstream, sem prefixo build2-, sem sufixo -package.
• project: e project =: minúsculas, a menos que maiúsculas/minúsculas mistas sejam o identificador upstream (Qt é a exceção documentada).
• Pacote name:: prefixo lib para bibliotecas, a menos que tanto Debian quanto upstream tornem impossível um conflito com executável.
• Divida biblioteca vs executável em pacotes separados.
• Esquema de inclusão de cabeçalho público (prefixo de subdiretório vs prefixo de nome de arquivo).
• include/ / src/ combinados vs separados.

Mantenha-se o mais próximo possível do layout upstream.

Portão F: pré-seed e depois bdep new --package

Crie o diretório do pacote. Faça link simbólico apenas para os arquivos de metadados upstream que existem (README.md, LICENSE / equivalente, NEWS / CHANGES / ChangeLog). Faça commit apenas disso. Em seguida:

bdep new --package --lang ... --type lib,...,third-party <nome>

Itere excluindo e re-executando, não editando o scaffold manualmente, até que o layout corresponda. A sub-opção third-party é obrigatória. Faça commit com a linha de comando exata como mensagem.

Se o nome base do changelog não for um nome reconhecido, defina changes-file: manualmente depois. Veja ${ROOT}/HOWTO/package-changes-file.md.

Portão G: versão, manifesto, dependências

• A versão permanece X.Y.Z-a.0.z até bdep release --no-open.
• summary: menos de 70 caracteres, sem palavras evasivas, sem ponto final.
• -tests / -examples / -benchmarks acompanhantes: copie o resumo principal e acrescente (tests) (ou o tipo correspondente). Não o reescreva. Veja ${ROOT}/HOWTO/tests-extra-dependencies.md.
• license: é SPDX (ou other:). Veja ${ROOT}/guides/packaging-license.md.
• Descomente o pré-requisito pkg.cppget.org. Use a seção menos estável que ainda contenha todas as dependências. Não deixe queue.cppget.org em um repositories.manifest duradouro.
• bdep sync -a após edições de depends.
• Cabeçalhos de interface nas bibliotecas públicas deste pacote vão em intf_libs. Todo o resto vai em impl_libs.

Portão H: preencher código-fonte e buildfiles

Preencha a árvore do pacote com código-fonte upstream antes de tocar nos buildfiles: faça link simbólico de arquivos de cabeçalho/fonte individuais primeiro, e faça link simbólico de um subdiretório inteiro apenas quando isso economizar muitos links simbólicos individuais (requer o layout buildfile-in-prefix, veja packaging-guide-antipatterns.md). Siga o exemplo prático em ${ROOT}/guides/packaging-guide-summary.md Passo 5.

Obrigatório: para cada link simbólico de diretório recém-adicionado, adicione uma entrada symlink=dir correspondente ao <pkg>/.gitattributes do próprio pacote (crie o arquivo se ele ainda não existir) no mesmo commit. Verifique com find <pkg>/ -type l -exec test -d {} \; -print e cruze cada resultado. Esta é a Regra rígida 11; pular isso quebra o pacote em um checkout no Windows. Faça commit dos links simbólicos (e .gitattributes) antes de ajustar os buildfiles, para que o rollback seja fácil.

Em seguida, ajuste apenas os arquivos gerados. Preserve a estrutura gerada e os comentários.

Carregue sob demanda:

• cabeçalhos / cabeçalhos privados: ${ROOT}/HOWTO/third-party-private-headers.md
• SONAME / nome de saída: ${ROOT}/HOWTO/buildfile-output-name.md
• opções de compilação / link: ${ROOT}/HOWTO/buildfile-compile-options.md

(Nota: o conteúdo foi truncado na entrada original. A sequência continua com os Portões I, J e K, cobrindo testes, CI e publicação.)