تحويل ملف mkbitmap إلى WebAssembly

Thomas Steiner

في مقالة ما هو WebAssembly ومن أين أتى؟، لقد أوضحت كيف انتهينا بإنشاء WebAssembly اليوم. في هذه المقالة، سأعرض لك منهجيتي لتجميع برنامج C حالي، وهو mkbitmap، إلى WebAssembly. وهو أكثر تعقيدًا من مثال مرحبًا، لأنّه يتضمّن العمل مع الملفات والتواصل بين WebAssembly وJavaScript والرسم على لوحة، ولكنّه لا يزال قابلاً للإدارة بما يكفي لعدم إرباكك.

هذه المقالة مكتوبة للمطوّرين على الويب الذين يريدون تعلُّم استخدام WebAssembly، وهي تعرض بالتفصيل الطريقة التي يمكنك اتّباعها إذا أردت تجميع شيء مثل mkbitmap في WebAssembly. كتحذير عادل، من الطبيعي عدم الحصول على تطبيق أو مكتبة لتجميعها عند التشغيل الأول، لهذا السبب لم تعمل بعض الخطوات الموضحة أدناه، لذلك اضطررتُ إلى التراجع وإعادة المحاولة بشكل مختلف. لا تعرض المقالة الأمر السحري للتجميع النهائي كما لو هبط من السماء، بل تصف التقدم الفعلي الذي أحرزته، وشملت بعض الاستياءات التي واجهها.

معلومات حول mkbitmap

يقرأ برنامج C في mkbitmap الصورة ويطبِّق واحدة أو أكثر من العمليات التالية عليها بالترتيب: العكس وفلترة المرور المرتفع والتحجيم والضبط على الحدّ. يمكن التحكّم في كل عملية بشكلٍ فردي وتفعيلها أو إيقافها. ويتمثل الاستخدام الرئيسي لـ mkbitmap في تحويل الصور الملونة أو ذات التدرج الرمادي إلى تنسيق مناسب كمدخل لبرامج أخرى، لا سيما برنامج التتبُّع potrace الذي يشكّل أساس SVGcode. بصفتها أداة معالجة أولية، تكون mkbitmap مفيدة بشكل خاص لتحويل الرسومات المخطّطة الممسوحة ضوئيًا، مثل الرسوم المتحركة أو النصوص المكتوبة بخط اليد، إلى صور ثنائية المستوى عالية الدقة.

ويمكنك استخدام mkbitmap من خلال تمرير عدد من الخيارات واسم ملف واحد أو عدة أسماء. للاطّلاع على جميع التفاصيل، يُرجى الاطّلاع على صفحة man الخاصة بالتطبيق:

$ mkbitmap [options] [filename...]

الحصول على الشفرة‏

تتمثل الخطوة الأولى في الحصول على رمز المصدر الخاص بـ mkbitmap. ويمكنك العثور عليه على الموقع الإلكتروني للمشروع. في وقت كتابة هذا التقرير، كان botrace-1.16.tar.gz هو الإصدار الأحدث.

التجميع والتثبيت على الجهاز

الخطوة التالية هي تجميع الأداة وتثبيتها محليًا للتعرف على سلوكها. يحتوي ملف INSTALL على التعليمات التالية:

1. cd إلى الدليل الذي يحتوي على رمز الحزمة المصدر، ثم اكتب ./configure لضبط الحزمة لنظامك.

   قد يستغرق تشغيل configure بعض الوقت. أثناء التشغيل، يتم طباعة بعض الرسائل التي تشير إلى الميزات التي يتم التحقّق منها.

2. اكتب make لتجميع الحزمة.

3. يمكنك اختياريًا كتابة make check لتشغيل أي اختبارات ذاتية مضمّنة في الحزمة، وذلك باستخدام الملفات الثنائية التي تم إنشاؤها للتو والتي لم يتم تثبيتها بعد.

4. اكتب make install لتثبيت البرامج وأي ملفات بيانات ومستندات. عند التثبيت في بادئة يملكها الجذر، يُنصح بإعداد الحزمة وإنشاؤها كمستخدم عادي، والاستعانة بمرحلة make install التي يتم تنفيذها مع امتيازات الجذر.

من خلال اتّباع هذه الخطوات، من المفترض أن تحصل على ملفّين قابلَين للتنفيذ، potrace وmkbitmap، مع التركيز على الملفّ الأخير في هذه المقالة. يمكنك التأكّد من أنّه يعمل بشكل صحيح من خلال تشغيل "mkbitmap --version". في ما يلي نتيجة كل الخطوات الأربع من جهازي، تم اقتصاصها كثيرًا لتبسيطها:

