{"id":2103,"date":"2024-07-10T21:18:56","date_gmt":"2024-07-10T21:18:56","guid":{"rendered":"https:\/\/www.w3computing.com\/articles\/?p=2103"},"modified":"2024-07-10T21:19:00","modified_gmt":"2024-07-10T21:19:00","slug":"how-to-use-the-cpp-emscripten-toolchain-for-webassembly","status":"publish","type":"post","link":"https:\/\/www.w3computing.com\/articles\/how-to-use-the-cpp-emscripten-toolchain-for-webassembly\/","title":{"rendered":"How to Use the C++ Emscripten Toolchain for WebAssembly"},"content":{"rendered":"\n

Introduction<\/h2>\n\n\n\n

WebAssembly (Wasm) is a binary instruction format for a stack-based virtual machine. It is designed as a portable target for compilation of high-level languages like C++, enabling deployment on the web for client and server applications. Emscripten is an open-source compiler toolchain that allows you to compile C++ code into WebAssembly. This tutorial will guide you through the process of using the Emscripten toolchain to compile C++ code into WebAssembly and run it in a web environment.<\/p>\n\n\n\n

Prerequisites<\/h3>\n\n\n\n

Before diving into the tutorial, ensure you have the following:<\/p>\n\n\n\n

    \n
  1. Basic understanding of C++.<\/li>\n\n\n\n
  2. Familiarity with web development (HTML, JavaScript).<\/li>\n\n\n\n
  3. Installed Node.js and npm.<\/li>\n\n\n\n
  4. Installed Python (Emscripten uses Python scripts).<\/li>\n<\/ol>\n\n\n\n

    Installing Emscripten<\/h2>\n\n\n\n

    To start using Emscripten, you first need to install it. Emscripten requires several dependencies, which can be easily managed using its SDK (emsdk).<\/p>\n\n\n\n

    Step 1: Clone the Emscripten SDK<\/h3>\n\n\n\n

    First, clone the emsdk repository:<\/p>\n\n\n

    git clone https:\/\/github.com\/emscripten-core\/emsdk.git\ncd emsdk<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
    Step 2: Install and Activate the Latest SDK<\/h3>\n\n\n\n
    Next, install the latest SDK and activate it:<\/p>\n\n\n
    .\/emsdk install latest\n.\/emsdk activate latest<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
    Step 3: Set Up Environment Variables<\/h3>\n\n\n\n
    Set up the environment variables to make the emsdk tools available in your terminal session:<\/p>\n\n\n
    source .\/emsdk_env.sh<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
    You might want to add the above line to your .bashrc<\/code> or .zshrc<\/code> file to set up the environment variables automatically for every session.<\/p>\n\n\n\n
    Compiling C++ Code to WebAssembly<\/h2>\n\n\n\n
    Step 1: Writing a Simple C++ Program<\/h3>\n\n\n\n
    Let’s start with a simple C++ program. Create a file named hello.cpp<\/code> with the following content:<\/p>\n\n\n
    #include<\/span> <iostream><\/span><\/span>\n\nint<\/span> main<\/span>()<\/span> <\/span>{\n    std<\/span>::cout<\/span> << \"Hello, WebAssembly!\"<\/span> << std<\/span>::endl<\/span>;\n    return<\/span> 0<\/span>;\n}<\/code><\/span>Code language:<\/span> C++<\/span> (<\/span>cpp<\/span>)<\/span><\/small><\/pre>\n\n\n
    Step 2: Compiling with Emscripten<\/h3>\n\n\n\n
    To compile the C++ code to WebAssembly, use the emcc<\/code> compiler provided by Emscripten. Run the following command:<\/p>\n\n\n
    emcc hello.cpp -o hello.html<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
    This command tells Emscripten to compile hello.cpp<\/code> and generate an HTML file named hello.html<\/code> along with the corresponding WebAssembly and JavaScript files.<\/p>\n\n\n\n
    Step 3: Understanding the Output<\/h3>\n\n\n\n
    Emscripten generates several files:<\/p>\n\n\n\n
      \n
    1. hello.html<\/code> – An HTML file to load and run the WebAssembly module.<\/li>\n\n\n\n
    2. hello.js<\/code> – A JavaScript file that loads the WebAssembly module.<\/li>\n\n\n\n
    3. hello.wasm<\/code> – The WebAssembly binary file.<\/li>\n<\/ol>\n\n\n\n
      You can open hello.html<\/code> in a web browser to see the output of your C++ program.<\/p>\n\n\n\n
      Integrating WebAssembly with JavaScript<\/h2>\n\n\n\n
      While running C++ code in a browser is interesting, the true power of WebAssembly comes from its ability to interact with JavaScript. Let’s modify our example to demonstrate this interaction.<\/p>\n\n\n\n
      Step 1: Modifying the C++ Program<\/h3>\n\n\n\n
      Update hello.cpp<\/code> to expose a function to JavaScript:<\/p>\n\n\n
      #include<\/span> <emscripten.h><\/span><\/span>\n\nextern<\/span> \"C\"<\/span> {\n    EMSCRIPTEN_KEEPALIVE\n    void<\/span> sayHello<\/span>()<\/span> <\/span>{\n        std<\/span>::cout<\/span> << \"Hello from WebAssembly!\"<\/span> << std<\/span>::endl<\/span>;\n    }\n}<\/code><\/span>Code language:<\/span> C++<\/span> (<\/span>cpp<\/span>)<\/span><\/small><\/pre>\n\n\n
      The EMSCRIPTEN_KEEPALIVE<\/code> macro ensures that the sayHello<\/code> function is not removed by Emscripten’s optimizer. The extern \"C\"<\/code> block prevents C++ name mangling, making the function name predictable in JavaScript.<\/p>\n\n\n\n
      Step 2: Compiling with Emscripten<\/h3>\n\n\n\n
      Compile the updated C++ code:<\/p>\n\n\n
      emcc hello.cpp -o hello.js -s EXPORTED_FUNCTIONS='[\"_sayHello\"]' -s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]'<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      The -s EXPORTED_FUNCTIONS<\/code> option specifies the functions to be exposed to JavaScript. The -s EXTRA_EXPORTED_RUNTIME_METHODS<\/code> option includes additional runtime methods that facilitate interaction between JavaScript and WebAssembly.<\/p>\n\n\n\n
      Step 3: Writing JavaScript to Call WebAssembly Functions<\/h3>\n\n\n\n
      Create an HTML file named index.html<\/code> with the following content:<\/p>\n\n\n
      <!DOCTYPE html<\/span>><\/span>\n<html<\/span>><\/span>\n<head<\/span>><\/span>\n    <title<\/span>><\/span>WebAssembly with Emscripten<\/title<\/span>><\/span>\n<\/head<\/span>><\/span>\n<body<\/span>><\/span>\n    <h1<\/span>><\/span>WebAssembly with Emscripten<\/h1<\/span>><\/span>\n    <button<\/span> id<\/span>=\"sayHelloButton\"<\/span>><\/span>Say Hello<\/button<\/span>><\/span>\n    <script<\/span> src<\/span>=\"hello.js\"<\/span>><\/span><\/script<\/span>><\/span>\n    <script<\/span>><\/span>\n        var<\/span> sayHelloButton = document<\/span>.getElementById(\"sayHelloButton\"<\/span>);\n        sayHelloButton.addEventListener(\"click\"<\/span>, function<\/span>(<\/span>) <\/span>{\n            Module.ccall(\"sayHello\"<\/span>, null<\/span>, [], []);\n        });\n    <\/span><\/script<\/span>><\/span>\n<\/body<\/span>><\/span>\n<\/html<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
      Step 4: Running the Application<\/h3>\n\n\n\n
      Serve the index.html<\/code> file using a local web server. You can use a simple Python HTTP server:<\/p>\n\n\n
      python -m http.server<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      Open your browser and navigate to http:\/\/localhost:8000<\/code>. Click the “Say Hello” button to see the interaction between JavaScript and WebAssembly.<\/p>\n\n\n\n
      Advanced Emscripten Features<\/h2>\n\n\n\n
      File System Integration<\/h3>\n\n\n\n
      Emscripten provides a virtual file system that allows your WebAssembly code to read and write files. This can be useful for scenarios like processing user-uploaded files or saving data locally.<\/p>\n\n\n\n
      Step 1: Modifying the C++ Program<\/h3>\n\n\n\n
      Update hello.cpp<\/code> to demonstrate file system usage:<\/p>\n\n\n
      #include<\/span> <emscripten.h><\/span><\/span>\n#include<\/span> <stdio.h><\/span><\/span>\n\nextern<\/span> \"C\"<\/span> {\n    EMSCRIPTEN_KEEPALIVE\n    void<\/span> writeFile<\/span>()<\/span> <\/span>{\n        FILE* file = fopen(\"\/hello.txt\"<\/span>, \"w\"<\/span>);\n        if<\/span> (file) {\n            fputs<\/span>(\"Hello, File System!\"<\/span>, file);\n            fclose(file);\n        }\n    }\n\n    EMSCRIPTEN_KEEPALIVE\n    void<\/span> readFile<\/span>()<\/span> <\/span>{\n        FILE* file = fopen(\"\/hello.txt\"<\/span>, \"r\"<\/span>);\n        if<\/span> (file) {\n            char<\/span> buffer[100<\/span>];\n            fgets(buffer, sizeof<\/span>(buffer), file);\n            fclose(file);\n            printf<\/span>(\"File content: %s\\n\"<\/span>, buffer);\n        }\n    }\n}<\/code><\/span>Code language:<\/span> C++<\/span> (<\/span>cpp<\/span>)<\/span><\/small><\/pre>\n\n\n
      Step 2: Compiling with Emscripten<\/h3>\n\n\n\n
      Compile the updated C++ code:<\/p>\n\n\n
      emcc hello.cpp -o hello.js -s EXPORTED_FUNCTIONS='[\"_writeFile\", \"_readFile\"]' -s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]' --preload-file hello.txt<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      The --preload-file<\/code> option bundles the specified file with the WebAssembly module.<\/p>\n\n\n\n
      Step 3: Writing JavaScript to Call File System Functions<\/h3>\n\n\n\n
      Update index.html<\/code> to include buttons for writing and reading the file:<\/p>\n\n\n
      <!DOCTYPE html<\/span>><\/span>\n<html<\/span>><\/span>\n<head<\/span>><\/span>\n    <title<\/span>><\/span>WebAssembly with Emscripten<\/title<\/span>><\/span>\n<\/head<\/span>><\/span>\n<body<\/span>><\/span>\n    <h1<\/span>><\/span>WebAssembly with Emscripten<\/h1<\/span>><\/span>\n    <button<\/span> id<\/span>=\"writeFileButton\"<\/span>><\/span>Write File<\/button<\/span>><\/span>\n    <button<\/span> id<\/span>=\"readFileButton\"<\/span>><\/span>Read File<\/button<\/span>><\/span>\n    <script<\/span> src<\/span>=\"hello.js\"<\/span>><\/span><\/script<\/span>><\/span>\n    <script<\/span>><\/span>\n        var<\/span> writeFileButton = document<\/span>.getElementById(\"writeFileButton\"<\/span>);\n        writeFileButton.addEventListener(\"click\"<\/span>, function<\/span>(<\/span>) <\/span>{\n            Module.ccall(\"writeFile\"<\/span>, null<\/span>, [], []);\n        });\n\n        var<\/span> readFileButton = document<\/span>.getElementById(\"readFileButton\"<\/span>);\n        readFileButton.addEventListener(\"click\"<\/span>, function<\/span>(<\/span>) <\/span>{\n            Module.ccall(\"readFile\"<\/span>, null<\/span>, [], []);\n        });\n    <\/span><\/script<\/span>><\/span>\n<\/body<\/span>><\/span>\n<\/html<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
      Step 4: Running the Application<\/h3>\n\n\n\n
      Serve the index.html<\/code> file using a local web server and open it in your browser. Click the “Write File” and “Read File” buttons to see file system operations in action.<\/p>\n\n\n\n
      Using C++ Libraries with Emscripten<\/h2>\n\n\n\n
      Emscripten supports many popular C++ libraries, allowing you to leverage existing codebases in your WebAssembly projects. In this section, we’ll demonstrate how to use the SDL2 library with Emscripten.<\/p>\n\n\n\n
      Step 1: Installing SDL2<\/h3>\n\n\n\n
      Emscripten includes precompiled versions of several libraries, including SDL2. You can install SDL2 using emsdk:<\/p>\n\n\n
      .\/emsdk install sdl2\n.\/emsdk activate sdl2<\/code><\/span><\/pre>\n\n\n
      Step 2: Writing an SDL2 Program<\/h3>\n\n\n\n
      Create a file named sdl_example.cpp<\/code> with the following content:<\/p>\n\n\n
      #include<\/span> <SDL.h><\/span><\/span>\n#include<\/span> <emscripten.h><\/span><\/span>\n\nSDL_Window* window;\nSDL_Renderer* renderer;\n\nvoid<\/span> main_loop<\/span>()<\/span> <\/span>{\n    SDL_Event event;\n    while<\/span> (SDL_PollEvent(&event)) {\n        if<\/span> (event.type == SDL_QUIT) {\n            emscripten_cancel_main_loop();\n            return<\/span>;\n        }\n    }\n\n    SDL_SetRenderDrawColor(renderer, 0<\/span>, 0<\/span>, 0<\/span>, 255<\/span>);\n    SDL_RenderClear(renderer);\n\n    SDL_SetRenderDrawColor(renderer, 255<\/span>, 0<\/span>, 0<\/span>, 255<\/span>);\n    SDL_RenderPresent(renderer);\n}\n\nint<\/span> main<\/span>()<\/span> <\/span>{\n    SDL_Init(SDL_INIT_VIDEO);\n    window = SDL_CreateWindow(\"SDL2 Emscripten Example\"<\/span>, SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED, 800<\/span>, 600<\/span>, SDL_WINDOW_SHOWN);\n    renderer = SDL_CreateRenderer(window, -1<\/span>, 0<\/span>);\n\n    em\n\nscripten_set_main_loop<\/span>(main_loop, 0<\/span>, 1<\/span>)<\/span><\/span>;\n\n    return<\/span> 0<\/span>;\n}<\/code><\/span>Code language:<\/span> C++<\/span> (<\/span>cpp<\/span>)<\/span><\/small><\/pre>\n\n\n
      Step 3: Compiling with Emscripten<\/h3>\n\n\n\n
      Compile the SDL2 program:<\/p>\n\n\n
      emcc sdl_example.cpp -o sdl_example.html -s USE_SDL=2<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      The -s USE_SDL=2<\/code> option tells Emscripten to link against the SDL2 library.<\/p>\n\n\n\n
      Step 4: Running the Application<\/h3>\n\n\n\n
      Serve the sdl_example.html<\/code> file using a local web server and open it in your browser. You should see a window with a black background and a red rectangle.<\/p>\n\n\n\n
      Debugging WebAssembly<\/h2>\n\n\n\n
      Debugging WebAssembly can be challenging due to its binary nature. However, Emscripten provides several tools and techniques to make debugging easier.<\/p>\n\n\n\n
      Source Maps<\/h3>\n\n\n\n
      Emscripten can generate source maps to map the WebAssembly code back to the original C++ source code. This allows you to use browser developer tools to debug your C++ code.<\/p>\n\n\n\n
      Step 1: Compiling with Source Maps<\/h3>\n\n\n\n
      Compile your C++ code with the -g<\/code> option to generate source maps:<\/p>\n\n\n
      emcc hello.cpp -o hello.js -g<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      Step 2: Using Browser Developer Tools<\/h3>\n\n\n\n
      Open the HTML file in your browser and open the developer tools (usually by pressing F12). In the “Sources” tab, you should see the original C++ source files. You can set breakpoints, step through code, and inspect variables just like you would with JavaScript.<\/p>\n\n\n\n
      Logging and Console Output<\/h3>\n\n\n\n
      You can use standard C++ functions like printf<\/code> and std::cout<\/code> to log messages to the browser console. This can be useful for debugging and understanding the flow of your program.<\/p>\n\n\n\n
      Optimizing WebAssembly<\/h2>\n\n\n\n
      Emscripten provides several optimization options to reduce the size and improve the performance of your WebAssembly modules.<\/p>\n\n\n\n
      Step 1: Compiling with Optimizations<\/h3>\n\n\n\n
      Use the -O<\/code> options to enable optimizations. For example, -O2<\/code> enables moderate optimizations, while -O3<\/code> enables aggressive optimizations:<\/p>\n\n\n
      emcc hello.cpp -o hello.js -O2<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      Step 2: Using Link-Time Optimization<\/h3>\n\n\n\n
      Link-Time Optimization (LTO) can further reduce the size of your WebAssembly modules by performing optimizations across all compilation units. Use the -flto<\/code> option to enable LTO:<\/p>\n\n\n
      emcc hello.cpp -o hello.js -O2 -flto<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      Step 3: Minifying JavaScript<\/h3>\n\n\n\n
      Emscripten can minify the generated JavaScript code to reduce its size. Use the --closure 1<\/code> option to enable Closure Compiler:<\/p>\n\n\n
      emcc hello.cpp -o hello.js -O2 --closure 1<\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
      Conclusion<\/h2>\n\n\n\n
      In this tutorial, we covered the basics of using the Emscripten toolchain to compile C++ code to WebAssembly. We explored various features, including integrating WebAssembly with JavaScript, using the virtual file system, leveraging existing C++ libraries, debugging, and optimizing WebAssembly modules. With these skills, you can start building high-performance web applications using C++ and WebAssembly.<\/p>\n\n\n\n
      WebAssembly is a powerful technology that enables you to run C++ code in the browser with near-native performance. Emscripten makes it easy to compile your existing C++ codebases to WebAssembly and integrate them with modern web technologies. As you continue to explore WebAssembly and Emscripten, you’ll discover even more possibilities for creating fast, efficient, and feature-rich web applications.<\/p>\n\n\n\n
      Additional Resources<\/h3>\n\n\n\n