\[ Using -
[Building](building.html) -
[🦋](perl6.html) -
[Notes](notes.html) -
[Legal](legal.html) -
[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!
This page documents the Perl 5 support, for the *experimental*
Perl 6 support, see [here](perl6.html).
- [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
-----------
### Getting WebPerl
If you plan on building WebPerl, for example if you'd like to add more CPAN
modules, then head on over to [Building WebPerl](building.html). Otherwise, if
you'd just like to get started quickly and work with the prebuilt WebPerl
(includes many of the Perl core modules plus a couple extras), then download
[`webperl_prebuilt_v0.09-beta.zip`](https://github.com/haukex/webperl/releases/download/v0.09-beta/webperl_prebuilt_v0.09-beta.zip)
and unpack it. This ZIP file includes the contents of the
[`web`](https://github.com/haukex/webperl/tree/master/web) directory of the
source code, as well as the build products `emperl.*` (currently three files).
If you'd like to work with the source code as checked out from GitHub, then you
can copy these `emperl.*` files into the `web` directory of the source tree.
### 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" (`webperl.js`
may save files such as `/tmp/scripts.pl`, but that's *not* guaranteed).
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.
It also may not work at all in a "sandboxed" `iframe`.
For providing your application to your users, either use `