Customizing bottles using bottle hooks

Customizing bottles using bottle hooks
Prev	Chapter 7. Advanced Manual Configuration Options	Next

Customizing bottles using bottle hooks

Bottle hooks are a mechanism that lets you automatically customize the bottles created by CrossOver. Because it relies on scripts, it is very flexible. For instance it can modify drive letter assignments but also registry settings, the contents of the c: drive, etc. This mechanism is especially useful when you want to customize a bottle which you distribute to a range of machines, or to customize a managed bottle for each specific user.

Bottle hooks can be created at three levels:

System-wide hooks apply to all bottles on the system, including non-root user bottles if CrossOver was installed as root. Thus they are best suited to adapt the bottles to the configuration or hardware of the machine. These hooks are located in the $CX_ROOT/support/scripts.d directory.
User hooks are the same as system-wide hooks but apply only to one specific user's bottles. They are run after all the system-wide hooks have been run. They are located in the ~/.cxgames/scripts.d directory.
Finally, each bottle can have its own set of hooks. These are especially suited to configure a managed bottle for use by each non-root user. This is also the only kind of hook that is automatically packaged with the bottle when it is archived, and are thus guaranteed to run when the bottle is restored later, even if this is on another computer. These hooks are located in the scripts.d directory in the bottle.

Each hook is an executable file, usually a shell script, and must be placed in one of the above hook directories. The name of the hook must be of the form nn.name, where nn are two decimal digits that dictate the order in which the hooks are run, and name must not contain any dot or tilde usually indicates the hook's purpose.

The hooks are then called as described in the following events:

When a bottle is created

hook create template

The template parameter indicates the name of the template the bottle is based on, for instance 'win98'.
When a bottle is restored

hook restore
When a bottle is upgraded to a new CrossOver version

hook upgrade-from old-bottle-version

Where old-bottle-version is the CrossOver version the bottle was last used with. This can help you gauge how out of date the bottle was, but note that the hooks are called only after CrossOver has upgraded the bottle.
When a bottle stub is created

hook create-stub managed-wineprefix

This case happens when a managed bottle is used in a non-root account for the first time. In this case the $WINEPREFIX environment variable points to the freshly created bottle stub, while managed-wineprefix points to root's reference copy in /opt/cxoffice/support.
When a bottle stub is updated

hook update-stub managed-wineprefix

This case happens when the administrator has updated the managed bottle's reference copy in managed-wineprefix and the user's bottle stub must not be updated to match.

In all cases the hooks are called in the Wine context. This means that they can count on the following environment variables being set:

CX_ROOT: Contains the absolute path to the directory where CrossOver is installed.
CX_BOTTLE: Contains the name of the current bottle.
WINEPREFIX: Contains the absolute path to the bottle directory.

Bottle hooks can also use the wine script to call Winelib or Windows applications to modify registry settings or other aspects of the bottle.

Here is an example of a bottle hook that modifies the drive letter assignments so that there is no Y: drive, and the H: drive points to the user's $HOME directory.

#!/bin/sh
rm "$WINEPREFIX/dosdevices/y:"
if [ ! -d "$WINEPREFIX/dosdevices/h:" ]
then
    ln -s -f "$HOME" "$WINEPREFIX/dosdevices/h:"
fi

Prev	Up	Next
Chapter 7. Advanced Manual Configuration Options	Home	Setting the bottle search path