build2-package은(는) 무엇을 하나요?
ROOT 확인
HERE는 이 SKILL.md가 포함된 디렉터리입니다 (시스템 컨텍스트 기준 절대 경로).
ROOT는 build2 스킬 트리입니다. 다음 후보 중 guides/packaging-guide-summary.md가 존재하는 첫 번째 것을 사용하세요:
HERE/../build2(형제 레이아웃: 이 디렉터리가build2스킬 옆에 있음. 사용자 레벨 스킬 디렉터리에 복사된 경우 포함)HERE/../..(중첩 레이아웃: 이 디렉터리가build2스킬의skills/하위 디렉터리에 있음)
둘 다 없으면 중단합니다.
모든 이후 read_file 경로는 ${ROOT}/...입니다.
이 파일은 절차서입니다. ${ROOT}/guides/와 ${ROOT}/HOWTO/ 아래의 패키징 가이드가 각 단계 수행 방법에 대한 진실 공급원입니다. 레이아웃, bdep new 호출, 브랜치 이름, 게시 순서를 임의로 만들지 마십시오.
외부 작업에는 명시적 승인이 필요합니다.
이 스킬은 실제로 공개적으로 보이는 패키지를 생성하고 최종적으로 게시합니다. 사용자 로컬 작업 트리 밖에서 보이는 작업은 자동으로 수행되지 않습니다. 여기에는 GitHub 저장소 생성, git push (브랜치 또는 태그), GitHub 저장소 전송 또는 이름 변경, 풀 리퀘스트 열기/병합, bdep ci 실행, bdep publish 실행이 포함됩니다.
/build2-package(또는 /build2 package) 실행은 이러한 작업에 대한 승인이 아니며, 해당 작업이 발생하는 게이트에 도달하는 것도 승인이 아닙니다. 이번 실행에서 처음으로 이러한 작업 중 하나를 수행하기 전에, 정확히 무엇이 발생할지(명령어와 외부에 공개되는 내용)를 명시하고, 해당 특정 작업에 대한 사용자의 명시적 승인을 기다리십시오. 한 작업에 대한 승인은 이후 작업으로 이어지지 않으며, 매번 다시 물어보십시오. 기본 가정: 사용자가 명시적으로 해당 단계를 요청하지 않는 한 이러한 작업은 발생하지 않습니다.
로컬 커밋, 브랜치 생성, 파일 편집, 로컬 빌드 및 테스트, 읽기 전용 클론 또는 페치 등 나머지 모든 작업은 질문 없이 진행됩니다.
엄격한 규칙
이 규칙은 선택 사항이 아닙니다. 하나라도 위반하면 실행이 실패한 것입니다.
- 절대
buildfile을 처음부터 작성하지 마십시오. 항상bdep new로 시작하십시오. 이 워크플로우에서는${ROOT}/scripts/new-package.sh를 사용하지 마십시오. - 첫 번째
bdep new --type empty,third-party커밋 이후부터 게시 시점의review브랜치 fast-forward 병합까지main브랜치를 건드리지 마십시오. - 절대 종속성을 번들(벤더)하지 마십시오.
depends로 언번들하십시오. - 루트
buildfile에 주lib{}/exe{}대상을 절대 두지 마십시오. - 업스트림이 컴파일 모드를 제공하는 경우 라이브러리를 헤더 전용으로 만들지 마십시오.
- 소스 배포 레시피(
b dist, 그 후 압축 풀린 아카이브에서configure,update,test,clean)를 절대 건너뛰지 마십시오. 초록색bdep ci만으로는 충분하지 않습니다. - 생성된
depends: * build2/depends: * bpkg줄을 절대 낮추지 마십시오. - 업스트림 태그, 라이선스 또는 공개 헤더 포함 체계를 절대 추측하지 마십시오. 트리나 가져온 페이지에 없으면 중단하고 질문하십시오.
- 논리적 패키징 단계(또는 밀접하게 관련된 그룹)당 하나의 git 커밋을 만드십시오. 트리가 정확히 하나의
bdep new호출인 커밋은 해당 명령줄을 커밋 메시지로 사용하고 다른 것은 사용하지 않습니다. 하나의 업스트림 파일에 대해.orig/.patch오버레이 쌍을 생성하는 커밋은Patch <filename>: <reason>(선택적<details>본문, 복잡하지 않은 패치의 경우)을 메시지로 사용합니다. packaging-guide-antipatterns.md를 참조하십시오. - 로컬 테스트, 설치 사례 테스트, 배포 테스트, CI가 모두 통과할 때까지
review를main에 병합하지 말고,bdep release를 실행하지 말고,bdep publish를 실행하지 마십시오. - 모든 디렉터리 레벨 심볼릭 링크(일반 파일 심볼릭 링크가 아님)는 해당 패키지의
<pkg>/.gitattributes(새 파일,bdep new --package는 생성하지 않음)에 일치하는symlink=dir항목이 있어야 하며, 심볼릭 링크를 추가하는 동일한 커밋에서 처리해야 합니다.find <pkg>/ -type l -exec test -d {} \; -print로 확인하고 모든 결과를<pkg>/.gitattributes와 교차 확인하십시오.git은 심볼릭 링크 유형을 기록하지 않으며 체크아웃 시 항상 파일 심볼릭 링크를 다시 생성하므로, 이를 건너뛰면 Windows 체크아웃에서 패키지가 손상됩니다. - 패키징 프로세스 자체, 작동하지 않은 이전 접근 방식, 또는 과정 중의 실수에 대해 설명하는 주석이나 README 메모를 절대 남기지 마십시오. 주석과 README는 최종 상태만 반영합니다(packaging-guide-antipatterns.md의 "일기 스타일 주석이나 메모를 남기지 마십시오" 참조).
- 사용자의 해당 특정 작업에 대한 명시적 승인 없이 GitHub 저장소를 생성, 푸시, 전송 또는 이름 변경하거나, 풀 리퀘스트를 열거나 병합하거나,
bdep ci를 실행하거나,bdep publish를 실행하지 마십시오. 승인은 그 시점에 주어져야 합니다(위의 "외부 작업에는 명시적 승인이 필요합니다" 참조). 기본값은 이러한 작업이 발생하지 않는 것입니다.
필수 읽기 (이번 턴, 쓰기 전)
저장소를 생성하거나, buildfile을 편집하거나, 게시하기 전에 다음 파일을 read_file로 전체 읽으십시오. 훑어보지 마십시오.
${ROOT}/guides/packaging-guide-summary.md${ROOT}/guides/packaging-guide-testing.md${ROOT}/guides/packaging-guide-antipatterns.md${ROOT}/HOWTO/package-naming.md
그런 다음 이 파일 끝의 맵에서 필요할 때 로드하십시오. 이 파일이 이름을 지정하는 가이드를 메모리로 대체하지 마십시오.
진행하면서 체크리스트 문서와 다시 확인
전체 패키징 스트레치(게이트 A-K, 또는 new-version/revision 실행)는 단일 컨텍스트 창이 보유할 수 있는 것보다 훨씬 많은 턴에 걸칠 수 있습니다. 이후 게이트에 도달할 때쯤이면 위의 필수 읽기를 포함한 이전 턴이 이미 요약되어 사라졌을 수 있습니다. 처음에 가이드를 한 번 읽었다고 해서 그 규칙이 여전히 컨텍스트에 있다는 것을 의미하지 않으므로 대화 기억에 의존하지 마십시오.
적어도 게이트당 한 번, 그리고 게이트 K(게시 시점) 직전에 현재 트리 상태를 다음 체크리스트 스타일 문서와 다시 열고 다시 확인하십시오:
${ROOT}/guides/packaging-guide-antipatterns.md: 하지 말아야 할 것 (수동 작성 buildfile, 패키지에서 업스트림 수정, 변경된 업스트림 레이아웃, 컴파일 모드가 있음에도 헤더 전용, 번들된 종속성, 루트 buildfile의 메인 대상, 과도하게 광범위한 리비전, 잘못된 헤더 포함, 임시 패치, 일기 스타일 주석 또는 메모).${ROOT}/guides/packaging-guide-review.md: cppget.org 리뷰어가 적용하는 동일한 체크리스트. 실제 리뷰 중에 발견하기보다는 게시 전에 트리를 확인하십시오.${ROOT}/HOWTO/third-party-private-headers.md: 비공개 헤더는 설치 트리에 도달해서는 안 됩니다.${ROOT}/HOWTO/buildfile-compile-options.md: 로컬 vs 내보내기 컴파일/링크 옵션.${ROOT}/HOWTO/package-naming.md: 게이트 E에서 결정된 이름 지정, 늦게 발견된 이름 변경은 비용이 많이 듭니다.${ROOT}/guides/packaging-guide-summary.md5단계: 모든 패키지의 모든 디렉터리 심볼릭 링크는 해당 패키지의<pkg>/.gitattributes에symlink=dir항목이 있습니다(엄격한 규칙 11).
트리가 더 이상 이 중 하나와 일치하지 않으면, 다음 게이트로 이동하기 전에 수정하고 차이를 그대로 유지하지 마십시오.
인수
$ARGUMENTS는 /build2-package(또는 /build2 package) 뒤의 호출 텍스트입니다. 순서대로 구문 분석하십시오. 첫 번째 일치 규칙이 우선합니다.
| 첫 번째 토큰 | 모드 |
|---|---|
| 비어 있음 / 생략됨 | 현재 작업 디렉터리가 이미 패키징 저장소가 아니면 new, 아니면 continue |
new | 초기 패키징 스트레치 |
new-version | 첫 번째 게시 후 새 업스트림 버전 |
revision | 패키징 리비전 (X.Y.Z+R) |
continue | 현재 작업 디렉터리에서 진행 중인 스트레치 재개 |
| 그 외 | git URL 또는 owner/repo처럼 보이면 해당 업스트림으로 new로 처리. 그렇지 않으면 질문. |
나머지 토큰: 선택적 <upstream-url> 및 선택적 <tag-or-version>. 모드에 필요하지만 누락된 경우 질문하십시오. 임의로 만들지 마십시오.
선택한 모드를 첫 번째 쓰기 전에 사용자에게 보고하십시오.
모드: continue
현재 작업 디렉터리(및 git 히스토리)를 검사하고 아래 일치 모드에서 첫 번째 미완료 게이트에서 재개하십시오. 증거가 대화 요약보다 우선합니다.
| 증거 | 재개 지점 |
|---|---|
.git 없음, 또는 bdep new --type empty,third-party 첫 번째 커밋 없음 | 처음부터 new |
첫 번째 커밋 존재, review 브랜치 없음 | review 생성 및 new 계속 |
review에 있음, upstream/ 서브모듈 없음 | 업스트림 추가 |
upstream/ 존재, 패키지 디렉터리 / bdep new --package 없음 | 패키지 구조 |
| 패키지 스캐폴드 존재, 테스트 또는 CI 통과하지 못함 | 테스트 |
테스트 통과, review가 main에 병합되지 않음 | 게시 시점 병합 |
병합 후 main에 있음, vX.Y.Z 태그 없음 | 릴리즈 후 게시 |
| 이미 게시됨, 사용자가 새 업스트림 요청 | new-version |
| 이미 게시됨, 사용자가 패키징 수정 요청 | revision |
저장소가 main에 있고 review에 있어야 할 패키징 커밋이 있으면 중단하십시오. 이는 프로세스 오류입니다. 게시된 히스토리를 다시 쓰지 마십시오. 복구 방법을 사용자에게 질문하십시오.
모드: new (초기 스트레치)
${ROOT}/guides/packaging-guide-summary.md의 체크리스트와 ${ROOT}/guides/packaging-guide-testing.md의 8-10단계를 따르십시오. 아래 번호가 매겨진 게이트는 건너뛰거나 순서를 바꿀 수 없는 게이트입니다.
게이트 A: 기존 작업
네 곳을 모두 순서대로 검색하고 결과를 보고하십시오:
https://cppget.org/?advanced-searchhttps://queue.cppget.orghttps://github.com/build2-packaginghttps://github.com/build2-packaging/WISHLIST
저장소 또는 게시된 패키지가 이미 존재하면 중단하고 중복을 시작하는 대신 해당 작업에 참여할지(continue / new-version / revision) 질문하십시오.
게이트 B: 빈 저장소 및 첫 번째 커밋
이 게이트의 외부 작업 전에 중단하고 명시적 승인을 받으십시오: GitHub 저장소 생성 및 초기 커밋 푸시. 로컬 스캐폴드(bdep new, git add, git commit)를 먼저 수행하여 푸시될 내용을 보여주는 데 도움이 될 수 있지만, 사용자가 진행하라고 말할 때까지 원격 저장소를 생성하거나 git push를 실행하지 마십시오.
사용자의 개인 작업 공간에 빈 공개 git 저장소를 생성하십시오. 설명: build2 package for <name>. SSH로 클론하십시오. README, 라이선스, GitHub 생성 파일이 없습니다.
bdep new --type empty,third-party
git add .
git commit -m "bdep new --type empty,third-party"
git push -u origin main
계속하기 전에 확인하십시오:
git rev-list --max-parents=0 HEAD는 이 커밋입니다.git show --stat --format=%s HEAD메시지는 정확히bdep new --type empty,third-party입니다.- 트리는 해당 명령으로 생성된 파일만 있습니다.
해당 커밋에 추가 파일이나 수동 편집이 있으면 재설정하고 다시 수행하십시오. 리뷰 프로세스는 이에 의존합니다.
게이트 C: 리뷰 브랜치
git checkout -b review
이 스트레치의 모든 이후 커밋에 대해 review 브랜치에 남아 있으십시오. git checkout main을 하지 마십시오. 병합하지 마십시오. 릴리즈하지 마십시오. 게시하지 마십시오.
게이트 D: 업스트림 서브모듈
git submodule add https://github.com/<upstream>/<repo>.git upstream
https://만 사용하십시오. 릴리즈 커밋(태그)을 체크아웃하십시오. 커밋: Add upstream submodule, <tag>.
게이트 E: 이름 및 레이아웃
필요하면 ${ROOT}/HOWTO/package-naming.md를 다시 읽으십시오. 결정하고 패키지 생성 전에 결정 사항을 기록하십시오:
- Git 저장소 이름: 업스트림 케이스,
build2-접두사 없음,-package접미사 없음. project:및project =: 소문자, 단, 대소문자 혼용이 업스트림 식별자인 경우는 예외(Qt가 문서화된 예외).- 패키지
name:: 라이브러리의 경우lib접두사, 단, Debian과 업스트림 모두 실행 파일 충돌을 불가능하게 만드는 경우는 제외. - 라이브러리와 실행 파일을 별도 패키지로 분할.
- 공개 헤더 포함 체계 (하위 디렉터리 접두사 vs 파일명 접두사).
- 결합 vs 분할
include//src/.
가능한 한 업스트림 레이아웃에 가깝게 유지하십시오.
게이트 F: 사전 시드 후 bdep new --package
패키지 디렉터리를 생성하십시오. 존재하는 업스트림 메타 파일만 심볼릭 링크하십시오 (README.md, LICENSE / 동등, NEWS / CHANGES / ChangeLog). 그것만 커밋하십시오. 그런 다음:
bdep new --package --lang ... --type lib,...,third-party <name>
수동으로 스캐폴드를 편집하는 대신 삭제하고 다시 실행하여 레이아웃이 일치할 때까지 반복하십시오. third-party 하위 옵션은 필수입니다. 정확한 명령줄을 메시지로 하여 커밋하십시오.
변경 로그 기본 이름이 인식된 이름이 아니면 나중에 changes-file:을 수동으로 설정하십시오. ${ROOT}/HOWTO/package-changes-file.md를 참조하십시오.
게이트 G: 버전, 매니페스트, 종속성
bdep release --no-open까지 버전은X.Y.Z-a.0.z로 유지됩니다.summary: 70자 미만, 애매한 표현 없음, 마침표로 끝나지 않음.- 관련
-tests/-examples/-benchmarks: 메인 요약을 복사하고(tests)(또는 일치하는 종류)를 추가하십시오. 다시 작성하지 마십시오.${ROOT}/HOWTO/tests-extra-dependencies.md를 참조하십시오. license:는 SPDX(또는other:)입니다.${ROOT}/guides/packaging-license.md를 참조하십시오.pkg.cppget.org사전 조건의 주석을 해제하십시오. 모든 종속성을 포함하는 가장 덜 안정적인 섹션을 사용하십시오. 장기repositories.manifest에queue.cppget.org를 남기지 마십시오.depends편집 후bdep sync -a를 실행하십시오.- 이 라이브러리의 공개 헤더에 있는 인터페이스 헤더는
intf_libs에 넣으십시오. 나머지는 모두impl_libs에 넣으십시오.
게이트 H: 소스 및 빌드 파일 채우기
빌드 파일을 건드리기 전에 업스트림 소스로 패키지 트리를 채우십시오: 먼저 개별 헤더/소스 파일을 심볼릭 링크하고, 많은 개별 심볼릭 링크를 저장할 때만 전체 하위 디렉터리를 심볼릭 링크하십시오(buildfile-in-prefix 레이아웃 필요, packaging-guide-antipatterns.md 참조). ${ROOT}/guides/packaging-guide-summary.md 5단계의 작업 예제를 따르십시오.
필수: 방금 추가한 모든 디렉터리 심볼릭 링크에 대해 동일한 커밋에서 해당 패키지의 <pkg>/.gitattributes에 일치하는 symlink=dir 항목을 추가하십시오(파일이 없으면 생성). find <pkg>/ -type l -exec test -d {} \; -print로 확인하고 모든 결과를 교차 확인하십시오. 이는 엄격한 규칙 11이며, 건너뛰면 Windows 체크아웃에서 패키지가 손상됩니다. 빌드 파일을 조정하기 전에 심볼릭 링크(및 .gitattributes)를 커밋하여 롤백이 쉽도록 하십시오.
그런 다음 생성된 파일만 조정하십시오. 생성된 구조와 주석을 유지하십시오.
필요 시 로드:
- 헤더 / 비공개 헤더:
${ROOT}/HOWTO/third-party-private-headers.md - SONAME / 출력 이름:
${ROOT}/HOWTO/package-soname.md - 컴파일 옵션:
${ROOT}/HOWTO/buildfile-compile-options.md - 패키지 전용(예: config, install):
${ROOT}/HOWTO/buildfile-configure-install.md - 라이선스 및 저작권 헤더 주석:
${ROOT}/HOWTO/license-and-copyright-comments.md - 알고리즘 또는 엄격한 종속성:
${ROOT}/HOWTO/tests-extra-dependencies.md
게이트 I: 로컬 테스트
다음을 순서대로 실행하십시오. 각 단계가 성공해야만 다음 단계로 진행하십시오:
- 빌드 확인:
b가 오류 없이 완료됩니다. - 테스트 실행:
b test가 오류 없이 완료됩니다. - 클린:
b clean이 오류 없이 완료됩니다. - 소스 배포:
b dist: ...를 실행하고, tarball을 임시 디렉터리에 풀고,configure && b update && b test && b clean을 실행하십시오. 이는 엄격한 규칙 6입니다. - 설치 사례 테스트:
${ROOT}/guides/packaging-guide-testing.md8단계를 따르십시오.
게이트 J: CI
CI 실행을 위한 Git 푸시를 준비하십시오. 중단하고 명시적 승인을 받으십시오.bdep ci를 실행하십시오. 초록색이 될 때까지 반복하고 게이트 I로 돌아가서 b dist를 다시 확인하십시오.
게이트 K: 게시
게시 순서를 준비하십시오. 중단하고 각 외부 작업에 대해 명시적 승인을 받으십시오:
review를main으로 fast-forward 병합 (review에서git checkout main && git merge review). PR을 열지 마십시오.bdep release --no-open을 실행하십시오.- 태그를 푸시하십시오:
git push origin main --tags bdep publish를 실행하십시오. 사용자 개인 cppget.org 인증이 필요합니다(사용자가 이를 설정했어야 함).
모드: new-version (새 업스트림 버전)
기존 패키지 저장소에서 실행됩니다. ${ROOT}/guides/packaging-guide-summary.md의 체크리스트를 따르지만 다음 게이트만 거치십시오:
- 게이트 B 건너뛰기 (저장소가 이미 존재함).
- 게이트 C 건너뛰기 (
review브랜치가 이미 존재해야 함. 존재하지 않으면 사용자에게 알리고 생성). - 게이트 D에서 업스트림 서브모듈을 새 태그로 업데이트.
git submodule update --remote upstream을 실행하고 새 태그를 체크아웃하십시오. 커밋:Update upstream submodule, <previous-tag> -> <new-tag>. - 게이트 F 건너뛰기 (패키지 구조가 이미 존재함).
- 게이트 E에서 버전을 새 업스트림 버전으로 업데이트하고 필요시 종속성을 업데이트하십시오.
- 게이트 H에서 필요한 소스/빌드 파일 변경 수행.
- 게이트 I, J, K는 그대로 따르십시오.
모드: revision (패키징 수정)
기존 패키지 저장소에서 실행됩니다. ${ROOT}/guides/packaging-guide-summary.md의 체크리스트를 따르지만 다음 게이트만 거치십시오:
- 게이트 B 건너뛰기 (저장소가 이미 존재함).
- 게이트 C 건너뛰기 (
review브랜치가 이미 존재해야 함. 존재하지 않으면 사용자에게 알리고 생성). - 게이트 D 건너뛰기 (업스트림 변경 없음).
- 게이트 E에서 패키지 리비전 번호를 증가시키십시오 (
X.Y.Z+R에서+R부분). - 게이트 H에서 수정을 수행하십시오.
- 게이트 I, J, K는 그대로 따르십시오.
문제 해결 및 복구
복구: 게시 전 커밋 분할
커밋이 너무 큽니다(하나의 논리적 단계보다 더 많은 변경 포함). 가장 최근 커밋부터 시작하십시오:
git reset HEAD~— 변경 사항을 스테이징 해제하고 작업 디렉터리에 보존합니다.- 논리적 그룹으로
git add하고 각각 메시지와 함께git commit하십시오.
각 커밋의 트리가 엄격한 규칙을 준수하는지 확인하십시오.
복구: 실패한 게시
bdep publish가 네트워크 오류, 인증 실패 등으로 실패했습니다. 로컬 상태가 깨끗하면 다시 시도하십시오. 게시 저장소가 이미 업데이트되었다고 의심되면 사용자에게 문의하십시오. 태그를 다시 푸시하거나 이미 게시한 버전을 다시 게시하지 마십시오.
복구: 잘못된 병합
review가 이미 main에 병합되었지만 게시되지 않았습니다. 잘못된 커밋을 되돌리려면 git revert를 사용하십시오(히스토리 다시 쓰기 금지). 그런 다음 review 브랜치를 수정하고 게이트 J에서 다시 시작하십시오.
알려진 문제
bdep new --package는 때때로 빈buildfile을 생성합니다. 이는 게이트 H에서 채워야 합니다.- 일부 업스트림 저장소에는 적절한 릴리즈 태그가 없습니다. 사용자에게 문의하고 수동으로 태그하거나 커밋 SHA를 사용하십시오.
- 타사 라이선스 파일이 항상 SPDX 형식과 일치하지 않을 수 있습니다. 확인하고 필요한 경우
other:접두사를 사용하십시오.