[ThorVG Web] 1주차 - 작업 환경 구축

과제 시작 전 요약

1주차 과제는 첨부한 사진처럼 ThorVG Web 개발 가이드를 읽고, 로컬에서 두 패키지를 빌드한 뒤 예제로서 그를 점검하는 것이라 이해했습니다.
그래서 글의 목차도 요구사항의 순서를 기반으로 구성했습니다.

1. Development Guide 요약
2. 본인 환경에서의 구성 과정 (스크린샷 포함)
3. 같은 환경에서 다시 따라 할 수 있을 정도의 정리

1. Development Guide 요약

ThorVG Web은 C++로 된 ThorVG 엔진을 WebAssembly로 컴파일하여 브라우저에서 쓰게 만드는 프로젝트입니다.
특히, 해당 레포 안에서 실제로 나가는 결과물은 두 가지로 @thorvg/lottie-player, @thorvg/webcanvas입니다.

둘 다 같은 ThorVG WASM 코어를 사용하고, Software / WebGL / WebGPU 쪽 렌더러를 고를 수 있습니다.

필요한 도구로는 Node 20+, pnpm 10+, Emscripten, Meson, Ninja입니다.
패키지별로 pnpm run build를 실행하게 되면 WASM 스크립트까지 함께 돌아가며, 로컬 확인은 playground, perf-test, HTML examples, React/Vue/Svelte 예제, ThorVG Viewer 같은 경로가 있습니다.

빌드 흐름을 한 줄로 정리하면 다음과 같습니다.

thorvg (C++ 코어, submodule)
  → wasm/ 바인딩
  → packages/*/dist
  → examples / playground / perf-test 로 확인

추가로 가이드에서 눈에 띄었던 점은 다음과 같습니다.

• Lottie Player는 sw / gl / wg 및 lite preset이 나뉘어 빌드된다.
• WebCanvas는 한 WASM 안에 여러 백엔드를 포함하는 쪽에 가깝다.
• 로컬에서 수정한 패키지를 playground 등에 붙일 때는 path install 방식으로 연결한다.

개인적인 생각

즉, 해당 가이드는 패키지 빌드, 로컬 툴로 확인, 필요시 빌드를 playground에 붙이기라는 일련의 과정을 정리하고 있습니다.

다만, 해당 기준 환경이 Linux + macOS에 가깝다고 생각합니다.
특히 export, sh ./wasm_*.sh 같은 전제가 많아, Windows에서는 그대로 따라가기 어려운 지점이 있었습니다.
현재 사용하고 있는 환경이 Windows였기에, 이번 주차를 통해 그 지점을 직접 보완하는 데 도움이 되지 않을까 하는 생각을 하며 글을 작성했습니다.

2. 본인 환경에서의 구성 과정

2-1. 디테일한 환경

우선, “본인 환경”에 대해 보다 디테일하게 작성해보겠습니다.

2-2. 진행 순서

과제 요구사항(환경 구축 → WebCanvas 빌드 → Lottie Player 빌드 → 예제 확인) 순서에 맞춰 진행했습니다.

a. 사전 준비

• thorvg submodule 초기화 (SSH 키가 없어 HTTPS로 thorvg를 직접 클론 후, submodule이 가리키는 커밋으로 checkout)
• Emscripten 6.0.0 설치 (CI와 동일 버전), Meson / Ninja 준비
• Git Bash에서 환경변수 설정

export EMSDK='C:/Users/<USER>/emsdk'
export PATH="$EMSDK/upstream/emscripten:$EMSDK:$PATH"

b. WebCanvas 빌드

cd packages/webcanvas
pnpm install
npm run clean
sh ./wasm_wcanvas_setup.sh
export THORVG_VERSION=$(npm run version --silent)
npx rollup -c --bundleConfigAsCjs

pnpm run build 한 번으로 끝나지 않고 위처럼 단계를 나눈 이유는 아래 “막혔던 부분”에 정리했습니다.
packages/webcanvas/dist/에 webcanvas.*.js, thorvg.wasm이 생성되면 성공입니다.

c. Lottie Player 빌드

cd packages/lottie-player
pnpm install
npm run clean
sh ./wasm_player_setup.sh
export THORVG_VERSION=$(npm run version --silent)
npx rollup -c --bundleConfigAsCjs

preset(기본 + sw/gl/wg + lite 3종)을 순서대로 빌드하므로 시간이 꽤 걸렸습니다. (현 환경 기준 약 7~8분)

d. 예제 구동

예제는 packages/*/dist를 상대 경로로 참조하므로 저장소 루트에서 서버를 띄웠습니다.

npx http-server . -p 8080 -c-1

• http://127.0.0.1:8080/examples/live-editor.html
• http://127.0.0.1:8080/examples/lottie.html

