-
-
Notifications
You must be signed in to change notification settings - Fork 398
Adding New Verbs
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.
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.
The following sections explain how to create a new verb in winetricks.
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.
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.
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 thefile1
metadata wrong.) - the verb shows up in
winetricks XXXX.verb list-installed
after you install it. (If it doesn't, you probably got theinstalled_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.)
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.
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
"
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
, setfile1=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 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.
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!
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.
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!
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.
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}
}