<div align="center">
<h1><code>wasm-tools</code></h1>
<strong>Bytecode Alliance의 프로젝트입니다.</strong>
<p>
<strong>WebAssembly 모듈을 저수준(low-level)으로 조작하기 위한 CLI 및 Rust 라이브러리</strong>
</p>
</div>
설치 (Installation)
CI에서 빌드된 아티팩트는 각 릴리스별로 다운로드할 수 있습니다.
소스 코드로부터 빌드하려면 먼저 사용하는 플랫폼에 맞는 Rust을 설치한 다음, 포함된 Cargo 패키지 관리자를 사용하여 다음과 같이 설치합니다:
$ cargo install --locked wasm-tools
대안으로 cargo binstall을 사용하는 경우, 이를 사용하여 사전 컴파일된 아티팩트를 설치할 수 있습니다:
$ cargo binstall wasm-tools
설치는 다음 명령어로 확인할 수 있습니다:
하위 명령어는 다음으로 탐색할 수 있습니다:
예시 (Examples)
기본 유효성 검사/출력/파싱:
$ wasm-tools validate foo.wasm
...
단순 변형(mutation) 및 명령어 파이프라인 연결:
$ wasm-tools mutate foo.wasm -t
...
컴포넌트(components) 작업:
$ wasm-tools component wit component.wasm
...
CLI 규칙 (CLI Conventions)
모든 CLI 명령어에 적용되는 몇 가지 규칙이 있습니다:
- 모든 하위 명령어는
-h를 사용하면 "간단 도움말(short help)"을, --help를 사용하면 "상세 도움말(long help)"을 출력합니다.
- 파일 입력을 지정하지 않은 경우(적용 가능한 경우), 입력은 기본적으로 stdin에서 읽어옵니다.
-o 또는 --output 플래그가 제공되지 않으면 출력이 기본적으로 stdout으로 전송됩니다. 다만, 바이너리 WebAssembly는 기본적으로 tty로 출력되지 않습니다.- WebAssembly 바이너리를 출력하는 명령어는 모두 대신 WebAssembly 텍스트 형식(WebAssembly text format)을 생성할 수 있는
-t 또는 --wat 플래그를 지원합니다.
-v 또는 --verbose 플래그를 전달하여 도구 전반에 걸친 로그 메시지를 활성화할 수 있습니다. 상세도(Verbosity)는 -vvv와 같이 해당 플래그를 여러 번 전달하여 높일 수 있습니다.- TTY 기반 출력의 경우 오류 메시지 및 콘솔 출력에서 색상이 기본적으로 활성화되며,
--color 인수를 통해 구성할 수 있습니다.
wasm-tools 바이너리 내부에는 wasm 모듈 및 컴포넌트 작업을 위한 여러 하위 명령어가 포함되어 있습니다. 또한 많은 하위 명령어들은 프로그램적으로 사용할 수 있는 Rust 크레이트(Rust crates)도 함께 제공합니다:
wasm-tools CLI는 WebAssembly 모듈 및 컴포넌트를 디버깅하는 데 유용한 도구들을 포함하고 있습니다. 다양한 하위 명령어들은 기능에 대해 더 자세히 설명하는 --help 안내 문서를 모두 가지고 있습니다.
WebAssembly 제안 (WebAssembly proposals)
이 저장소는 WebAssembly의 모든 표준화된 제안을 구현하는 것을 목표로 합니다.
Stage 4+에 해당하는 모든 제안은 검증(validation)에서 기본적으로 활성화됩니다. 텍스트 형식에서의 지원은 모든 제안에 대해 항상 활성화되어 있습니다.
현재 이 저장소에서 구현된 Stage 4+ 제안은 다음과 같습니다:
(참고: 이것은 Phase 4가 아니지만, wast는 'feature' 개념을 가지고 있지 않습니다)
이러한 제안들은 구현되었지만 아직 Stage 4에 도달하지 않았습니다. 이는 검증(validation)에서 기본적으로 비활성화된다는 것을 의미하며, 제안이 발전함에 따라 구현 방식이 시간이 지남에 따라 변경될 수 있습니다. 또한, 이러한 제안들이 구현된 이후로 해당 제안 자체가 변경되었을 수도 있으므로 불일치(mismatch)가 발생할 수도 있습니다.
라이브러리 (Libraries)
위에서 언급했듯이, wasm-tools CLI의 많은 도구들이 이 저장소에도 구현된 라이브러리를 사용합니다. 이러한 라이브러리는 다음과 같습니다:
별도의 프로젝트에 임베딩할 때는 CLI 도구링보다는 라이브러리를 직접 사용하는 것이 권장됩니다.
C/C++ 바인딩 (bindings)
crates/c-api의 CMakeLists.txt를 사용하면, wasm-tools는 wasm-tools.h 헤더에서 사용할 수 있습니다. 참고로 이 바인딩이 현재 저장소의 모든 기능을 포괄적으로 다루지는 않지만, 유용한 함수를 발견하시면 기여해 주시기 바랍니다!
버전 관리 및 릴리스 (Versioning and Releases)
이 저장소는 CLI와 crates.io(Rust의 패키지 매니저)에 게시되는 크레이트 모음을 모두 가지고 있습니다. 이 저장소에서 사용되는 버전 관리 방식은 다음과 같습니다:
wasm-tools - CLI는 버전 패턴 1.X.Y를 따릅니다. 일반적으로 Y는 0이며, 이 저장소의 릴리스에 따라 X가 증가합니다.wat - 이 Rust 크레이트(crate) 역시 1.X.Y로 버전이 지정되며 wasm-tools의 버전을 따릅니다.wast - 이 Rust 크레이트는 X.0.Y로 버전이 지정됩니다. 여기서 X는 wasm-tools의 1.X.Y에서 X와 일치합니다.- 기타 모든 크레이트(crates) - 이 저장소의 다른 모든 크레이트는
0.X.Y로 버전이 지정되며, 여기서 X는 wasm-tools의 1.X.Y와 일치합니다.
위에서 언급된 모든 버전의 Y는 이 저장소의 어떤 릴리스에서도 동일하게 유지된다는 점에 유의하십시오. 이러한 버전 관리 체계는 CLI와 wat 크레이트가 API 안정성(API stability) 측면에서 갖는 안정적인 특성을 반영하기 위함입니다. 그러나 다른 크레이트들은 모두 메이저 버전 증가를 겪으며, 이는 모든 릴리스에서 자동으로 API 호환성이 보장되는 것은 아닙니다. 이는 WebAssembly 자체가 고정된 기반이 아닌 진화하는 표준임을 반영합니다. 이 저장소의 모든 크레이트는 "프로덕션 사용(production use)"에 적합하지만, 시간이 지남에 따라 API 안정성은 보장되지 않음에 유의해야 합니다. 버전 업그레이드에 어려움이 있다면 언제든지 이슈를 제기해 주시면 도움을 드릴 수 있습니다.
또한, 이 저장소는 현재 엄격한 릴리스 주기(release cadence)가 없습니다. 릴리스는 필요할 때마다 진행됩니다. 릴리스를 요청하고 싶으시다면 Zulip에서 연락하거나, 이슈를 제기하거나, PR에 댓글을 남기거나, 기타 방식으로 유지 관리자에게 연락해 주십시오.
유지 관리자를 위한 릴리스 프로세스는 다음과 같습니다:
- 이 링크로 이동합니다.
- UI에서 "Run workflow"를 클릭합니다.
- 기본
bump 인수를 사용하고 "Run workflow"를 누릅니다.
- CI(지속적 통합, Continuous Integration)에 의해 PR이 생성될 때까지 기다립니다. 문제가 발생했는지 여부는 "Actions" 탭을 확인하실 수 있습니다.
- PR이 열리면, 이를 닫았다가 다시 엽니다. 질문하지 마십시오.
- PR을 검토하고 승인한 다음, 병합(merge) 대기열에 넣습니다.
여기까지가 전부이지만, 문제가 발생할 경우 지속적으로 CI(Continuous Integration)를 확인하는 것이 좋습니다.
패치 릴리스 프로세스 (Patch Release Process)
패치 릴리스는 자주 발생하지 않기 때문에 현재 프로세스가 다소 복잡합니다. 하지만 기본 아이디어는 일반적인 릴리스와 동일합니다:
wasm-tools 버전 1.N.0에 대한 패치 릴리스를 진행할 것임을 결정합니다.- 만약
N이 main 브랜치의 최신 버전이거나, 근본적으로 N 이후로 주요 릴리스가 발생하지 않았다면, 먼저 main에 변경 사항을 반영합니다. 그런 다음 이 링크로 이동하여 bump-patch를 인수로 사용하여 main 브랜치에 워크플로우(workflow)를 실행합니다. v1.N.0 태그부터의 모든 변경 사항을 재확인하여 어떤 크레이트(crate)에서도 하위 호환성 파괴(breaking changes)가 발생하지 않았는지 확인해야 합니다.
- 만약
N이 main 브랜치의 최신 버전이 아니라면, v1.N.0 태그에서 시작하여 저장소에 release-N이라는 새 브랜치를 생성합니다. 다음으로 이 브랜치에 PR(Pull Request) 형태로 변경 사항을 반영하고, CI가 한동안 실행되지 않았을 수 있으므로 수정이 필요할 수 있다는 점에 유의해야 합니다. 그런 다음 위와 동일한 워크플로우를 bump-patch 인수를 사용하여 release-N 브랜치에 실행합니다. 다시 한번 하위 호환성 파괴 변경 사항이 없었는지 확인하세요.
기본적으로, main 브랜치가 N을 넘어 이동한 경우 release-N을 수동으로 생성해야 할 수도 있습니다. 하지만 그 이후부터는 워크플로우가 실행되고 PR이 병합되는 등 기본적인 과정만 거치면 됩니다.
기여하기 (Contributing)
이 저장소에 기여하는 방법에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요.
라이선스 (License)
본 프로젝트는 Apache 2/Apache 2 with LLVM exceptions/MIT 라이선스를 통해 트리플 라이선싱(triple licenced) 되어 있습니다. 그 이유는 다음과 같습니다:
- Apache 2/MIT은 rust 생태계에서 흔하게 사용됩니다.
- Apache 2/MIT은 rust 컴파일러에서도 사용되며, 이 코드의 일부가 그곳으로 마이그레이션될 수 있습니다.
- 이 코드의 일부는 컴파일러 출력에 사용될 수 있으며, 이때 Apache 2 with LLVM exceptions 라이선스가 유용합니다.
더 자세한 내용은 다음을 참조하십시오.
기여(Contribution)