Компиляция кода C/C++ в WebAssembly

Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

После того как вы написали код на C / C ++, вы можете скомпилировать его в WebAssembly, например, с помощью инструмента Emscripten. Давайте посмотрим, как это работает.

Подготовка рабочей среды для Emscripten

Первым делом установим компоненты для дальнейшей работы.

Необходимые компоненты

Установите Emscripten SDK и настройте рабочее окружение используя инструкции: https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html

Компиляция примера

Когда рабочее окружение подготовлено, попробуем собрать пример кода на языке Си при помощи Emscripten. Вам доступно большое количество опций для настройки компиляции, но мы рассмотрим только два основных сценария компиляции с использованием Emscripten:

  • Компиляция в wasm и созданиее HTML-страницы для запуска вашего кода, а также JavaScript кода, необходимого для работы wasm модуля в веб-среде.
  • Просто компиляция в wasm и создание JavaScript кода.

Мы рассмотрим оба способа ниже.

Создание HTML и JavaScript

Это самый простой способ, который мы рассмотрим. С его помощью вы сможете использовать Emscripten для создания всего что нужно, чтобы ваш код работал в браузере как модуль WebAssembly.

  1. Нам понадобится простой пример для компиляции. Скопируйте следующий код программы на Си и сохраните его в файле  hello.c в новой папке на вашем локальном диске:
    #include <stdio.h>
    
    int main(int argc, char ** argv) {
      printf("Hello World\n");
    }
  2. Теперь, используя терминал, перейдите в каталог, в котором находится ваш файл hello.c, и выполните следующую команду:
    emcc hello.c -s WASM=1 -o hello.html

Рассмотрим параметры, которые мы передали компилятору:

  • -s WASM=1 — Указывает, что мы хотим получить wasm модуль. Если не использовать этот параметр, по умолчанию Emscripten просто создает  asm.js;
  • -o hello.html — Указывает, что мы хотим, чтобы Emscripten сгенерировал HTML-страницу hello.html запускающую наш код, а также сам модуль wasm и код JavaScript который позволит использовать модуль в веб-среде.

На этом этапе в вашем каталоге должны находится:

  • Бинарный код модуля wasm (hello.wasm)
  • Файл JavaScript, содержащий код связывающий нативные функции Си и JavaScript/wasm (hello.js)
  • HTML-страница для загрузки, компиляции и инициализации wasm модуля, и отображающий его вывод в браузере (hello.html)

Запуск вашего примера

Теперь, все что нужно чтобы запустить полученный  hello.html в браузере, это поддержка WebAssembly. Он включен по умолчанию в Firefox 52+, Chrome 57+ и последних версиях Opera. Также вы можете использовать модули WebAssembly в Firefox 47+, включив флаг javascript.options.wasm в about:config, или в Chrome 51+ и Opera 38+ перейдя в chrome://flags и включив флаг Experimental WebAssembly.

Если все работает как планировалось, вы должны увидеть надпись "Hello world" на открывшейся веб-странице и в JavaScript консоли вашего браузера. Поздравляем, вы только что скомпилировали программу на Си в WebAssembly и запустили ее в своем браузере!

Примечание: На самом деле, если просто открыть полученный hello.html, то ничего работать не будет. Подразумевается что все файлы находятся на веб-сервере и вы запускаете страницу через localhost/hello.html. Для этих целей можно использовать отладочный веб-сервер Emscripten. Чтобы его запустить, откройте терминал, перейдите в каталог, в котором находятся ваши файлы и выполните команду emrun hello.html

Использование пользовательского HTML шаблона

