easy-wasm-c

A package to make compilation for C/C++ files to WASM format easier.

Usage no npm install needed!

<script type="module">
  import easyWasmC from 'https://cdn.skypack.dev/easy-wasm-c';
</script>

README

Easy-Wasm-C

A package to make compilation for C/C++ files to WASM/WebAssembly format easier. The purpose of this package is to simplify the workflow of creating .wasm or WebAssembly Files for NodeJS projects. Minimally opinionated, facilitates complication and workflow via the Spawn API from Node's Child Process Library. Several commands are available that will be documented here in this README.

Dependencies and Requirements

There are only 3 hard dependencies:

In terms of requirements, WebAssembly is only available in NodeJS versions 7.x with the --expose-wasm flag and >8.x versions out of the box.

Installation

This is an npm package meant to be leveraged as a CLI. Hence...

npm install easy-wasm-c --save

This can be installed globally, but this is generally not recommended. After installation, start by creating a .env file in your project directory. Likely, you will already have done this for a project if you are using DotEnv for it. In your .env file, specify the value:

EMSDKPATH=yourpath

And point this to the path of your emsdk installation. For example, if your emsdk installation was in your home directory or /home/yourname/emsdk, the value would be specified as:

EMSDKPATH=/home/yourname/emsdk

At this point, if you have never installed emsdk before, easy-wasm-c has the following command to facilitate the installation of emsdk:

easy-wasm-c import
easy-wasm-c env

This will clone the emsdk repository from github to wherver you have pointed EMSDKPATH. After you have done this, you can issue these to get all the files you'll need in order to get a project going. You should notice that there are now two files: easy-wasm-c.config.js and env-make.sh or env-make.bat depending on your OS. Depending on your OS, you'll then issue the following command:

source env-make.sh # Linux/Unix
env-make.bat # Windows

Why do you have to do this instead of easy-wasm-c being able to handle this? Because the Unix/Linux Permission system does not allow the child process to modify the parent environment. So this means that you'll have to do this part manually. Inside the contents of env-make, you'll see a series of commands that will look like this:

EMSDKPATH install latest
EMSDKPATH update-tags
EMSDKPATH activate latest
source emsdk_env.sh

The purpose of env-make is to be able to in 1 command, install, update, activate, and prepare emcc for usage on your system. For WebAssembly, the usage of Emscripten is necessary. This approach sets the path of emcc per-terminal and per-session, so this means once your quit the current terminal session, it will be lost and you will have to execute env-make again.

Note that emsdk will detect that if you have already had emsdk and emcc installed, it will skip over all the installation and update parts and tell you that the components have already been detected and installed. This means that you can safely always run the full set of commands and it will merely install and update the parts that are not found or outdated.

If this is done correctly, you should now be able to use emcc in your terminal. Verify it by seeing something that looks like this:

name@user:~/test$ emcc
emscripten:INFO: generating system asset: is_vanilla.txt... (this will be cached in "/EMSDKPATH/.emscripten_cache/is_vanilla.txt" for subsequent builds)
emscripten:INFO:  - ok
shared:INFO: (Emscripten: Running sanity checks)
emcc:WARNING: no input files

If you see this, your setup is now complete and you are ready to start compiling!

Usage

Once you have gone through the process of installing WebAssembly, we can finally start the process of compiling files for use. Assuming that you went through the process of making your project ready, you should see an easy-wasm-c.config.js file in your project directory. Open it up and you'll see something that looks like this:

module.exports  = {
  command:  "wasm-src/main.c -o main.wasm -O3 -s SIDE_MODULE=1"
}

This is the default path and name. Of course, you can always change this depending on your project needs. The way the project works is that it appends the command to emcc. So in this case, easy-wasm-c through the spawn API issues emcc wasm-src/main.c -o main.wasm -O3 -s SIDE_MODULE=1. Note the pathing is assumed to be issued to your current working directory. Issue the following command to compile main.c file to main.wasm:

easy-wasm-c compile

If no errors are found during compile time, then you'll merely see Done. in the terminal. Otherwise the framework will issue the stderr, stdout and err system calls for you to note your errors from compilation. If everything goes well, you'll see a main.wasm file in your current working directory. That means that your WebAssembly file is ready to be used!

Commands

Note that before you can even issue a command, the .env file with the EMSDKPATH must be defined.

easy-wasm-c import: Clones the emsdk repository to the EMSDKPATH supplied in the .env file.

easy-wasm-c <cmd> [kwargs...]: Executes a command from emsdk, where cmd is the emsdk command and kwargs is the continuous list of arguments. For the full supported arguments, view the emsdk CLI page.

easy-wasm-c env [-o/--overwrite | -i/--no-install | -a/--no-activate | -u/--no-update] : Writes env-make.sh or env-make.bat depending on your OS. The following arguments are as follows:

  • -o/--overwrite: Overwrites the existing easy-wasm-c.config.js and env-make.sh/env-make.bat files. By default, if these files exist, they will not be overwritten. They will be written if they do not exist in the current working directory.
  • -i/--no-install: Do not writeemsdk install latest. Skip the emcc installation step.
  • -a/--noactivate: Do not write emsdk activate latest. Do not write the .emscripten file.
  • -u/--update: Do not write emsdk update-tags. Do not update the list of tags available to emsdk.

easy-wasm-c compile: Issues the command from the easy-wasm-c.config.js file, compiling your entry point file into a .wasm file.

Credits

This project could not have been done without the help from the following sources:

Contributing, Bugs, and Comments

Thank you in your interest in wanting to help out with this project. All feedback should go in the Issues section of the project. I look forward to being able to receive feedback as well as making this project better for everyone!