Emscripten dan npm

Bagaimana cara Anda mengintegrasikan WebAssembly ke dalam penyiapan ini? Dalam artikel ini, kita akan membahasnya dengan C/C++ dan Emscripten sebagai contoh.

Surma

WebAssembly (wasm) sering kali digambarkan sebagai primitif performa atau cara untuk menjalankan codebase C++ yang ada di web. Dengan squoosh.app, kami ingin menunjukkan bahwa setidaknya ada perspektif ketiga untuk wasm: memanfaatkan ekosistem yang besar dari bahasa pemrograman lainnya. Dengan Emscripten, Anda dapat menggunakan kode C/C++, Rust memiliki dukungan wasm bawaan, dan tim Go juga sedang mengerjakannya. Saya yakin banyak bahasa lain akan menyusul.

Dalam skenario ini, wasm bukan inti aplikasi Anda, melainkan bagian teka-teki: modul lain. Aplikasi Anda sudah memiliki JavaScript, CSS, aset gambar, sistem build yang berfokus pada web, dan mungkin juga framework seperti React. Bagaimana cara mengintegrasikan WebAssembly ke dalam penyiapan ini? Dalam artikel ini, kita akan membahasnya dengan C/C++ dan Emscripten sebagai contoh.

Docker

Catatan: Meskipun saya akan menggunakan Docker, Anda tidak perlu memahami Docker secara mendalam untuk mengikuti artikel ini. Jika Docker telah diinstal di komputer, Anda sudah siap.

Saya mendapati bahwa Docker sangat berharga saat bekerja dengan Emscripten. Library C/C++ sering ditulis agar berfungsi dengan sistem operasi tempat library tersebut dibuat. Memiliki lingkungan yang konsisten sangat membantu. Dengan Docker, Anda mendapatkan sistem Linux virtual yang sudah disiapkan untuk berfungsi dengan Emscripten dan telah menginstal semua alat dan dependensi. Jika ada yang tidak ada, Anda cukup menginstalnya tanpa harus khawatir tentang pengaruhnya terhadap mesin Anda sendiri atau project Anda yang lain. Jika terjadi kesalahan, buang penampung dan mulai ulang. Jika berhasil sekali, Anda dapat yakin bahwa kode tersebut akan terus berfungsi dan menghasilkan hasil yang identik.

Docker Registry memiliki image Emscripten dari trzeci yang telah saya gunakan secara ekstensif.

Integrasi dengan npm

Pada sebagian besar kasus, titik entri ke project web adalah package.json npm. Secara umum, sebagian besar project dapat dibuat dengan npm install && npm run build.

Secara umum, artefak build yang dihasilkan oleh Emscripten (file .js dan .wasm) harus diperlakukan sebagai modul JavaScript lain dan aset lain. File JavaScript dapat ditangani oleh bundler seperti webpack atau rollup, dan file wasm harus diperlakukan seperti aset biner lainnya yang lebih besar, seperti gambar.

Dengan demikian, artefak build Emscripten harus dibuat sebelum proses build "normal" Anda dimulai:

{
    "name": "my-worldchanging-project",
    "scripts": {
    "build:emscripten": "docker run --rm -v $(pwd):/src trzeci/emscripten
./build.sh",
    "build:app": "<the old build command>",
    "build": "npm run build:emscripten && npm run build:app",
    // ...
    },
    // ...
}

Tugas build:emscripten baru dapat memanggil Emscripten secara langsung, tetapi seperti yang disebutkan sebelumnya, sebaiknya gunakan Docker untuk memastikan lingkungan build konsisten.

docker run ... trzeci/emscripten ./build.sh memberi tahu Docker untuk membuat container baru menggunakan image trzeci/emscripten dan menjalankan perintah ./build.sh. build.sh adalah skrip shell yang akan Anda tulis selanjutnya. --rm memberi tahu Docker untuk menghapus penampung setelah selesai berjalan. Dengan cara ini, Anda tidak akan membuat kumpulan image mesin yang sudah tidak berlaku dari waktu ke waktu. -v $(pwd):/src berarti Anda ingin Docker "mencerminkan" direktori saat ini ($(pwd)) ke /src di dalam penampung. Setiap perubahan yang Anda buat pada file di direktori /src di dalam penampung akan dicerminkan ke project sebenarnya. Direktori yang dicerminkan ini disebut "bind mount".

