```
본 문서는
D:\llama agent\tweak\하위 모든 트윅 프로젝트(<TweakName>)에 공통 적용되는 표준 아키텍처, 빌드 파이프라인, deb 패키징 규격, RootHide 런타임 호환성 및 트러블슈팅 가이드이다. ```
```
```
- 템플릿 대상:
D:\llama agent\tweak\<TweakName> - 현재 트윅 인스턴스: (
<TweakName> 원본 정보) - 로컬 경로:
D:\llama agent\tweak\<TweakName> - Git 저장소:
D:\llama agent\tweak\<TweakName>\.git - 타겟 환경: Relaxin / RootHide / iOS 18.7.1 (22H31)
- 지원 아키텍처:
arm64e - 현재 패키지 버전: 최신 빌드 버전
- 프로젝트 상태: 검증 완료 (Stable)
```
```
모든 트윅 프로젝트는 아래의 표준 디렉터리 구조를 반드시 준수해야 한다: ```
<TweakName>\
├── PROJECT.md # 트윅 프로젝트 규격서 및 상태 문서
├── <TweakName>.deb # 원본 패키지 레퍼런스 (불변 보존)
├── .git\ # 로컬 Git 형상 관리
├── extracted\ # 원본 패키지 분석 및 역공학 레퍼런스
├── src\ # 최신 개발 소스코드 (Makefile, Tweak.xm, control, layout 등)
├── build\ # 빌드 완료된 산출물 deb 패키지
├── mcp\ # MCP / 외부 참조 소스 및 문서
├── logs\ # 런타임 로그, 크래시 리포트(ips), 진단 결과
├── temp\ # 임시/스테이징 작업 파일 (작업 완료 후 정리)
└── docs\ # 검증된 기술 지식, 원인 분석 보고서
```
- 규칙: 프로젝트 루트에는
PROJECT.md, 원본.deb, 테스트 이미지 및 상기 지정된 디렉터리 외의 임시 파일/중간 빌드 잔여물을 절대 방치하지 않는다. 모든 중간 작업은temp\내에서만 수행한다.
```
```
- VM 사양: VMware Player /
D:\vm\macOS 14.vmx - SSH 호스트:
csw@192.168.1.21(SSH 키 기반 무비밀번호 인증) - THEOS 경로:
/Users/csw/theos - ldid 경로:
/usr/local/bin/ldid
# VM 백그라운드 시작
& "C:\Program Files (x86)\VMware\VMware Player\vmrun.exe" -T player start "D:\vm\macOS 14.vmx" nogui
```
# SSH 연결 확인 (30~60초 대기 후)
ssh csw@192.168.1.21 "echo connected" ```
- 절대 금지:
scp -r "src\*" csw@192.168.1.21:<VM_DIR>/(하위 폴더 구조 깨짐) - 올바른 동기화: 각 모듈 및 디렉터리 단위로 명시적 복사 수행
scp -r "D:\llama agent\tweak\<TweakName>\src\Hooks" csw@192.168.1.21:<VM_DIR>/src/
scp -r "D:\llama agent\tweak\<TweakName>\src\Manager" csw@192.168.1.21:<VM_DIR>/src/
scp "D:\llama agent\tweak\<TweakName>\src\Makefile" csw@192.168.1.21:<VM_DIR>/Makefile
scp -r "D:\llama agent\tweak\<TweakName>\src\layout" csw@192.168.1.21:<VM_DIR>/ ```
Windows 환경에서 scp로 복사 시 권한이 707로 생성되어 빌드 실패의 원인이 되므로 권한 재설정 필수:
ssh csw@192.168.1.21 "chmod -R 755 <VM_DIR>/layout/DEBIAN" ```
- Qwen 연산 연속성 보호: 로컬 LLM(llama.cpp) 특성상 방대한 컨텍스트 처리 시 응답에 수분이 소요될 수 있다.
- 타임아웃 발생 시 대응 원칙:
- MCP 레이어에서 타임아웃(
context deadline exceeded등) 에러가 발생하더라도 절대 기계적으로abort를 호출하지 않는다. - 반드시
opencode_session_list의 output 토큰 증가 여부나 VM 내 파일 생성/수정 상태를 확인하여 Qwen이 여전히 연산/실행 중인지 확인하고 기다린다. - 토큰 수치(output 토큰 증가 여부)가 변화 없거나 VM 파일 생성 상태가 변하지 않으면 abort 시킨다.
- MCP 레이어에서 타임아웃(
```
```
SSH Non-interactive 쉘에서는 .zshrc가 자동 로드되지 않으므로 필수 환경변수와 PATH를 명시적으로 로드해야 한다:
ssh csw@192.168.1.21 'source ~/.zshrc && export PATH="/usr/local/bin:$PATH" && cd <VM_DIR> && make clean && make package THEOS_PACKAGE_SCHEME=roothide' ```
ARCHS및TARGET을 명령행에서 임의로 오버라이드하지 않는다. Makefile 기본값(arm64e, SDK 버전)을 유지한다.- RootHide 빌드에서는
/var/jb와 같은 rootless 전용 종속 경로가 바이너리 또는 설정 파일에 하드코딩되지 않도록 주의한다.
```
```
iOS 패키지 관리자(dpkg, Sileo, Zebra, Filza)는 데비안 아카이브 규격을 매우 엄격하게 파싱합니다. 아래 규격을 단 하나라도 위반하면 bad deb 또는 is not a deb format archive 오류로 설치가 거부됩니다.
```
- 치명적 오류 원인: macOS 터미널에서 기본
ar rcs <pkg>.deb ...실행 시, macOS BSD ar가 아카이브 첫 번째 멤버로__.SYMDEF SORTED심볼 테이블을 삽입하고 멤버명을#1/NN장명 헤더로 변경함. - dpkg 요구 조건: 아카이브의 첫 번째 멤버는 정확히
debian-binary(16 bytes 공백 패딩, 크기 4, 내용2.0)이어야 함. 첫 멤버가 다른 파일이면 즉시bad deb판정. - 표준 ar 멤버 구성 (순서 필수):
- Magic:
!<arch>(8 bytes) - Member 1:
debian-binary(4 bytes,2.0) - Member 2:
control.tar.*(gzip, xz, zst 지원) - Member 3:
data.tar.*(gzip, xz, zst 지원)
- Magic:
- 해결 방안: Theos/Procursus
dpkg-deb -b를 사용하거나, 검증된 순수 GNU ar Python 빌더(create_deb.py)를 통해 생성한다.
- 절대 금지:
DEBIAN상위 폴더 자체를 tar로 묶는 행위 (tar czf control.tar.gz DEBIAN)- 아카이브 내부 경로가
DEBIAN/control이 되면, dpkg가 루트에서 메타데이터 파일을 찾지 못해bad deb (missing control file)로 거부함.
- 아카이브 내부 경로가
- 올바른 방식: 반드시
DEBIAN디렉터리 내부로 진입(cd)하여 아카이브 루트가 직접./control(또는control)이 되도록 묶어야 함:cd /path/to/DEBIAN && tar -czf ../control.tar.gz --format=gnu .
- 검증: 아카이브 목록 조회 시 멤버가 반드시
.,./control형태로 나타나야 함.
- 검증: 아카이브 목록 조회 시 멤버가 반드시
- 파일 경로는 아카이브 루트 기준
./Library,./var처럼./접두사를 포함하는 상대경로로 구성해야 함:cd /path/to/staging && tar -czf ../data.tar.gz --format=gnu ./Library ./var
```
```
- 크래시 메커니즘:
RootHide의
roothidepatch.dylib(PatchLoader)는 dylib 로드 시 동일 디렉터리에<binary>.roothidepatch파일이 존재하면(lstat == 0) 동적 패치 대상으로 인식하고 JIT 활성화를 요구함:snprintf(patcher, sizeof(patcher), "%s.roothidepatch", path); if (lstat(patcher, &st) == 0) { assert(PLRequiredJIT() == 0); // <-- JIT 활성화 실패 시 SIGABRT 크래시 발생 void *handler = dlopen(patcher, RTLD_NOW); }
- Dopamine 3 / iOS 18 환경의 SpringBoard는 JIT 활성화(
jbdProcessEnableJIT)를 지원하지 않으므로, 내용이 없는 0바이트 빈.roothidepatch파일이 패키지에 남아있으면 즉시assert가 발동되어 SpringBoard가SIGABRT로 죽고 세이프모드로 진입함. - 규칙: 실제 패치 실행 코드가 없는 0바이트 빈
.roothidepatch파일(심볼릭 링크 포함)은 패키지에 절대 포함하지 않는다.
- iOS 18 (macOS 15+) dyld는 바이너리의
LC_RPATH중복을 허용하지 않음. 동일 경로가 2회 이상 나타나면 치명적 로드 거부(duplicate LC_RPATH) 오류를 발생시킴. - RootHide 패치 과정에서
/var/jb가@loader_path/.jbroot로 치환되면서 기존 RPATH와 중복될 수 있으므로, FAT 바이너리의 모든 슬라이스(arm64e)에서 중복 RPATH가 완전히 제거되었는지 검증해야 함. - 각 슬라이스당 고유한 RPATH(
@loader_path/.jbroot/Library/Frameworks,@loader_path/.jbroot/usr/lib)만 정확히 1회씩 유지.
```
```
빌드 완료된 .deb 패키지를 기기에 전달하기 전, 아래 5대 검증을 반드시 통과해야 한다:
```
- 포맷 검증 (GNU ar):
- 첫 3개 멤버가
debian-binary,control.tar.*,data.tar.*순서인가? - BSD 심볼 테이블(
__.SYMDEF)이나#1/네이밍이 없는가?
- 첫 3개 멤버가
- Control 구조 검증:
control.tar.*압축 해제 시 최상위에./control(또는control) 파일이 직접 위치하는가? (DEBIAN/접두사 없을 것)Package:,Version:,Architecture: iphoneos-arm64e메타데이터가 정상인가?
- Data 구조 검증:
- 패키지 내부에 0바이트 빈
.roothidepatch파일이 0개인가? - 파일 및 디렉터리 경로가
./접두사로 시작하는가?
- 패키지 내부에 0바이트 빈
- Mach-O 바이너리 검증:
- FAT 바이너리에
arm64e슬라이스가 정상 포함되어 있는가 (lipo -info)? - 슬라이스별
LC_RPATH중복이 0개인가? ldid -Sad-hoc 서명이 유효한가?
- FAT 바이너리에
- 체크섬 및 파일 크기 기록:
- 파일 크기(bytes) 및 SHA256 해시값을 기록하여 아티팩트 무결성 보존.
- 파일 크기(bytes) 및 SHA256 해시값을 기록하여 아티팩트 무결성 보존.
```
```
| 에러 증상 | 근본 원인 | 표준 해결 조치 |
|---|---|---|
bad deb / is not a deb format |
1. BSD ar 사용으로 __.SYMDEF 심볼 테이블 삽입2. control.tar 내부 경로가 DEBIAN/control임 |
1. 순수 GNU ar / dpkg-deb 사용2. DEBIAN 디렉터리 내부에서 tar를 묶어 ./control 루트화 |
duplicate LC_RPATH (iOS 18) |
Mach-O 로드 커맨드에 동일한 LC_RPATH 2회 이상 중복 |
슬라이스별 중복 RPATH 제거 후 ldid -S 재서명 |
assert(PLRequiredJIT() == 0) / 세이프모드 |
빈 .roothidepatch 파일이 존재하여 JIT assert 발동 |
패키지에서 0바이트 빈 .roothidepatch 파일 완전 제거 |
ldid not found |
SSH 비대화형 세션 PATH에 ldid 미포함 | export PATH="/usr/local/bin:$PATH" 명시 |
control file is not a regular file |
Windows scp 복사로 인한 DEBIAN 권한 문제 (707) | chmod -R 755 <VM_DIR>/layout/DEBIAN 실행 |
THEOS not set |
.zshrc 환경변수 미로드 |
source ~/.zshrc 명시 |
No rule to make target arm64e |
명령행 ARCHS 오버라이드로 인한 규칙 불일치 |
Makefile 기본값 사용 (명령행 오버라이드 금지) |
undefined symbol |
이전 빌드 오브젝트 오염 | make clean && make package 수행 |
| 버전 | 일자 | 변경 내역 | 결과 |
|---|---|---|---|
1.1.12-2 |
2026-10-05 | • control.tar.gz 내부 경로 ./control 규격 수정 (bad deb 해결)• 순수 GNU ar 포맷 재패키징 (bad deb 해결) • 빈 .roothidepatch 파일 완전 제거 (SpringBoard 세이프모드 해결)• arm64e 슬라이스 중복 LC_RPATH 제거 및 ldid ad-hoc 재서명 |
정상 빌드 및 검증 완료 (SHA256: c10e44...) |
1.1.12-1 |
2026-10-05 | 중복 LC_RPATH 제거 및 dpkg-deb 재패키징 시도 (빈 .roothidepatch 미제거로 세이프모드 발생) | 실패 (세이프모드) |
1.1.12 |
2026-10-05 | 원본 배포 패키지 (iOS 18 dyld duplicate LC_RPATH 및 .roothidepatch 포함) | 설치 실패 / 번들 로드 거부 |
트윅이 실기기 환경(iOS 18 / RootHide)에서 정상 작동(세이프모드 없음, 주요 기능 정상 동작, 안정성 검증)하는 것이 최종 확인되면 아래 배포 및 문서화 절차를 반드시 수행한다:
- GitHub 리포지토리 생성:
- 네임스페이스:
eliteguy1/<TweakName> - GitHub CLI(
gh repo create eliteguy1/<TweakName> --public등) 또는 GitHub API/MCP를 통해 리포지토리를 생성한다.
- 네임스페이스:
- 원격 저장소 연동 및 소스/보고서 푸시:
- 로컬 트윅 저장소(
D:\llama agent\tweak\<TweakName>)에 원격 저장소(origin)를 연동한다:cd "D:\llama agent\tweak\<TweakName>" git remote add origin https://github.com/eliteguy1/<TweakName>.git
- 검증 완료된 개발 소스 코드(
src/,Makefile등), 패키징 설정 및 관련 보고서를 모두 커밋 후 푸시한다:git add -A git commit -m "<Version>: Final verified release" git push -u origin master
- 로컬 트윅 저장소(
빌드 및 실기기 검증이 성공적으로 완료될 때마다 버전별로 상세한 최종 보고서를 마크다운(.md) 파일로 작성하여 프로젝트 내 docs/ 디렉터리에 체계적으로 저장한다:
- 저장 위치 및 파일 명명 규격:
- 저장 경로:
D:\llama agent\tweak\<TweakName>\docs\<TweakName>_<Version>_최종보고서.md(또는<TweakName>_<Version>_Report.md)
- 저장 경로:
- 최종 보고서 필수 포함 항목:
- 확인한 사실 (Verified Facts):
- 실기기 테스트 환경 (기종, iOS 버전, RootHide/Relaxin 버전)
- 패키지 설치 상태, SpringBoard 정상 구동 여부 (세이프모드 미진입 확인)
- 런타임 로그, 화면 렌더링, 실제 기능별 정상 동작 확인 내역
- 원인 분석 (Root Causes):
- 이전 버전 또는 초기 빌드에서 발생했던 문제/크래시(SIGABRT, 세이프모드, duplicate LC_RPATH, JIT assert, 0바이트 roothidepatch 등)의 정확한 기술적 근본 원인 분석
- 결과 및 해결 내역 (Results & Solutions):
- 소스 코드 및 패키징 레벨에서의 구체적인 수정 내용과 해결 과정
- 산출물 무결성(FAT 슬라이스, ldid ad-hoc 서명, GNU ar 구조, SHA256 해시) 검증 결과
- 확인한 사실 (Verified Facts):
- 형상 관리 반영:
- 작성된 보고서는 소스 코드와 함께 Git에 커밋하여 버전별 개발/트러블슈팅 이력으로 영구 보존 및 GitHub에 푸시한다.