View source for User:Charlotte/Getting Started in WebAssembly with C++

This is an introduction to [[WebAssembly]], in the browser using [http://kripken.github.io/emscripten-site/ Emscripten].
==Firstly, why did I make this article?==
I found that there was a lack of tutorials and/or information in one easy to understand place, so I decided to make this.

I hope you find it helpful.

''Note this is written for Linux/OSX''

I will update this for Windows as soon as I can, but it shouldn't be too hard using the information on the WebAssembly site.
==Let's get started shall we?==

Okay so, firstly we'll need to get the Emsdk (development tools for WebAssembly) instructions to doing so can be found [http://webassembly.org/getting-started/developers-guide/ here on the WebAssembly site] but I'll copy them here so you can get all the information in one place.

Let's check we have the dependencies:
* [[Git]]
* Cmake
* GCC/XCode
* Python 2.7.x (installed on most Linux & OSX systems by default.)

If you don't have these installed use your package manager to get them apt or brew for OSX or whatever package manager you have for Linux.

<code>xcode-select --install</code> for xcode
==Installing the Emsdk==

Let's get the repository we need and compile the tools!

<syntaxhighlight lang=bash>
$ git clone https://github.com/juj/emsdk.git
$ cd emsdk
$ ./emsdk install latest
$ ./emsdk activate latest
</syntaxhighlight>

After this you'll see a prompt asking you to do <code>source emsdk_env.sh</code>, which sets up the environment paths for the SDK. I suggest adding it to your <code>bashrc</code> (or your setup env vars for your terminal) just to make things easier in terms of not having to remember it each time.
==Using the Emsdk==

Now let's compile something to check it's all working as expected.

For this I'll assume you have a directory for playing with this in so let's make a directory under that for this test run and to get you used to the software
<syntaxhighlight lang=bash>
$ mkdir test
$ cd test
$ touch test.cpp
</syntaxhighlight>
then open <code>test.cpp</code> in your code editor of choice and copy this file into it.
<syntaxhighlight lang=cpp>
#include <iostream>

extern "C" {
    int main() {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
}
</syntaxhighlight>

Then we can compile it with a nice one-liner, and run it with one more.
<syntaxhighlight lang=bash>
$ em++ -s WASM=1 -o test.html test.cpp
$ emrun test.html
</syntaxhighlight>

Now let me explain this a bit, if you have done C++ before most of this may make sense.

For functions to be accessible outside of the binary they need to be wrapped in <code>extern "C"</code> this tells the compiler not to mangle the name, I don't know much about it but it's necessary you can read up on it more [[wikipedia:Name_mangling|here]].

'''Wait, what is this massive JavaScript file?'''

If you look in the directory we compiled that code in you'll see a file called <code>test.js</code> which is rather large, I haven't looked into it too much yet but it is necessary for setting up the environment for WebAssembly to run in, also includes polyfills, my more JS inclined friends told me.

I'll look into it more at some point.
==Let's do something more interesting==

Now that is very nice and all but it's just printing a string to the console, let's get something a bit more interesting, passing data between JavaScript and C++.

Let's change that <code>test.cpp</code> to pass a string from it, to JS and print it
<syntaxhighlight lang=cpp>
#include <string>

extern "C" {
    extern void print_js(char *);

    char test;
    int main() {
        strncpy(&test,"Hello, World!", 16);
        print_js(&test);
        return 0;
    }
}

But one moment, where is that <code>print_js</code> defined I hear you ask, in this next file I've called <code>lib.js</code> as it supplies supporting code.
<syntaxhighlight lang=javascript>
//lib.js
mergeInto(LibraryManager.library, { // template part
    print_js: function(str) { // Our code!
        console.log(str);
    }
}); // template part
</syntaxhighlight>

Now if you try to compile this as before we will get an error <code>warning: unresolved symbol: print_js</code> which is expected, so let's link the library in with this
<syntaxhighlight lang=bash>
$ em++ -s WASM=1 --js-library lib.js -o test.html main.cpp
</syntaxhighlight>

Now if we run this as before you'll notice something, no output on screen, instead the output will only be in the JS console, which you can access with <code>Ctrl+Shift+K</code> in Firefox.

Wait, but what's this? all you get is a number, the reason for this is in C and C++ strings are a pointer to the first character, and the continues until you hit <code>\0</code> the end of a string. So we need to tell Javascript that, thankfully WebAssembly makes that easy, giving JS full access to WASM's memory, so let's fix our <code>lib.js</code> to deal with this
<syntaxhighlight lang=javascript>
mergeInto(LibraryManager.library, {
    print_js: function (p) { // p for pointer
        let h = Module.HEAPU8; // Access to memory as unsigned 8 bit/byte groups
        let s = "";
        for (i = p; h[i]; i++) { // continues until h[i] = 0, the end of a string in C/C++
          s += String.fromCharCode(h[i]);
        }
        console.log(s);
    },
  });
</syntaxhighlight>
And if we compile that again, we'll get <code>Hello, World!</code> in the JS console! So now we have strings being sent one way, how about back to C++/WASM from Javascript? Let's get on to this.

We need to make a change to our <code>lib.js</code> so we can store the location of the string's first character, so change it as follows
<syntaxhighlight lang=javascript>
mergeInto(LibraryManager.library, {
  print_js: function (p) {
    let h = Module.HEAPU8;
    let s = "";
    for (i = p; h[i]; i++) {
      s += String.fromCharCode(h[i]);
    }
    console.log(s);
    //return s;
  },
  stringPointer: function(p) {
    window.stringLocation = p;
  }
});
</syntaxhighlight>
Which just stores the pointer passed to it in a global variable called stringLocation. Now we need to call this from our C++ code passing the pointer to string, which is a small change to our original code.
<syntaxhighlight lang=cpp>
#include <string>

extern "C" {
    extern void print_js(char *);
    extern void stringPointer(char *);


    char js_str;
    int main() {
        stringPointer(&js_str);
        strncpy(&js_str,"Hello, World!", 20);
        print_js(&js_str);
        return 0;
    }
}
</syntaxhighlight>
Then we need to add a new file, so it's easier to call functions defined in <code>lib.js</code> and so we can access WebAssembly stuff like memory.

Create a file called <code>post.js</code> and fill it with this:
<syntaxhighlight lang=javascript>
function setString_js(str){
    let h = Module.HEAPU8;
    let p = window.stringLocation;
    for(i = 0; i < str.length; i++){
        h[p+i] = str[i].charCodeAt(0);
    }
    h[p+str.length] = 0;
}

/*
This function makes it possible to call print_js func.
from pure JS easily.
*/
function print_js() {
    Module.asmLibraryArg._print_js(window.stringLocation);
}
</syntaxhighlight>
<code>Module.asmLibraryArg._<func_name></code> is how we access functions defined in <code>lib.js</code> and the first function in here writes to the stringLocation, character by character and then terminates with a <code>\0</code> as defined by the C/C++ string spec.

Then compiling this we just need to add one more arg.
<syntaxhighlight lang=bash>
$ em++ -s WASM=1 --js-library lib.js --post-js post.js -o test.html main.cpp
</syntaxhighlight>
And then by using the js console you can call
<syntaxhighlight lang=javascript>
setString_js("testing")
print_js();
//testing
</syntaxhighlight>
And there you have it passing a string, to actually use this in C++ you'd have to call a function telling it to read the string into another location to be kept, but for the purpose of this tutorial let's just echo it out.

The change to our C++ code is rather small, adding another function to be called when JS changes the string.
<syntaxhighlight lang=cpp>
#include <iostream>
#include <string>

extern "C" {
    extern void print_js(char *);
    extern void stringPointer(char *);


    char js_str;
    int main() {
        stringPointer(&js_str);
        strncpy(&js_str,"the text you want", 20);
        print_js(&js_str);
        return 0;
    }

    void print_str(char * str) {
        std::cout << str << std::endl;
    }
}
</syntaxhighlight>
and a one line change to our post.js
<syntaxhighlight lang=javascript>
function setString_js(str){
    let h = Module.HEAPU8;
    let p = window.stringLocation;
    for(i = 0; i < str.length; i++){
        h[p+i] = str[i].charCodeAt(0);
    }
    h[p+str.length] = 0;
    Module._print_str(window.stringLocation);
}

function print_js() {
    Module.asmLibraryArg._print_js(window.stringLocation);
}
</syntaxhighlight>
This is something new to us now, Module._print_str(...) which is how we call WASM functions from Javascript.

this requires one more change to our compiling command
<syntaxhighlight lang=bash>
$ em++ -s WASM=1 --js-library lib.js --post-js post.js -s EXPORTED_FUNCTIONS='["_main","_print_str"]' -o index.html main.cpp
</syntaxhighlight>
So you add functions to be used or accessed outside of the C++ code, prepending <code>_</code> there is an alternate way of doing this by using
<syntaxhighlight lang=cpp>
#include <emscripten.h>

extern "C" {
    EMSCRIPTEN_KEEPALIVE
    int main() {
        stringPointer(&js_str);
        strncpy(&js_str,"the text you want", 20);
        print_js(&js_str);
        return 0;
    }
}
</syntaxhighlight>
which then gets rid of the need of <code>-s EXPORTED_FUNCTIONS</code> all together.

Anyway as you run this you'll see it all works as expected.

Now we've dealt with passing strings back and forth, from now onwards I'll stop supplying the whole files when I make changes, I'll just specify where they are.
==Booleans==
For booleans, they are represented by 0 and 1 in C/C++, the code I used to do this is
<syntaxhighlight lang=cpp>
//...
extern void boolPointer(bool *);

bool js_bool;
int main() {
    //...
    js_bool = true;
    get_bool_js(&js_bool);
    //...
}

and added to lib.js

boolPointer: function(p) {
    window.boolLocation = p;
},
get_bool_js: function(p) {
    let h = Module.HEAPU8;
    console.log(h[p]);
}
</syntaxhighlight>
and then for sending booleans back to WASM, added this to <code>post.js</code>
<syntaxhighlight lang=javascript>
function setBool_js(bool) {
    let h = Module.HEAPU8;
    let p = window.stringLocation;
    if (bool) {
        h[p] = 1;
    } else {
        h[p] = 0;
    }
}
</syntaxhighlight>

And that is booleans done!

On to numbers now (as I write this, I haven't done this yet and I fear this being tricky)

==Numbers!==
===Floats===
Added to <code>main.cpp</code>
<syntaxhighlight lang=cpp>
// ...
extern void floatPointer(float *);
extern void get_float_js(float *);
// ...
js_float = 3.141;
get_float_js(&js_float);
 [</syntaxhighlight>
and then to lib.js
<syntaxhighlight lang=javascript>
floatPointer: function(p) {
    window.floatLocation = p;
},
get_float_js: function(p) {
    let dv = new DataView(Module.wasmMemory.buffer);
    console.log(dv.getFloat32(p, true)); 
    // true or false depends on your OS so you may need to tweak this
}
</syntaxhighlight>

[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getFloat32 Information on DataView]

Then to set the float in <code>post.js</code> is a few lines
<syntaxhighlight lang=javascript>
function setFloat_js(f_val) {
    let dv = new DataView(Module.wasmMemory.buffer);
    dv.setFloat32(window.floatLocation, f_val, true);
}
</syntaxhighlight>
==Written by Charlotte Lily Fields==
Want to give me feedback or support me in writing more? You can do so here:
* [https://twitter.com/Foxsan48 Twitter: @Foxsan48]
* [https://ko-fi.com/charlotte Ko-Fi/Charlotte]
* [https://www.patreon.com/CharlotteFields Patreon]
[https://jbt.github.io/markdown-editor/ Written with the help of the Markdown editor from JBT]

Originally posted [https://foxsan48.github.io/en/#!pages/tut.md on github.io].