documentation/registry.sgml

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