documentation/registry.sgml

   1   <sect1 id="registry">
   2     <title>The Registry</title>
   3
   4     <para>
   5       After Win3.x, the registry became a fundamental part of Windows.
   6       It is the place where both Windows itself, and all
   7       Win95/98/NT/2000/XP/etc.-compliant applications, store
   8       configuration and state data. While most sane system
   9       administrators (and Wine developers) curse badly at the twisted
  10       nature of the Windows registry, it is still necessary for Wine
  11       to support it somehow.
  12     </para>
  13
  14     <sect2>
  15       <title>The default registry</title>
  16
  17       <para>
  18         A Windows registry contains many keys by default, and some of
  19         them are necessary for even installers to operate correctly.
  20         The keys that the Wine developers have found necessary to
  21         install applications are distributed in a file called
  22         <filename>winedefault.reg</filename>. It is automatically
  23         installed for you if you use the
  24         <filename>tools/wineinstall</filename> script in the Wine source,
  25         but if you want to install it manually, you can do so by using the
  26         <command>regedit</command> tool to be found in the
  27         <filename>programs/regedit/</filename>
  28         directory in Wine source.
  29         <filename>winedefault.reg</filename> should even be applied if
  30         you plan to use a native Windows registry, since Wine needs some
  31         specific registry settings in its registry (for special
  32         workarounds for certain programs etc.).
  33         In the main Wine source code directory in a <glossterm>terminal</glossterm>, run:
  34       </para>
  35   <screen>
  36   <prompt>$ </><userinput>cd programs/regedit</>
  37   <prompt>$ </><userinput>./regedit ../../winedefault.reg</>
  38   </screen>
  39     </sect2>
  40
  41     <sect2>
  42       <title>Using a Windows registry</title>
  43
  44       <para>
  45         If you point Wine at an existing Windows installation (by
  46         setting the appropriate directories in
  47         <filename>~/.wine/config</filename>, then Wine is able to load
  48         registry data from it. However, Wine will not save anything to
  49         the real Windows registry, but rather to its own registry
  50         files (see below). Of course, if a particular registry value
  51         exists in both the Windows registry and in the Wine registry,
  52         then Wine will use the latter. In the Wine config file, there
  53         are a number of configuration settings in the [registry] section
  54         (see below) specific to the handling of Windows registry content by Wine.
  55       </para>
  56     </sect2>
  57
  58       <sect2>
  59         <title>The Registry</title>
  60         <para>
  61           The initial default registry content to be used by the Wine
  62           registry files is in the file
  63           <filename>winedefault.reg</filename>. It contains directory
  64           paths, class IDs, and more; it must be installed before most
  65           <filename>INSTALL.EXE</filename> or
  66           <filename>SETUP.EXE</filename> applications will work.
  67         </para>
  68       </sect2>
  69
  70     <sect2>
  71       <title>Registry structure</title>
  72
  73       <para>
  74         The Windows registry is an elaborate tree structure, and not
  75         even most Windows programmers are fully aware of how the
  76         registry is laid out, with its different "hives" and numerous
  77         links between them; a full coverage is out of the scope of
  78         this document. But here are the basic registry keys you might
  79         need to know about for now.
  80       </para>
  81
  82
  83       <variablelist>
  84         <varlistentry>
  85           <term>HKEY_LOCAL_MACHINE</term>
  86           <listitem>
  87             <para>
  88               This fundamental root key (in win9x it's stored in the
  89               hidden file <filename>system.dat</filename>) contains
  90               everything pertaining to the current Windows
  91               installation.
  92             </para>
  93           </listitem>
  94         </varlistentry>
  95         <varlistentry>
  96           <term>HKEY_USERS</term>
  97           <listitem>
  98             <para>
  99               This fundamental root key (in win9x it's stored in the
 100               hidden file <filename>user.dat</filename>) contains
 101               configuration data for every user of the installation.
 102             </para>
 103           </listitem>
 104         </varlistentry>
 105         <varlistentry>
 106           <term>HKEY_CLASSES_ROOT</term>
 107           <listitem>
 108             <para>
 109               This is a link to HKEY_LOCAL_MACHINE\Software\Classes.
 110               It contains data describing things like file
 111               associations, OLE document handlers, and COM classes.
 112             </para>
 113           </listitem>
 114         </varlistentry>
 115         <varlistentry>
 116           <term>HKEY_CURRENT_USER</term>
 117           <listitem>
 118             <para>
 119               This is a link to HKEY_USERS\your_username, i.e., your
 120               personal configuration.
 121             </para>
 122           </listitem>
 123         </varlistentry>
 124       </variablelist>
 125     </sect2>
 126
 127     <sect2>
 128       <title>Wine registry data files</title>
 129
 130       <para>
 131         In the user's home directory, there is a subdirectory named
 132         <filename>.wine</filename>, where Wine will try to save its
 133         registry by default. It saves into four files, which are:
 134       </para>
 135
 136       <variablelist>
 137         <varlistentry>
 138           <term><filename>system.reg</filename></term>
 139           <listitem>
 140             <para>
 141               This file contains HKEY_LOCAL_MACHINE.
 142             </para>
 143           </listitem>
 144         </varlistentry>
 145         <varlistentry>
 146           <term><filename>user.reg</filename></term>
 147           <listitem>
 148             <para>
 149               This file contains HKEY_CURRENT_USER.
 150             </para>
 151           </listitem>
 152         </varlistentry>
 153         <varlistentry>
 154           <term><filename>userdef.reg</filename></term>
 155           <listitem>
 156             <para>
 157               This file contains HKEY_USERS\.Default (i.e. the default
 158               user settings).
 159             </para>
 160           </listitem>
 161         </varlistentry>
 162         <varlistentry>
 163           <term><filename>wine.userreg</filename></term>
 164           <listitem>
 165             <para>
 166               Wine saves HKEY_USERS to this file (both current and
 167               default user), but does not load from it, unless
 168               <filename>userdef.reg</filename> is missing.
 169             </para>
 170           </listitem>
 171         </varlistentry>
 172       </variablelist>
 173       <para>
 174         All of these files are human-readable text files, so unlike
 175         Windows, you can actually use an ordinary text editor on them
 176         if you want (make sure you don't have Wine running when modifying
 177         them, otherwise your changes will be discarded).
 178       </para>
 179       <para>
 180         FIXME: global configuration currently not implemented.
 181
 182         In addition to these files, Wine can also optionally load from
 183         global registry files residing in the same directory as the
 184         global <filename>wine.conf</filename> (i.e.
 185         <filename>/usr/local/etc</filename> if you compiled from
 186         source). These are:
 187       </para>
 188
 189       <variablelist>
 190         <varlistentry>
 191           <term><filename>wine.systemreg</filename></term>
 192           <listitem>
 193             <para>
 194               Contains HKEY_LOCAL_MACHINE.
 195             </para>
 196           </listitem>
 197         </varlistentry>
 198         <varlistentry>
 199           <term><filename>wine.userreg</filename></term>
 200           <listitem>
 201             <para>
 202               Contains HKEY_USERS.
 203             </para>
 204           </listitem>
 205         </varlistentry>
 206       </variablelist>
 207     </sect2>
 208
 209     <sect2>
 210       <title>System administration</title>
 211
 212       <para>
 213         With the above file structure, it is possible for a system
 214         administrator to configure the system so that a system Wine
 215         installation (and applications) can be shared by all the
 216         users, and still let the users all have their own personalized
 217         configuration. An administrator can, after having installed
 218         Wine and any Windows application software he wants the users
 219         to have access to, copy the resulting
 220         <filename>system.reg</filename> and
 221         <filename>wine.userreg</filename> over to the global registry
 222         files (which we assume will reside in
 223         <filename>/usr/local/etc</filename> here), with:
 224       </para>
 225   <screen>
 226   cd ~/.wine
 227   cp system.reg /usr/local/etc/wine.systemreg
 228   cp wine.userreg /usr/local/etc/wine.userreg
 229   </screen>
 230       <para>
 231         and perhaps even symlink these back to the administrator's
 232         account, to make it easier to install apps system-wide later:
 233       </para>
 234   <screen>
 235   ln -sf /usr/local/etc/wine.systemreg system.reg
 236   ln -sf /usr/local/etc/wine.userreg wine.userreg
 237   </screen>
 238       <para>
 239         Note that the <filename>tools/wineinstall</filename> script
 240         already does all of this for you, if you install Wine source as root.
 241         If you then install Windows applications while logged in as
 242         root, all your users will automatically be able to use them.
 243         While the application setup will be taken from the global
 244         registry, the users' personalized configurations will be saved
 245         in their own home directories.
 246       </para>
 247       <para>
 248         But be careful with what you do with the administrator account
 249         - if you do copy or link the administrator's registry to the
 250         global registry, any user might be able to read the
 251         administrator's preferences, which might not be good if
 252         sensitive information (passwords, personal information, etc)
 253         is stored there. Only use the administrator account to install
 254         software, not for daily work; use an ordinary user account for
 255         that.
 256       </para>
 257     </sect2>
 258
 259     <sect2>
 260       <title>The [registry] section</title>
 261
 262       <para>
 263         Now let's look at the <link linkend="config-file">Wine
 264         configuration file</link> options for handling the registry.
 265       </para>
 266
 267       <variablelist>
 268         <varlistentry>
 269           <term>GlobalRegistryDir</term>
 270           <listitem>
 271             <para>
 272               Optional.  Sets the path to look for the Global
 273               Registry.
 274             </para>
 275           </listitem>
 276         </varlistentry>
 277         <varlistentry>
 278           <term>LoadGlobalRegistryFiles</term>
 279           <listitem>
 280             <para>
 281               Controls whether to try to load the global registry
 282               files, if they exist.
 283             </para>
 284           </listitem>
 285         </varlistentry>
 286         <varlistentry>
 287           <term>LoadHomeRegistryFiles</term>
 288           <listitem>
 289             <para>
 290               Controls whether to try to load the user's registry
 291               files (in the <filename>.wine</filename> subdirectory of
 292               the user's home directory).
 293             </para>
 294           </listitem>
 295         </varlistentry>
 296         <varlistentry>
 297           <term>LoadWindowsRegistryFiles</term>
 298           <listitem>
 299             <para>
 300               Controls whether Wine will attempt to load registry data
 301               from a real Windows registry in an existing MS Windows
 302               installation.
 303             </para>
 304           </listitem>
 305         </varlistentry>
 306         <varlistentry>
 307           <term>WritetoHomeRegistryFiles</term>
 308           <listitem>
 309             <para>
 310               Controls whether registry data will be written to the
 311               user's registry files. (Currently, there is no
 312               alternative, so if you turn this off, Wine cannot save
 313               the registry on disk at all; after you exit Wine, your
 314               changes will be lost.)
 315             </para>
 316           </listitem>
 317         </varlistentry>
 318         <varlistentry>
 319           <term>SaveOnlyUpdatedKeys</term>
 320           <listitem>
 321             <para>
 322               Controls whether the entire registry is saved to the
 323               user's registry files, or only subkeys the user have
 324               actually changed. Considering that the user's registry
 325               will override any global registry files and Windows
 326               registry files, it usually makes sense to only save
 327               user-modified subkeys; that way, changes to the rest of
 328               the global or Windows registries will still affect the
 329               user.
 330             </para>
 331           </listitem>
 332         </varlistentry>
 333         <varlistentry>
 334           <term>PeriodicSave</term>
 335           <listitem>
 336             <para>
 337               If this option is set to a nonzero value, it specifies
 338               that you want the registry to be saved to disk at the
 339               given interval. If it is not set, the registry will only
 340               be saved to disk when the wineserver terminates.
 341             </para>
 342           </listitem>
 343         </varlistentry>
 344         <varlistentry>
 345           <term>UseNewFormat</term>
 346           <listitem>
 347             <para>
 348               This option is obsolete. Wine now always uses the new
 349               format; support for the old format was removed a while
 350               ago.
 351             </para>
 352           </listitem>
 353         </varlistentry>
 354       </variablelist>
 355     </sect2>
 356   </sect1>
 357
 358 <!-- Keep this comment at the end of the file
 359 Local variables:
 360 mode: sgml
 361 sgml-parent-document:("configuring.sgml" "chapter" "sect1" "")
 362 End:
 363 -->