Introduction

Many people have written front ends for wine that allow managing multiple wine bottles and let users contribute recipes for installing various applications.

It would be nice if the bottles managed by these front ends were interchangeable, so you could create a bottle with one front end, and see it in the list of bottles of another front end (and launch its app from either).

It would also be nice if the user-contributed recipes were interchangeable, e.g. if you could use a recipe written for one front end with other front ends. We could then have a global repository of recipes which would grow much faster than the isolated recipe repository for any individual front end.

And what the heck, it would be nice if menu items for the apps disappeared properly when you delete the bottle. (That probably just requires creating symlinks from ~/.local/applications/foo into ~/.local/share/wine/foo/xdgmenu or something like that; the devil is in the details.)

Directories

• $XDG_DATA_HOME/wine (this defaults to $HOME/.local/share/wine) - directory where all the wineprefixes will live
• Any non-standard metadata for frontend 'myfe' will live in subdirectory myfe of the wineprefix
• These should be compliant with the XDG spec: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

Cleaning up a prefix

It is our hope that acceptable removal of a prefix should be as simple as deleting the prefix -- this means, for instance, that menu items disappear and front ends "know" that the prefix and its associated apps are gone.

TODO: this is a bit tricky implementation. Steps:

• winemenubuilder should make symlinks in ~/.local/applications rather than .desktop files. The .desktop files can then reside in the prefix; when they're deleted, the links should become broken and thus not show
• winemenubuilder (or other tools, eg front ends or computer janitor) can clean out these broken links
• desktop environments need to be double checked that they do the right thing (nothing) when they encounter these links -- these would be normal bugs

Unresolved issues

Software Center would like to be able to list and remove Wine prefixes, but to do this it needs to know "the purpose" of each one. This generally means a specific app, however it's quite possible for a given prefix to have more than one program installed. We'll need some sort of way of indicating this (perhaps new metadata?)

Recipes (verbs)

Recipes (also called verbs) are bourne shell scripts that are sourced by the front end. They may call functions defined by the front end; all such functions are lowercase and start with w_. They may read variables defined by the front end; all such variables are uppercase, and most start with W_. The winetricks environment variable WINE and the standard Wine variable WINEPREFIX are obeyed.

Each recipe consists of metadata followed by a function.

The metadata looks like this:

w_metadata verbname category \
 key=value \
 key=value \
 ...

where legal categories are 'apps' or 'games' at the moment.

e.g.

w_metadata wog games \
   title="World of Goo Demo" \
   publisher="2D Boy" \
   year="2008" \
   media="download" \
   file1="WorldOfGooDemo.1.0.exe"

A simple function looks like this:

load_bioshock_demo() {
    w_download http://us.download.nvidia.com/downloads/nZone/demos/nzd_BioShockPC.zip 7a19186602cec5210e4505b58965e8c04945b3cf
    cd "$W_TEMP"
    w_try unzip -q "$W_CACHE/$W_PACKAGE"/nzd_BioShockPC.zip
    w_try cd "BioShock PC Demo"
    w_try wine setup.exe
}

Supported metadata

For the moment, the list of supported metadata elements is kept short on purpose. More will be added when needed.

• file1 - file to check in cache to see if installer is cached
• media - download or dvd (or not set, if not an installable item)
• publisher - company releasing the app, e.g. "Electronic Arts", "Activision", or "Adobe"
• title - name of app (ideally same as name in wine appdb and gamerankings.com)
• year - year app was released for PC
• wineversion - version of wine known to work (optional), e.g. 1.3.7.

The 'wineversion' metadata should be familiar to PlayOnLinux scripters. Other front ends may choose to ignore this field (e.g. wisotool will ignore it because wisotool is partly aimed at Wine developers, who always want to use the one they just built).

Predefined Variables

Recipes can rely on the following variables being set before they are executed:

• LANG - used when outputting localized messages. If not set, use English.
• WINE - if this isn't set by the user, the framework sets it to which wine
• WINEPREFIX - if this isn't set by the user, the framework sets it to ~/.wine
• W_APPDATA_UNIX - Unix path to user's Application Data folder
• W_APPDATA_WIN - Windows path to user's Application Data folder
• W_CACHE - a Unix path to the directory where downloaded files are cached.
• W_CACHE_WIN - a Windows path version of W_CACHE
• W_DRIVE_C - a Unix path to the C:\ directory
• W_ISO_MOUNT_ROOT - the Unix path to where the install disc is mounted
• W_ISO_MOUNT_LETTER - the drive letter the install disc is mounted on
• W_KEY - the key for this package (set by w_read_key)
• W_OPT_UNATTENDED - if 1, install app without asking any questions
• W_PACKAGE - the code for the currently executing recipe. e.g. this is set to bioshock_demo before calling load_bioshock_demo.
• W_PROGRAMS_DRIVE - drive letter the standard Program Files directory is on
• W_PROGRAMS_UNIX - Unix path to standard Programs Files directory
• W_PROGRAMS_WIN - Windows path to standard Programs Files directory
• W_PROGRAMS_X86_UNIX - Unix path to standard 32 bit Programs Files directory
• W_PROGRAMS_X86_WIN - Windows path to standard 32 bit Programs Files directory
• W_TMP - a Unix path to a directory which exists and is empty when the function starts, and is deleted when the function exits. This is where to unpack .zip files, etc.
• W_TMP_WIN - same as W_TMP, but as a Windows path

Predefined Functions

Recipes may call any of the following shell functions:

• w_ahk_do - execute an Autohotkey script
• w_declare_exe - tell the framework how to run the app
• w_die - abort with an error message
• w_download - takes an appid, a URL and an sha1sum, downloads the given file to the directory $W_CACHE/$appid
• w_download_manual - takes an appid, a URL, a filename, and an sha1sum, and asks the user to download a file from the given page
• w_metadata - called before verb is defined to add it to the list of verbs
• w_mount - takes a volume name; mounts the given volume (either from a disc or an iso)
• w_pathconv - convert between unix and windows paths (fixme: split into two functions)
• w_read_key - prompt the user for a disc key (or read a cached one)
• w_try - executes the following command, possibly with logging, and aborts nicely if the command fails
• w_try_regedit - run regedit, abort on failure
• w_try_winetricks - run winetricks, abort on failure
• w_verify_sha1sum - verify the checksum of a single file, die if mismatch
• w_warn - display nice warning. If GUI mode, waits for user to confirm.
• w_workaround_wine_bug - checks whether given wine bug should be worked around.

Reference Implementation

For a preview version of wisotool that implements the new api, see http://code.google.com/p/winezeug/source/browse/trunk/wisotool2

This currently embeds four recipes inside itself; later the recipes will live in a separate directory, (usually) one file per recipe.