الخطوة 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

الخطوة 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'.

الخطوة 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'.

الخطوة 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'.

للتحقّق من نجاح الأمر، شغِّل mkbitmap --version:

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

إذا ظهرت لك تفاصيل الإصدار، يعني ذلك أنّك نجحت في تجميع mkbitmap وتثبيته. بعد ذلك، عليك تنفيذ ما يعادل هذه الخطوات باستخدام WebAssembly.

تجميع mkbitmap إلى WebAssembly

Emscripten هي أداة لتجميع برامج C/C++ إلى WebAssembly. تشير مستندات إنشاء المشاريع في Emscripten إلى ما يلي:

من السهل جدًا إنشاء مشاريع كبيرة باستخدام Emscripten. يوفّر Emscripten نصّين برمجيَّين بسيطَين لضبط ملفات الإنشاء لاستخدام emcc كبديل لـ gcc، وفي معظم الحالات، لا يتغيّر باقي نظام الإنشاء الحالي لمشروعك.

يتابع المستند (تم تعديله قليلاً للإيجاز):

لنفترض أنّك عادةً ما تُنشئ الإصدار باستخدام الأوامر التالية:

./configure
make

لإنشاء الإصدار باستخدام Emscripten، يمكنك استخدام الأوامر التالية بدلاً من ذلك:

emconfigure ./configure
emmake make

إذًا، يصبح ./configure بشكل أساسي emconfigure ./configure وmake يصبح emmake make. يوضّح القسم التالي كيفية إجراء ذلك باستخدام mkbitmap.

الخطوة 0، make clean:

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

الخطوة 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

الخطوة 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'.

إذا سارت الأمور على ما يرام، من المفترض أن يكون هناك الآن .wasm ملفًا في مكان ما في الدليل. يمكنك العثور عليها من خلال تشغيل find . -name "*.wasm":

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

يبدو أنّ آخر ملفَّين هما الأكثر ملاءمةً، لذا عليك نقل cd إلى الدليل src/. يتوفّر الآن أيضًا ملفّان جديدان متطابقان، mkbitmap وpotrace. بالنسبة إلى هذه المقالة، فقط mkbitmap المناسبة. قد يكون من المربك بعض الشيء أنّ هذه الملفات لا تتضمّن امتداد .js، ولكنّها في الواقع ملفات JavaScript، ويمكن التحقّق منها من خلال إجراء مكالمة سريعة مع 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)

أعِد تسمية ملف JavaScript إلى mkbitmap.js من خلال استدعاء mv mkbitmap mkbitmap.js (وmv potrace potrace.js على التوالي إذا أردت). لقد حان وقت إجراء الاختبار الأول لمعرفة ما إذا كان قد تم تنفيذ الملف باستخدام Node.js على سطر الأوامر من خلال تشغيل node mkbitmap.js --version:

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

لقد نجحت في تجميع mkbitmap إلى WebAssembly. والخطوة التالية هي جعلها تعمل في المتصفّح.

mkbitmap باستخدام WebAssembly في المتصفّح

انسخ ملفَي mkbitmap.js وmkbitmap.wasm إلى دليل جديد باسم mkbitmap وأنشئ ملفًا index.html HTML نموذجيًا يحمِّل ملف 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>

ابدأ خادمًا محليًا يعرض دليل mkbitmap وافتحه في المتصفّح. من المفترض أن تظهر لك رسالة تطلب منك إدخال معلومات. وهذا أمر متوقَّع، لأنّه وفقًا لصفحة الدليل في الأداة، "[i]لم يتم تقديم وسيطات اسم الملف، لن تعمل صورة mkbitmap كفلتر، فهي تعمل على القراءة من الإدخال العادي"، والتي تكون القيمة prompt() تلقائيًا في Emscripten.

منع التنفيذ التلقائي

لإيقاف تنفيذ mkbitmap على الفور والانتظار بدلاً من ذلك إلى أن يُدخل المستخدم بيانات، عليك فهم عنصر Module في Emscripten. Module هو كائن JavaScript عمومي يتضمّن سمات يطلبها الرمز الذي ينشئه Emscripten في مراحل مختلفة أثناء تنفيذه. يمكنك تقديم تنفيذ Module للتحكّم في تنفيذ الرمز. عند بدء تشغيل تطبيق Emscripten، يفحص التطبيق القيم في عنصر Module ويطبّقها.

