build2-community/build2-package

¿Qué hace build2-package?

Resolver ROOT

Sea HERE el directorio que contiene este SKILL.md (ruta absoluta desde el contexto del sistema).

ROOT es el árbol de habilidades build2. Use el primer candidato cuyo guides/packaging-guide-summary.md exista:

1. HERE/../build2 (disposición de hermano: este directorio junto a una habilidad build2, incluyendo una copia en un directorio de habilidades de nivel de usuario)
2. HERE/../.. (disposición anidada: este directorio bajo el directorio skills/ de la habilidad build2)

Si ninguno existe, deténgase.

Todas las rutas posteriores de read_file son ${ROOT}/....

Este archivo es el procedimiento. Las guías de empaquetado bajo ${ROOT}/guides/ y ${ROOT}/HOWTO/ son la fuente de verdad sobre cómo se realiza cada paso. No invente un diseño, una invocación de bdep new, un nombre de rama o una secuencia de publicación.

Las acciones externas requieren aprobación explícita

Esta habilidad crea un paquete real y visible públicamente y eventualmente lo publica. Nada que se vuelva visible fuera de su propio árbol de trabajo local ocurre automáticamente. Esto cubre: crear un repositorio en GitHub, cualquier git push (una rama o una etiqueta), transferir o renombrar un repositorio en GitHub, abrir o fusionar una solicitud de extracción, ejecutar bdep ci, y ejecutar bdep publish.

Ejecutar /build2-package (o /build2 package) no es aprobación para ninguna de estas acciones, ni tampoco llegar a la puerta donde ocurre una de ellas. Antes de realizar una de ellas por primera vez en esta ejecución, deténgase, indique exactamente lo que está por ocurrir (el comando, y lo que hace visible externamente), y espere la aprobación explícita del usuario para esa acción específica. La aprobación para una de estas acciones no se transfiere a una posterior, pregunte de nuevo cada vez. Suposición predeterminada: ninguna de estas ocurre a menos que el usuario solicite explícitamente ese paso.

Todo lo demás, confirmaciones locales, creación de ramas, edición de archivos, compilaciones y pruebas locales, clonación o recuperación de solo lectura, procede sin preguntar.

Reglas estrictas

Estas no son opcionales. Violar cualquiera de ellas es una ejecución fallida.

1. Nunca escriba buildfiles desde cero. Siempre comience desde bdep new. No use ${ROOT}/scripts/new-package.sh para este flujo de trabajo.
2. Nunca toque main después de la primera confirmación bdep new --type empty,third-party hasta la fusión de avance rápido de review en el momento de la publicación.
3. Nunca agrupe (venda) dependencias. Desagrúpelas como depends.
4. Nunca ponga objetivos lib{} / exe{} principales en el buildfile raíz.
5. Nunca haga una biblioteca solo de encabezados si el upstream distribuye un modo compilado.
6. Nunca omita la receta de distribución de código fuente (b dist, luego configure, update, test, clean en el archivo desempaquetado). bdep ci verde no es suficiente.
7. Nunca baje las líneas generadas depends: * build2 / depends: * bpkg.
8. Nunca adivine una etiqueta upstream, licencia o esquema de inclusión de encabezados públicos. Si no está en el árbol o en una página obtenida, deténgase y pregunte.
9. Una confirmación de git por paso lógico de empaquetado (o un grupo estrechamente relacionado). Una confirmación cuyo árbol es exactamente una invocación de bdep new usa esa línea de comando como el mensaje de confirmación, nada más. Una confirmación que crea un par .orig/.patch superpuesto para un archivo upstream usa Parche <nombre_de_archivo>: <motivo> (cuerpo opcional <detalles> para un parche no trivial) como su mensaje, consulte packaging-guide-antipatterns.md.
10. No fusione review en main, no ejecute bdep release, y no ejecute bdep publish hasta que las pruebas locales, las pruebas de caso instalado, las pruebas de distribución y CI estén en verde.
11. Cada enlace simbólico a nivel de directorio (no un enlace simbólico de archivo plano) necesita una entrada symlink=dir coincidente en el propio <pkg>/.gitattributes de ese paquete (un archivo nuevo, bdep new --package no genera uno), en la misma confirmación que agrega el enlace simbólico. Verifique con find <pkg>/ -type l -exec test -d {} \; -print y coteje cada acierto contra <pkg>/.gitattributes. git no registra el tipo de enlace simbólico y siempre recrea un enlace simbólico de archivo en la verificación, por lo que omitir esto rompe el paquete en una verificación de Windows.
12. Nunca deje un comentario o nota README que narre el proceso de empaquetado en sí mismo, un enfoque anterior que no funcionó, o un percance en el camino. Los comentarios y README reflejan solo el estado final (consulte packaging-guide-antipatterns.md, "No deje comentarios o notas estilo diario").
13. Nunca cree un repositorio, haga push, transfiera o renombre un repositorio en GitHub, abra o fusione una solicitud de extracción, ejecute bdep ci, o ejecute bdep publish sin la aprobación explícita del usuario para esa acción específica, dada en el momento (consulte "Las acciones externas requieren aprobación explícita" arriba). El valor predeterminado es que ninguna de estas ocurra.

