Cómo compilar mkbitmap en WebAssembly

Thomas Steiner

En ¿Qué es WebAssembly y de dónde viene?, Te expliqué cómo llegamos al WebAssembly actual. En este artículo, te mostraré mi enfoque para compilar un programa C existente, mkbitmap, en WebAssembly. Es más complejo que el ejemplo de Hello World, ya que incluye trabajar con archivos, comunicarse entre las plataformas de WebAssembly y JavaScript, y dibujar en un lienzo, pero aún es lo suficientemente manejable como para no abrumarte.

El artículo está escrito para desarrolladores web que quieran aprender a usar WebAssembly y muestra paso a paso cómo proceder si quieres compilar algo como mkbitmap en WebAssembly. Ten en cuenta que es completamente normal que no se compile una app o biblioteca en la primera ejecución, por lo que algunos de los pasos que se describen a continuación no funcionaron. Por lo tanto, tuve que retroceder y volver a intentarlo de otra manera. El artículo no muestra el comando de compilación final mágico como si hubiera caído del cielo, sino que describe mi progreso real, incluidas algunas frustraciones.

Acerca de mkbitmap

El programa C mkbitmap lee una imagen y le aplica una o más de las siguientes operaciones, en este orden: inversión, filtrado de paso alto, escalamiento y umbral. Cada operación se puede controlar y activar o desactivar de forma individual. El uso principal de mkbitmap es convertir imágenes en color o en escala de grises en un formato adecuado como entrada para otros programas, en particular el programa de trazado potrace que forma la base de SVGcode. Como herramienta de procesamiento previo, mkbitmap es particularmente útil para convertir imágenes de línea escaneadas, como dibujos animados o texto escrito a mano, en imágenes de dos niveles de alta resolución.

Para usar mkbitmap, debes pasarle varias opciones y uno o varios nombres de archivo. Para obtener todos los detalles, consulta la página man de la herramienta:

$ mkbitmap [options] [filename...]
Imagen de caricatura en color.
La imagen original (Source).
Imagen de caricatura convertida a escala de grises después del procesamiento previo.
Primero se ajusta y, luego, se aplica un umbral: mkbitmap -f 2 -s 2 -t 0.48 (Fuente).

Obtén el código

El primer paso es obtener el código fuente de mkbitmap. Puedes encontrarla en el sitio web del proyecto. En el momento de escribir este documento, potrace-1.16.tar.gz es la versión más reciente.

Compila e instala de forma local

El siguiente paso es compilar e instalar la herramienta de forma local para tener una idea de cómo se comporta. El archivo INSTALL contiene las siguientes instrucciones:

  1. cd al directorio que contiene el código fuente del paquete y escribe ./configure para configurar el paquete para tu sistema.

    La ejecución de configure puede tardar un tiempo. Mientras se ejecuta, imprime algunos mensajes que indican qué funciones está verificando.

  2. Escribe make para compilar el paquete.

  3. De manera opcional, escribe make check para ejecutar las autopruebas que se incluyen con el paquete, por lo general, con los objetos binarios no instalados que se acaban de compilar.

  4. Escribe make install para instalar los programas y cualquier archivo de datos y documentación. Cuando se instala en un prefijo que es propiedad de root, se recomienda que el paquete se configure y compile como un usuario normal, y que solo se ejecute la fase make install con privilegios de root.

Si sigues estos pasos, deberías obtener dos ejecutables, potrace y mkbitmap, este último es el foco de este artículo. Para verificar que funcionó correctamente, ejecuta mkbitmap --version. Este es el resultado de los cuatro pasos de mi máquina, muy resumido para que sea breve:

Paso 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

Paso 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'.

Paso 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'.

Paso 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'.

Para verificar si funcionó, ejecuta mkbitmap --version:

$ mkbitmap --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.

Si obtienes los detalles de la versión, significa que compilaste e instalaste correctamente mkbitmap. A continuación, haz que el equivalente de estos pasos funcione con WebAssembly.

Compila mkbitmap en WebAssembly

Emscripten es una herramienta para compilar programas C/C++ en WebAssembly. En la documentación Building Projects de Emscripten, se indica lo siguiente:

Compilar proyectos grandes con Emscripten es muy fácil. Emscripten proporciona dos secuencias de comandos simples que configuran tus archivos make para usar emcc como reemplazo directo de gcc. En la mayoría de los casos, el resto del sistema de compilación actual de tu proyecto no se modifica.

Luego, la documentación continúa (un poco editada para que sea más breve):

Considera el caso en el que normalmente compilas con los siguientes comandos:

./configure
make

Para compilar con Emscripten, en su lugar, usarías los siguientes comandos:

emconfigure ./configure
emmake make

Por lo tanto, ./configure se convierte en emconfigure ./configure y make se convierte en emmake make. A continuación, se muestra cómo hacerlo con mkbitmap.

Paso 0, make clean:

$ make clean
Making clean in src
 rm -f potrace mkbitmap
test -z "" || rm -f
rm -rf .libs _libs
[…]
rm -f *.lo

Paso 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

Paso 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'.

