Monday, December 28, 2020

How to setup a C++ WebAssembly component to run in a create-react-app React project

I had a hard time trying to get a C/C++ WebAssembly component to work in a React application generated from the create-react-app utility. Some blogs suggested using the react-app-rewired package to override the configuration and use the wasm-loader; but I kept getting magic header not detected errors when loading the wasm file or some ES6 syntax errors. Finally I found a StackOverflow post that gave me some ideas on getting it to work. 

In this post, I outline the steps I did to create, use a C/C++ WebAssembly in a ReactJS application generated by the create-react-app tool, on a Linux Ubuntu machine. This example will call the WebAssembly's function to add in two numbers (1 and 2) and return the resultant value. The resultant value would be displayed at the top of the web page as shown in the screen shot below.

Create a ReactJS application with create-react-app

  1. Open up a Terminal. Change to your project directory and type in the following commands to create the ReactJS application cra-wasm-adder.

    $ cd /path/to/reactprj/
    $ npx create-react-app cra-wasm-adder


    The cra-wasm-adder ReactJS application is created.

  2. Underneath the root of the newly created project, create a source directory, e.g. src_cpp for the C/C++ WebAssembly code.

    $ cd /path/to/reactprj/cra-wasm-adder/
    $ mkdir src_cpp


    The src_cpp directory is created.

Create the C/C++ source code files

  1. In the newly created src_cpp directory, use a favorite source code editor to create a C/C++ file, e.g. adder.cpp. Enter the following code.



    Note: the adder function simply sums up two integer numbers and returns the value.

  2. Create a Shell script file, e.g. make.sh to call the Emscripten compiler emcc to compile the C/C++ source code.

    Note: the emcc compiles the C/C++ source code into a Javascript plumbing helper file and a WebAssembly (*.wasm) file.

  3. In the make.sh file, define the module name and output file names.



  4. Then type in the emcc command to generate a Javascript plumbing helper file and the WebAssembly (*.wasm) file.


    Note: the Javascript generated by the emcc compiler (my version is 2.0.5) is not fully compatible with the ReactJS transpiler. The file has to be edited for compatibility purposes. This modifications may differ for different versions of the compiler

  5. Type in the sed command to insert a line /* eslint-disable */  at the top of the Javascript plumbing file to disable the Ecmascript linting.



  6. Type in the sed command to replace the import.meta.url string to the WebAssembly file relative to the root of the public directory of the ReactJS project, e.g. /path/to/reactprj/public/.


    Note: in this example, the *.wasm file is placed directly underneath the root of the /path/to/reactprj/public/; so the resultant change looks like the code below.


  7. Type in the sed command to add in the window object to the self.location.href string.


    The result change Javascript looks like the snippet below.


  8. Type in the sed commands to comment out the dataURIPrefix declaration  and isDataURI function block.



    The resultant Javascript code is shown below.


  9. Next, type in the sed commands to modify the wasmBinaryFile variable to point to the actual relative location in the ReactJS' public directory and to remove and replace the getBinary and getBinaryPromise function blocks.


    After running the commands, the Javascript should like the code below:



  10.  Finally, type in the sed command to remove the call to the isDataURI function in the instantiateAsync function.


    The resultant Javascript:


  11. The last thing the make.sh script needs to do is to move the generated WebAssembly file to the /path/to/reactprj/public/ directory and the modified Javascript file to the /path/to/reactprj/src/ directory.

    mv $OUTPUT_JS ../src/
    mv $OUTPUT_WASM ../public/



    The directory structure should look like the screen shot below:

Run the Shell script

  1. In a Terminal, change directory to the location of the make.sh shell script.

    $ cd /path/to/reactprj/src_cpp/

  2. Type in the following to run the script.

    $ bash make.sh

    If the compilation is successful, the resultant Javascript and WebAssembly should be placed in the directories as shown below.


Create WebAssembly React component

  1. In a text editor, create the React component under the /path/to/reactprj/src/ directory to use the WebAssembly component, e.g. AddNumbers.js .


  2. Type in the following code to import in the generated Javascript plumbing file and call the WebAssembly adder function.


Running the ReactJS application

  1. In a Terminal, run the React JS application.

    $ npm run start

    The browser opens up the development site.


  2. Note the message at the top which prints out the result of calling the WebAssembly's adder function: Hello 1+2=3.

The source code for this example is freely available on https://gitlab.com/dominoc925/cra-wasm-adder


No comments: