Expand Up @@ -14,18 +14,19 @@ Emscripten's API allows for several types of virtual filesystem, depending on th
| Filesystem | Description | Web Browser | Node.js | |------|-----|------|------| | `WORKERFS` | Mount Emscripten filesystem images. | ✅ | ✅[^workerfs] | | `WORKERFS` | Mount Emscripten filesystem images. | ✅ | ✅ | | `NODEFS` | Mount existing host directories. | ❌ | ✅ | | `IDBFS` | Browser-based persistent storage using the [IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). | ✅[^idbfs] | ❌ |
[^workerfs]: Be aware of the current GitHub issue [#328](https://github.com/r-wasm/webr/issues/328). [^idbfs]: Using the `PostMessage` [communication channel](communication.qmd) only.
## Emscripten filesystem images ## Filesystem images
Emscripten filesystem images can be mounted using the `WORKERFS` filesystem type. Filesystem images are pre-prepared files containing a collection of files and associated metadata. The `WORKERFS` filesystem type can be used to efficiently make the contents of a filesystem image available to the WebAssembly R process.
The [`file_packager`](https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool) tool, provided by Emscripten, takes in a directory structure as input and produces webR compatible filesystem images as output. The [`file_packager`](https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool) tool may be invoked from R using the [rwasm](https://r-wasm.github.io/rwasm/) R package: ### Emscripten's `file_packager` tool
The [`file_packager`](https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool) tool, provided by Emscripten, takes in a directory structure as input and produces a webR compatible filesystem image as output. The [`file_packager`](https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool) tool may be invoked from R using the [rwasm](https://r-wasm.github.io/rwasm/) R package:
```{r eval=FALSE} > rwasm::file_packager("./input", out_dir = ".", out_name = "output") Expand All @@ -40,12 +41,25 @@ $ file_packager output.data --preload ./input@/ \
In the above examples, the files in the directory `./input` are packaged and an output filesystem image is created^[When using the `file_packager` CLI, a third file named `output.js` will also be created. If you only plan to mount the image using webR, this file may be discarded.] consisting of a data file, `output.data`, and a metadata file, `output.js.metadata`.
To prepare for mounting the filesystem image with webR, ensure that both files have the same basename (in this example, `output`) and are deployed to static file hosting^[e.g. GitHub Pages, Netlify, AWS S3, etc.]. The resulting URLs for the two files should differ only by the file extension. To prepare for mounting the filesystem image with webR, ensure that both files have the same basename (in this example, `output`). The resulting URLs or relative paths for the two files should differ only by the file extension.
#### Compression
Filesystem image `.data` files may optionally be `gzip` compressed prior to deployment. The file extension for compressed filesystem images should be `.data.gz`, and compression should be indicated by setting the property `gzip: true` on the metadata JSON stored in the `.js.metadata` file.
## Mount a filesystem image from URL ### Process archives with the `rwasm` package
By default, the [`webr::mount()`](api/r.qmd#mount) function downloads and mounts a filesystem image from a URL source, using the `WORKERFS` filesystem type. Archives in `.tar` format, optionally gzip compressed as `.tar.gz` or `.tgz` files, can also be used as filesystem images by pre-processing the `.tar` archive using the [rwasm](https://r-wasm.github.io/rwasm/) R package. The `rwasm::add_tar_index()` function reads the archive contents and appends the required filesystem metadata to the end of the `.tar` archive data in a way that is understood by webR.
```{r eval=FALSE} > rwasm::add_tar_index("./path/to/archive.tar.gz") ```
Once processed by the `rwasm` R package, the archive can be deployed and used directly as a filesystem image.
## Mounting a filesystem image
When running in a web browser, the [`webr::mount()`](api/r.qmd#mount) function downloads and mounts a filesystem image from a URL source, using the `WORKERFS` filesystem type.
```{r eval=FALSE} webr::mount( Expand All @@ -54,17 +68,15 @@ webr::mount( ) ```
A URL for the filesystem image `.data` file should be provided as the source argument, and the image will be mounted in the virtual filesystem under the path given by the `mountpoint` argument. If the `mountpoint` directory does not exist, it will be created prior to mounting.
### Compression Filesystem images should be deployed to static file hosting^[e.g. GitHub Pages, Netlify, AWS S3, etc.] and the resulting URL provided as the source argument. The image will be mounted in the virtual filesystem under the path given by the `mountpoint` argument. If the `mountpoint` directory does not exist, it will be created prior to mounting.
Filesystem image `.data` files may optionally be `gzip` compressed prior to deployment. The file extension for compressed filesystem images should be `.data.gz`, and compression should be indicated by setting the property `gzip: true` on the metadata JSON stored in the `.js.metadata` file. When running under Node.js, the source may also be provided as a relative path to a filesystem image on disk.
### JavaScript API
WebR's JavaScript API includes the [`WebR.FS.mount()`](api/js/classes/WebR.WebR.md#fs) function, a thin wrapper around Emscripten's own [`FS.mount()`](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.mount). The JavaScript API provides more flexibility but requires a little more set up, including creating the `mountpoint` directory if it does not already exist.
The filesystem type should be provided as a `string`, with the `options` argument a JavaScript object of type [`FSMountOptions`](api/js/modules/WebR.md#fsmountoptions). The filesystem image data should be provided as a JavaScript `Blob` and the metadata as a JavaScript object deserialised from the underlying JSON content. The filesystem type should be provided as a `string`, with the `options` argument of type [`FSMountOptions`](api/js/modules/WebR.md#fsmountoptions). The filesystem image data should be provided either as a JavaScript `Blob` object or an `ArrayBuffer`-like object, and the metadata provided as a JavaScript object that has been deserialised from the underlying JSON content.
::: {.panel-tabset} ## JavaScript Expand Down