웹 개발 마조히스트를 위한 안내서

• C/C++ 코드를 Emscripten으로 WebAssembly로 포팅하여 브라우저에서 동작하는 웹앱 제작 과정을 실제 Rubik’s Cube 솔버 예제 기반으로 상세히 설명함
• Hello World부터 멀티스레딩, 콜백, 영구 스토리지, 모듈화 등 브라우저/WebAssembly 환경에서 마주치는 구체적 난관과 문제 해결법을 단계별로 다룸
• JavaScript 비동기 초기화, 함수 내보내기, Web Worker 및 Spectre 이슈, IDBFS 통한 IndexedDB 영구 저장 등 실전 트러블슈팅에 초점
• Emscripten의 추상화가 실제로는 자주 '새는' 현상(leaky abstractions)임을 반복적으로 강조하며, 웹 플랫폼의 한계와 내부 구조를 알 필요성을 강조함
• 프론트엔드의 최소한의 JavaScript/HTML 지식만으로 복잡한 C 코드 베이스를 웹으로 옮기는 실전 경험을 통해, 기존 C/C++ 라이브러리를 웹으로 이식하려는 개발자에게 실질적인 도움과 노하우를 제공하는 경험 기반 가이드임

소개

• 최근 Rubik’s Cube 최적해 알고리듬을 웹 앱으로 구현하는 프로젝트를 진행하였음
• C로 개발한 Rubik’s Cube 최적화 솔버를 Emscripten으로 컴파일해 WebAssembly로 웹 브라우저에서 구동하는 과정을 기록함
• WebAssembly를 쓰는 주된 이유는 자바스크립트 대비 거의 네이티브에 가까운 성능을 웹에서 확보할 수 있기 때문임
• 본 글은 전통적인 웹 개발 튜토리얼이 아닌, 기존 C/C++ 코드를 웹으로 이식하고자 하는 개발자를 위한 ‘고통의 여정’임
• 웹 개발 경험이 많지 않아도 HTML, JavaScript의 기본 구조와 브라우저 개발자 도구 활용법만 알면 따라갈 수 있음

환경 구축

• 모든 예제 코드는 git 저장소, github에서 확인 가능함
• Emscripten 설치 필요(설치법은 공식 사이트 참고), 웹서버는 darkhttpd 또는 Python http.server 등 사용
• 튜토리얼 코드 예제는 Linux 및 UNIX 계열에서 테스트되었음. Windows 사용자는 WSL(Windows Subsystem for Linux) 을 추천함

Hello World

• C 코드의 Hello World를 emcc -o index.html hello.c 명령으로 컴파일하면 index.html(웹 페이지), index.wasm(WebAssembly 바이트코드), index.js(JavaScript glue code) 세 파일이 생성됨
• 브라우저나 Node.js에서 동작 가능하며, 각각의 환경에서 다른 활용법이 존재함
• .wasm만 생성하려면 -sSTANDALONE_WASM 옵션 사용
• Emscripten에서 .wasm만 생성도 가능하지만, 대부분의 경우 JavaScript glue code가 필수적임

Intermezzo I: WebAssembly란?

• WebAssembly(WASM) 은 웹 브라우저 내 고성능 가상 머신에서 실행되는 저수준 언어임
• WASM은 2017년 이후 모든 주요 브라우저에서 지원됨
• 원래 Emscripten은 C/C++ 코드를 asm.js라는 JavaScript 하위 집합으로 변환했으나, WASM의 등장으로 전환됨
• 텍스트 표현식도 존재하며, 스택 기반 구조임. 최근까지 32비트 아키텍처만 지원해 4GB 이상의 메모리를 못 썼으나, WASM64가 점진적으로 브라우저에 도입되고 있음

라이브러리 빌드

• C 함수 multiply() 를 WASM으로 빌드 후 JavaScript에서 호출하는 기본 예시 진행
• 기본 빌드시 Emscripten은 함수 이름에 언더스코어(_) 를 붙임(예: _multiply)
• 함수 외부 노출은 -sEXPORTED_FUNCTIONS 옵션 지정 필요함
• 라이브러리 로딩 시 초기화가 비동기적이므로, onRuntimeInitialized나 await 등 비동기 처리 필요함
• 실습 코드는 저장소 01_library 폴더에 있음

Intermezzo II: JavaScript와 DOM

