ThorVG OSSCA 2026
GitHub
← 과제 목록

[과제] 1주차) 프로젝트 작업환경 구축 강주희

@zurdhva
  • #과제
목차

환경

  • OS: macOS (Apple Silicon, aarch64)
  • 컴파일러: Apple Clang 21.0.0 (Xcode Command Line Tools)
  • 빌드 시스템: Meson + Ninja
  • 패키지 매니저: Homebrew
  • 터미널: zsh

1. 저장소 클론

ThorVG 메인 레포(thorvg/thorvg)를 클론했다.

git clone https://github.com/thorvg/thorvg.git
  • example 코드는 이 메인 레포 안에 없고, 별도 레포(thorvg/thorvg.example)에 있다는 걸 README에서 확인. 두 레포를 각각 클론해야 함.

2. 필요 패키지 설치 확인

빌드에 필요한 도구들이 이미 있는지 먼저 점검했다.

brew --version
meson --version
ninja --version
pkg-config --version
brew list sdl2
  • brew, pkg-config(2.5.1), sdl2(정확히는 sdl2-compat 2.32.70)는 이미 설치되어 있었음.
  • meson, ninja는 없어서(command not found) 별도 설치 필요.
brew install meson ninja
  • 설치 후 재확인: meson 1.11.2, ninja 1.13.2 정상 확인.

3. ThorVG 소스 빌드 & 설치

cd thorvg
meson setup builddir
ninja -C builddir
sudo ninja -C builddir install
  • meson setup 로그에서 빌드 옵션 요약을 확인:
    • Raster Engine: CPU YES / GL NO / WebGPU NO
    • Loader: SVG YES, TTF YES, LOTTIE YES (PNG/JPG/WEBP는 기본 OFF)
    • Extra: Lottie Expressions YES, OpenMP YES
  • ninja -C builddir로 238/238 오브젝트 링크 완료 → libthorvg-1.1.dylib 생성.
  • sudo ninja -C builddir install로 시스템에 설치. 설치 경로는 Homebrew 기본 prefix인 /opt/homebrew 하위.
    • /opt/homebrew/lib/libthorvg-1.1.dylib
    • /opt/homebrew/include/thorvg-1/thorvg.h
    • /opt/homebrew/lib/pkgconfig/thorvg-1.pc ← 이후 example 빌드에서 이걸 찾게 됨

4. thorvg.example 레포 클론

cd ..
git clone https://github.com/thorvg/thorvg.example.git
cd thorvg.example

5. example meson setup

meson setup builddir

핵심 확인 포인트 — 의존성이 제대로 잡히는지:

Run-time dependency thorvg-1 found: YES 1.0.0
Run-time dependency sdl2 found: YES 2.32.70
Run-time dependency gl found: YES
Run-time dependency glesv2 found: NO
Run-time dependency wgpu_native found: NO
Build targets in project: 61
  • thorvg-1, sdl2, gl은 정상 탐지.
  • glesv2(OpenGL ES), wgpu_native(WebGPU)는 시스템에 없어서 NO → 해당 백엔드를 쓰는 example만 빌드에서 제외됨. 기본 소프트웨어 렌더러 / GL 기반 example은 영향 없음.
  • CAPI(C 바인딩)도 별도 옵션으로 켜지 않아서 관련 example은 스킵.

6. example 빌드

ninja -C builddir
  • 122/122 타겟 전부 링크 성공. (61개 소스 → 122개 바이너리, .p 접미사가 붙은 중간 산출물 포함)

7. 실행 검증

./builddir/src/Lottie
image

용어 정리

작업하면서 헷갈렸던 개념들을 정리했다.

Meson

  • 빌드 시스템 설정 도구(build system generator). 직접 컴파일을 하는 게 아니라, meson.build 파일(프로젝트 설정)을 읽어서 실제 빌드에 필요한 파일(예: build.ninja)을 생성해주는 역할.
  • meson setup builddir 명령이 하는 일: 소스 트리를 분석하고, 컴파일러/의존성(OpenMP, pthread, SDL2 등)을 탐지하고, builddir 폴더에 빌드 준비 파일을 만드는 것.
  • CMake와 비슷한 포지션이지만, 문법이 더 간결하고 기본 백엔드로 Ninja를 쓰기 때문에 빌드 속도가 빠른 편.
  • --backend=vs, --backend=xcode 옵션으로 Visual Studio나 Xcode 프로젝트 파일을 생성하는 것도 가능 (Meson이 “설정 생성기”라는 역할이라 가능한 기능).

Ninja

  • 실제로 컴파일·링크를 수행하는 저수준 빌드 실행기(build executor).
  • Meson이 생성한 build.ninja 파일에 정의된 규칙(어떤 소스를 어떤 순서로, 어떤 플래그로 컴파일할지)을 읽어서 실행만 담당.
  • Make와 비슷한 역할이지만 병렬 빌드에 최적화되어 있어 대규모 프로젝트에서 체감 속도 차이가 큼.
  • ninja -C builddir에서 -C는 “해당 디렉토리로 이동해서 실행”이라는 뜻.
  • 즉 역할 분담: Meson = 설정/의존성 탐지, Ninja = 실제 빌드 실행.

pkg-config / .pc 파일

  • 라이브러리를 설치하면 컴파일할 때 필요한 정보(헤더 경로 -I, 라이브러리 경로 -L, 링크할 라이브러리명 -l, 버전 등)를 .pc 확장자 파일로 남겨두는 관례가 있음.
  • pkg-config --modversion thorvg-1 같은 명령으로 이 정보를 조회할 수 있고, 빌드 시스템(Meson 포함)은 내부적으로 이 .pc 파일을 읽어서 dependency('thorvg-1') 같은 선언을 실제 라이브러리와 연결함.
  • 즉, ThorVG를 meson setup + ninja install로 설치하면 thorvg-1.pc가 자동 생성되고, 이게 있어야 다른 프로젝트(thorvg.example)에서 dependency('thorvg-1')로 바로 찾을 수 있음.

SDL2

  • Simple DirectMedia Layer의 줄임말. 크로스플랫폼 멀티미디어 라이브러리로, 윈도우 생성, 입력(키보드/마우스) 처리, 화면에 픽셀을 그리는 캔버스 기능 등을 제공.
  • ThorVG 엔진 자체는 SDL2에 의존하지 않지만, thorvg.example의 데모 앱들은 “렌더링 결과를 화면에 띄워서 보여주기 위한 창”이 필요해서 SDL2를 의존성으로 사용.
  • 즉 구조상: ThorVG(그래픽 연산) → 픽셀 버퍼 생성 → SDL2가 그 버퍼를 실제 화면 창에 표시.

정적/동적 라이브러리 (.dylib)

  • 빌드 결과로 나온 libthorvg-1.1.dylib은 macOS의 동적 라이브러리(shared library) 확장자. Linux의 .so, Windows의 .dll에 대응.
  • example 실행 파일들은 이 .dylib을 실행 시점에 로드해서 사용하며, 설치 경로(/opt/homebrew/lib)가 시스템의 라이브러리 탐색 경로에 포함되어 있어 별도 경로 지정 없이 바로 실행 가능했음.

댓글

Discussion 원문