Skip to content

Adding New Verbs

Jump to bottom Edit New page
kekkoudesu edited this page Jul 10, 2023 · 5 revisions

First Steps

Winetricks verbs are mostly just little shell scripts. (See also LearningAboutShellScripting.)

Try this: open a terminal window, create a small text file called foo.verb, and put the single line

echo Testing, testing, 1 2 3

Then run it by running sh foo.verb in your terminal.

You should see this output:

Testing, testing, 1 2 3

Now try running it with winetricks: winetricks foo.verb

You should see this output:

Testing, testing, 1 2 3 Unknown arg foo Usage: winetricks [options] [verb|path-to-verb] ... ...

Poor Winetricks was a little confused by that simple verb, but you can see that it did run it.

The next section shows a more real, but still simple, winetricks verb.

Hello, Winetricks

Here's a very simple winetricks verb:

w_metadata osmos_example games \ 
    title="Osmos demo example"

load_osmos_example()
{ 
    w_download http://gamedaily.newaol.com/pub/OsmosDemo_Installer_1.5.6.exe 7568f97100a73985a0fd625b63b205f4477578e8 cd "$W_CACHE/$W_PACKAGE"
    $WINE OsmosDemo_Installer_1.5.6.exe
}

All it does is download (using the function w_download) and install the demo for the game Osmos.

Creating a New Verb

The following sections explain how to create a new verb in winetricks.

Verb Metadata

The w_metadata line tells winetricks about the verb. The above example, though, it doesn't tell winetricks all it should. A more complete version would look more like this:

w_metadata osmos_example games \ 
    title="Osmos demo example" \ 
    publisher="Hemisphere Games" \ 
    year="2009" \ media="download" \ 
    file1="OsmosDemo_Installer_1.5.6.exe" \ 
    installed_exe1="$W_PROGRAMS_X86_WIN/OsmosDemo/OsmosDemo.exe"
  • descriptive fields are shown in the user interface and help with sorting.
  • file1 identifies the filename of a downloadable installer, so winetricks can know if it needs to download more. (Or, for a DVD game, file1 is the volume name of the first disc plus ".iso".)
  • installed_exe1 (or installed_file1) is the path to a file the verb installs. This is the Windows Path, not the Unix Path. Winetricks uses it as a shortcut for knowing if a verb has already been run, and skips over the load function if it has. This can be especially helpful for dependency installation into existing prefixes.

See the Supported Metadata section for a full list of labels you can use.

Try to follow the existing standards for naming verbs. Demos, for instance, should end with demo.

Verb Body

The shell function that follows the w_metadata line is the body of the verb, responsible for mounting or downloading the installer, running it, and waiting for it to finish.

It has to be named load_XXXX, where XXXX is the name announced in the call to w_metadata.

See Predefined Functions for a list of all the functions verb bodies can call.

Testing your verb

You can try out the above example by putting it into a file named osmos_example.verb, then running winetricks osmos_example.verb.

(The filename needs to match the name provided to w_metadata, which needs to match the load_XXXX function that makes up the verb body.)

This should install it into the default wineprefix (~/.wine).

Try it now!

Make sure that...

  • winetricks doesn't return until the installer is really done
  • the verb shows up in winetricks XXXX.verb list-cached after you install it. (If it doesn't, you probably got the file1 metadata wrong.)
  • the verb shows up in winetricks XXXX.verb list-installed after you install it. (If it doesn't, you probably got the installed_exe1 metadata wrong.)
  • the game actually runs well without any hacks or workarounds

list-cached and list-installed won't really know about the verb until it is integrated into winetricks itself. (Putting XXXX.verb on the commandline before list-cached and list-installed is too awkward for real use, it's just for testing.)

Applying Workarounds for Wine Bugs

If wine has a bug that keeps your game from running well, but there is an easy workaround, you should automate the workaround. For instance, before wine version 1.3.8, Osmos required the Visual C++ 2005 runtime libraries because of Wine bug 24416. You can automate that workaround when needed with the lines

if w_workaround_wine_bug 24416 "installing C runtime library" 1.3.8, then w_call vcrun2005 fi

The w_workaround_wine_bug test requires a wine bug number; these are the numbers referred to by Wine's bugzilla and Wine's App Database. The next parameter is an optional description of the workaround. Finally, if the bug is fixed in some versions of wine, indicate which ones by giving a range of version numbers, separated by a comma. "1.2," means "fixed in wine-1.2 and later". ",1.3.2" means "worked in all versions before 1.3.3, but broken in 1.3.3 and later". "1.3.1,1.3.4" means "worked for a brief shining moment starting with wine-1.3.1 and ending with wine-1.3.4".

It's a bit of a chore finding the exact bug number, and half the time you have to file a new bug to get that number. But it's worth it, because that helps the Wine developers realize they need to fix the problem, and because later, once the bug is fixed, the verb can be updated to not apply the workaround in fixed versions of wine.

See TamingTroublesomeTitles for some tips on finding workarounds.

Installers that don't wait

If winetricks finishes before the installer is done, that probably means you need to use ahk_do to run an Autohotkey script to wait for the installer to finish. For instance, in the above example, instead of $WINE OsmosDemo_Installer_1.5.6.exe, you could use _w_ahk_do:

w_ahk_do " 
    run OsmosDemo_Installer_1.5.6.exe 
    WinWait, Osmos Demo Setup, Installation Complete 
    WinWaitClose 
"

Installing from DVD

First, make sure you can mount the disc :-) Usually, gnome does this for you automatically. If you're using KDE, you may have to coax its file manager into doing it by clicking on its icon for the disc.