Mari kita lihat build.sh:

#!/bin/bash

set -e

export OPTIMIZE="-Os"
export LDFLAGS="${OPTIMIZE}"
export CFLAGS="${OPTIMIZE}"
export CXXFLAGS="${OPTIMIZE}"

echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
(
    # Compile C/C++ code
    emcc \
    ${OPTIMIZE} \
    --bind \
    -s STRICT=1 \
    -s ALLOW_MEMORY_GROWTH=1 \
    -s MALLOC=emmalloc \
    -s MODULARIZE=1 \
    -s EXPORT_ES6=1 \
    -o ./my-module.js \
    src/my-module.cpp

    # Create output folder
    mkdir -p dist
    # Move artifacts
    mv my-module.{js,wasm} dist
)
echo "============================================="
echo "Compiling wasm bindings done"
echo "============================================="

Ada banyak hal yang perlu dianalisis di sini.

set -e menempatkan shell ke mode "fail fast". Jika ada perintah dalam skrip yang menampilkan error, seluruh skrip akan langsung dibatalkan. Hal ini dapat sangat membantu karena output terakhir skrip akan selalu berupa pesan sukses atau error yang menyebabkan build gagal.

Dengan pernyataan export, Anda menentukan nilai beberapa variabel lingkungan. Dengan parameter ini, Anda dapat meneruskan parameter command line tambahan ke compiler C (CFLAGS), compiler C++ (CXXFLAGS), dan linker (LDFLAGS). Semuanya menerima setelan pengoptimal melalui OPTIMIZE untuk memastikan bahwa semuanya dioptimalkan dengan cara yang sama. Ada beberapa kemungkinan nilai untuk variabel OPTIMIZE:

• -O0: Jangan melakukan pengoptimalan apa pun. Tidak ada kode mati yang dihapus, dan Emscripten juga tidak meminifikasi kode JavaScript yang dihasilkannya. Cocok untuk proses debug.
• -O3: Mengoptimalkan performa secara agresif.
• -Os: Mengoptimalkan performa dan ukuran secara agresif sebagai kriteria sekunder.
• -Oz: Mengoptimalkan ukuran secara agresif, mengorbankan performa jika diperlukan.

Untuk web, saya merekomendasikan -Os.

Perintah emcc memiliki banyak opsi sendiri. Perhatikan bahwa emcc seharusnya merupakan "penggantian langsung untuk compiler seperti GCC atau clang". Jadi, semua flag yang mungkin Anda ketahui dari GCC kemungkinan besar juga akan diterapkan oleh emcc. Flag -s bersifat khusus karena memungkinkan kita mengonfigurasi Emscripten secara khusus. Semua opsi yang tersedia dapat ditemukan di settings.js Emscripten, tetapi file tersebut bisa sangat membingungkan. Berikut adalah daftar flag Emscripten yang menurut saya paling penting bagi developer web:

• --bind mengaktifkan embind.
• -s STRICT=1 menghentikan dukungan untuk semua opsi build yang tidak digunakan lagi. Hal ini memastikan bahwa kode Anda di-build dengan cara yang kompatibel dengan versi mendatang.
• -s ALLOW_MEMORY_GROWTH=1 memungkinkan memori diperluas secara otomatis jika diperlukan. Pada saat penulisan, Emscripten akan mengalokasikan memori sebesar 16 MB pada awalnya. Saat kode Anda mengalokasikan potongan memori, opsi ini akan menentukan apakah operasi ini akan membuat seluruh modul wasm gagal saat memori habis, atau apakah kode lem diizinkan untuk memperluas total memori untuk menampung alokasi.
• -s MALLOC=... memilih penerapan malloc() yang akan digunakan. emmalloc adalah implementasi malloc() yang kecil dan cepat khusus untuk Emscripten. Alternatifnya adalah dlmalloc, implementasi malloc() yang sepenuhnya matang. Anda hanya perlu beralih ke dlmalloc jika sering mengalokasikan banyak objek kecil atau jika ingin menggunakan threading.
• -s EXPORT_ES6=1 akan mengubah kode JavaScript menjadi modul ES6 dengan ekspor default yang berfungsi dengan bundler apa pun. Juga memerlukan penetapan -s MODULARIZE=1.

