HWPJS

    개발 환경 설정

    HWPJS 프로젝트를 개발하기 위한 환경 설정 방법입니다.

    요구사항

    Node.js

    • Node.js >= 12.22.0 < 13 || >= 14.17.0 < 15 || >= 15.12.0 < 16 || >= 16.0.0

    개발 환경 설정

    개발 환경에서는 mise를 사용하여 필요한 도구를 설치합니다.

    mise 설치

    mise는 버전 관리 도구로, 프로젝트에 필요한 모든 도구를 자동으로 설치하고 관리합니다.

    macOS / Linux:

    curl https://mise.run | sh

    Windows:

    powershell -c "irm https://mise.run | iex"

    또는 공식 문서를 참고하여 설치할 수 있습니다.

    프로젝트 도구 설치

    프로젝트 루트 디렉토리에서 다음 명령어를 실행하면 .mise.toml에 정의된 모든 도구가 자동으로 설치됩니다:

    mise install

    설치되는 도구:

    • Rust: stable (LTS)
    • Bun: latest (LTS)
    • Node.js: 24.11.1 (LTS)
    • Ruby: 3.3

    크로스 컴파일 (다중 플랫폼 빌드)

    다양한 플랫폼을 위한 크로스 컴파일을 위해서는 필요한 Rust 타겟을 설치해야 합니다:

    # 모든 타겟 설치 (WASM 제외)
rustup target add x86_64-pc-windows-msvc
rustup target add x86_64-apple-darwin
rustup target add x86_64-unknown-linux-gnu
rustup target add i686-pc-windows-msvc
rustup target add aarch64-apple-darwin
rustup target add aarch64-pc-windows-msvc

# WASM 타겟 (별도 설치)
rustup target add wasm32-wasip1-threads

    크로스 컴파일 도구:

    • Windows 크로스 컴파일: cargo-xwin 설치 필요

      cargo install cargo-xwin

    • Linux 크로스 컴파일: cross가 컨테이너 런타임(Docker 등)을 사용합니다. macOS에서는 Colima를 권장합니다. 아래 "Linux x64 크로스 빌드 (macOS)" 절을 참고해 환경을 설치한 뒤 build:node:linux-x64를 실행하면 됩니다.

    빌드 스크립트:

    • build:node:windows-*: --cross-compile 플래그 사용 (cargo-xwin 자동 감지)
    • build:node:linux-*: --use-cross 플래그 사용 (Colima 또는 Docker 필요)
    • build:node:macos-*: 네이티브 빌드 (Mac만 가능)
    • build:wasm: WASM 빌드

    Linux x64 크로스 빌드 (macOS)

    맥에서 Linux x64용 Node 네이티브 모듈을 빌드하려면 Colima(또는 Docker Desktop)와 cross가 필요합니다. macOS에서는 Docker Desktop 없이 경량 VM을 쓰는 Colima 사용을 권장합니다.

    Apple Silicon (M1/M2 등) 에서는 QEMU로 x86_64를 에뮬레이션하므로, 프로젝트는 Ubuntu 24 기반 커스텀 이미지와 LLD 링커를 사용해 빌드 안정성을 높였습니다.

    1. Colima 설치 및 실행 (macOS 권장)

    Colima는 Docker 호환 CLI를 제공하는 경량 컨테이너 런타임입니다.

    # Colima와 Docker CLI 설치
brew install colima docker

# Colima VM 시작 (처음 한 번, 이후 재부팅 시 필요 시 colima start)
colima start

    실행 후 docker 명령을 사용할 수 있습니다. 상태 확인: colima status

    2. cross 설치

    cargo install cross

    3. Linux x64 빌드 실행

    cd packages/hwpjs
bun run build:node:linux-x64

    Apple Silicon 맥에서는 x86_64 이미지를 사용하도록 플랫폼을 지정하는 것이 좋습니다.

    cd packages/hwpjs
CROSS_BUILD_OPTS="--platform linux/amd64" bun run build:node:linux-x64

    빌드가 끝나면 packages/hwpjs/dist/hwpjs.linux-x64-gnu.node가 생성됩니다. 첫 빌드는 Docker 이미지 빌드와 의존성 컴파일 때문에 10~20분 정도 걸릴 수 있습니다.

    참고

    • Cross.toml: Linux x64 타겟에 대해 docker/Dockerfile.x86_64-unknown-linux-gnu(Ubuntu 24.04 + Rust + LLD)를 사용하도록 설정되어 있습니다.
    • Docker Desktop을 이미 사용 중이라면 Colima 없이 cross와 Docker만으로 동일한 빌드가 가능합니다.
    • "content digest not found" 오류: Apple Silicon에서 ubuntu:24.04 multi-arch 이미지를 풀 때 arm64 digest 참조가 실패할 수 있습니다. Dockerfile에서 --platform=linux/amd64와 amd64 전용 digest를 명시해 두었으므로, 해당 오류가 나면 Dockerfile 상단의 digest가 최신인지 확인하세요.