2-3. 막혔던 부분

EMSDK 경로 형식

Git Bash에서 쓰던 습관대로 EMSDK를 /c/Users/...로 넣었더니, Meson이 컴파일러를 찾지 못했습니다.

ERROR: Unknown compiler(s): [['/c/Users/.../em++']]
Running `em++ --version` gave "[WinError 2] 지정된 파일을 찾을 수 없습니다"

Meson은 Windows 네이티브로 동작하기 때문에 MSYS 스타일 경로를 해석하지 못합니다.
→ EMSDK='C:/Users/<USER>/emsdk'처럼 Windows 드라이브 표기로 바꾸니 통과됐습니다.
참고로 emsdk_env.sh를 source하면 /c/...로 다시 덮어쓰므로, source 이후에 한 번 더 C:/ 형태로 export 해야 했습니다.

THORVG_VERSION 인라인 환경변수

WebCanvas의 pnpm run build는 WASM까지는 성공했는데, 마지막에 이렇게 실패했습니다.

WASM setup completed successfully!
'THORVG_VERSION'은(는) 내부 또는 외부 명령... 아닙니다.

package.json의 build 스크립트가 THORVG_VERSION=$(npm run version --silent) rollup -c ... 형태인데,
VAR=값 명령은 POSIX 셸 문법이라 npm이 Windows에서 cmd로 실행하면 그대로 깨집니다.
→ WASM setup은 셸 스크립트로 돌리고, Rollup은 Git Bash에서 export THORVG_VERSION=... 후 따로 실행하는 방식으로 분리했습니다.

tsc 부재로 인한 연쇄 실패

Lottie Player의 기본 preset 빌드에서 아래 오류가 났습니다.

em++: error: tsc executable not found in node_modules or in $PATH

기본 빌드가 --emit-tsd로 TypeScript 선언 파일을 생성하는데, 이때 tsc가 필요합니다.
문제는 이 실패가 조용히 지나가고, 한참 뒤 Rollup에서 전혀 다른 모양으로 나타난다는 점입니다.

[!] RollupError: Could not resolve "../dist/thorvg" from "src/base-lottie-player.ts"

WASM 링크가 실패해 dist/thorvg.js가 없으니 번들이 참조를 못 찾는 것인데,
에러만 보면 Rollup 설정 문제처럼 보여서 원인을 찾는 데 시간이 걸렸습니다.
→ npm install -g typescript 후 clean부터 다시 빌드하니 해결됐습니다.

2-4. 스크린샷

WebCanvas — examples/live-editor.html

Lottie Player — examples/lottie.html

3. 같은 환경에서 따라 하기

요구사항 중 “본인의 글만 보고도 타인이 같은 환경에서 개발 환경을 셋업할 수 있을 정도”에 해당하는 부분입니다.
위에 작성했던 환경 부분과 유사하다면, 해당 흐름도를 따라 문제없이 빌드할 수 있을 것이라 예상됩니다.

3-1. 재현 순서

# 0) Git Bash 권장 / Node·pnpm·typescript 준비된 상태
# 1) 클론
git clone https://github.com/thorvg/thorvg.web.git
cd thorvg.web

# 2) thorvg 코어
# SSH가 되면: git submodule update --init --recursive
# 안 되면:
git submodule status
git clone https://github.com/thorvg/thorvg.git thorvg
cd thorvg && git checkout <핀 커밋> && cd ..

# 3) Meson PATH (필요 시)
# export PATH="/c/Users/<USER>/AppData/Roaming/Python/Python312/Scripts:$PATH"

# 4) emsdk 6.0.0 설치 후
export EMSDK='C:/Users/<USER>/emsdk'
export PATH="$EMSDK/upstream/emscripten:$EMSDK:$PATH"
emcc --version

# 5) WebCanvas
cd packages/webcanvas
pnpm install
npm run clean
sh ./wasm_wcanvas_setup.sh
export THORVG_VERSION=$(npm run version --silent)
npx rollup -c --bundleConfigAsCjs

# 6) Lottie Player
cd ../lottie-player
pnpm install
npm run clean
sh ./wasm_player_setup.sh
export THORVG_VERSION=$(npm run version --silent)
npx rollup -c --bundleConfigAsCjs

# 7) 예제 (저장소 루트)
cd ../..
npx http-server . -p 8080 -c-1

3-2. 막혔을 때

마무리

이번 1주차에서는 Development Guide를 기준으로 ThorVG Web의 큰 흐름을 이해했고,
Windows 환경에서 WebCanvas / Lottie Player 빌드와 예제 확인까지 진행했습니다.

Development Guide를 읽으며 해당 오픈소스에 더욱 가까워지는 기회가 되었습니다. 감사합니다.