Flag berikut tidak selalu diperlukan atau hanya berguna untuk tujuan proses debug:

• -s FILESYSTEM=0 adalah flag yang terkait dengan Emscripten dan kemampuannya untuk mengemulasikan sistem file untuk Anda saat kode C/C++ menggunakan operasi sistem file. Alat ini melakukan beberapa analisis pada kode yang dikompilasi untuk memutuskan apakah akan menyertakan emulasi sistem file dalam kode glue atau tidak. Namun, terkadang analisis ini dapat salah dan Anda membayar kode perekat tambahan sebesar 70 kB yang cukup besar untuk emulasi sistem file yang mungkin tidak Anda perlukan. Dengan -s FILESYSTEM=0, Anda dapat memaksa Emscripten untuk tidak menyertakan kode ini.
• -g4 akan membuat Emscripten menyertakan informasi proses debug di .wasm dan juga menghasilkan file peta sumber untuk modul wasm. Anda dapat membaca lebih lanjut tentang proses debug dengan Emscripten di bagian debug.

Dan, berhasil! Untuk menguji penyiapan ini, mari kita buat my-module.cpp kecil:

    #include <emscripten/bind.h>

    using namespace emscripten;

    int say_hello() {
      printf("Hello from your wasm module\n");
      return 0;
    }

    EMSCRIPTEN_BINDINGS(my_module) {
      function("sayHello", &say_hello);
    }

Dan index.html:

    <!doctype html>
    <title>Emscripten + npm example</title>
    Open the console to see the output from the wasm module.
    <script type="module">
    import wasmModule from "./my-module.js";

    const instance = wasmModule({
      onRuntimeInitialized() {
        instance.sayHello();
      }
    });
    </script>

(Berikut adalah ringkasan yang berisi semua file.)

Untuk mem-build semuanya, jalankan

$ npm install
$ npm run build
$ npm run serve

Membuka localhost:8080 akan menampilkan output berikut di konsol DevTools:

Menambahkan kode C/C++ sebagai dependensi

Jika ingin mem-build library C/C++ untuk aplikasi web, Anda memerlukan kodenya untuk menjadi bagian dari project. Anda dapat menambahkan kode ke repositori project secara manual atau Anda juga dapat menggunakan npm untuk mengelola jenis dependensi ini. Misalnya, saya ingin menggunakan libvpx di webapp. libvpx adalah library C++ untuk mengenkode gambar dengan VP8, codec yang digunakan dalam file .webm. Namun, libvpx tidak ada di npm dan tidak memiliki package.json, sehingga saya tidak dapat menginstalnya menggunakan npm secara langsung.

Untuk keluar dari masalah ini, ada napa. napa memungkinkan Anda menginstal URL repositori git sebagai dependensi ke folder node_modules.

Catatan: Jika Anda tidak suka menggunakan napa, lihat lampiran untuk mengetahui solusi yang lebih berfokus pada Docker yang tidak memerlukan napa.

Instal napa sebagai dependensi:

$ npm install --save napa

dan pastikan untuk menjalankan napa sebagai skrip penginstalan:

{
// ...
"scripts": {
    "install": "napa",
    // ...
},
"napa": {
    "libvpx": "git+https://github.com/webmproject/libvpx"
}
// ...
}

Saat Anda menjalankan npm install, napa akan meng-clone repositori GitHub libvpx ke node_modules dengan nama libvpx.

Sekarang Anda dapat memperluas skrip build untuk mem-build libvpx. libvpx menggunakan configure dan make untuk di-build. Untungnya, Emscripten dapat membantu memastikan bahwa configure dan make menggunakan compiler Emscripten. Untuk tujuan ini, ada perintah wrapper emconfigure dan emmake:

# ... above is unchanged ...
echo "============================================="
echo "Compiling libvpx"
echo "============================================="
(
    rm -rf build-vpx || true
    mkdir build-vpx
    cd build-vpx
    emconfigure ../node_modules/libvpx/configure \
    --target=generic-gnu
    emmake make
)
echo "============================================="
echo "Compiling libvpx done"
echo "============================================="

echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
# ... below is unchanged ...

Catatan: Beberapa project menyediakan flag --host (atau yang serupa; libvpx menggunakan --target non-standar) untuk mem-build arsitektur prosesor tertentu. Hal ini sering kali akan menarik kode assembler yang memanfaatkan fitur khusus untuk arsitektur tersebut dan tidak dapat dikompilasi ke WebAssembly. Jika tanda seperti itu ada (periksa dengan ./configure --help), pastikan untuk menetapkannya ke target generik.

Library C/C++ dibagi menjadi dua bagian: header (biasanya file .h atau .hpp) yang menentukan struktur data, class, konstanta, dll. yang ditampilkan library dan library sebenarnya (biasanya file .so atau .a). Untuk menggunakan konstanta VPX_CODEC_ABI_VERSION library dalam kode, Anda harus menyertakan file header library menggunakan pernyataan #include:

#include "vpxenc.h"
#include <emscripten/bind.h>

int say_hello() {
    printf("Hello from your wasm module with libvpx %d\n", VPX_CODEC_ABI_VERSION);
    return 0;
}

Masalahnya adalah compiler tidak tahu di mana harus mencari vpxenc.h. Inilah kegunaan flag -I. Ini memberi tahu compiler direktori mana yang akan diperiksa untuk file header. Selain itu, Anda juga perlu memberikan file library yang sebenarnya ke compiler:

