docs

Author: JoeOsborn

system/include/emscripten/wasmfs.h

@@ -48,6 +48,32 @@ typedef backend_t (*backend_constructor_t)(void*);
 
 backend_t wasmfs_create_memory_backend(void);
 
+// Fetch backend
+//
+// Creates a new fetchfs backend.  FetchFS will backstop filesystem
+// reads to HTTP fetch requests, which will download just specific
+// ranges of the requested files.  FetchFS works best when your web
+// server supports HTTP range requests, and it's important that those
+// files are not stored encrypted or compressed at rest.  FetchFS by
+// default will dispatch HTTP requests to URLs beginning with base_url
+// and ending with whatever the file's path is relative to where the
+// fetchfs directory is mounted.
+//
+// You can also provide a `manifest`, which is a mapping from file
+// paths (again, relative to where the fetchfs is mounted) to URLs
+// (relative to base_url).  This is useful if your C program expects
+// files at certain locations, while your web server may have those
+// files at arbitrary different locations.  The manifest can be built
+// using wasmfs_fetch_create_manifest and
+// wasmfs_fetch_add_to_manifest.  When the fetchfs is mounted,
+// directories and files corresponding to the manifest entries will be
+// automatically created.
+// 
+// For example, a manifest like `{'/test.txt':'resources/file.txt'}`
+// mounted at `/dat` (using either wasmfs_mount or
+// wasmfs_create_directory) will let you write `open("/dat/test.txt",
+// O_RDONLY)`.
+//
 // Note: this cannot be called on the browser main thread because it might
 // deadlock while waiting for its dedicated worker thread to be spawned.
 //
@@ -57,15 +83,17 @@ backend_t wasmfs_create_memory_backend(void);
 //
 // TODO: Add an async version of this function that will work on the main
 // thread.
+//
 backend_t wasmfs_create_fetch_backend(const char* base_url __attribute__((nonnull)),
                                       uint32_t chunkSize,
                                       void *manifest);
 
-// Create a FetchFS manifest record that can be populated and passed into
+// Create a FetchFS manifest record that can be populated with
+// wasmfs_fetch_add_to_manifest and passed into
 // wasmfs_fetch_create_backend.
 void *wasmfs_fetch_create_manifest();
 
-// Add a path to URL mapping to the given manifest.
+// Add a path-to-URL mapping to the given manifest.
 void wasmfs_fetch_add_to_manifest(void *manifest __attribute__((nonnull)),
                                   const char *path __attribute__((nonnull)),
                                   const char *url __attribute__((nonnull)));