Si todo salió bien, ahora debería haber archivos .wasm en algún lugar del directorio. Para encontrarlos, ejecuta find . -name "*.wasm":

$ find . -name "*.wasm"
./a.wasm
./src/mkbitmap.wasm
./src/potrace.wasm

Los dos últimos parecen prometedores, así que cd en el directorio src/. Ahora también hay dos archivos nuevos correspondientes, mkbitmap y potrace. En este artículo, solo mkbitmap es relevante. El hecho de que no tengan la extensión .js es un poco confuso, pero en realidad son archivos JavaScript, que se pueden verificar con una llamada rápida a 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)

Para cambiar el nombre del archivo JavaScript a mkbitmap.js, llama a mv mkbitmap mkbitmap.js (y a mv potrace potrace.js, respectivamente, si lo deseas). Ahora es el momento de realizar la primera prueba para ver si funcionó. Para ello, ejecuta el archivo con Node.js en la línea de comandos con node mkbitmap.js --version:

$ node mkbitmap.js --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.

Compilaste correctamente mkbitmap en WebAssembly. Ahora, el siguiente paso es hacer que funcione en el navegador.

mkbitmap con WebAssembly en el navegador

Copia los archivos mkbitmap.js y mkbitmap.wasm en un directorio nuevo llamado mkbitmap y crea un archivo de plantilla HTML index.html que cargue el archivo 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>

Inicia un servidor local que entregue el directorio mkbitmap y ábrelo en tu navegador. Deberías ver un mensaje que te solicite una entrada. Esto es lo esperado, ya que, según la página man de la herramienta, "[i]f no filename arguments are given, then mkbitmap acts as a filter, reading from standard input", que para Emscripten es, de forma predeterminada, un prompt().

La app mkbitmap muestra un mensaje que solicita una entrada.

Cómo impedir la ejecución automática

Para evitar que mkbitmap se ejecute de inmediato y, en su lugar, hacer que espere la entrada del usuario, debes comprender el objeto Module de Emscripten. Module es un objeto global de JavaScript con atributos a los que llama el código generado por Emscripten en varios puntos de su ejecución. Puedes proporcionar una implementación de Module para controlar la ejecución del código. Cuando se inicia una aplicación de Emscripten, observa los valores del objeto Module y los aplica.

En el caso de mkbitmap, establece Module.noInitialRun en true para evitar la ejecución inicial que hizo que apareciera la instrucción. Crea una secuencia de comandos llamada script.js, inclúyela antes de <script src="mkbitmap.js"></script> en index.html y agrega el siguiente código a script.js. Cuando vuelvas a cargar la app, el mensaje debería desaparecer.

var Module = {
  // Don't run main() at page load
  noInitialRun: true,
};

Crea una compilación modular con algunas marcas de compilación más

Para proporcionar entradas a la app, puedes usar la compatibilidad con el sistema de archivos de Emscripten en Module.FS. En la sección Cómo incluir compatibilidad con el sistema de archivos de la documentación, se indica lo siguiente:

Emscripten decide si incluir la compatibilidad con el sistema de archivos automáticamente. Muchos programas no necesitan archivos, y la compatibilidad con el sistema de archivos no es de tamaño despreciable, por lo que Emscripten evita incluirlo cuando no ve un motivo para hacerlo. Eso significa que, si tu código C/C++ no accede a los archivos, el objeto FS y otras APIs del sistema de archivos no se incluirán en el resultado. Por otro lado, si tu código C/C++ usa archivos, se incluirá automáticamente la compatibilidad con el sistema de archivos.

Lamentablemente, mkbitmap es uno de los casos en los que Emscripten no incluye automáticamente la compatibilidad con el sistema de archivos, por lo que debes indicarle explícitamente que lo haga. Esto significa que debes seguir los pasos de emconfigure y emmake descritos anteriormente, con un par de marcas más configuradas a través de un argumento CFLAGS. Las siguientes marcas también pueden ser útiles para otros proyectos.

Además, en este caso en particular, debes establecer la marca --host en wasm32 para indicarle a la secuencia de comandos configure que estás compilando para WebAssembly.

El comando emconfigure final se ve de la siguiente manera:

$ emconfigure ./configure --host=wasm32 CFLAGS='-sFILESYSTEM=1 -sEXPORTED_RUNTIME_METHODS=FS,callMain -sMODULARIZE=1 -sEXPORT_ES6 -sINVOKE_RUN=0'

No olvides volver a ejecutar emmake make y copiar los archivos recién creados en la carpeta mkbitmap.

Modifica index.html para que solo cargue el módulo ES script.js, desde el que luego importarás el módulo 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();

Cuando abras la app ahora en el navegador, deberías ver el objeto Module registrado en la consola de DevTools, y el mensaje desaparecerá, ya que ya no se llama a la función main() de mkbitmap al principio.

La app mkbitmap con una pantalla blanca, que muestra el objeto Module registrado en la consola de DevTools.

Ejecuta la función principal de forma manual