# ... above is unchanged ...
echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
(
    # Compile C/C++ code
    emcc \
    ${OPTIMIZE} \
    --bind \
    -s STRICT=1 \
    -s ALLOW_MEMORY_GROWTH=1 \
    -s ASSERTIONS=0 \
    -s MALLOC=emmalloc \
    -s MODULARIZE=1 \
    -s EXPORT_ES6=1 \
    -o ./my-module.js \
    -I ./node_modules/libvpx \
    src/my-module.cpp \
    build-vpx/libvpx.a

# ... below is unchanged ...

Jika menjalankan npm run build sekarang, Anda akan melihat bahwa proses ini mem-build .js baru dan file .wasm baru, serta halaman demo memang akan menghasilkan konstanta:

Anda juga akan melihat bahwa proses build memerlukan waktu yang lama. Alasan waktu build yang lama dapat bervariasi. Dalam kasus libvpx, prosesnya memerlukan waktu lama karena mengompilasi encoder dan decoder untuk VP8 dan VP9 setiap kali Anda menjalankan perintah build, meskipun file sumber belum berubah. Bahkan perubahan kecil pada my-module.cpp akan memerlukan waktu lama untuk di-build. Akan sangat berguna untuk menyimpan artefak build libvpx setelah di-build untuk pertama kalinya.

Salah satu cara untuk melakukannya adalah menggunakan variabel lingkungan.

Catatan: Jika Anda tidak menyukai solusi ini, lihat lampiran untuk solusi yang lebih berfokus pada Docker.

# ... above is unchanged ...
eval $@

echo "============================================="
echo "Compiling libvpx"
echo "============================================="
test -n "$SKIP_LIBVPX" || (
    rm -rf build-vpx || true
    mkdir build-vpx
    cd build-vpx
    emconfigure ../node_modules/libvpx/configure \
    --target=generic-gnu
    emmake make
)
echo "============================================="
echo "Compiling libvpx done"
echo "============================================="
# ... below is unchanged ...

(Berikut adalah ringkasan yang berisi semua file.)

Perintah eval memungkinkan kita menetapkan variabel lingkungan dengan meneruskan parameter ke skrip build. Perintah test akan melewati pembuatan libvpx jika $SKIP_LIBVPX ditetapkan (ke nilai apa pun).

Sekarang Anda dapat mengompilasi modul, tetapi lewati pembuatan ulang libvpx:

$ npm run build:emscripten -- SKIP_LIBVPX=1

Menyesuaikan lingkungan build

Terkadang library bergantung pada alat tambahan untuk di-build. Jika dependensi ini tidak ada di lingkungan build yang disediakan oleh image Docker, Anda harus menambahkannya sendiri. Misalnya, Anda juga ingin mem-build dokumentasi libvpx menggunakan doxygen. Doxygen tidak tersedia di dalam penampung Docker, tetapi Anda dapat menginstalnya menggunakan apt.

Jika Anda melakukannya di build.sh, Anda harus mendownload ulang dan menginstal ulang doxygen setiap kali ingin mem-build library. Hal ini tidak hanya membuang-buang waktu, tetapi juga akan menghentikan Anda mengerjakan project saat offline.

Di sini, sebaiknya Anda membuat image Docker sendiri. Image Docker dibuat dengan menulis Dockerfile yang menjelaskan langkah-langkah build. Dockerfile cukup andal dan memiliki banyak perintah, tetapi sebagian besar waktu Anda dapat melakukannya hanya dengan menggunakan FROM, RUN, dan ADD. Dalam hal ini:

FROM trzeci/emscripten

RUN apt-get update && \
    apt-get install -qqy doxygen

Dengan FROM, Anda dapat mendeklarasikan image Docker yang ingin digunakan sebagai titik awal. Saya memilih trzeci/emscripten sebagai dasar — image yang telah Anda gunakan selama ini. Dengan RUN, Anda menginstruksikan Docker untuk menjalankan perintah shell di dalam container. Apa pun perubahan yang dilakukan perintah ini pada penampung kini menjadi bagian dari image Docker. Untuk memastikan bahwa image Docker telah di-build dan tersedia sebelum menjalankan build.sh, Anda harus menyesuaikan package.json secara sedikit:

{
    // ...
    "scripts": {
    "build:dockerimage": "docker image inspect -f '.' mydockerimage || docker build -t mydockerimage .",
    "build:emscripten": "docker run --rm -v $(pwd):/src mydockerimage ./build.sh",
    "build": "npm run build:dockerimage && npm run build:emscripten && npm run build:app",
    // ...
    },
    // ...
}

(Berikut adalah ringkasan yang berisi semua file.)

Tindakan ini akan mem-build image Docker Anda, tetapi hanya jika belum di-build. Kemudian, semuanya berjalan seperti sebelumnya, tetapi sekarang lingkungan build memiliki perintah doxygen yang tersedia, yang akan menyebabkan dokumentasi libvpx juga di-build.

Kesimpulan

Tidak mengherankan bahwa kode C/C++ dan npm tidak cocok secara alami, tetapi Anda dapat membuatnya berfungsi dengan cukup nyaman dengan beberapa alat tambahan dan isolasi yang disediakan Docker. Penyiapan ini tidak akan berfungsi untuk setiap project, tetapi ini adalah titik awal yang baik yang dapat Anda sesuaikan dengan kebutuhan Anda. Jika Anda memiliki peningkatan, harap bagikan.

Lampiran: Menggunakan lapisan image Docker

Solusi alternatifnya adalah mengenkapsulasi lebih banyak masalah ini dengan Docker dan pendekatan cerdas Docker untuk penyimpanan dalam cache. Docker mengeksekusi Dockerfile langkah demi langkah dan menetapkan hasil dari setiap langkah sebagai image-nya sendiri. Gambar perantara ini sering disebut "lapisan". Jika perintah dalam Dockerfile belum berubah, Docker tidak akan benar-benar menjalankan kembali langkah tersebut saat Anda mem-build ulang Dockerfile. Sebagai gantinya, lapisan akan digunakan kembali dari terakhir kali image dibuat.

Sebelumnya, Anda harus melakukan beberapa upaya agar tidak mem-build ulang libvpx setiap kali mem-build aplikasi. Sebagai gantinya, Anda dapat memindahkan petunjuk build untuk libvpx dari build.sh ke Dockerfile untuk memanfaatkan mekanisme cache Docker:

FROM trzeci/emscripten

RUN apt-get update && \
    apt-get install -qqy doxygen git && \
    mkdir -p /opt/libvpx/build && \
    git clone https://github.com/webmproject/libvpx /opt/libvpx/src
RUN cd /opt/libvpx/build && \
    emconfigure ../src/configure --target=generic-gnu && \
    emmake make

(Berikut adalah ringkasan yang berisi semua file.)

Perhatikan bahwa Anda perlu menginstal git dan meng-clone libvpx secara manual karena Anda tidak memiliki mount bind saat menjalankan docker build. Sebagai efek samping, Anda tidak perlu lagi menggunakan napa.