Sometimes you will want to use a custom HTML template. Let's look at how we can do this.

  1. First of all, save the following C code in a file called hello2.c, in a new directory:

    #include <stdio.h>
    
    int main(int argc, char ** argv) {
        printf("Hello World\n");
    
    }
  2. Search for the file shell_minimal.html in your emsdk repo. Copy it into a sub-directory called html_template inside your previous new directory.

  3. Now navigate into your new directory (again, in your Emscripten compiler environment terminal window), and run the following command:

    emcc -o hello2.html hello2.c -O3 -s WASM=1 --shell-file html_template/shell_minimal.html

    The options we've passed are slightly different this time:

    • We've specified -o hello2.html, meaning that the compiler will still output the JavaScript glue code and .html.
    • We've also specified --shell-file html_template/shell_minimal.html — this provides the path to the HTML template you want to use to create the HTML you will run your example through.
  4. Now let's run this example. The above command will have generated hello2.html, which will have much the same content as the template with some glue code added into load the generated wasm, run it, etc. Open it in your browser and you'll see much the same output as the last example.

Note: You could specify outputting just JavaScript rather than the full HTML by specifying a .js file instead of an HTML file in the -o flag, e.g. emcc -o hello2.js hello2.c -O3 -s WASM=1. You could then build your custom HTML complete from scratch. This isn't recommended however — Emscripten requires a large variety of JavaScript "glue" code to handle memory allocation, memory leaks, and a host of other problems, which is already included in the provided template. It is easier to use that than having to write it all out yourself, although as you become more experienced at what it all does, you'll be able to create your own customized versions for your needs.

Вызов пользовательской функции, определенной в Си

If you have a function defined in your C code that you want to call as needed from JavaScript, you can do this using the Emscripten ccall() function, and the EMSCRIPTEN_KEEPALIVE declaration (which adds your functions to the exported functions list (see Why do functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get No functions to process?)). Let's look at how this works.

  1. To start with, save the following code as hello3.c in a new directory:

    #include <stdio.h>
    #include <emscripten/emscripten.h>
    
    int main(int argc, char ** argv) {
        printf("Hello World\n");
    }
    
    #ifdef __cplusplus
    extern "C" {
    #endif
    
    void EMSCRIPTEN_KEEPALIVE myFunction(int argc, char ** argv) {
      printf("MyFunction Called\n");
    }
    
    #ifdef __cplusplus
    }
    #endif

    By default, Emscripten-generated code always just calls the main() function, and other functions are eliminated as dead code. Putting EMSCRIPTEN_KEEPALIVE before a function name stops this from happening. You also need to import the emscripten.h library to use EMSCRIPTEN_KEEPALIVE.

    Note: We are including the #ifdef blocks so that if you are trying to include this in C++ code, the example will still work. Due to C versus C++ name mangling rules, this would otherwise break, but here we are setting it so that it treats it as an external C function if you are using C++.

  2. Now add html_template/shell_minimal.html into this new directory too, just for convenience (you'd obviously put this in a central place in your real dev environment).

  3. Now let's run the compilation step again. From inside your latest directory (and while inside your Emscripten compiler environment terminal window), compile your C code with the following command. (Note that we need to compile with NO_EXIT_RUNTIME, which is necessary as otherwise when main() exits the runtime would be shut down - necessary for proper C emulation, e.g., atexits are called - and it wouldn't be valid to call compiled code.)

    emcc -o hello3.html hello3.c -O3 -s WASM=1 --shell-file html_template/shell_minimal.html -s NO_EXIT_RUNTIME=1  -s EXTRA_EXPORTED_RUNTIME_METHODS='["ccall"]'
  4. If you load the example in your browser again, you'll see the same thing as before!

  5. Now we need to run our new myFunction() function from JavaScript. First of all, let's add a <button> as shown below, just above the first opening <script type='text/javascript'> tag.

    <button class="mybutton">Run myFunction</button>
  6. Now add the following code inside the last <script> element (just above the closing </script> tag):

    document.querySelector('.mybutton').addEventListener('click', function(){
      alert('check console');
      var result = Module.ccall('myFunction', // name of C function 
                                 null, // return type
                                 null, // argument types
                                 null); // arguments
    });

This illustrates how ccall() is used to call the exported function.

Смотрите также

Метки документа и участники

Внесли вклад в эту страницу: thatlldo
Обновлялась последний раз: thatlldo,