C++ 코드를 웹으로 포팅하는 Emscripten 알아보기 (feat. WebGL)

프로젝트 환경

• 개발 환경 운영체제 : Ubuntu 20.04

• 개발 IDE : CLion

• 빌드 가능한 컴파일러 : gcc, clang, msvc

• 지원 가능한 OpenGL 버전 : OpenGL ES 3.0 이상 또는 OpenGL 4.3 이상

1. emsdk 설치

# Fetch the latest version of the emsdk (not needed the first time you clone)
git pull

# Download and install the latest SDK tools.
./emsdk install latest

# Make the "latest" SDK "active" for the current user. (writes .emscripten file)
./emsdk activate latest

# Activate PATH and other environment variables in the current terminal
source ./emsdk_env.sh

2. 전용 CMakeLists.txt 생성

cmake_minimum_required(VERSION 3.4.1)

PROJECT(CSEngineWeb)

# 만약 Shared 라이브러리가 존재하면 해당 프로퍼티 설정을 넣어주셔야 합니다!
SET_PROPERTY(GLOBAL PROPERTY TARGET_SUPPORTS_SHARED_LIBS TRUE)

SET(CMAKE_VERBOSE_MAKEFILE true)
set(CMAKE_BUILD_TYPE Debug)

# 기존 /usr 내에 있는 라이브러리는 링크하지 않습니다!
# 이미 emsdk에 내장되어있기 때문에 링크가 되어있다면 해제해줍니다.
#link_directories(/usr/lib)
#link_directories(/usr/lib32)
#link_directories(/usr/local/lib)

# 만약 WebGL을 사용한다면 아래처럼 설정해주시면 됩니다.
find_package(OpenGL REQUIRED)
include_directories(${OPENGL_INCLUDE_DIR})

...

# 제 프로젝트에 들어가는 Shared 라이브러리 입니다.
add_library( SquirrelLib
            SHARED
            ${SQUIRREL_SRC})


add_executable(CSEngineWeb CSEngine_Web_glfw.cpp ${CSENGINE_SRC})


# 기존 /usr 내에 있는 include 디렉토리도 선언하지 않습니다!
# 이미 emsdk에 내장되어있기 때문에 선언되어있다면 해제해줍니다.
#include_directories(/usr/include)
#include_directories(/usr/local/include)

include_directories(../../External/Squirrel/include)


target_link_libraries(CSEngineWeb glfw)
target_link_libraries(CSEngineWeb SquirrelLib)

# html 형식으로 빌드하기 위해선 아래와 같이 옵션을 추가로 설정해줘야 합니다.
# 해당 파트가 가장 중요하다고 볼 수 있겠습니다!
set_target_properties(CSEngineWeb
        PROPERTIES SUFFIX ".html"
        LINK_FLAGS " --bind -s USE_GLFW=3 -s ASSERTIONS=1 -s WASM=1 -O3 -std=c++14 -s ALLOW_MEMORY_GROWTH=1 -s EXCEPTION_CATCHING_ALLOWED=[..] -s USE_WEBGL2=1 -g4 --preload-file Assets.zip")

LINK_FLAGS

• USE_GLFW=3 : GLFW3을 사용한다고 설정합니다. 코드에서 GLFW를 사용하는지 확인하고 작성해주시면 됩니다.

• ASSERTIONS=1 : 메모리 할당 오류에 대한 검사를 활성화 합니다. 기본적으론 1로 지정되어있으나 최적화 단계가 O1이상이 되면 해제되기 때문에 따로 넣어주었습니다.

• O3 : 코드의 최적화 단계를 뜻합니다. 기본적으론 O0부터 O3까지 진행을 하게 되는데 디버그 목적이라면 낮은 단계를 사용하는걸 추천드립니다. 참고로 OpenGL에서의 Warning은 O3에서도 상세하게 나타나게 됩니다!

• ALLOW_MEMORY_GROWTH=1 : 프로그램이 요구하는 메모리 양이 변경되는 상황에 대해 허용해줍니다. 해당 옵션 없이 빌드하면 프로그램이 런타임 도중 메모리를 사용할 수 있는 최대치를 넘으면 뻗어버립니다.

• EXCEPTION_CATCHING_ALLOWED=[..] : 이게 참.. 중요한 요소인 것 같습니다. 왜냐하면 try catch문이 정상적으로 작동하지 않기 때문입니다! 원래 doc의 내용대로라면 정상적으로 예외처리가 되어야 하는데 해당 구문이 저에겐 먹히지 않네요... 이것저것 다 달고 구글링을 열심히 했는데도 마땅한 방안을 못 찾았습니다. 게다가 emscripten에서도 exception 처리는 생각보다 무겁기 때문에 정상적으로 처리하기 힘들다고 적혀있습니다. 다시 정리해보면 예외처리문인try catch문은 사용을 피하는게 정신건강에 이롭습니다!

• USE_WEBGL2=1 : WebGL 2.0을 활성화 여부입니다. 참고로 ES 2.0은 WebGL 1.0, ES 3.0은 WebGL 2.0으로 돌아갑니다! 저같은 경우엔 OpenGL ES 3.0이 최소사양이기 때문에 WebGL 2.0을 활성화하였습니다.

• -preload-file : 기존의 파일들을 불러와서 사용하고 싶다면 저 문구를 통해 어떤 파일들을 사용할지 설정해줍니다. 여기서 설정된 파일들은 .data 확장명을 가진 zip 형식 파일로 들어가게 됩니다.

3. CLion의 Toolchains 설정

Toolchains

• CMake : 설정 그대로

• Make : 설정 그대로

• C Compiler : emsdk/upstream/emscripten/emcc를 설정

• C++ Compiler : emsdk/upstream/emscripten/em++를 설정

• Debugger : 설정 그대로

CMake

-DCMAKE_TOOLCHAIN_FILE=[emsdk가 설치되어있는 경로]/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake

4. 빌드 된 html 확인하기

파이썬을 이용해 로컬 http 서버 실행하기

python -m http.server

5. 알아두면 좋은 내용들

전처리기 매크로

#ifdef __EMSCRIPTEN__
    static_cast<SceneMgr*>(m_sceneMgr)->SetScene(new WebDemoScene());
#endif

예외처리구문 대용?

1. 예외처리를 try 대신 bool 형태로 반환하는 예외 확인 함수를 따로 작성한다.

2. goto문을 사용한다(...)

6. 마무리