في حالة mkbitmap، اضبط Module.noInitialRun على true لمنع التشغيل الأولي الذي أدّى إلى ظهور الطلب. أنشئ نصًا برمجيًا باسم script.js، وأدرِجه قبل <script src="mkbitmap.js"></script> في index.html وأضِف الرمز التالي إلى script.js. عند إعادة تحميل التطبيق الآن، سيختفي الطلب.

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

إنشاء إصدار وحدات باستخدام بعض علامات الإصدار الإضافية

لتقديم مدخلات للتطبيق، يمكنك استخدام نظام الملفات المتوافق مع Emscripten في Module.FS. يوضّح قسم تضمين أنظمة الملفات المتوافقة في المستندات ما يلي:

يحدّد Emscripten ما إذا كان سيتم تضمين ميزة دعم نظام الملفات تلقائيًا. ولا تحتاج العديد من البرامج إلى ملفات، كما أنّ حجم دعم نظام الملفات غير مهم، لذلك تتجنّب Emscripten تضمينها عندما لا تجد سببًا لذلك. وهذا يعني أنّه في حال لم يصل رمز C/C++ إلى الملفات، لن يتم تضمين الكائن FS وواجهات برمجة التطبيقات الأخرى لنظام الملفات في الناتج. من ناحية أخرى، إذا كان رمز C/C++ يستخدم الملفات، سيتم تلقائيًا تضمين ميزة توافق نظام الملفات.

يُعدّ mkbitmap أحد الحالات التي لا يتضمّن فيها Emscripten تلقائيًا دعمًا لنظام الملفات، لذا عليك توجيهه صراحةً لإجراء ذلك. وهذا يعني أنّك بحاجة إلى اتّباع خطوات emconfigure وemmake الموضّحة سابقًا، مع ضبط علامتَين إضافيتَين من خلال وسيطة CFLAGS. قد تكون الإشارات التالية مفيدة لمشاريع أخرى أيضًا.

• اضبط -sFILESYSTEM=1 لتضمين ميزة توافق نظام الملفات.
• اضبط -sEXPORTED_RUNTIME_METHODS=FS,callMain لتصدير Module.FS وModule.callMain.
• اضبط -sMODULARIZE=1 و-sEXPORT_ES6 لإنشاء وحدة ES6 حديثة.
• اضبط -sINVOKE_RUN=0 لمنع التشغيل الأولي الذي أدّى إلى ظهور الطلب.

في هذه الحالة على وجه التحديد، عليك ضبط علامة --host على wasm32 لإعلام النص البرمجي configure الذي تجمعه WebAssembly.

يظهر الأمر emconfigure الأخير على النحو التالي:

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

لا تنس تشغيل emmake make مرة أخرى ونسخ الملفات التي تم إنشاؤها حديثًا إلى مجلد mkbitmap.

عدِّل index.html لكي تحمِّل وحدة ES script.js فقط، والتي يمكنك من خلالها استيراد وحدة 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();

عند فتح التطبيق الآن في المتصفّح، من المفترض أن يظهر الكائن Module الذي تم تسجيل الدخول إليه في وحدة تحكّم أدوات مطوّري البرامج، وسيختفي الطلب، لأنّ الوظيفة main() في mkbitmap لم تعُد مطلوبة في البداية.

تنفيذ الدالة الرئيسية يدويًا

الخطوة التالية هي استدعاء دالة main() في mkbitmap يدويًا من خلال تشغيل Module.callMain(). تأخذ الدالة callMain() صفيفًا من الوسيطات التي تتطابق الواحدة تلو الأخرى مع ما يتم تمريره في سطر الأوامر. إذا كنت تريد تنفيذ mkbitmap -v في سطر الأوامر، يمكنك استدعاء Module.callMain(['-v']) في المتصفّح. يؤدي ذلك إلى تسجيل رقم إصدار mkbitmap في وحدة تحكّم DevTools.

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

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

run();

إعادة توجيه الناتج العادي

يكون الإخراج العادي (stdout) تلقائيًا هو وحدة التحكّم. ومع ذلك، يمكنك إعادة توجيهها إلى شيء آخر، مثل دالة تخزِّن الإخراج في متغيّر. يعني ذلك أنّه يمكنك إضافة الإخراج إلى ملف HTML من خلال ضبط السمة 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();

نقل ملف الإدخال إلى نظام ملفات الذاكرة

للحصول على ملف الإدخال في نظام ملفات الذاكرة، تحتاج إلى ما يعادل mkbitmap filename في سطر الأوامر. لفهم كيفية معالجة هذه المشكلة، إليك أولاً بعض المعلومات الأساسية عن كيفية توقّع mkbitmap للمدخلات وإنشاء المخرجات.

