Web Build Configuration

Configuration of the web build is done via url parameters or via changing properties in boxedwine-shell.js
The nature of the parameter determines which mode. In fact the url can override existing parameter values where appropriate.


By default any changes to HOME_DIRECTORY directory are discarded upon web browser tab close.
Config.storageMode = STORAGE_MEMORY;

2 other options are available:

  • STORAGE_DROPBOX (requires configuration – see below)


By default uploading/downloading occurs inside the directory /root/home/username/files/.
It is possible to modify this by appending a ?dir=somedir to the url, else change HOME_DIRECTORY
also possible to:

  • specify an alternate root zip file system.
    i.e. root=win32.zip. If not set it is assumed the root fs is boxedwine.zip and built from a directory called root.
  • specify a zip file to appear uncompressed underneath the HOME_DIRECTORY.
    i.e. app=chomp.zip would appear as /root/home/username/chomp/. Use: zip -r9qdgds 10m chomp.zip ./chomp/*
  • change the program to execute via ?p=/home/username/chomp/CHOMP.EXE. surround in quotes if path includes spaces.
  • set the working directory via ?work=chomp. This simplifies p as it can then be relative to the working directory.
  • set an overlay via ?overlay=more.zip;files.zip. Where each zip file contains additional files to add to the root file system. Existing files are overridden.
  • use c:/ as shorthand for /home/username/.wine/c_drive/

Some simplifications are possible:
boxedwine.html?p=notepad – run notepad in the root fs
boxedwine.html?root=win32&app=chomp&work=chomp&p=CHOMP.EXE – no need to add .zip for root and app zip file name
boxedwine.html?app=chomp&p=CHOMP.EXE – if p does not start with a ‘/‘ and app is set, then the working directory is set to dir + app, i.e. /home/username/files/chomp

Useful scratchpad
Drag and drop is supported. Set AUTO_RUN to false. Simply drag a directory into the page. A dialog will appear and list entries for all executable files found.
Getting files into/out of the emulator is provided behind the SHOW_UPLOAD_DOWNLOAD flag in the shell file. Jszip is used to download a directory as an archive.

Other configuration options:
AUTO_RUN – indicates if start button is shown or page auto-runs. default true
ALLOW_PARAM_OVERRIDE_FROM_URL – indicates if url can be appended with params as above for dir, app and p.
ZLIB – boxedwine internally supports zip file systems, however recent builds of emscripten are not compatible. Therefore support for zipped file system is now provided by browserfs and ZLIB is no longer used in the emscripten build.

Advanced settings:

Remote serving of DLL files (&remote=true)
As the DLL files utilised will depend on what is executed, it makes sense to only provide the minimal number of DLL files and augment with files from the network as required.

To use:
create a directory with minimal required DLLs (same directory structure as main zip file). Reference this via &overlay=dll-min.zip
create a directory /dlls with the additional DLLs from root/lib/wine
call the build script with extra parameter ‘remote’ ie buildjsfs_sdl2.sh remote
This will additionally build dlls.json that should be copied along with the dlls directory to your webserver.

adding the remote param also ensures that the original dlls in lib/wine are not zipped into the main zip file.

Notes on file system modes:

DROPBOX – OAuth dance provided via dropbox.js library [https://github.com/dropbox/dropbox-js] and oauth_receiver.html.
Because of this boxedwine must be served from a web server when using this option (make sure you copy and comment back in dropbox.min.js script that is found in the source tree).
Also must set DROPBOX_APP_KEY and RECEIVE_URL (absolute path) inside the shell file.
Remember to also set the receive_url in your dropbox app console.

LOCAL_STORAGE – There are limits depending on browser and OS.
MEMORY – likely to be slower then using the buildjs_*.sh version. More noticeable for larger file system images.

other dials/tweaks for emscripten build files.
see var Module inside the html file.

Misc notes:

You can avoid using url params and hardcode the values straight into the shell file. Search for MANUAL: in shell file.