• JavaScript에서 HTML의 구성요소에 접근 및 수정하려면 Document Object Model(DOM) 을 활용해야 함
• 이벤트 리스너(addEventListener) , 내장 연산자/함수 등으로 동적 UI 구현 가능
• 예제를 위해 입력, 버튼, 결과 표시가 있는 기본적인 HTML/JavaScript 연동 구조 설명
• script 분리/병합의 실전적 방법과 이슈(예: defer의 사용, DOM 요소 로드 순서)도 안내함

라이브러리 모듈화 및 로딩

• WASM 라이브러리를 다중 포함하거나 Node.js/웹 양쪽에서 재사용하기 위해 MODULARIZE, EXPORT_NAME 옵션으로 모듈 형태로 빌드할 수 있음
• .mjs (ES6 모듈) 확장자가 Node.js 호환성을 위해 추천됨
• 웹/Node 양쪽에서 import MyLibrary from ... 식 모듈 사용 가능

멀티스레딩

• WebAssembly에서 성능 강화를 위해 pthreads 기반 멀티스레드 코드 포팅 가능함
• 함수 내 다수의 스레드를 생성해 병렬로 계산 작업(예: 소수 개수 세기) 을 실행함
• 빌드시 -pthread, -sPTHREAD_POOL_SIZE= 옵션 필요함
• 실제 브라우저에서는 Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Embedder-Policy: require-corp와 같은 HTTP 헤더 추가 필요
• 모든 예제는 저장소 03_threads 폴더에서 확인 가능함

Intermezzo III: Web Workers 및 Spectre

• Emscripten 멀티스레드는 Web Workers로 구현됨(Web Workers는 별도의 프로세스이자 메시지 기반 통신 구조)
• 공유 메모리(SharedArrayBuffer) 사용에는 보안 상의 제약이 존재
• 2018년 Spectre 취약점 발생 후, 크로스 오리진 격리(cross-origin isolated) 요구사항 및 관련 헤더 필수화됨

메인 스레드 블로킹 주의

• 긴 작업이 브라우저의 메인 UI 스레드를 BLOCK할 경우 사용자 경험이 급격히 저하됨
• 이를 피하기 위해 웹 워커(Worker)를 도입: UI/입력 처리와 연산 처리를 명확히 분리
• postMessage, onmessage로 메인-워커 간 이벤트 기반 통신 구현
• 웹 워커 내에서 Emscripten-WASM 모듈을 불러 비동기 연산만 전담

콜백 함수

• C 함수의 파라미터로 함수 포인터(콜백) 전달 시, 자바스크립트의 함수 객체와 자동 연동이 불가능함
• Emscripten 제공 addFunction(), UTF8ToString() 등을 활용해야 하며, 빌드시 -sEXPORTED_RUNTIME_METHODS, -sALLOW_TABLE_GROWTH 옵션 추가 필요
• 콜백은 반드시 메인 스레드에서만 호출되어야 안정적으로 동작함(웹 워커에서는 접근 불가)

영속적 스토리지

• 사용자의 브라우저에 데이터를 영구 저장하기 위해 Emscripten의 IDBFS(IndexedDB 기반 파일 시스템) 를 사용함
• 빌드시 --lidbfs.js 플래그와 **--pre-js ** 등으로 초기 세팅 필요
• C 코드에서는 파일 입출력 함수(fopen, fread, fwrite)를 그대로 사용할 수 있으나, 실제 데이터 반영/동기화 처리는 반드시 JavaScript에서 명시적 매핑 및 싱크 처리가 필요함
• 브라우저의 Sandbox/보안 정책 특성상, 로컬 파일 시스템 직접 접근은 Node.js에서만 가능하며, 브라우저에서는 IDBFS와 같은 백엔드를 활용해야 안전하게 영구 데이터 저장 가능함

결론

• 본 튜토리얼 전 과정을 통해 복잡한 네이티브 C/C++ 코드를 최소한의 JavaScript와 HTML만으로도 안전하고 성능 저하 없이 브라우저 상에서 실행할 수 있는 실질적인 방법을 자세히 배울 수 있음
• 실전 환경에서 멀티스레드, 콜백, 비동기 처리, 스토리지 연동까지 모든 핵심 트랙의 난관/해결책을 경험하고, 관련 설정 및 브라우저 제약사항 등 최신 트렌드도 익힐 수 있음
• 제공되는 Git 저장소 예제를 참고하여 자체 프로젝트에 적용 및 확장 가능함