تنسيقات الإدخال المتوافقة لملف mkbitmap هي PNM (PBM وPGM وPPM) وBMP. تنسيقات الإخراج هي PBM للصور النقطية وPGM للخرائط الرمادية. في حال تقديم وسيطة filename، سينشئ mkbitmap تلقائيًا ملف إخراج يتم الحصول على اسمه من اسم ملف الإدخال عن طريق تغيير لاحقته إلى .pbm. على سبيل المثال، إذا كان اسم ملف الإدخال هو example.bmp، سيكون اسم ملف الإخراج هو example.pbm.

يوفر Emscripten نظام ملفات افتراضي يحاكي نظام الملفات المحلي، بحيث يمكن تجميع التعليمات البرمجية الأصلية التي تستخدم واجهات برمجة تطبيقات الملفات المتزامنة وتشغيلها مع تغيير بسيط أو عدم حدوث أي تغيير. لكي يقرأ mkbitmap ملف إدخال كما لو تم تمريره كوسيطة سطر أوامر filename، عليك استخدام عنصر FS الذي يوفّره Emscripten.

يستند عنصر FS إلى نظام ملفات في الذاكرة (يُشار إليه عادةً باسم MEMFS) ويحتوي على دالة writeFile() التي تستخدمها لكتابة الملفات في نظام الملفات الافتراضي. استخدِم writeFile() كما هو موضّح في نموذج الرمز البرمجي التالي.

للتأكّد من نجاح عملية كتابة الملف، يمكنك تشغيل الدالة readdir() لكائن FS مع المَعلمة '/'. ستظهر لك example.bmp وعدد من الملفات التلقائية التي يتم إنشاؤها تلقائيًا دائمًا.

يُرجى العلم أنّه تمت إزالة الطلب السابق الذي تم توجيهه إلى Module.callMain(['-v']) لطباعة رقم الإصدار. ويرجع ذلك إلى أنّ Module.callMain() هي دالة يُتوقّع تنفيذها مرة واحدة فقط بشكل عام.

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

أول عملية تنفيذ فعلية

بعد تنفيذ كل شيء في مكانه الصحيح، يمكنك تنفيذ mkbitmap من خلال تشغيل Module.callMain(['example.bmp']). سجِّل محتوى مجلد '/' في MEMFS، ومن المفترض أن يظهر لك ملف الإخراج example.pbm الذي تم إنشاؤه حديثًا بجانب ملف الإدخال 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();

إخراج ملف الإخراج من نظام ملفات الذاكرة

تتيح دالة readFile() لعنصر FS الحصول على example.pbm الذي تم إنشاؤه في الخطوة الأخيرة من نظام ملفات الذاكرة. تعرض الدالة Uint8Array الذي تحوّله إلى عنصر File وتحفظه على القرص، لأنّ المتصفّحات لا تتيح بشكل عام عرض ملفات PBM مباشرةً في المتصفّح. (هناك طرق أكثر سهولة لحفظ ملف، ولكن استخدام <a download> تم إنشاؤه ديناميكيًا هو الطريقة الأكثر توافقًا على نطاق واسع). بعد حفظ الملف، يمكنك فتحه في عارض الصور المفضّل لديك.

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

إضافة واجهة مستخدم تفاعلية

حتى هذه المرحلة، يكون ملف الإدخال مُبرمَجًا بشكلٍ ثابت ويتم تشغيل mkbitmap باستخدام المَعلمات التلقائية. الخطوة الأخيرة هي السماح للمستخدم باختيار ملف إدخال ديناميكيًا، وتعديل مَعلمات mkbitmap، ثم تشغيل الأداة باستخدام الخيارات المحدّدة.

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

ليس من الصعب تحليل تنسيق ملف PBM، لذا يمكنك استخدام بعض رموز JavaScript لعرض معاينة للصورة الناتجة. اطّلِع على رمز المصدر للنموذج التجريبي المضمّن أدناه لمعرفة طريقة واحدة لإجراء ذلك.

الخاتمة

تهانينا، لقد نجحت في تجميع mkbitmap إلى WebAssembly وجعلها تعمل في المتصفّح. لقد واجهت بعض المشاكل وكنت بحاجة إلى تجميع الأداة أكثر من مرة إلى أن نجحت، ولكن كما ذكرت أعلاه، هذا جزء من التجربة. تذكَّر أيضًا علامة webassembly في StackOverflow إذا واجهت مشكلة. مع أطيب التحيّات،

الشكر والتقدير

راجعت سام كليج وراشيل أندرو هذه المقالة.