networkSetup/docs/code-design/03-files-and-registry.md

파일 목록, 설치 위치와 레지스트리

2026-10-19 실행 범위 변경: 공통 파일 해석만 1차에 구현한다. 아래 MSI 컴포넌트·레지스트리 컴파일은 후속이다. MSIX는 패키지 상대 경로와 지원 선언을 검증한다. 현재 설계 참조.

아래 APPDIR·설치 경로·MSI 컴포넌트·레지스트리 작성 규칙은 EXE 백엔드 계약이다. 공통 파일 수집은 MSIX에도 재사용하되 MSIX는 패키지 상대 경로와 지원 manifest 선언으로 매핑한다. 임의 HKLM 쓰기·사용자 지정 설치 폴더는 자동 변환하지 않는다. 패키지 파일과 쓰기 가능한 앱 데이터를 분리한다. 범용 출력 계약 참조.

파일 목록 편집과 해석

파일/폴더 추가, 상대 경로 유지, 포함/제외 패턴, 필수 파일 지정, 대상 폴더 변경을 지원한다. 화면에는 최종 배포 경로, 크기, PE 여부, 서명 상태, 직전 릴리스 대비 추가·수정·삭제를 표시한다. 패턴만 저장하되 빌드마다 확장한 실제 목록도 보존한다.

규칙의 처리 순서는 소스 alias 해석 → include 합집합 → exclude 제거 → 필수 파일 검사 → 대상 경로 계산 → 충돌 검사다. 같은 대상에 둘 이상 매핑되면 뒤의 규칙으로 덮어쓰지 않고 실패한다. 결과는 정규화된 대상 경로 기준으로 정렬한다.

Windows 대소문자 충돌, .., 절대 대상 경로, 예약 이름, ADS, 끝의 공백/점과 지원하지 않는 경로 길이를 검사한다. junction/symlink 등 reparse point는 최초 버전에서 거부한다. 출력·작업 폴더가 입력에 포함되는 순환 수집도 차단한다. 원본은 읽기만 하고 실제 파일 복사본을 스테이징한다. 하드링크로 복사하여 원본을 함께 서명하는 방식은 금지한다.

배포 범위는 실제 빌드 결과와 필요한 리소스로 한정한다. PDB, 소스, 테스트, 로그, 비밀 설정 제외는 프로젝트에서 명시하며, 이름이 .config라는 이유로 런타임 필수 파일까지 제외하지 않는다. 최초 입력 루트는 D:\egbim\repo\14.1 전체 대신 검증된 배포 스테이징 폴더로 설정한다.

설치 위치

디렉터리 id	기본 의미
INSTALLROOT	Windows의 64비트 Program Files 아래 Baron
APPDIR	INSTALLROOT 아래 EG-BIM
COMMONDATADIR	ProgramData 아래 제품 공용 데이터; 필요한 경우만 정의

드라이브 문자 C:는 하드코딩하지 않는다. 기존 설치가 있으면 탐지한 경로를 우선하며 신규 설치는 기본 경로 또는 검증된 사용자 지정 경로를 사용한다. 경로 설정은 WiX 디렉터리와 MSI 속성으로 변환한다. ProgramFiles64Folder와 설치 범위는 x64/perMachine에 맞춘다. WiX Directory

앱이 수정하는 CUI·도면·사용자 설정을 Program Files의 공급자 파일과 섞지 않는다. 공용/사용자 데이터로 옮기는 작업은 제품 변경과 마이그레이션 설계가 선행되어야 한다. 생성기가 파일 소유권을 추정해 자동 이동·삭제하지 않는다.

MSI 컴포넌트 규칙

기본적으로 파일 하나에 컴포넌트 하나를 할당하고 해당 파일을 key path로 지정한다. 레지스트리 전용 컴포넌트도 별도로 만든다. 컴포넌트의 안정적인 식별 기준은 대상 경로·아키텍처·설치 범위·리소스 종류이며 소스 절대 경로·파일 해시·정렬 순번을 GUID 생성 기준으로 쓰지 않는다.

처음 할당한 WiX id와 Component GUID는 identity.lock.json에 보존한다. 경로/키 경로/비트수/소유권이 바뀌면 기존 GUID를 기계적으로 재사용하지 않고 호환성 검토 대상으로 분류한다. 삭제된 식별자는 tombstone으로 남겨 무관한 리소스에 재사용하지 않는다. 동일 프로젝트 동시 빌드가 서로 다른 GUID를 확정하지 못하도록 잠근다.

기존 ISM의 컴포넌트 GUID를 그대로 가져온다고 패치 호환성이 확보되지는 않는다. 최초 전환은 전체 업그레이드로 검증하고 이후 WiX 기준 릴리스부터 패치 계열을 관리한다.

레지스트리 편집

입력 필드는 hive, 32/64비트 view, key, 값 이름(기본값 포함), 타입, 값, 설치 조건, 제거 정책이다. 초기 지원 타입은 string, expandableString, integer, binary, multiString이며 DWORD 범위·바이너리 형식·문자열 배열을 타입별로 검증한다. 지원하지 않는 타입은 자동 문자열 변환하지 않는다. WiX RegistryValue

문자열에는 literal과 msiFormatted를 구분한다. literal의 대괄호 등은 MSI 형식으로 오인되지 않게 변환하고, formatted는 [APPDIR] 같은 허용 속성만 참조한다. XML은 라이브러리로 직렬화하여 사용자 값을 원시 WXS에 삽입하지 않는다.

perMachine 기본은 HKLM이다. 파일 연결/COM 등록은 HKCR의 병합 뷰를 무작정 수정하지 않고 실제 소유 hive와 뷰를 명시한다. HKCU는 관리자 권한 설치를 실행한 계정과 실제 앱 사용자가 다를 수 있으므로 최초 버전의 perMachine 프로젝트에서는 사용자별 기본값 초기화를 앱 첫 실행 작업으로 분리한다. HKCU 설치 기능은 별도 구현·시험 없이는 차단한다.

제거 시 기본 정책은 생성한 값만 제거하는 것이다. 공유 키 전체나 Software\Baron 전체 삭제는 허용하지 않는다. 사용자 수정 값과 기존 값 보존 정책은 MSI repair/upgrade 동작까지 검증한 템플릿만 제공하며 UI 체크박스 하나로 보장한다고 표시하지 않는다.

설정 미리보기는 빌드 PC 레지스트리를 바꾸지 않는다. .reg 파일이나 ISM을 가져오는 기능은 향후 파서로 변환·검토하고 실행하지 않는다. 설치 과정 편집기는 표준 기능과 등록된 핸들러의 추가·삭제·조건 설정을 지원한다. 임의 셸 스크립트 입력은 최초 범위에서 제외하고, COM/서비스/CustomAction에는 소유권·롤백·권한 계약을 요구한다. 설치 과정과 UI 설계