Lecturas obligatorias (en este turno, antes de cualquier escritura)

Lea estos archivos en su totalidad con read_file antes de crear un repositorio, editar un buildfile o publicar. No los hojeé.

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

Luego cargue bajo demanda desde el mapa al final de este archivo. Nunca sustituya la memoria por una guía que este archivo nombra.

Vuelva a verificar con los documentos de lista de verificación a medida que avanza

Un tramo de empaquetado completo (Puertas A-K, o una ejecución de new-version/revision) puede abarcar muchos más turnos de los que contiene una sola ventana de contexto. Los turnos anteriores, incluidas las lecturas obligatorias anteriores, pueden estar ya resumidos para cuando llegue a una puerta posterior. Haber leído una guía una vez al principio no significa que sus reglas todavía estén en contexto, no confíe en la memoria de la conversación para ellas.

Vuelva a abrir y vuelva a verificar el estado actual del árbol contra estos documentos de estilo lista de verificación al menos una vez por puerta, y de nuevo justo antes de la Puerta K (momento de publicación):

• ${ROOT}/guides/packaging-guide-antipatterns.md: qué no hacer (buildfiles escritos a mano, arreglar upstream en el paquete, diseño upstream cambiado, solo encabezados a pesar de un modo compilado, dependencias agrupadas, objetivos principales en el buildfile raíz, una revisión demasiado amplia, mala inclusión de encabezados, parches ad hoc, comentarios o notas estilo diario).
• ${ROOT}/guides/packaging-guide-review.md: la misma lista de verificación que un revisor de cppget.org aplica. Autoverifique el árbol contra ella antes de publicar en lugar de descubrirlo durante la revisión real.
• ${ROOT}/HOWTO/third-party-private-headers.md: los encabezados privados no deben llegar al árbol de instalación.
• ${ROOT}/HOWTO/buildfile-compile-options.md: qué opciones de compilación/enlace son locales frente a exportadas.
• ${ROOT}/HOWTO/package-naming.md: las decisiones de nomenclatura tomadas en la Puerta E, un cambio de nombre descubierto tarde es costoso.
• ${ROOT}/guides/packaging-guide-summary.md Paso 5: cada enlace simbólico de directorio en cada paquete tiene una entrada symlink=dir en el propio <pkg>/.gitattributes de ese paquete (Regla estricta 11).

Si el árbol ya no coincide con uno de estos, corríjalo antes de pasar a la siguiente puerta en lugar de arrastrar la desviación hacia adelante.

Argumentos

$ARGUMENTS es el texto de invocación después de /build2-package (o después de /build2 package). Analícelo en orden. La primera regla coincidente gana.

Primer token	Modo
vacío / omitido	new si cwd no es ya un repositorio de empaquetado, si no continue
new	tramo de empaquetado inicial
new-version	nueva versión upstream después de la primera publicación
revision	revisión de empaquetado (X.Y.Z+R)
continue	reanudar el tramo en progreso en cwd
cualquier otra cosa	si parece una URL de git o owner/repo, trátelo como new con ese upstream. De lo contrario, pregunte.

Tokens restantes: <upstream-url> opcional y <tag-or-version> opcional. Si falta alguno y es requerido para el modo, pregunte. No los invente.

Informe el modo elegido al usuario antes de la primera escritura.

Modo: continue

Inspeccione cwd (y su historial de git) y reanude en la primera puerta incompleta en el modo coincidente a continuación. La evidencia vence al resumen de conversación.

Evidencia	Reanudar en
Sin .git, o sin primera confirmación bdep new --type empty,third-party	new desde el principio
Primera confirmación existe, sin rama review	crear review y continuar new
En review, sin submódulo upstream/	añadir upstream
upstream/ presente, sin directorio de paquete / sin bdep new --package	estructura del paquete
Andamio del paquete presente, pruebas o CI no en verde	pruebas
Pruebas en verde, review no fusionado a main	fusión en tiempo de publicación
En main después de la fusión, sin etiqueta vX.Y.Z	liberar luego publicar
Ya publicado, usuario solicitó un nuevo upstream	new-version
Ya publicado, usuario solicitó una corrección de empaquetado	revision

Si el repositorio está en main con confirmaciones de empaquetado que deberían haber estado en review, deténgase. Eso es un error de proceso. No reescriba el historial publicado. Pregunte al usuario cómo recuperarse.

