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 macOS command-line -- most of these sections require text commands to be issued.
CrossOver supports rolling out Windows applications to a large number of users and on a large number of systems. The basic technique is bottle publication which allows all the users of a single system to share a single installation of each application. Bottle publication is simple -- just create a bottle with the included files and applications that you wish to distribute, remove any private data (for example, cached passwords and user names), and click the Publish button. After publication, all users on that system will have access to the software within the published bottle.
When a user accesses a published bottle, a 'stub bottle' will be created in their home account. Stub bottles contain a user's custom alterations to the bottle, and contain symbolic links that refer to most large files and directories in the published bottle. A stub bottle has the same name as the published bottle to which it refers.
The simplest way to distribute a published bottle to another Mac is to copy it into the same location on the new system (it's typically located in @DOC_SYSBOTTLEDIR@). 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 have a facility to automatically push icons onto users' docks, you may wish to include one or more icons created by CrossOver in your distribution package. An icon will still work if copied from one machine to another, as long as the bottle path is the same on both. As soon as CrossOver is launched via the icon, it will review the icon file and may replace it with an equivalent system-local icon if appropriate.
Note
After publishing a bottle, you will have two sets of icons, one of which refers to your private bottle, and one of which refers to the published bottle. Make sure you distribute the icons that refers to the published bottle.
Providing custom or ready-made preference files
Many sysadmins will want to modify some of CrossOver's default behavior before rolling it out widely. This can be done either by running scripted commands in each user account, or by preparing a ready-made defaults file (Typically
~/Library/Preferences/com.codeweavers.@PRODUCT_ID@.plist) and copying that file into the Preferences directory of each user account.
A few of the most useful default settings are:
Changing where a user's bottles are located
The default user bottle directory is @DOC_USERBOTTLEDIR@. 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.@PRODUCT_ID@ BottleDir /path/to/user_private/non_networked/bottle/dirIt is very important that you not point this setting to a directory that contains the published bottles themselves, as user settings will conflict with the system settings.
Using a networked or remote volume for the bottle directory may result in serious performance problems and is generally a bad idea.
Changing where CrossOver looks for published bottles
If you want to store the published bottles on an external volume, or on one that's shared between multiple systems, you will probably need to redirect CrossOver to look in an alternative directory. This can be accomplished using the ManagedBottleDirs preference:
$ defaults write com.codeweavers.@PRODUCT_ID@ ManagedBottleDirs /path/to/shared/non_networked/bottle/dir<!-- Unclear to me if the following is applicable to both unix and mac... including here in case -->
CrossOver allows you to add new drives to be used by Windows applications, and to change their label or serial number. If you need to create a new drive or have an application which depends on a serial number or Windows volume label then follow the examples below.
For example to make the path /mnt available as the drive <J:> in a bottle, you would execute the following command:
$ ln -s /mnt "@DOC_USERBOTTLEDIR@/bottle-name/dosdevices/j:"To associate this drive to the /dev/sda1 device you would add a double colon to the command.
$ ln -s /dev/sda1 "@DOC_USERBOTTLEDIR@/bottle-name/dosdevices/j::"For 'real' devices, CrossOver should automatically get the serial number and label for a volume. However you can also set these manually. To set the serial number of a given mount point you need to create a file called .windows-serial on the root of the virtual drive.
$ echo '12345678' >/mnt/.windows-serialTo set the label you would create a file called .windows-label on the root of the virtual drive.
$ echo 'MY_LABEL' >/mnt/.windows-labelBottle 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 published 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. Thus they are ideal 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
@DOC_USERCONFDIR@/scripts.d directory.
Finally, each bottle can have its own set of hooks. These are
especially suited to configure a published bottle for use by each
non-root user. This is also the only kind of hook which is
automatically packaged with the bottle when it is archived, and is
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 and 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.
Before and after a bottle stub is created
<hook> pre-create-stub <published-wineprefix>
<hook> create-stub <published-wineprefix>
This case happens when a published 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 <published-wineprefix> points to root's reference copy in
@DOC_SYSBOTTLEDIR@.
Before and after a bottle stub gets updated
<hook> pre-update-stub <published-wineprefix>
<hook> update-stub <published-wineprefix>
This case happens when the administrator has updated the published bottle's reference copy in <published-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 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.
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