El siguiente paso es llamar manualmente a la función main() de mkbitmap ejecutando Module.callMain(). La función callMain() toma un array de argumentos, que coinciden uno por uno con lo que pasarías en la línea de comandos. Si en la línea de comandos ejecutaras mkbitmap -v, llamarías a Module.callMain(['-v']) en el navegador. Esto registra el número de versión de mkbitmap en la consola de DevTools.

// This is `script.js`.
import loadWASM from './mkbitmap.js';

const run = async () => {
  const Module = await loadWASM();
  Module.callMain(['-v']);
};

run();

La app de mkbitmap con una pantalla blanca, que muestra el número de versión de mkbitmap registrado en la consola de DevTools.

Redirecciona la salida estándar

De forma predeterminada, el resultado estándar (stdout) es la consola. Sin embargo, puedes redireccionarlo a otra cosa, por ejemplo, a una función que almacene el resultado en una variable. Esto significa que puedes agregar el resultado al HTML configurando la propiedad 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();

La app de mkbitmap muestra el número de versión de mkbitmap.

Cómo obtener el archivo de entrada en el sistema de archivos en la memoria

Para obtener el archivo de entrada en el sistema de archivos de memoria, necesitas el equivalente de mkbitmap filename en la línea de comandos. Para comprender cómo abordo esto, primero debes conocer algunos antecedentes sobre cómo mkbitmap espera su entrada y crea su salida.

Los formatos de entrada admitidos de mkbitmap son PNM (PBM, PGM, PPM) y BMP. Los formatos de salida son PBM para mapas de bits y PGM para mapas en escala de grises. Si se proporciona un argumento filename, mkbitmap creará de forma predeterminada un archivo de salida cuyo nombre se obtiene del nombre del archivo de entrada cambiando su sufijo a .pbm. Por ejemplo, para el nombre de archivo de entrada example.bmp, el nombre de archivo de salida sería example.pbm.

Emscripten proporciona un sistema de archivos virtual que simula el sistema de archivos local, de modo que el código nativo que usa APIs de archivos síncronos se pueda compilar y ejecutar con pocos cambios o sin ellos. Para que mkbitmap lea un archivo de entrada como si se pasara como argumento de línea de comandos de filename, debes usar el objeto FS que proporciona Emscripten.

El objeto FS está respaldado por un sistema de archivos en la memoria (conocido como MEMFS) y tiene una función writeFile() que se usa para escribir archivos en el sistema de archivos virtual. Usa writeFile() como se muestra en la siguiente muestra de código.

Para verificar que la operación de escritura de archivos funcionó, ejecuta la función readdir() del objeto FS con el parámetro '/'. Verás example.bmp y una serie de archivos predeterminados que siempre se crean automáticamente.

Ten en cuenta que se quitó la llamada anterior a Module.callMain(['-v']) para imprimir el número de versión. Esto se debe a que Module.callMain() es una función que, por lo general, se espera que se ejecute solo una vez.

// 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();

La app mkbitmap muestra un array de archivos en el sistema de archivos de memoria, incluido example.bmp.

Primera ejecución real

Con todo en orden, ejecuta mkbitmap con Module.callMain(['example.bmp']). Registra el contenido de la carpeta '/' de MEMFS y deberías ver el archivo de salida example.pbm recién creado junto al archivo de entrada 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();

La app mkbitmap muestra un array de archivos en el sistema de archivos de memoria, incluidos example.bmp y example.pbm.

Obtén el archivo de salida del sistema de archivos en memoria

La función readFile() del objeto FS permite obtener el example.pbm creado en el último paso del sistema de archivos en memoria. La función muestra un Uint8Array que conviertes en un objeto File y guardas en el disco, ya que, por lo general, los navegadores no admiten archivos PBM para la visualización directa en el navegador. (Existen formas más elegantes de guardar un archivo, pero usar un <a download> creado de forma dinámica es la opción más compatible). Una vez que se guarde el archivo, podrás abrirlo en tu visor de imágenes favorito.

// 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();

Finder de macOS con una vista previa del archivo .bmp de entrada y el archivo .pbm de salida.

Agrega una IU interactiva

Hasta este punto, el archivo de entrada está codificado y mkbitmap se ejecuta con parámetros predeterminados. El último paso es permitir que el usuario seleccione de forma dinámica un archivo de entrada, modifique los parámetros mkbitmap y, luego, ejecute la herramienta con las opciones seleccionadas.

// 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']);

El formato de imagen PBM no es particularmente difícil de analizar, por lo que, con un poco de código JavaScript, incluso podrías mostrar una vista previa de la imagen de salida. Consulta el código fuente de la demo incorporada a continuación para ver una forma de hacerlo.

Conclusión

Felicitaciones, compilaste correctamente mkbitmap en WebAssembly y lo hiciste funcionar en el navegador. Hubo algunos callejones sin salida y tuviste que compilar la herramienta más de una vez hasta que funcionó, pero, como escribí antes, eso es parte de la experiencia. Además, recuerda la etiqueta webassembly de StackOverflow si no puedes avanzar. ¡Feliz compilación!

Agradecimientos

Sam Clegg y Rachel Andrew revisaron este artículo.