본문으로 건너뛰기

Verible 프론트엔드 이관 문서

이 문서는 현재 Verilog Simulator 페이지에 붙어 있는 Verible 기능을 다른 프론트엔드 엔지니어가 안전하게 이어받을 수 있도록 정리한 이관용 문서입니다.

1) 현재 구현 상태 (요약)​

  • 동작 방식: 완전 서버리스 (브라우저에서 verible.js + verible.wasm 실행)
  • 제공 기능:
    • Verible 문서/범위 포맷팅
    • 저장 시 자동 포맷
    • filelist.f 기반 프로젝트 난독화
    • 난독화 결과 ZIP(obf_out.zip) 다운로드
    • 난독화 결과를 새 워크스페이스(*_Obfuscated)로 생성 및 자동 활성화
    • 워크스페이스 우클릭으로 활성 워크스페이스 전환
  • 제거된 기능:
    • 단일 파일 난독화 버튼
    • 원본 코드 복구 버튼

2) 왜 이렇게 설계했는가​

프로젝트 난독화는 파일 간 심볼 맵 일관성이 핵심이라, 단일 파일 난독화(obfuscate)는 sim/syn 신뢰성이 낮습니다.
그래서 현재 UI는 프로젝트 난독화 중심으로 단순화했습니다.

3) 코드 위치​

핵심 파일​

  • src/pages/tools/verilog-simulator.js
    • Verible 버튼/핸들러/UI
    • filelist.f 파싱 및 소스 수집
    • 새 워크스페이스 생성/활성화
  • src/lib/veribleWasm/veribleWasmFormatter.ts
    • WASM 로더 및 브리지 래퍼
    • 포맷팅 API
    • 프로젝트 난독화 API 호출
  • src/lib/verilogSimZip.js
    • 일반 워크스페이스 ZIP
    • 경로 유지 ZIP 생성(zipNamedTextFiles)
  • scripts/sync-verible-wasm.cjs
    • verible.js, verible.wasm를 static/verible-wasm로 동기화

WASM 바이너리 위치​

  • 소스(개발 자산): wasm-tools/wasm-web-Verible_static
  • 서빙 대상: static/verible-wasm

4) 런타임 아키텍처​

  1. 브라우저가 static/verible-wasm/verible.js, verible.wasm를 로드
  2. WasmVeribleBridge 생성
  3. 포맷팅은 lspRequest()로 JSON-RPC (textDocument/formatting, textDocument/rangeFormatting)
  4. 프로젝트 난독화는 obfuscateProject() 사용
  5. 결과를
    • 새 워크스페이스 파일 집합에 반영
    • obf_out.zip 아티팩트로 다운로드

5) 프로젝트 난독화 흐름 (현재 기준)​

전체 난독화 (filelist 기준) 버튼 클릭 시:

  1. 활성 워크스페이스에서 filelist.f 조회
  2. filelist.f 파싱
    • 주석/빈 줄 무시
    • -f/-F 중첩 filelist 처리
    • +incdir+ 파싱
    • 경로 안전성 체크(path traversal 방어)
  3. 대상 소스(.v/.sv/.vh) 수집
  4. runVeribleProjectObfuscation() 호출
  5. 결과 처리
    • obf_out/* 형태로 ZIP 다운로드
    • 워크스페이스 복제본({원본}_Obfuscated) 생성
    • 복제본을 활성 워크스페이스로 전환
    • symbol_map.txt, obfuscation_manifest.json 파일 추가

6) 이관 시 필수 체크포인트​

A. WASM API 호환성​

WasmVeribleBridge가 아래 중 하나를 반드시 제공해야 합니다.

  • 권장: obfuscateProject()
  • 차선: resetObfuscationMap() + obfuscateWithMap() + obfuscationMap()

위 API가 없으면 프로젝트 난독화는 신뢰할 수 없습니다.

B. 정적 파일 동기화​

  • prestart/prebuild에 scripts/sync-verible-wasm.cjs 포함 확인
  • static/verible-wasm/verible.js
  • static/verible-wasm/verible.wasm

C. 캐시 이슈​

WASM 교체 후 기능이 안 바뀌면 브라우저 캐시 가능성이 큽니다.

  • 강력 새로고침(Ctrl+Shift+R)
  • 필요 시 서비스워커/캐시 무효화

D. 워크스페이스 정책​

  • 난독화 결과는 원본을 덮지 않고 복제 워크스페이스로 생성
  • 원본/난독화본 병렬 비교 가능하도록 유지

7) 다른 프론트엔드로 이관 절차​

Step 1. 정적 파일 경로 맞추기​

  • 타깃 프로젝트에 static/verible-wasm 경로 생성
  • verible.js/verible.wasm 복사 자동화

Step 2. 래퍼 모듈 이식​

  • src/lib/veribleWasm/veribleWasmFormatter.ts 이식
  • 타깃 앱의 baseUrl 규칙에 맞게 locateFile 경로만 조정

Step 3. 페이지 통합​

  • verilog-simulator.js에서 아래 단위를 묶어 이식
    • 포맷 버튼 + 저장시 자동 포맷
    • filelist.f 파싱/수집 유틸
    • 프로젝트 난독화 핸들러
    • 새 워크스페이스 생성/활성화 로직
    • 워크스페이스 우클릭 활성화 메뉴

Step 4. ZIP/아티팩트 출력​

  • zipNamedTextFiles() 포함 여부 확인
  • 산출물:
    • obf_out/filelist_obf.f
    • obf_out/symbol_map.txt
    • obf_out/manifest.json

8) 검증 시나리오 (handoff QA)​

  1. Sample 워크스페이스에서 전체 난독화 (filelist 기준) 실행
  2. Sample_Obfuscated 워크스페이스가 생성되고 활성화되는지 확인
  3. Run 실행 시 sim 성공 여부 확인
  4. 필요 시 Lint로 기본 정합성 확인
  5. 워크스페이스 바 우클릭 → 다른 워크스페이스를 활성화 전환 가능한지 확인
  6. obf_out.zip에 obf_out/*, symbol_map.txt, manifest.json 포함 확인
  7. 포맷팅 버튼/저장시 포맷 동작 확인

9) 알려진 제한/리스크​

  • verible.js 동적 import 특성상 빌드에서 Critical dependency 경고가 나올 수 있음
  • WASM API 불일치(구버전 바이너리) 시 프로젝트 난독화 실패
  • 브라우저 캐시 때문에 바이너리 교체가 즉시 반영되지 않을 수 있음

10) 릴리스 전 체크리스트​

  • static/verible-wasm/verible.js/verible.wasm 최신본 확인
  • WasmVeribleBridge API 노출 확인(obfuscateProject 권장)
  • filelist.f 기반 난독화 → 새 워크스페이스 자동 전환 확인
  • 난독화본에서 Run 성공 확인
  • ZIP 산출물 구조 확인
  • 워크스페이스 우클릭 활성화 기능 확인