https://github.com/shamadee/wasm-init
Build tool and template generator for WebAssembly Projects
https://github.com/shamadee/wasm-init
Last synced: 9 months ago
JSON representation
Build tool and template generator for WebAssembly Projects
- Host: GitHub
- URL: https://github.com/shamadee/wasm-init
- Owner: shamadee
- License: mit
- Created: 2017-03-26T05:39:16.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2018-04-03T06:33:02.000Z (almost 8 years ago)
- Last Synced: 2025-03-27T05:34:51.392Z (10 months ago)
- Language: JavaScript
- Homepage:
- Size: 55.7 KB
- Stars: 171
- Watchers: 11
- Forks: 25
- Open Issues: 5
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
- awesome-wasm - wasm-init - Work environment and code generator for WebAssembly projects
README
# **wasm-init**
## Work environment and code generator for WebAssembly projects
wasm-init abstracts the WebAssembly setup and compile process and aims to dramatically simplify the development workflow.
## **Install**
This package requires that you have [**Emscripten**](https://github.com/juj/emsdk.git) installed on your machine. You can get it like so:
```
git clone https://github.com/juj/emsdk.git
cd emsdk
./emsdk install sdk-incoming-64bit binaryen-master-64bit
./emsdk activate sdk-incoming-64bit binaryen-master-64bit
```
(Note, that the install will take a while. More information is [here](http://webassembly.org/getting-started/developers-guide/).)
The best way to install this module is via `npm install wasm-init`.
## **Use**
### **Quick Setup**
* Add the following scripts to your project's package JSON:
```json
"scripts": {
"wasm-init": "wasm-init",
"compile": "wasm-compile",
"start": "gulp" // optional for hot-reloading
}
```
* `npm run wasm-init minimal`
* Add the relative path to the emsdk folder in your *wasm.config.js* file
* `npm run wasm-init build`
* `node server` and go to *localhost:3000*, open the console and check that WASM has loaded successfully
* make changes to your C++ file and recompile with `npm run compile`
## **The whole story**
At the heart of wasm-init is the *wasm.config.js* file, which takes Emscripten's compile process and breaks it down into configurable elements. To compile C++ to WASM with Emscripten, you need at bare minimum the following properties:
```javascript
// wasm.config.js
module.exports = {
emscripten_path: './../emsdk',
inputfile: 'lib.cpp',
outputfile: 'lib.js',
flags: [
'-s WASM=1',
],
};
```
`emscripten_path` is the relative path to the *emsdk* directory, from your project folder. (In the above case, we would expect Emscripten to be located in the same parent-directory as the project.)
### **Templates**
These scripts make the module's functionality accessible. Be aware that `npm run wasm-init` **will create several files and folders inside your project directory.** This is your fastest route to a working project setup, however, you can also set up all the files manually, if you so desire.
### **Custom**
The best way to a custom setup is to start with just the wasm.config.js file (you can generate it with `npm run wasm-init minimal`), and enter the emcc_path, inputfiles, outputfile, and flags according to your needs. When you run `npm run wasm-init build`, it will generate those files for you.
To compile, simply use `npm run compile`, which will take your C++ code and output a JavaScript file with Emscripten bindings, as well as the sought after .wasm file. To take advantage of wasm-init's easy loading mechanism for WebAssembly modules, you will need the wrapper file loadWASM.js. The wasm module is from there returned by a promise. Making the module accessible to your application is as easy as the following:
```javascript
let m = {}
loadWASM().then(wasmModule => {
m = wasmModule;
m._myFunc(); // this is the call to the C++ function myFunc();
});
```
When you want to export individual functions from C++ to WASM, you can do this with the *exported_functions* property in wasm.config.js:
```javascript
...
exported_functions: [
'_myFunc',
]
...
```
It is required to **prepend the C++ function names with an underscore!**,
If you are on board with wasm-init's automation, the quickest road to success would be:
`npm run wasm-init emcc_path=./../emsdk` (modify path accordingly). This will set Emscripten's file path in the wasm.config.js file automatically. This will also install and compile all necessary files, including a server.js, index.js and index.html file, that are already setup to include WASM in the browser.
(**Executing `npm run wasm-init` will overwrite any files that may already be there, as does `npm run wasm-init build`!** ).
If you now run your browser (either manually or with gulp), and go to localhost:3000, open up the console, and you should see the message from the C++ file printed.
### **Flags**
The following flags for `npm run wasm-init` are usable:
`build` - builds files according to instructions in wasm.config.js
`minimal` - only creates the wasm.config.js file
`no-wrapper` - no wrapper (loadWASM.js) file
`no-cpp` - no C++ file
`no-indexjs` - no index.js file
`no-html` - no html file
`no-server` - no server.js file
If you want built-in hot-reloading functionality, via gulp and browser-sync, just add the flag
`hot` .
Note, that this will install the gulp and browser-sync packages automatically. This will also generate a gulpfile.js file, which is already setup to work with the template code.
Lastly,
`npm run wasm-init clean`
will **delete the autogenerated files**, except wasm.config.js .
`npm run wasm-init clean-all`
will **delete all autogenerated files**. Please use it carefully!
**Collaborators**: [Deep Pulusani](https://github.com/sdeep27), [Shahrod Khalkhali](https://github.com/shahrodkh), [Matthias Wagner](https://github.com/matzewagner)