In Che cos'è WebAssembly e da dove proviene?, Ho spiegato come abbiamo ottenuto il WebAssembly di oggi. In questo articolo, ti mostrerò il mio approccio alla compilazione di un programma C esistente, mkbitmap
, in WebAssembly. È più complesso dell'esempio hello world, in quanto include il lavoro con i file, la comunicazione tra i domini WebAssembly e JavaScript e il disegno in una tela, ma è comunque abbastanza gestibile da non sopraffarti.
L'articolo è rivolto agli sviluppatori web che vogliono imparare a utilizzare WebAssembly e illustra passo passo la procedura da seguire per compilare qualcosa come mkbitmap
in WebAssembly. Ti avverto che è del tutto normale che la compilazione di un'app o di una libreria non vada a buon fine alla prima esecuzione, motivo per cui alcuni dei passaggi descritti di seguito non hanno funzionato. Ho dovuto tornare indietro e riprovare in modo diverso. L'articolo non mostra il comando magico di compilazione finale come se fosse caduto dal cielo, ma descrive piuttosto i miei progressi effettivi, incluse alcune frustrazioni.
Informazioni su mkbitmap
Il programma C mkbitmap
legge un'immagine e vi applica una o più delle seguenti operazioni, in questo ordine: inversione, filtro passa alto, ridimensionamento e soglia. Ogni operazione può essere controllata singolarmente e attivata o disattivata. L'uso principale di mkbitmap
è convertire le immagini a colori o in scala di grigi in un formato adatto come input per altri programmi, in particolare il programma di tracciato potrace
che costituisce la base di SVGcode. Come strumento di preelaborazione, mkbitmap
è particolarmente utile per convertire disegni a linee scansionati, come cartoni animati o testo scritto a mano, in immagini bilevel ad alta risoluzione.
Per utilizzare mkbitmap
, devi passare una serie di opzioni e uno o più nomi file. Per tutti i dettagli, consulta la pagina man dello strumento:
$ mkbitmap [options] [filename...]
Ottieni il codice
Il primo passaggio consiste nell'ottenere il codice sorgente di mkbitmap
. Puoi trovarlo sul sito web del progetto. Al momento della stesura di questo articolo, potrace-1.16.tar.gz è la versione più recente.
Compila e installa localmente
Il passaggio successivo consiste nel compilare e installare lo strumento localmente per avere un'idea del suo comportamento. Il file INSTALL
contiene le seguenti istruzioni:
cd
alla directory contenente il codice sorgente del pacchetto e digita./configure
per configurare il pacchetto per il tuo sistema.L'esecuzione di
configure
potrebbe richiedere del tempo. Durante l'esecuzione, stampa alcuni messaggi che indicano le funzionalità che sta controllando.Digita
make
per compilare il pacchetto.Se vuoi, digita
make check
per eseguire eventuali autotest forniti con il pacchetto, in genere utilizzando i binari appena compilati e non installati.Digita
make install
per installare i programmi, eventuali file di dati e la documentazione. Quando esegui l'installazione in un prefisso di proprietà di root, è consigliabile configurare e compilare il pacchetto come utente normale ed eseguire solo la fasemake install
con i privilegi di root.
Se segui questi passaggi, dovresti ottenere due file eseguibili, potrace
e mkbitmap
, quest'ultimo oggetto dell'articolo. Puoi verificare che funzioni correttamente eseguendo mkbitmap --version
. Ecco l'output di tutti e quattro i passaggi della mia macchina, molto ridotto per brevità:
Passaggio 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
Passaggio 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'.
Passaggio 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'.
Passaggio 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'.
Per verificare se ha funzionato, esegui mkbitmap --version
:
$ mkbitmap --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.
Se visualizzi i dettagli della versione, significa che hai compilato e installato mkbitmap
. A questo punto, fai in modo che l'equivalente di questi passaggi funzioni con WebAssembly.
Compilare mkbitmap
in WebAssembly
Emscripten è uno strumento per la compilazione di programmi C/C++ in WebAssembly. La documentazione di Building Projects di Emscripten afferma quanto segue:
Creare progetti di grandi dimensioni con Emscripten è molto semplice. Emscripten fornisce due semplici script che configurano i file make per utilizzare
emcc
come sostituto diretto digcc
. Nella maggior parte dei casi, il resto del sistema di compilazione attuale del progetto rimane invariato.
La documentazione continua (un po' modificata per brevità):
Supponiamo che di solito esegui la compilazione con i seguenti comandi:
./configure
make
Per eseguire la compilazione con Emscripten, utilizza invece i seguenti comandi:
emconfigure ./configure
emmake make
Quindi, essenzialmente, ./configure
diventa emconfigure ./configure
e make
diventa emmake make
. Di seguito viene mostrato come eseguire questa operazione con mkbitmap
.
Passaggio 0, make clean
:
$ make clean
Making clean in src
rm -f potrace mkbitmap
test -z "" || rm -f
rm -rf .libs _libs
[…]
rm -f *.lo
Passaggio 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
Passaggio 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'.
Se tutto è andato bene, ora nella directory dovrebbero essere presenti file .wasm
. Puoi trovarli eseguendo find . -name "*.wasm"
:
$ find . -name "*.wasm"
./a.wasm
./src/mkbitmap.wasm
./src/potrace.wasm
Gli ultimi due sembrano promettenti, quindi cd
nella directory src/
. Ora sono disponibili anche due nuovi file corrispondenti, mkbitmap
e potrace
. Per questo articolo, è pertinente solo mkbitmap
. Il fatto che non abbiano l'estensione .js
è un po' confuso, ma in realtà sono file JavaScript, verificabili con una rapida chiamata head
:
$ 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)
Rinomina il file JavaScript in mkbitmap.js
chiamando mv mkbitmap mkbitmap.js
(e mv potrace potrace.js
, se vuoi).
Ora è il momento del primo test per verificare se il file funziona eseguendolo con Node.js sulla riga di comando eseguendo node mkbitmap.js --version
:
$ node mkbitmap.js --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.
Hai compilato mkbitmap
in WebAssembly. Il passaggio successivo consiste nel farlo funzionare nel browser.
mkbitmap
con WebAssembly nel browser
Copia i file mkbitmap.js
e mkbitmap.wasm
in una nuova directory denominata mkbitmap
e crea un file boilerplate HTML index.html
che carichi il file JavaScript mkbitmap.js
.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>mkbitmap</title>
</head>
<body>
<script src="mkbitmap.js"></script>
</body>
</html>
Avvia un server locale che serve la directory mkbitmap
e aprilo nel browser. Dovresti visualizzare un messaggio che ti chiede di inserire un input. Questo è come previsto, poiché, secondo la pagina di manual dello strumento, "[i]f no filename arguments are given, then mkbitmap acts as a filter, reading from standard input", che per Emscripten per impostazione predefinita è un prompt()
.
Impedire l'esecuzione automatica
Per interrompere l'esecuzione immediata di mkbitmap
e fare in modo che attenda l'input dell'utente, devi comprendere l'oggetto Module
di Emscripten. Module
è un oggetto JavaScript globale con attributi che il codice generato da Emscripten chiama in vari punti della sua esecuzione.
Puoi fornire un'implementazione di Module
per controllare l'esecuzione del codice.
Quando un'applicazione Emscripten viene avviata, esamina i valori dell'oggetto Module
e li applica.
Nel caso di mkbitmap
, imposta Module.noInitialRun
su true
per impedire l'esecuzione iniziale che ha causato la visualizzazione del prompt. Crea uno script chiamato script.js
, includilo prima di <script src="mkbitmap.js"></script>
in index.html
e aggiungi il seguente codice a script.js
. Ora, quando ricarichi l'app, la richiesta non dovrebbe più essere visualizzata.
var Module = {
// Don't run main() at page load
noInitialRun: true,
};
Crea una compilazione modulare con altri flag di compilazione
Per fornire input all'app, puoi utilizzare il supporto del file system di Emscripten in Module.FS
. La sezione Inclusione del supporto del file system della documentazione afferma quanto segue:
Emscripten decide se includere automaticamente il supporto del file system. Molti programmi non hanno bisogno di file e il supporto del file system non è di dimensioni trascurabili, quindi Emscripten evita di includerlo quando non vede un motivo per farlo. Ciò significa che se il codice C/C++ non accede ai file, l'oggetto
FS
e altre API del file system non verranno inclusi nell'output. D'altra parte, se il codice C/C++ utilizza file, il supporto del file system verrà incluso automaticamente.
Purtroppo mkbitmap
è uno dei casi in cui Emscripten non include automaticamente il supporto del file system, quindi devi chiedergli esplicitamente di farlo. Ciò significa che devi seguire i passaggi emconfigure
e emmake
descritti in precedenza, con un paio di flag aggiuntivi impostati tramite un argomento CFLAGS
. I seguenti flag potrebbero essere utili anche per altri progetti.
- Imposta
-sFILESYSTEM=1
in modo che sia incluso il supporto del file system. - Imposta
-sEXPORTED_RUNTIME_METHODS=FS,callMain
in modo cheModule.FS
eModule.callMain
vengano esportati. - Imposta
-sMODULARIZE=1
e-sEXPORT_ES6
per generare un modulo ES6 moderno. - Imposta
-sINVOKE_RUN=0
per impedire l'esecuzione iniziale che ha causato la visualizzazione della richiesta.
Inoltre, in questo caso specifico, devi impostare il flag --host
su wasm32
per indicare allo script configure
che stai compilando per WebAssembly.
Il comando emconfigure
finale sarà il seguente:
$ emconfigure ./configure --host=wasm32 CFLAGS='-sFILESYSTEM=1 -sEXPORTED_RUNTIME_METHODS=FS,callMain -sMODULARIZE=1 -sEXPORT_ES6 -sINVOKE_RUN=0'
Non dimenticare di eseguire di nuovo emmake make
e di copiare i file appena creati nella cartella mkbitmap
.
Modifica index.html
in modo che carichi solo il modulo ES script.js
, da cui poi importi il modulo 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();
Quando apri l'app nel browser, dovresti vedere l'oggetto Module
registrato nella console DevTools e la richiesta non è più visualizzata, poiché la funzione main()
di mkbitmap
non viene più chiamata all'avvio.
Eseguire manualmente la funzione principale
Il passaggio successivo consiste nell'eseguire manualmente la funzione main()
di mkbitmap
eseguendo Module.callMain()
. La funzione callMain()
accetta un array di argomenti, che corrispondono uno a uno a quelli che passeresti nella riga di comando. Se nella riga di comando esegui mkbitmap -v
, nel browser chiamerai Module.callMain(['-v'])
. Il numero di versione di mkbitmap
viene registrato nella console DevTools.
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
Module.callMain(['-v']);
};
run();
Reindirizza l'output standard
L'output standard (stdout
) per impostazione predefinita è la console. Tuttavia, puoi reindirizzarlo a qualcos'altro, ad esempio una funzione che memorizza l'output in una variabile. Ciò significa che puoi aggiungere l'output all'HTML impostando la proprietà Module.print
.
// 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();
Inserisci il file di input nel file system in memoria
Per inserire il file di input nel file system della memoria, devi avere l'equivalente di mkbitmap filename
nella riga di comando. Per capire come affronto questo problema, di seguito sono riportate alcune informazioni su come mkbitmap
si aspetta l'input e crea l'output.
I formati di input supportati di mkbitmap
sono PNM (PBM, PGM, PPM) e BMP. I formati di output sono PBM per le bitmap e PGM per le mappe di grigi. Se viene specificato un argomento filename
, per impostazione predefinita mkbitmap
crea un file di output il cui nome viene ottenuto dal nome del file di input modificando il suffisso in .pbm
. Ad esempio, per il nome del file di input example.bmp
, il nome del file di output sarà example.pbm
.
Emscripten fornisce un file system virtuale che simula il file system locale, in modo che il codice nativo che utilizza le API file sincrone possa essere compilato ed eseguito con poche o nessuna modifica.
Affinché mkbitmap
legga un file di input come se fosse stato passato come argomento della riga di comando filename
, devi utilizzare l'oggetto FS
fornito da Emscripten.
L'oggetto FS
è supportato da un file system in memoria (comunemente noto come MEMFS) e dispone di una funzione writeFile()
che viene utilizzata per scrivere file nel file system virtuale. Utilizza writeFile()
come mostrato nell'esempio di codice seguente.
Per verificare il funzionamento dell'operazione di scrittura del file, esegui la funzione readdir()
dell'oggetto FS
con il parametro '/'
. Vedrai example.bmp
e una serie di file predefiniti che vengono sempre creati automaticamente.
Tieni presente che la chiamata precedente a Module.callMain(['-v'])
per la stampa del numero di versione è stata rimossa. Questo accade perché Module.callMain()
è una funzione che in genere si prevede venga eseguita una sola volta.
// 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();
Prima esecuzione effettiva
Una volta completata la configurazione, esegui mkbitmap
eseguendo Module.callMain(['example.bmp'])
. Registra i contenuti della cartella '/'
di MEMFS e dovresti vedere il file di output example.pbm
appena creato accanto al file di input example.bmp
.
// 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();
Estrai il file di output dal file system in memoria
La funzione readFile()
dell'oggetto FS
consente di recuperare il example.pbm
creato nell'ultimo passaggio dal file system della memoria. La funzione restituisce un Uint8Array
che devi convertire in un oggetto File
e salvare su disco, poiché in genere i browser non supportano i file PBM per la visualizzazione diretta nel browser.
Esistono modi più eleganti per salvare un file, ma l'utilizzo di un <a download>
creato dinamicamente è la soluzione più ampiamente supportata. Una volta salvato il file, puoi aprirlo nel tuo visualizzatore di immagini preferito.
// 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();
Aggiungere un'interfaccia utente interattiva
A questo punto, il file di input è hardcoded e mkbitmap
viene eseguito con i parametri predefiniti. Il passaggio finale consiste nel consentire all'utente di selezionare dinamicamente un file di input, modificare i parametri mkbitmap
e quindi eseguire lo strumento con le opzioni selezionate.
// 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']);
Il formato di immagine PBM non è particolarmente difficile da analizzare, quindi con un po' di codice JavaScript puoi anche mostrare un'anteprima dell'immagine di output. Per un esempio di come eseguire questa operazione, consulta il codice sorgente della demo incorporata di seguito.
Conclusione
Congratulazioni, hai compilato mkbitmap
in WebAssembly e lo hai fatto funzionare nel browser. Ci sono stati alcuni casi in cui non è stato possibile procedere e hai dovuto compilare lo strumento più di una volta finché non ha funzionato, ma come ho scritto sopra, fa parte dell'esperienza. Se non riesci a risolvere il problema, ricordati anche il tag webassembly
di StackOverflow. Buona compilazione!
Ringraziamenti
Questo articolo è stato esaminato da Sam Clegg e Rachel Andrew.