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

The Publish Bottle command in CrossOver enables easy deployment of Windows applications across multiple users and systems. By creating a Published Bottle, each user on a single system can access a shared installation of each Windows application contained in the bottle. To install CrossOver on multiple stand-alone systems, it is possible to create an RPM or Debian package from a bottle. Additionally, if you use NFS or Samba to share drives on your network, installation can be done via a shared volume.

How to Publish a Bottle

Publishing a bottle will make the Windows application in that bottle accessible to users on the same system. When a user launches CrossOver a stub bottle is created in ~/.cxoffice for all published bottles. The local stub bottle will contain any user customizations and settings.

Begin 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 Main menu>Bottle>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.

Creating an RPM or Debian Package

CrossOver can create an installable package out of a bottle. This service allows you to create a bottle on one system, package it up, and reinstall it on many additional machines. The resulting packages must be installed with a corresponding CrossOver program package.

To create an installable package, select a bottle, and go to Main menu>Bottle>Create Package from Bottle.

In the package dialog window, you can choose between creating a Debian or RPM package. The Release, Packager, and Product ID fields are additional metadata that you can edit or leave as-in.

CrossOver will check for required package-building dependencies and offer to install them automatically.

A terminal will open and show the progress of package creation.

Packaging the bottle is now complete, and can be copied and installed on other systems.

You can also create packages using the command line. The following command will create Debian and RPM packages from a bottle called Notepad++.

 $ ~/cxoffice/bin/cxbottle --bottle Notepad++ --deb --rpm

Although you can create a package out of any bottle (published or private), the bottle will be installed on any new system as though the bottle had been published on that system. Once the bottle package installation is completed, the applications it contains are ready to go. Make sure you have purchased a CrossOver license for each system you're using, and be careful to comply with all of the license terms for each Windows program. CrossOver does not enforce software licensing restrictions.

Installing onto a Shared Volume

CrossOver may be installed on a shared volume and run on multiple systems. Make sure files created by root on the shared volume belong to root using the following commands.

 $ touch /common/software/root-file
 $ ls -l /common/software/root-file
 -rw-r--r-- 1 root root 0 Nov 4 14:07 /common/software/root-file

This should show that root-file belongs to root. Once this works, delete root-file and install CrossOver, specifying the shared drive as the install location.

You can now run applications using the command line. If you would like menus and associations to be available on your users' machines, please run the following commands.

• Create CrossOver's Menus.
  To create the CrossOver menu entries, run this command as root on each system.

$ /common/software/cxoffice/bin/cxmenu --ro-desktopdata --crossover --install

• Associate .exe files to CrossOver.
  Associating the .exe extension with CrossOver lets users launch Windows executables by clicking on them in their file browsers. Run this command as root on each system:

$ /common/software/cxoffice/bin/cxassoc --ro-desktopdata --crossover --install

• Setup .tie File Association.
  To associate the .tie extension with CrossOver so that users can install Windows applications using CrossTie profiles, run this command on each system.

$ /common/software/cxoffice/bin/cxtie --register

• Create menus and associations for Windows applications.
  Lastly, this command will scan a published bottle and create menu items and file associations for the Windows applications it contains. Replace bottle-name with the name of your published bottle. If you have more than one published bottle on your shared drive, repeat the above command for each. Run this command as root on each system.

$ /common/software/cxoffice/bin/cxbottle --ro-desktopdata --bottle bottle-name --install

Side-By-Side Installations

If necessary it's possible to install two or more versions of CrossOver on the same system so they don't interfere with each other. Each installation tags its resources with a Product ID so it knows which desktop menus and associations belong to it. To install a secondary copy of CrossOver using the graphical installer, simply pick a new installation directory. The installer will detect the existing CrossOver installation and choose a new Product ID to avoid interference. When upgrading a side-by-side configuration using the graphical installer, always double-check the installation directory to make sure you are upgrading the CrossOver instance you intended.

It is also possible to set up side-by-side configurations using Debian or RPM packages. To do so you must first repackage CrossOver to change the package name and the product id. Begin by installing the version of CrossOver you want to repackage. Then run the following command line, changing cxnew to the new package name, and 2 to the release number you wish to use. You can use --deb or --rpm to create Debian and RPM packages respectively.

 $ ~/cxoffice/bin/cxrepackage --deb --productid cxnew --release 2

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 /home/balfour/Music and map it to the D: drive letter.

 $ ln -s /home/balfour/Music "/home/balfour/.cxoffice/(bottle-name)/dosdevices/d:"

You would add a double colon to the command to associate the D: drive letter to the /dev/sda1 device.

 $ ln -s /dev/sda1 "/home/balfour/.cxoffice/(bottle-name)/dosdevices/d::"

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 > /home/balfour/Music/.windows-serial
$ echo TestLabel > /home/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.

System-wide hooks apply to all bottles on the system, including non-root user bottles. Thus they are ideal to adapt the bottles to the configuration or hardware of the machine. These hooks are in the /opt/cxoffice/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 run. They are located in the /.cxoffice/scripts.d directory.

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

Setting the Bottle Search Path

One quick way to move bottles to a non-default location and have CrossOver still find them is to first create a bottle in CrossOver, move the bottle to the new location, and then create a symbolic link in the ~/.cxoffice directory which points to the bottle's new location.

You can also control the list of directories where CrossOver looks for bottles by setting the CX_BOTTLE_PATH environment variable. By default, this variable is set to ~/.cxoffice. You can add additional paths to search by editing the file ~/.cxoffice/cxoffice.conf.

 [EnvironmentVariables]
 "CX_BOTTLE_PATH"="/extra/bottles:~/.cxoffice"

CrossOver will first look for bottles in /extra/bottles and then in the standard location. The order is also important as CrossOver will create new bottles in the first writable directory present in the search path. CrossOver will not move existing bottles to the new location. You'll need to either keep the default bottle location in the list, or move your existing bottle folders manually.

You can also change this setting globally by editing /opt/cxoffice/etc/cxoffice.conf. You should make sure each user gets their own bottle directory by using the USER environment variable.

 [EnvironmentVariables]
 "CX_BOTTLE_PATH"="/extra/${USER}/bottles"

Published bottles are stored and searched for in /opt/cxoffice/etc. You can change this location by editing the environment variable CX_MANAGED_BOTTLE_PATH in the file /opt/cxoffice/etc/cxoffice.conf`.

 [EnvironmentVariables]
 "CX_MANAGED_BOTTLE_PATH"="/extra/published_bottles"