Most users will not need to use the instructions in this chapter. You should not attempt any of these procedures unless you have passing knowledge of the command line since many of these sections require text commands to be used.

Publishing Bottles

CrossOver supports rolling out Windows applications to many users and on many systems through the use of the Publish Bottle command. A Published Bottle allows all the users of a single system to share a single installation of each Windows application in the bottle.

Start by installing the Windows application you want to share into a new bottle. Then remove any private data from the Windows applications (for example, cached passwords and user names). Finally, go to the Bottle menu > Publish Bottle.

By default, the published bottle will be named published_ExistingBottleName. It's recommended to keep this name so you can reference which initial bottle was used. Enter an administrator account password and CrossOver will publish the bottle.

The published bottle will appear in the left-hand sidebar of CrossOver. Other users on the computer can now log in, launch CrossOver, and have access to the Windows applications in the published bottle.

When a user opens a published bottle, a stub bottle is generated in their home account. These stub bottles store a user's customized changes to the bottle and have symbolic links that direct back to large files and directories in the published bottle. The stub bottle is named the same as the published bottle it refers to. Other users cannot see changes to a published bottle until it is updated with the Bottle>Update Published Bottle menu item.

Distributing Published Bottles

To distribute a published bottle to another Mac, you can simply copy it to the same location on the new system. The default location to make the bottle available to all users is /Library/Application Support/CrossOver/Bottles. Users on that system only need to run CrossOver once after the bottle has been added, at which point CrossOver will create any icons that are a part of that bottle.

Depending on your needs and network configuration, you may wish to provide some or all of the following customizations before pushing packages out to the target machines.

Distributing ready-made icons

If you can automatically add icons to users' docks, you might want to consider including icons from CrossOver in your distribution package. Copying the icon from one machine to another will still work, as long as the bottle path is the same on both. Once CrossOver is launched via the icon, it will check the icon file and may replace it with a similar system-local icon if necessary.

Note that after publishing a bottle, you will have two sets of icons. One points to your private bottle, and the other to the published bottle. Make sure you distribute the icons that refer to the published bottle.

Providing custom or ready-made Preferences

Sysadmins may want to modify some of CrossOver's default behavior before distribution. This can be done either by running scripted commands in each user account or by preparing a ready-made defaults file. CrossOver's defaults file is located in ~/Library/Preferences/com.codeweavers.CrossOver.plist. Copy that file into the same location in a user's account and CrossOver will have the same preferences when launched. Here are some common settings that can be changed in CrossOver's defaults file.

Change where a user's bottles are located.
The default user bottle directory is ~/Library/Application Support/CrossOver/Bottles. Even when using published bottles this directory is used to store user-local settings. The location of this directory can be changed via the BottleDir preference:

$ defaults write com.codeweavers.CrossOver.plist BottleDir /path/to/user_private/non_networked/bottle/dir

Do not point this location to a directory that contains the published bottles, as user settings will conflict with system settings. It is also not advisable to use a remote or networked volume for the bottle directory as this can lead to significant performance issues.

Change where CrossOver looks for published bottles.
If you want to store the published bottle on an external volume, or one that's shared between multiple systems, you will need to redirect CrossOver to search in a different folder. You can do this by adjusting the ManagedBottleDirs preference.

$ defaults write com.codeweavers.CrossOver.plist ManagedBottleDirs /path/to/shared/non_networked/bottle/dir

Customizing a drive label or serial number

CrossOver will automatically get the serial number and label for real volumes when they're connected, such as CD-ROMs and external hard drives. If your application relies on a specific Windows volume serial number or label, you can easily set it through the Wine Configuration control panel in CrossOver. This example will set a volume label and serial number on the directory /Users/balfour/Music and map it to the D: drive letter.

Select the bottle containing your Windows application and open the Wine Configuration control panel.

Click the Drives tab and then the Add button. Choose the drive letter you want to add.

Select the newly-created drive letter and click Browse.

Pick the directory you want to assign the drive letter.

With the drive letter selected, enter the label and serial number you want to use, and then click Apply and Ok.

To check if the changes were saved, go to the Drives tab in the Wine Configuration control panel, select the drive letter, and the volume & serial will be displayed. You can also set a label and serial by creating a .windows-serial and .windows-label text file in the root of the directory.

$ echo 123456 > /Users/balfour/Music/.windows-serial
$ echo TestLabel > /Users/balfour/Music/.windows-label

Customizing bottles using bottle hooks

CrossOver can run bottle hooks, which allow for automatic customization of bottles. These hooks are created using scripts, making them highly flexible. They can modify aspects such as drive letter assignments, registry settings, and the contents of the C: drive. This customization feature is particularly useful for distributing bottles to multiple machines or customizing them for specific users. To use bottle hooks you will need to create a scripts.d directory in one of the following locations.

User hooks apply only to one specific user's bottles. They are located in ~/Library/Application Support/CrossOver/support/scripts.d

Bottle hooks are stored in an individual bottle and are ideal for configuring published bottles for non-root users. This type of hook is automatically included in the bottle when it is archived, ensuring it will even run when restored on a different computer. These hooks are placed in a scripts.d directory at the top level of a bottle.

Each hook is a shell script that needs to be set executable and placed in one of the above scripts.d directories. Hooks use a naming convention of nn.name, where nn is two decimal digits that dictate the order in which the hooks are run, and name usually indicates the hook's purpose. The name can't contain a dot or tilde. An example hook name would be 10.remap_drive.

In all cases, hooks are called in the Wine context. This means they don't need to use the --bottle option and 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.

The following section lists the different actions that trigger a hook. The template parameter indicates the name of the template the bottle is based on (win98, win2000, winxp, winvista, win7, win8, win10, win11). 64-bit bottles have _64 appended to the template name (win10_64).

When a bottle is created
hook create template

When a bottle is restored
hook restore

When a bottle is upgraded to a new CrossOver version
hook upgrade-from old-bottle-version
old-bottle-version is the CrossOver version the bottle was last used with. This can help you determine how old the bottle is, but note that the hook is executed only after CrossOver upgrades the bottle.

Before and after a stub bottle is created
hook pre-create-stub published-wineprefix
hook create-stub published-wineprefix
When a published bottle is used for the first time in a non-root account this hook is triggered. The $WINEPREFIX variable points to the newly created stub bottle, while published-wineprefix refers to the root's reference copy in /Library/Application Support/CrossOver/Bottles.

Before and after a stub bottle gets updated
hook pre-update-stub published-wineprefix
hook update-stub published-wineprefix

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

Below, you will find some code examples that illustrate how to write bottle hook scripts.

Modify 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

When a bottle is published or updated, remove a registry key from the stub bottle.

#!/bin/sh
if [ "$1" = "create-stub" ] || [ "$1" = "update-stub" ]
then
 $CX_BOTTLE reg delete "HKLM\Software\Test\Config"
fi

When a bottle is published, create a new directory in the stub bottle.

#!/bin/sh
if [ "$1" = "create-stub" ]
then
 # Create a user-specific directory
 mkdir -p "${WINEPREFIX}/drive_c/users/crossover/My Documents/Test Application/Saves"
fi