To install a non-steam title from a single DVD, you need to know its volume name. You can get this in several ways:

  • look at KDE or Gnome's file manager or desktop icon for the disc
  • use the command volname /dev/sr0 (doesn't always work)
  • use the command sh winetricks volnameof=/dev/sr0

You use this volume name in two places:

  • in w_metadata, set file1=VOLNAME.iso
  • at top of your load function, call w_mount VOLNAME

Then run the game's installer as usual, except instead of cd'ing to the cache, run it as ${W_ISO_MOUNT_LETTER}:setup.exe.

See the deadspace verb for a good example.

Installing from multiple discs is a bit more complicated, see the diablo2 verb

Installing a Steam title from DVD is experimental; for now, do STEAM_DVD=1 before calling w_steam_install_game.

Unattended Mode

Unattended mode is optional. Most users won't need this. You should skip this the first few times you contribute winetricks verbs.

If you want the verb to be run by the winetricks automated regression test, you'll need to support unattended mode. If you're lucky, this means passing the right commandline options to the installer. See unattended.sourceforge.net for tips on common commandline options to enable unattended (sometimes called silent) mode.

A lot of installers provide the \S command-line option for a silent install. We only want to trigger a silent install when winetricks is invoked with -q or --unattended. For that, we check $W_OPT_UNATTENDED to see if the user wants an unattended install. If it is non-empty, the user has enabled unattended mode.

You can check whether the variable is non-empty by using parameter expansion: ${W_OPT_UNATTENDED:+ /S}. See the Parameter Expansion section in the manpage for bash (1) for more information on this option, or the GNU Project's web documentation.

If you're unlucky, the installer may not provide an unattended install option. If that is the case, you need to use AutoHotkey to click buttons for the user.

Look at some of the existing verbs in winetricks to see how they do it. Osmos uses AutoHotkey to click buttons for the user; office2007pro and penpenxmas use magic commandline options.

Contributing your verb

Once you get a verb working, you can contribute it to Winetricks by sending it to the winetricks-dev mailing list, or by opening a pull request at https://github.com/Winetricks/winetricks/pulls.

Thanks!

Practical Example: OpenTTD

OpenTTD is a small transit simulator that has a nice download page that already has sha1sums. We'll use the win7 installer version in this example.

Step 1: Create a Minimum Working Example

First, start out by creating a file named openttd.verb, which contains a basic verb definition as described above.

w_metadata openttd games 
    title="OpenTDD (inspired by Transit Tycoon Deluxe)" \
    publisher="openttd.org" \
    year="2011" \
    media="download" \
    file1="openttd-1.1.0-windows-win32.exe"

load_openttd()
{ 
    w_download http://binaries.openttd.org/releases/1.1.0/openttd-1.1.0-windows-win32.exe f6c42da8614577e022cb2f4496ff470a89f4c6c7 
    cd "$W_CACHE/openttd" $WINE openttd-1.1.0-windows-win32.exe 
}

Then test it by running winetricks openttd.verb.

Hey, presto, it installs and runs!

Step 2: Define installed_exe1

Now see where the game got installed. The easiest way to do this in a terminal is to install the aliases described in CommandlineTips, then do prefix openttd goc.

That takes you to the top of the virtual C drive for the new game. You can then use bash's tab completion to avoid having to type out Program Files in full, e.g. cd Pro<TAB>/Open<TAB> followed by ls.

And there you see openttd.exe. Now you know where the game's executable lives, and can fill in the installed_exe1 line at the end of the metadata:

w_metadata openttd games \ 
    title="OpenTTD (inspired by Transit Tycoon Deluxe)" \
    publisher="openttd.org" \
    year="2011" \
    media="download" \
    file1="openttd-1.1.0-windows-win32.exe" \
    installed_exe1="$W_PROGRAMS_X86_WIN/OpenTTD/openttd.exe"

Now test to make sure the install check works:

winetricks openttd.verb list-installed

OpenTTD should show up in the list of installed games.

Step 3: Make Unattended Installs (-q) Work

This step is optional, but it helps the winetricks maintainer verify he hasn't broken your verb later.

See Unattended Mode for more explanation.

First, check to see if the game's installer has an unattended (or silent) install option. You can often tell by paging through the non-binary data in the executable. You can do this for OpenTTD by running cd ~/.cache/winetricks/openttd followed by strings openttd-1.1.0-windows-win32.exe | less.

There is a lot of garbage to wade through, but after paging down 14 times, you might see http://nsis.sf.net/NSIS_Error. Aha!

According to http://unattended.sourceforge.net/installers.php, NSIS installers will usually attempt a silent install if you provide the /S (must be uppercase) option. Trying this out interactively with wine openttd-1.1.0-windows-win32.exe /S verifies that it really works, and installs the game without drawing the window.

All we need to do to support silent mode is change our script to use /S when $W_OPT_UNATTENDED is non-empty, e.g. by using the fancy ${W_OPT_UNATTENDED:+ /S} syntax.

The verb body will now look like this:

load_openttd()
{ 
    w_download http://binaries.openttd.org/releases/1.1.0/openttd-1.1.0-windows-win32.exe f6c42da8614577e022cb2f4496ff470a89f4c6c7 
    cd "$W_CACHE/openttd" $WINE openttd-1.1.0-windows-win32.exe ${W_OPT_UNATTENDED:+ /S} 
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally