C/C++ 도구

WebAssembly 컴포넌트는 LLVM용 C 언어 계열 프런트엔드인 clang을 사용하여 C 및 C++로 빌드할 수 있습니다.

wit-bindgen은 주어진 .wit 파일로부터 게스트 언어 바인딩을 생성하는 도구입니다. C 또는 C++ 코드를 WebAssembly 컴포넌트로 컴파일할 때, C 또는 C++를 “게스트” 언어라고 하고 WebAssembly를 “호스트” 언어라고 합니다. 이 경우 “바인딩“은 C 또는 C++ 선언, 즉 WIT 함수에 대응하는 타입 시그니처와 WIT 타입에 대응하는 타입 정의입니다. 바인딩 생성기는 선언만 생성하므로, 자체 .wit 파일을 개발하는 경우 이러한 선언을 실제로 구현하는 코드는 직접 작성해야 합니다. WASI에 내장된 WIT 인터페이스의 경우, 해당 코드는 사용하게 될 WebAssembly 런타임의 일부입니다.

C/C++에는 현재 통합 툴체인이 없습니다. 그러나 wit-bindgen은 Rust, C, Java(TeaVM), TinyGo용 소스 수준 바인딩을 생성할 수 있으며, 향후 더 많은 언어 생성기를 추가할 수 있습니다.

wit-bindgen을 사용하면 wasm32-wasi 대상과 함께 clang을 사용하여 WebAssembly 모듈로 직접 컴파일할 수 있는 C 애플리케이션을 빌드할 수 있습니다.

1. 의존성 다운로드

먼저 다음 의존성을 설치하십시오.

1. wit-bindgen CLI
2. wasm-tools
   • wasm-tools는 컴파일된 WebAssembly 모듈과 컴포넌트를 검사하는 데 사용할 수 있으며, 선택적인 수동 워크플로에서 preview1 모듈과 preview2 컴포넌트 간 변환에도 사용할 수 있습니다.
3. WASI SDK
   • WASI SDK는 WASI를 지원하는 C/C++ 툴체인으로, C/C++를 WebAssembly로 컴파일하는 데 필요한 여러 아티팩트와 함께 WASI 인터페이스로 구현된 C 표준 라이브러리(libc)의 한 버전을 포함합니다.
   • Linux 시스템에서는 “Install” 섹션으로 건너뛸 수 있습니다. 소스에서 빌드하려면 README의 처음부터 시작하십시오.

WASI SDK를 설치하면 WASI sysroot로 구성된 로컬 버전의 clang이 포함됩니다. (sysroot는 특정 대상 플랫폼용 헤더 파일과 라이브러리를 담고 있는 디렉터리입니다.) WASI SDK를 사용할 수 있도록 구성하려면 이 지침을 따르십시오.

2. WIT에서 프로그램 스켈레톤 생성

먼저 샘플 adder/world.wit 파일의 내용을 로컬 파일에 붙여 넣으십시오. 그런 다음 이 파일을 사용하여 wit-bindgen으로 C 스켈레톤을 생성하십시오.

$ wit-bindgen c path/to/adder/world.wit
Generating "adder.c"
Generating "adder.h"
Generating "adder_component_type.o"

이 명령은 여러 파일을 생성합니다.

1. adder.h(adder 월드 기반). 이 헤더 파일에는 일부 보일러플레이트와 함께 add 함수의 프로토타입이 포함되어 있으며, 다음과 같은 형태여야 합니다. (함수 이름 앞에 “exports” 접두사가 붙어 있습니다.)

  uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y);

2. adder.c는 컴포넌트 모델 ABI와 인터페이스하여 함수를 호출합니다. 이 파일에는 다음과 같은 형태의 extern 선언이 포함되어 있습니다.

    extern void __component_type_object_force_link_adder(void);

3. adder_component_type.o에는 __component_type_object_force_link_adder 함수의 정의를 포함한 오브젝트 코드가 들어 있으며, 이 파일은 clang을 통해 링크해야 합니다.

3. 프로그램 코드 작성

다음으로, adder 월드를 구현하는 코드, 즉 adder.h에 선언된 인터페이스 함수의 정의를 충족하는 코드를 담은 component.c 파일을 생성하십시오.

#include "adder.h"

uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y)
{
	return x + y;
}

4. wasi-sdk의 wasm32-wasip2-clang으로 WebAssembly Preview 2 컴포넌트 컴파일

“P1“은 WASI API의 초기 버전인 WASI Preview 1을 가리킵니다. “P2“는 컴포넌트 모델을 도입한 WASI Preview 2를 가리킵니다.

과거에는 P2 컴포넌트를 빌드하려면 P1 컴포넌트에서 변환해야 했지만, 이제는 WASI SDK가 설치한 wasm32-wasip2-clang 바이너리를 사용하여 P2 컴포넌트를 직접 빌드할 수 있습니다.

필요한 경우 /opt/wasi-sdk를 WASI SDK를 설치한 경로로 변경하십시오.

/opt/wasi-sdk/bin/wasm32-wasip2-clang \
    -o adder.wasm \
    -mexec-model=reactor \
    component.c \
    adder.c \
    adder_component_type.o

이 명령의 각 부분을 살펴보면 다음과 같습니다.

• -o adder.wasm은 바이너리 WebAssembly 코드를 담을 출력 파일을 설정합니다.
• -mexec-model=reactor는 생성되는 코드에 원하는 실행 모델을 제어합니다. 인수는 reactor 또는 command 중 하나일 수 있습니다. 이 경우에는 reactor 컴포넌트를 빌드하기 위해 -mexec-model=reactor를 전달합니다. 리액터 컴포넌트는 라이브러리에 더 가깝고, command 컴포넌트는 실행 파일에 더 가깝습니다.
• component.c에는 adder 월드를 구현하기 위해 작성한 코드가 들어 있습니다.
• adder.c와 adder_component_type.o는 wit-bindgen이 생성한 것으로, component.c를 WebAssembly 바이너리로 빌드하는 데 필요한 스캐폴딩(예: 함수 익스포트)을 포함합니다.

이 명령이 완료되면 소스 폴더에 adder.wasm이라는 새 파일이 생성됩니다.

다음 명령으로 adder.wasm이 유효한 WebAssembly 컴포넌트인지 확인할 수 있습니다.

> wasm-tools print adder.wasm | head -1
(component

P2를 지원하지 않는 플랫폼용으로 빌드하는 경우처럼 P1 모듈을 빌드하거나 기존 P1 모듈을 P2 모듈로 변환하거나 둘 다 해야 하는 사용 사례라면, wasi-sdk의 clang과 wasm-tools를 사용하는 보다 수동적인 방법에 대한 자세한 내용을 아래에서 확인할 수 있습니다.

$WASI_SDK_PATH/bin/clang \
    -o adder.wasm \
    -mexec-model=reactor \
    component.c \
    adder.c \
    adder_component_type.o

> wasm-tools print adder.wasm | head -1
(module $adder.wasm

wasm-tools component new adder.wasm -o adder.component.wasm

#include "adder.h"
#include <stdio.h>

uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y)
{
	uint32_t result = x + y;
        // On traditional platforms, printf() prints to stdout, but on Wasm platforms,
        // stdout and the idea of printing to an output stream is
        // introduced and managed by WASI.
        //
        // When building this code with wasi-libc (as a part of wasi-sdk), the printf call
        // below is implemented with code that uses `wasi:cli/stdout` and `wasi:io/streams`.
	printf("%d", result);
	return result;
}

> wasm-tools component new adder.wasm -o adder.component.wasm
error: failed to encode a component from module

Caused by:
    0: failed to decode world from module
    1: module was not valid
    2: failed to resolve import `wasi_snapshot_preview1::fd_close`
    3: module requires an import interface named `wasi_snapshot_preview1`

wasm-tools component new \
    adder.wasm \
    --adapt wasi_snapshot_preview1.wasm \
    -o adder.component.wasm

5. 빌드된 컴포넌트 검사하기

마지막으로, 컴포넌트의 임포트와 익스포트(WASI 임포트를 사용한 경우 이를 포함)의 WIT 표현을 검사할 수 있습니다:

$ wasm-tools component wit adder.component.wasm
package root:component;

world root {
  import wasi:io/error@0.2.2;
  import wasi:io/streams@0.2.2;
  import wasi:cli/stdin@0.2.2;
  import wasi:cli/stdout@0.2.2;
  import wasi:cli/stderr@0.2.2;
  import wasi:cli/terminal-input@0.2.2;
  import wasi:cli/terminal-output@0.2.2;
  import wasi:cli/terminal-stdin@0.2.2;
  import wasi:cli/terminal-stdout@0.2.2;
  import wasi:cli/terminal-stderr@0.2.2;
  import wasi:clocks/wall-clock@0.2.2;
  import wasi:filesystem/types@0.2.2;
  import wasi:filesystem/preopens@0.2.2;

  export add: func(x: s32, y: s32) -> s32;
}
...

6. wasmtime --invoke로 컴포넌트 실행하기

Wasmtime을 임베드하는 호스트 애플리케이션을 작성하지 않고 add 익스포트를 빠르게 실행하려면, Wasmtime CLI로 직접 호출할 수 있습니다.

wasmtime run --invoke 'add(2, 2)' adder.wasm

Wasmtime 버전에 따라 축약형도 동작할 수 있습니다:

wasmtime --invoke 'add(2,2)' adder.wasm

7. 예제 C 호스트에서 컴포넌트 실행하기

이 저장소에는 add 인터페이스를 구현하는 컴포넌트를 실행할 수 있는 C 애플리케이션이 포함되어 있습니다. 이 애플리케이션은 Wasmtime C API를 사용하여 Wasmtime을 임베드합니다: component-model/examples/example-c-host/host.c.

이 애플리케이션은 세 개의 인수를 받습니다: 더할 두 숫자와 덧셈을 실행한 Wasm 컴포넌트입니다. 예를 들면 다음과 같습니다.

./adder-host <x> <y> <path-to-component.wasm>

Dockerfile을 사용하여 C 애플리케이션으로 add 컴포넌트를 실행하거나, 애플리케이션을 직접 실행할 수 있습니다.

옵션 A: 호스트를 직접 컴파일하고 실행하기

시스템에 Wasmtime C API 헤더와 라이브러리가 설치되어 있다면, 호스트를 직접 컴파일하고 실행할 수 있습니다:

Linux에서는 다음 명령이 Dockerfile과 같은 방식으로 C API 아티팩트를 /usr/local에 설치합니다:

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  gcc libc6-dev curl xz-utils ca-certificates

WASMTIME_VERSION=42.0.1
case "$(uname -m)" in
  x86_64) WASMTIME_ARCH=x86_64 ;;
  aarch64|arm64) WASMTIME_ARCH=aarch64 ;;
  *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac

curl -sL "https://github.com/bytecodealliance/wasmtime/releases/download/v${WASMTIME_VERSION}/wasmtime-v${WASMTIME_VERSION}-${WASMTIME_ARCH}-linux-c-api.tar.xz" \
  | sudo tar xJ --strip-components=1 -C /usr/local

sudo ldconfig

cd component-model/examples/example-c-host
gcc -o adder-host host.c -lwasmtime
./adder-host 1 2 /absolute/path/to/adder.wasm

Linux에서 libwasmtime.so가 기본 라이브러리 경로에 없다면, 실행하기 전에 LD_LIBRARY_PATH를 설정하십시오:

LD_LIBRARY_PATH=/path/to/wasmtime/lib ./adder-host 1 2 /absolute/path/to/adder.wasm

예상 출력:

1 + 2 = 3

옵션 B: Docker로 실행하기

Wasmtime C API를 설치하는 대신, C 애플리케이션을 빌드하도록 제공된 Dockerfile을 사용할 수 있습니다.

component-model/examples/example-c-host에서 다음을 실행하십시오:

cd component-model/examples/example-c-host
docker build -t example-c-host:latest .

그런 다음 컴포넌트를 볼륨으로 전달하여 컨테이너를 실행하십시오:

docker run --rm \
  -v "$(pwd)/../example-host/add.wasm":/component/add.wasm:ro \
  example-c-host:latest

예상 출력:

1 + 2 = 3

기본 명령은 adder-host 1 2 /component/add.wasm을 실행하므로, 다음과 같이 인수를 재정의할 수도 있습니다:

docker run --rm \
  -v "$(pwd)/../example-host/add.wasm":/component/add.wasm:ro \
  example-c-host:latest 40 2 /component/add.wasm