\[ Using - [Building](building.html) - [Notes](notes.html) - [Legal](legal.html) - [GitHub Wiki](https://github.com/haukex/webperl/wiki/Using-WebPerl) \] Using WebPerl ============= **Notice: WebPerl is very much in beta.** Some things may not work yet, and parts of the API may still change. Your feedback is always appreciated! - [Basic Usage](#basic-usage) - [Serving WebPerl](#serving-webperl) - [Including Perl code in your HTML](#including-perl-code-in-your-html) - [The Perl Interpreter and its Environment](#the-perl-interpreter-and-its-environment) - [Memory Management and Anonymous `sub`s](#memory-management-and-anonymous-subs) - [Virtual Filesystem](#virtual-filesystem) - [webperl.js](#webperljs) - The JS `Perl` object - [WebPerl.pm](#webperlpm) - Perl <-> JavaScript mappings - [The Mini IDE](#the-mini-ide) Basic Usage ----------- ### Serving WebPerl You should serve WebPerl via a webserver of your choice, or you can use the included simple `webperl.psgi` for testing. You can run it using [`plackup` from Plack](https://metacpan.org/pod/distribution/Plack/script/plackup) by simply saying `plackup webperl.psgi`. The following four files make up WebPerl: - `webperl.js` - Contains the WebPerl JavaScript API and supporting code. - `emperl.js` - Emscripten-generated supporting JavaScript. - `emperl.wasm` - The `perl` binary and libraries compiled to WebAssembly. - `emperl.data` - The Emscripten virtual file system data (`.pm` files etc.). I strongly recommend you add a MIME type of `application/wasm` for `.wasm` files, otherwise you may see warnings like "wasm streaming compile failed: TypeError: Response has unsupported MIME type" and "falling back to ArrayBuffer instantiation". For example, in an Apache `.htaccess` file, you can say: `AddType application/wasm .wasm` Note that opening the files locally (via `file://`) may not work due to browsers' Same-Origin Policy. However, there are some workarounds: * On Linux, the "wasm streaming compile failed: TypeError: Response has unsupported MIME type / falling back to ArrayBuffer instantiation" warnings can be worked around by adding the line `application/wasm wasm` to `~/.mime.types` or `/etc/mime.types` * In Firefox, if your files reside in different directories, the same-origin policy can be made more lax for `file://` URIs by disabling the [security.fileuri.strict_origin_policy](http://kb.mozillazine.org/Security.fileuri.strict_origin_policy) option. **But be aware** of the security implications of disabling this option! See also the Emscripten deployment notes at , in particular I'd recommended using gzip encoding to serve the WebPerl files. ### Including Perl code in your HTML In your HTML file, add the following (usually inside the `` tags): Then, you can add one or more `` tag which loads a Perl script from the server - but not both! The code from multiple `` tag will cause `webperl.js` to fetch `foo.pl` from the *web server*, not the virtual filesystem! - *However*, that Perl script will *also* only see the virtual filesystem, not the web server, so it won't even be able to see "itself". You can still fetch things from the webserver using e.g. AJAX requests. While a WebPerl instance is running, you can modify files in the virtual file system as you might be used to from regular Perl. But the virtual filesystem is reloaded every time WebPerl is reloaded, so any changes are lost! The exception is the "`IDBFS`" provided by Emscripten, which stores files in an `IndexedDB`, so they typically persist in the browser's storage across sessions. WebPerl mounts an instance of this filesystem at `/mnt/idb`, which you are free to use. If you want your Perl script to write to files there, you **must** also use Emscripten's `FS.syncfs()` interface after writing files, for example: js(q/ FS.syncfs(false, function (err) { if(err) alert("FS sync failed: "+err); else console.log("FS sync ok"); }); /); Remember that users may clear this storage at any time, so it is not really a permanent storage either. If you need to safely store files, it's best to store them on the user's machine (or the web server, if they are different machines) using one of the methods described above. In particular, even though you might make heavy use of `/mnt/idb` when testing with the "mini IDE", remember that this storage is *not* a way to distribute files to your users, and in fact, some users' browsers may automatically regularly clear the `IndexedDB`, or have it disabled altogether. For providing your application to your users, either use `