Modo: new (tramo inicial)

Siga la lista de verificación en ${ROOT}/guides/packaging-guide-summary.md y los pasos 8-10 en ${ROOT}/guides/packaging-guide-testing.md. Las puertas numeradas a continuación son las que no deben omitirse ni reordenarse.

Puerta A: trabajo existente

Busque en los cuatro, en este orden, e informe los aciertos:

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

Si ya existe un repositorio o paquete publicado, deténgase y pregunte si unirse a ese trabajo (continue / new-version / revision) en lugar de comenzar un duplicado.

Puerta B: repositorio vacío y primera confirmación

Deténgase y obtenga aprobación explícita antes de las acciones externas de esta puerta: crear el repositorio de GitHub y enviar la confirmación inicial al mismo. Haga el andamio local (bdep new, git add, git commit) primero si eso ayuda a mostrar lo que está a punto de enviarse, pero no cree el repositorio remoto ni ejecute git push hasta que el usuario haya dicho que continúe.

Cree un repositorio git público vacío en el espacio de trabajo personal del usuario. Descripción: build2 package for <name>. Clone con SSH. Sin README, sin licencia, sin archivos generados por 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 es esta confirmación.
• git show --stat --format=%s HEAD el mensaje es exactamente bdep new --type empty,third-party.
• El árbol son solo archivos generados por ese comando.

Si hay algún archivo extra o edición manual en esa confirmación, reinicie y rehaga. El proceso de revisión depende de esto.

Puerta C: rama review

git checkout -b review

Permanezca en review para cada confirmación posterior en este tramo. No git checkout main. No fusione. No libere. No publique.

Puerta D: submódulo upstream

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

Use solo https://. Verifique la confirmación de la versión (etiqueta). Confirme: Add upstream submodule, <tag>.

Puerta E: nombres y diseño

Lea ${ROOT}/HOWTO/package-naming.md de nuevo si es necesario. Decida y escriba las decisiones antes de generar el paquete:

• Nombre del repositorio Git: caso upstream, sin prefijo build2-, sin sufijo -package.
• project: y project =: minúsculas a menos que el caso mixto sea el identificador upstream (Qt es la excepción documentada).
• name: del paquete: prefijo lib para bibliotecas a menos que tanto Debian como upstream hagan imposible un conflicto de ejecutables.
• Dividir biblioteca vs ejecutable en paquetes separados.
• Esquema de inclusión de encabezados públicos (prefijo de subdirectorio vs prefijo de nombre de archivo).
• include/ / src/ combinado vs dividido.

Manténgase lo más cerca posible del diseño upstream.

Puerta F: pre-seed luego bdep new --package

Cree el directorio del paquete. Enlace simbólicamente solo los archivos meta upstream que existan (README.md, LICENSE / equivalente, NEWS / CHANGES / ChangeLog). Confirme eso solo. Luego:

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

Itere eliminando y volviendo a ejecutar, no editando a mano el andamio, hasta que el diseño coincida. La subopción third-party es obligatoria. Confirme con la línea de comando exacta como mensaje.

Si el nombre base del changelog no es un nombre reconocido, establezca changes-file: a mano más tarde. Consulte ${ROOT}/HOWTO/package-changes-file.md.

Puerta G: versión, manifiesto, dependencias

• La versión permanece X.Y.Z-a.0.z hasta bdep release --no-open.
• summary: menos de 70 caracteres, sin palabras comodín, sin punto final.
• -tests / -examples / -benchmarks acompañantes: copie el resumen principal y agregue (tests) (o el tipo correspondiente). No lo reescriba. Consulte ${ROOT}/HOWTO/tests-extra-dependencies.md.
• license: es SPDX (o other:). Consulte ${ROOT}/guides/packaging-license.md.
• Descomente el prerrequisito pkg.cppget.org. Use la sección menos estable que aún contenga cada dependencia. No deje queue.cppget.org en un repositories.manifest de larga duración.
• bdep sync -a después de ediciones de depends.
• Los encabezados de interfaz en los encabezados públicos de esta biblioteca van en intf_libs. Todo lo demás va en impl_libs.

Puerta H: llenar fuente y buildfiles

Llene el árbol del paquete con la fuente upstream antes de tocar los buildfiles: primero enlace simbólicamente archivos de encabezado/fuente individuales, y enlace simbólicamente un subdirectorio completo solo cuando eso ahorre muchos enlaces simbólicos individuales (requiere el diseño buildfile-in-prefix, consulte packaging-guide-antipatterns.md). Siga el ejemplo trabajado en ${ROOT}/guides/packaging-guide-summary.md Paso 5.

Obligatorio: para cada enlace simbólico de directorio recién agregado, agregue una entrada symlink=dir coincidente al propio <pkg>/.gitattributes de ese paquete (cree el archivo si aún no existe) en la misma confirmación. Verifique con find <pkg>/ -type l -exec test -d {} \; -print y coteje cada acierto. Esta es la Regla estricta 11, omitirla rompe el paquete en una verificación de Windows. Confirme los enlaces simbólicos (y .gitattributes) antes de ajustar los buildfiles, para que la reversión sea fácil.

Luego ajuste solo archivos generados. Preserve la estructura generada y los comentarios.

Cargue bajo demanda:

• encabezados / encabezados privados: ${ROOT}/HOWTO/third-party-private-headers.md
• SONAME / nombre de salida: ${ROOT}/HOWTO/package-output-name.md
• opciones de compilación / enlace: ${ROOT}/HOWTO/buildfile-compile-options.md
• parches y superposiciones: ${ROOT}/HOWTO/package-patches.md
• archivos de cambios: ${ROOT}/HOWTO/package-changes-file.md

Puerta I: pruebas locales y de distribución

Ejecute la receta de distribución (b dist; configure, compile, pruebe, limpie en el archivo desempaquetado). Luego ejecute bdep test en cada configuración que cubra todos los objetivos y ejecutables (no solo la biblioteca principal). Luego ejecute bdep test --install en una instalación simulada. Luego "método de prueba de caso instalado" del Paso 10 de packaging-guide-testing.md. Arregle cualquier error antes de llegar a CI.

Puerta J: CI

Deténgase y obtenga aprobación explícita antes de las acciones externas de esta puerta: ejecutar bdep ci (que sube a cppget.org).

No ejecute hasta que las pruebas locales locales y de distribución estén en verde. Luego:

bdep ci -dg pkg.cppget.org --server https://ci.cppget.org

Analice el informe. Si hay errores, arréglelos localmente (o solicite la versión más reciente del CI si cree que es un problema transitorio). No confirme nuevamente en main durante esta iteración. Un resultado verde de CI es necesario pero no suficiente: aún necesita la receta de distribución local y la prueba de caso instalado (Puerta I).

Puerta K: publicar

Deténgase y obtenga aprobación explícita antes de las acciones externas de esta puerta: la fusión de avance rápido de review en main, hacer push tanto de main como de review, ejecutar bdep release y bdep publish.

Antes de ejecutar la publicación, vuelva a verificar todo el árbol del paquete contra ${ROOT}/guides/packaging-guide-review.md, contra ${ROOT}/guides/packaging-guide-antipatterns.md y contra la regla de enlace simbólico de directorio (Regla estricta 11). Corrija cualquier discrepancia.

Luego:

git checkout main
git merge review --ff-only
# Vuelva a verificar que la fusión fue un avance rápido.
git push origin main
git push origin review
bdep release --no-open
bdep publish -d pkg.cppget.org --server https://pkg.cppget.org

Después de la publicación, cree un README en el repositorio (en main, en una confirmación separada). Consulte los README de paquetes existentes en https://github.com/build2-packaging como plantilla: título del paquete, estado de CI, enlaces a cppget.org y al upstream.

Modo: new-version (nueva versión upstream)

Omita las Puertas A-C y comience desde la Puerta D si esta es la primera nueva versión. Para versiones posteriores, omita también B-D a menos que el repositorio necesite una nueva creación (por ejemplo, se eliminó).

Modo: revision (revisión de empaquetado)

Si solo hay que tocar archivos de empaquetado, no es necesario un submódulo upstream fresco. Cree la rama review desde main si no existe. Toda la confirmación y el desarrollo permanecen en review.

No invente una versión de revisión. Pregunte al usuario qué versión de revisión va a ser (X.Y.Z+<rev>).

MAPA DE RECURSOS BAJO DEMANDA

A continuación se enumeran los archivos auxiliares que el procedimiento anterior referencias pero que no forman parte de las lecturas obligatorias del turno inicial. Cárguelos con read_file cuando el flujo de trabajo alcance una sección que los nombre (por ejemplo, justo antes de la Puerta G, cargue el archivo de licencia; justo antes de H, cargue el archivo de encabezados privados; etc.).

• ${ROOT}/guides/packaging-license.md
• ${ROOT}/HOWTO/package-changes-file.md
• ${ROOT}/HOWTO/package-output-name.md
• ${ROOT}/HOWTO/package-patches.md
• ${ROOT}/HOWTO/tests-extra-dependencies.md
• ${ROOT}/HOWTO/third-party-private-headers.md
• ${ROOT}/HOWTO/buildfile-compile-options.md
• ${ROOT}/HOWTO/package-naming.md (ya enumerado en las lecturas obligatorias; incluido aquí para actualizaciones en puertas posteriores)

Importante: No cargue todo el mapa al inicio. Cargue solo cuando el trabajo llegue a la sección que lo necesita. La ventana de contexto es limitada.