WebAssembly란 무엇이며 어디에서 가져왔나요?에서 나는 우리가 오늘날의 WebAssembly를 어떻게 완성하게 되었는지 설명했습니다. 이 도움말에서는 기존 C 프로그램인 mkbitmap를 WebAssembly로 컴파일하는 방법을 보여줍니다. 이는 파일 작업, WebAssembly 및 JavaScript 랜딩 간의 통신, 캔버스에 그리기가 포함되므로 hello world 예시보다 더 복잡하지만, 여전히 부담 없이 관리할 수 있습니다.
이 도움말은 WebAssembly를 배우려는 웹 개발자를 대상으로 하며 mkbitmap과 같은 것을 WebAssembly로 컴파일하려는 경우 진행할 수 있는 단계별 방법을 보여줍니다. 공정하게 말씀드리자면, 최초 실행 시 앱이나 라이브러리를 컴파일하지 못하는 것은 완전히 정상입니다. 그렇기 때문에 아래에 설명된 일부 단계가 작동하지 않아서 이전으로 돌아가 다른 방법으로 다시 시도해야 했습니다. 이 기사는 마치 하늘에서 떨어진 것처럼 최종 컴파일 명령을 보여주지 않고 오히려 실제 진행 상황을 설명하고 일부 불편 사항을 포함합니다.
mkbitmap 정보
mkbitmap C 프로그램은 이미지를 읽고 반전, 하이패스 필터링, 확장, 임곗값 순서로 하나 이상의 작업을 이미지에 적용합니다. 각 작업을 개별적으로 제어하고 사용 설정하거나 사용 중지할 수 있습니다. mkbitmap의 주요 용도는 컬러 또는 그레이 스케일 이미지를 다른 프로그램, 특히 SVGcode의 기반을 형성하는 추적 프로그램 potrace에 적합한 형식으로 변환하는 것입니다. 전처리 도구인 mkbitmap는 만화나 필기 입력 텍스트와 같은 스캔 라인 아트를 고해상도 2단계 이미지로 변환하는 데 특히 유용합니다.
여러 옵션과 하나 이상의 파일 이름을 전달하여 mkbitmap를 사용합니다. 자세한 내용은 도구의 설명서 페이지를 참조하세요.
$ mkbitmap [options] [filename...]
mkbitmap -f 2 -s 2 -t 0.48 (소스).코드 가져오기
첫 번째 단계는 mkbitmap의 소스 코드를 가져오는 것입니다. 프로젝트 웹사이트에서 확인할 수 있습니다. 이 문서의 작성 시점을 기준으로 potrace-1.16.tar.gz가 최신 버전입니다.
로컬에서 컴파일 및 설치
다음 단계는 도구를 로컬에서 컴파일하고 설치하여 어떻게 작동하는지 확인하는 것입니다. INSTALL 파일에는 다음 안내가 포함되어 있습니다.
cd를 패키지의 소스 코드가 포함된 디렉터리로 이동하고./configure를 입력하여 시스템용 패키지를 구성합니다.configure을(를) 실행하는 데 시간이 걸릴 수 있습니다. 실행 중에 어떤 기능을 확인하는지 알려주는 몇 가지 메시지가 출력됩니다.make를 입력하여 패키지를 컴파일합니다.선택적으로
make check를 입력하여 일반적으로 방금 빌드한 제거된 바이너리를 사용하여 패키지와 함께 제공되는 자체 테스트를 실행합니다.make install를 입력하여 프로그램과 데이터 파일, 문서를 설치합니다. 루트가 소유한 접두사에 설치할 때는 패키지를 일반 사용자로 구성하고 빌드하고 루트 권한으로make install단계만 실행하는 것이 좋습니다.
이 단계를 따르면 potrace 및 mkbitmap 실행 파일이 두 개 생성됩니다. 후자는 이 문서에서 중점적으로 다룹니다. mkbitmap --version를 실행하여 올바르게 작동하는지 확인할 수 있습니다. 다음은 간결성을 위해 크게 편집한 내 컴퓨터의 네 단계의 출력입니다.
1단계, ./configure:
$ ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... ./install-sh -c -d
checking for gawk... no
checking for mawk... no
checking for nawk... no
checking for awk... awk
checking whether make sets $(MAKE)... yes
[…]
config.status: executing libtool commands
2단계, make:
$ make
/Applications/Xcode.app/Contents/Developer/usr/bin/make all-recursive
Making all in src
clang -DHAVE_CONFIG_H -I. -I.. -g -O2 -MT main.o -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
mv -f .deps/main.Tpo .deps/main.Po
[…]
make[2]: Nothing to be done for `all-am'.
3단계, make check:
$ make check
Making check in src
make[1]: Nothing to be done for `check'.
Making check in doc
make[1]: Nothing to be done for `check'.
[…]
============================================================================
Testsuite summary for potrace 1.16
============================================================================
# TOTAL: 8
# PASS: 8
# SKIP: 0
# XFAIL: 0
# FAIL: 0
# XPASS: 0
# ERROR: 0
============================================================================
make[1]: Nothing to be done for `check-am'.
4단계, sudo make install:
$ sudo make install
Password:
Making install in src
.././install-sh -c -d '/usr/local/bin'
/bin/sh ../libtool --mode=install /usr/bin/install -c potrace mkbitmap '/usr/local/bin'
[…]
make[2]: Nothing to be done for `install-data-am'.
작동 여부를 확인하려면 mkbitmap --version를 실행합니다.
$ mkbitmap --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.
버전 세부정보를 가져오면 mkbitmap가 성공적으로 컴파일되어 설치된 것입니다. 그런 다음, 이 단계와 동등한 작업이 WebAssembly에서 작동하도록 합니다.
WebAssembly에 mkbitmap 컴파일
Emscripten은 C/C++ 프로그램을 WebAssembly로 컴파일하기 위한 도구입니다. Emscripten의 프로젝트 빌드 문서에는 다음과 같이 설명되어 있습니다.
Emscripten을 사용하면 대규모 프로젝트를 매우 쉽게 빌드할 수 있습니다. Emscripten은
emcc를gcc의 드롭인 대체로 사용하도록 makefile을 구성하는 간단한 두 가지 스크립트를 제공합니다. 대부분의 경우 프로젝트의 현재 빌드 시스템의 나머지 부분은 변경되지 않습니다.
그러면 문서가 계속 진행됩니다 (간결성을 위해 약간 편집됨).
일반적으로 다음 명령어로 빌드하는 경우를 고려해 보세요.
./configure
make
Emscripten으로 빌드하려면 대신 다음 명령어를 사용합니다.
emconfigure ./configure
emmake make
따라서 기본적으로 ./configure는 emconfigure ./configure가 되고 make는 emmake make가 됩니다. 다음은 mkbitmap를 사용하여 이 작업을 실행하는 방법을 보여줍니다.
0단계, make clean:
$ make clean
Making clean in src
rm -f potrace mkbitmap
test -z "" || rm -f
rm -rf .libs _libs
[…]
rm -f *.lo
1단계, emconfigure ./configure:
$ emconfigure ./configure
configure: ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... ./install-sh -c -d
checking for gawk... no
checking for mawk... no
checking for nawk... no
checking for awk... awk
[…]
config.status: executing libtool commands
2단계, emmake make:
$ emmake make
make: make
/Applications/Xcode.app/Contents/Developer/usr/bin/make all-recursive
Making all in src
/opt/homebrew/Cellar/emscripten/3.1.36/libexec/emcc -DHAVE_CONFIG_H -I. -I.. -g -O2 -MT main.o -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
mv -f .deps/main.Tpo .deps/main.Po
[…]
make[2]: Nothing to be done for `all'.
모두 잘 진행되었다면 디렉터리 어딘가에 .wasm 파일이 있을 것입니다. find . -name "*.wasm"를 실행하여 찾을 수 있습니다.
$ find . -name "*.wasm"
./a.wasm
./src/mkbitmap.wasm
./src/potrace.wasm
마지막 두 패키지는 가능성이 높으므로 src/ 디렉터리로 cd합니다. 이제 상응하는 새로운 파일 두 개(mkbitmap 및 potrace)도 있습니다. 이 도움말에서는 mkbitmap만 관련이 있습니다. .js 확장 프로그램이 없다는 사실이 약간 혼란스럽지만 사실 간단한 head 호출로 확인할 수 있는 JavaScript 파일입니다.
$ cd src/
$ head -n 20 mkbitmap
// include: shell.js
// The Module object: Our interface to the outside world. We import
// and export values on it. There are various ways Module can be used:
// 1. Not defined. We create it here
// 2. A function parameter, function(Module) { ..generated code.. }
// 3. pre-run appended it, var Module = {}; ..generated code..
// 4. External script tag defines var Module.
// We need to check if Module already exists (e.g. case 3 above).
// Substitution will be replaced with actual code on later stage of the build,
// this way Closure Compiler will not mangle it (e.g. case 4. above).
// Note that if you want to run closure, and also to use Module
// after the generated code, you will need to define var Module = {};
// before the code. Then that object will be used in the code, and you
// can continue to use Module afterwards as well.
var Module = typeof Module != 'undefined' ? Module : {};
// --pre-jses are emitted after the Module integration code, so that they can
// refer to Module (if they choose; they can also define Module)
mv mkbitmap mkbitmap.js (원하는 경우 각각 mv potrace potrace.js)를 호출하여 JavaScript 파일의 이름을 mkbitmap.js로 바꿉니다.
이제 node mkbitmap.js --version를 실행하여 명령줄에서 Node.js로 파일을 실행하여 첫 번째 테스트가 작동하는지 확인해 보겠습니다.
$ node mkbitmap.js --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.
mkbitmap를 WebAssembly에 컴파일했습니다. 이제 다음 단계는 브라우저에서 작동하도록 하는 것입니다.
브라우저에서 WebAssembly를 사용한 mkbitmap
mkbitmap.js 및 mkbitmap.wasm 파일을 mkbitmap라는 새 디렉터리에 복사하고 mkbitmap.js JavaScript 파일을 로드하는 index.html HTML 상용구 파일을 만듭니다.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>mkbitmap</title>
</head>
<body>
<script src="mkbitmap.js"></script>
</body>
</html>
mkbitmap 디렉터리를 제공하는 로컬 서버를 시작하고 브라우저에서 엽니다. 입력을 요청하는 메시지가 표시됩니다. 이는 도구의 설명 페이지에 따르면 '[i]파일 이름 인수가 주어지지 않은 경우 mkbitmap이 필터 역할을 하며 표준 입력에서 읽어서' Emscripten의 경우 기본적으로 prompt()이기 때문입니다.
자동 실행 방지
mkbitmap 실행을 즉시 중지하고 사용자 입력을 기다리게 하려면 Emscripten의 Module 객체를 이해해야 합니다. Module는 Emscripten이 생성한 코드가 실행의 여러 지점에서 호출하는 속성이 포함된 전역 JavaScript 객체입니다.
Module의 구현을 제공하여 코드 실행을 제어할 수 있습니다.
Emscripten 애플리케이션이 시작되면 Module 객체의 값을 보고 적용합니다.
mkbitmap의 경우 Module.noInitialRun를 true로 설정하여 프롬프트가 표시된 초기 실행을 방지합니다. script.js라는 스크립트를 만들어 index.html의 <script src="mkbitmap.js"></script> 앞에 포함하고 다음 코드를 script.js에 추가합니다. 이제 앱을 새로고침하면 메시지가 사라집니다.
var Module = {
// Don't run main() at page load
noInitialRun: true,
};
빌드 플래그를 더 추가하여 모듈식 빌드 만들기
앱에 입력을 제공하려면 Module.FS에서 Emscripten의 파일 시스템 지원을 사용하면 됩니다. 문서의 파일 시스템 지원 포함 섹션에는 다음과 같은 내용이 명시되어 있습니다.
Emscripten은 파일 시스템 지원을 자동으로 포함할지 여부를 결정합니다. 많은 프로그램에는 파일이 필요하지 않고 파일 시스템 지원의 크기도 무시할 수 없기 때문에 Emscripten에서는 이유가 파악되지 않으면 포함시키지 않습니다. 즉, C/C++ 코드가 파일에 액세스하지 않으면
FS객체 및 기타 파일 시스템 API가 출력에 포함되지 않습니다. 반면에 C/C++ 코드에서 파일을 사용하는 경우 파일 시스템 지원이 자동으로 포함됩니다.
불행히도 mkbitmap는 Emscripten에 파일 시스템 지원이 자동으로 포함되지 않는 사례 중 하나이므로 명시적으로 지정해야 합니다. 즉, CFLAGS 인수를 통해 몇 개의 플래그를 더 설정하여 앞에서 설명한 emconfigure 및 emmake 단계를 따라야 합니다. 다음 플래그는 다른 프로젝트에도 유용할 수 있습니다.
- 파일 시스템 지원이 포함되도록
-sFILESYSTEM=1를 설정합니다. Module.FS및Module.callMain가 내보내지도록-sEXPORTED_RUNTIME_METHODS=FS,callMain를 설정합니다.-sMODULARIZE=1및-sEXPORT_ES6를 설정하여 최신 ES6 모듈을 생성합니다.- 메시지를 표시하는 최초 실행을 방지하려면
-sINVOKE_RUN=0를 설정합니다.
또한 이 특정 경우에는 --host 플래그를 wasm32로 설정하여 WebAssembly용으로 컴파일하고 있음을 configure 스크립트에 알려야 합니다.
최종 emconfigure 명령어는 다음과 같습니다.
$ emconfigure ./configure --host=wasm32 CFLAGS='-sFILESYSTEM=1 -sEXPORTED_RUNTIME_METHODS=FS,callMain -sMODULARIZE=1 -sEXPORT_ES6 -sINVOKE_RUN=0'
emmake make를 다시 실행하고 새로 만든 파일을 mkbitmap 폴더에 복사해야 합니다.
ES 모듈 script.js만 로드하도록 index.html를 수정합니다. 그런 다음 여기에서 mkbitmap.js 모듈을 가져옵니다.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>mkbitmap</title>
</head>
<body>
<!-- No longer load `mkbitmap.js` here -->
<script src="script.js" type="module"></script>
</body>
</html>
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
console.log(Module);
};
run();
이제 브라우저에서 앱을 열면 DevTools 콘솔에 기록된 Module 객체가 표시되고 시작 시 mkbitmap의 main() 함수가 더 이상 호출되지 않으므로 프롬프트가 사라집니다.
수동으로 main 함수 실행
다음 단계는 Module.callMain()를 실행하여 mkbitmap의 main() 함수를 수동으로 호출하는 것입니다. callMain() 함수는 인수 배열을 취하며, 이 배열은 명령줄에서 전달할 내용과 하나씩 일치합니다. 명령줄에서 mkbitmap -v를 실행하는 경우 브라우저에서 Module.callMain(['-v'])를 호출합니다. 그러면 mkbitmap 버전 번호가 DevTools 콘솔에 로깅됩니다.
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
Module.callMain(['-v']);
};
run();
표준 출력 리디렉션
기본적으로 표준 출력 (stdout)은 콘솔입니다. 그러나 출력을 변수에 저장하는 함수 등 다른 것으로 리디렉션할 수는 있습니다. 즉, Module.print 속성을 설정하여 HTML에 출력을 추가할 수 있습니다.
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
let consoleOutput = 'Powered by ';
const Module = await loadWASM({
print: (text) => (consoleOutput += text),
});
Module.callMain(['-v']);
document.body.textContent = consoleOutput;
};
run();
입력 파일을 메모리 파일 시스템으로 가져오기
입력 파일을 메모리 파일 시스템으로 가져오려면 명령줄에 상응하는 mkbitmap filename가 필요합니다. 이에 접근하는 방법을 이해하려면 먼저 mkbitmap가 입력을 예상하고 출력을 생성하는 방법에 대한 배경 지식을 알아보겠습니다.
mkbitmap의 지원되는 입력 형식은 PNM (PBM, PGM, PPM) 및 BMP입니다. 출력 형식은 비트맵용 PBM, 그레이맵용 PGM입니다. filename 인수가 주어지면 mkbitmap는 기본적으로 접미사를 .pbm로 변경하여 입력 파일 이름에서 이름을 가져오는 출력 파일을 만듭니다. 예를 들어 입력 파일 이름 example.bmp의 경우 출력 파일 이름은 example.pbm입니다.
Emscripten은 로컬 파일 시스템을 시뮬레이션하는 가상 파일 시스템을 제공하므로, 동기식 파일 API를 사용하는 네이티브 코드를 변경 없이 컴파일하고 실행할 수 있습니다.
mkbitmap가 입력 파일을 filename 명령줄 인수로 전달된 것처럼 읽으려면 Emscripten에서 제공하는 FS 객체를 사용해야 합니다.
FS 객체는 메모리 내 파일 시스템 (일반적으로 MEMFS라고 함)에서 지원되며 가상 파일 시스템에 파일을 쓰는 데 사용하는 writeFile() 함수를 포함하고 있습니다. 다음 코드 샘플과 같이 writeFile()를 사용합니다.
파일 쓰기 작업이 작동하는지 확인하려면 '/' 매개변수를 사용하여 FS 객체의 readdir() 함수를 실행합니다. example.bmp 및 항상 자동으로 생성되는 여러 기본 파일이 표시됩니다.
버전 번호 출력을 위한 이전 Module.callMain(['-v']) 호출은 삭제되었습니다. 이는 Module.callMain()가 일반적으로 한 번만 실행될 것으로 예상되는 함수이기 때문입니다.
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
const buffer = await fetch('https://example.com/example.bmp').then((res) => res.arrayBuffer());
Module.FS.writeFile('example.bmp', new Uint8Array(buffer));
console.log(Module.FS.readdir('/'));
};
run();
첫 번째 실제 실행
모든 것이 준비되면 Module.callMain(['example.bmp'])를 실행하여 mkbitmap를 실행합니다. MEMFS의 '/' 폴더의 콘텐츠를 로깅하면 example.bmp 입력 파일 옆에 새로 생성된 example.pbm 출력 파일이 표시됩니다.
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
const buffer = await fetch('https://example.com/example.bmp').then((res) => res.arrayBuffer());
Module.FS.writeFile('example.bmp', new Uint8Array(buffer));
Module.callMain(['example.bmp']);
console.log(Module.FS.readdir('/'));
};
run();
메모리 파일 시스템에서 출력 파일 가져오기
FS 객체의 readFile() 함수를 사용하면 메모리 파일 시스템에서 마지막 단계에서 생성된 example.pbm를 가져올 수 있습니다. 브라우저는 일반적으로 브라우저에서 직접 볼 수 있는 PBM 파일을 지원하지 않으므로 이 함수는 File 객체로 변환하여 디스크에 저장하는 Uint8Array를 반환합니다.
파일을 저장하는 더 세련된 방법이 있지만 동적으로 생성된 <a download>를 사용하는 것이 가장 널리 지원되는 방법입니다. 파일이 저장되면 원하는 이미지 뷰어에서 열 수 있습니다.
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
const buffer = await fetch('https://example.com/example.bmp').then((res) => res.arrayBuffer());
Module.FS.writeFile('example.bmp', new Uint8Array(buffer));
Module.callMain(['example.bmp']);
const output = Module.FS.readFile('example.pbm', { encoding: 'binary' });
const file = new File([output], 'example.pbm', {
type: 'image/x-portable-bitmap',
});
const a = document.createElement('a');
a.href = URL.createObjectURL(file);
a.download = file.name;
a.click();
};
run();
대화형 UI 추가
이 시점까지 입력 파일이 하드코딩되고 mkbitmap가 기본 매개변수로 실행됩니다. 마지막 단계는 사용자가 동적으로 입력 파일을 선택하도록 하고 mkbitmap 매개변수를 조정한 다음 선택한 옵션으로 도구를 실행하는 것입니다.
// Corresponds to `mkbitmap -o output.pbm input.bmp -s 8 -3 -f 4 -t 0.45`.
Module.callMain(['-o', 'output.pbm', 'input.bmp', '-s', '8', '-3', '-f', '4', '-t', '0.45']);
PBM 이미지 형식은 특히 파싱하기가 어렵지 않으므로 일부 JavaScript 코드를 사용하면 출력 이미지의 미리보기도 표시할 수 있습니다. 이 작업을 수행하는 한 가지 방법은 아래에 삽입된 데모의 소스 코드를 참고하세요.
결론
축하합니다. mkbitmap를 WebAssembly로 컴파일하여 브라우저에서 작동하게 했습니다. 일부 막다른 골목이 있었고 작동할 때까지 도구를 두 번 이상 컴파일해야 했지만 위에서 언급했듯이 이는 경험의 일부입니다. 문제가 발생하면 StackOverflow의 webassembly 태그에 유의하세요. 즐겁게 컴파일하시길 바랍니다.
감사의 말
Sam Cleg 및 Rachel Andrew가 작성한 도움말입니다.