documentation/distributors

   1                 A small WINE distribution guide.
   2
   3 While packaging WINE for one of the Linux distributions I came across
   4 several points which have been clarified yet. Particular a how-to for WINE
   5 packaging distributors is missing. This document tries to give a brief
   6 overview over the rationales I thought up and how I tried to implement it.
   7 (While the examples use "rpm" most of this stuff can be applied to other
   8 packagers too.)
   9
  10 1. Rationales
  11
  12 A WINE install should:
  13 a. Not have a world writeable directory (-tree).
  14 b. Require only as much user input as possible. It would be very good if it
  15    would not require any at all. Just let the system administrator do "rpm
  16    -i wine.rpm" and let any user be able to run "wine sol.exe" instantly.
  17 c. Give the user as much flexibility to install his own applications, do
  18    his own configuring etc.
  19 d. Come as preconfigured as possible, so the user does not need to change
  20    any configuration files.
  21 e. Use only as much diskspace as needed per user.
  22
  23 A WINE install needs:
  24 f. A writeable C:\ directory structure on a per user basis. Applications do
  25    dump .ini files into c:\windows, installers dump .exe, .dll and more into
  26    c:\windows\ and subdirectories or into C:\Program Files\.
  27 g. The .exe and .dll from a global read-only Windows installation to be
  28    found by applications.
  29 h. Some special .dll and .exe files in the windows\system directory, since
  30    applications directly check for their presence.
  31
  32
  33 2. Implementation
  34
  35 2.1 Building the package
  36
  37 WINE is configured the usual way (depending on your buildenvironment).
  38 The "prefix" is chosen using your application placement policy
  39 (/usr/,/usr/X11R6/, /opt/wine/ or similar).  The configuration files
  40 (wine.conf, wineuser.reg, winesystem.reg) are targeted for /etc/wine/
  41 (rationale: FHS 2.0, multiple readonly configuration files of a package).
  42
  43 Example (split this into %build and %install section for rpm):
  44         CFLAGS=$RPM_OPT_FLAGS \
  45         ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
  46         make
  47         make install prefix=$BUILDROOT/usr/X11R6/
  48         install -d /etc/wine/
  49         install -m 644 wine.ini /etc/wine/wine.conf
  50
  51 Here we unfortunately do need to create wineuser.reg and winesystem.reg
  52 from the WINE distributed winedefault.reg. This can be done using
  53 ./regapi once for one example user and the reusing his .wine/user.reg
  54 and .wine/system.reg files. [FIXME: this needs to be done better]
  55
  56         install -m 644 winesytem.reg /etc/wine/
  57         install -m 644 wineuser.reg /etc/wine/
  58
  59 You will need to package the files:
  60         $prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/libwine.so.1.0,
  61         $prefix/man/man1/wine.1, $prefix/include/wine/*,
  62
  63         %config /etc/wine/*
  64         %doc ... choose from the toplevel directory and documentation/
  65
  66 Do not forget ldconfig for the postinstall, the postuninstall and 'rm
  67 libwine.so' for the postuninstall.
  68
  69 2.2 Creating a good default configuration file
  70
  71 For the rationales of needing as less input from the user as possible
  72 arises the need for a very good configuration file. The one supplied
  73 with WINE is currently lacking. We need:
  74
  75 - [Drive X]:
  76   + A for the floppy. Specify your distributions default floppy mountpoint
  77     here. (Path=/auto/floppy)
  78   + C for the C:\ directory. Here we use the users homedirectory, for most
  79     applications do see C:\ as root-writeable directory of every windows
  80     installation and this basically is it in the UNIX-user context.
  81     (Path=${HOME})
  82   + R for the CD-Rom drive. Specify your distributions default CD-ROM drives
  83     mountpoint here. (Path=/auto/cdrom)
  84   + T for temporary storage. We do use /tmp/ (rationale: between process
  85     temporary data belongs to /tmp/, FHS 2.0)
  86   + W for the original Windows installation. This drive points to the
  87     windows\ subdirectory of the original windows installation. This avoids
  88     problems with renamed 'windows' directories (as for instance 'lose95',
  89     'win' or 'sys\win95'). During compile/package/install we leave this
  90     to be '/', it has to be configured after the package install.
  91   + Z for the UNIX Root directory (Path=/). This avoids any problems with
  92     "could not find drive for current directory" users occasionaly complain
  93     about in the newsgroup and the ircchannel. It also makes the whole
  94     directory structure browseable. The type of Z should be network, so
  95     applications expect it to be readonly.
  96
  97 - [wine]:
  98   Windows=c:\windows\           (the windows/ subdirectory in the users
  99                                  homedirectory)
 100   System=c:\windows\system\     (the windows/system subdirectory in the users
 101                                  homedirectory)
 102   Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
 103   ; Using this trick we have in fact two windows installations in one, we
 104   ; get the stuff from the readonly installation and can write to our own.
 105   Temp=t:\                      (the TEMP directory)
 106 - [Tweak.Layout]
 107   WineLook=win95                (just the coolest look ;)
 108 - Possibly modify the [spooler], [serialports] and [parallelports] sections.
 109 (FIXME: possibly more, including printer stuff)
 110
 111 Add this prepared configuration file to the package.
 112
 113 2.3 Installing WINE for the system administrator
 114
 115 Install the package using the usual packager "rpm -i wine.rpm".
 116 You may edit /etc/wine/wine.conf, [Drive W], to point to a possible windows
 117 installation right after the install. Thats it.
 118
 119 2.4 Installing WINE for the user
 120
 121 The user will need to run a setup script before the first invocation of
 122 WINE. This script should:
 123 - Copy /etc/wine/wine.conf for user modification.
 124 - Allow specification of the original windows installation to use (which
 125   modifies the copied wine.conf file).
 126 - Create the windows directory structure (c:\windows,c:\windows\system,
 127   c:\Program Files,c:\Desktop,etc...)
 128
 129   (FIXME: Not sure this is needed for all files:)
 130 - Symlink all .dll and .exe files from the original windows installation to
 131   the windows directory. Why? Some program reference "%windowsdir%/file.dll"
 132   or "%systemdir%/file.dll" directly and fail if there are not present.
 133   This will give a huge number of symlinks, yes. However, if an installer
 134   later overwrites on of those files, it will overwrite the symlink (so
 135   that the file now lies in the windows/ subdirectory).
 136
 137 - On later invocation the script might want to compare regular files in
 138   the users windows directories and in the global windows directories and
 139   replace same files by symlinks (to avoid diskspace problems).
 140
 141 Done.
 142
 143 This procedure requires:
 144 - Much thought and work from the packager (1x)
 145 - No work for the sysadmin. Well except one "rpm -i" and possible one edit
 146   of the configuration file.
 147 - Some or no work from the user, except running the per-user setup script
 148   once.
 149 => It scales well and suffices most of the rationales.
 150
 151                                 Marcus Meissner <marcus@jet.franken.de>
 152
 153 ----------------------------------------------------------------
 154 Sample wine.ini for OpenLinux 2.x:
 155
 156 ;;
 157 ;; MS-DOS drives configuration
 158 ;;
 159 ;; Each section has the following format:
 160 ;; [Drive X]
 161 ;; Path=xxx       (Unix path for drive root)
 162 ;; Type=xxx       (supported types are 'floppy', 'hd', 'cdrom' and 'network')
 163 ;; Label=xxx      (drive label, at most 11 characters)
 164 ;; Serial=xxx     (serial number, 8 characters hexadecimal number)
 165 ;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
 166 ;;   This is the FS Wine is supposed to emulate on a certain
 167 ;;   directory structure.
 168 ;;   Recommended:
 169 ;;   - "win95" for ext2fs, VFAT and FAT32
 170 ;;   - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
 171 ;;   DON'T use "unix" unless you intend to port programs using Winelib !
 172 ;; Device=/dev/xx (only if you want to allow raw device access)
 173 ;;
 174
 175 ;
 176 ;
 177 ; Floppy 'A' and 'B'
 178 ;
 179 ; OpenLinux uses an automounter under /auto/, so we use that too.
 180 ;
 181 [Drive A]
 182 Path=/auto/floppy/
 183 Type=floppy
 184 Label=Floppy
 185 Serial=87654321
 186 Device=/dev/fd0
 187 Filesystem=win95
 188
 189 ;
 190 ; Comment in ONLY if you have a second floppy or the automounter hangs
 191 ; for 5 minutes.
 192 ;
 193 ;[Drive B]
 194 ;Path=/auto/floppy2/
 195 ;Type=floppy
 196 ;Label=Floppy
 197 ;Serial=87654321
 198 ;Device=/dev/fd1
 199 ;Filesystem=win95
 200
 201
 202 ;
 203 ; Drive 'C' links to the users homedirectory.
 204 ;
 205 ; This must point to a writeable directory structure (not your readonly
 206 ; mounted DOS partitions!) since programs want to dump stuff into
 207 ; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
 208 ;
 209 ; The basic structure is set up using the config script.
 210 ;
 211 [Drive C]
 212 Path=${HOME}
 213 Type=hd
 214 Label=MS-DOS
 215 Filesystem=win95
 216
 217 ;
 218 ; /tmp/ directory
 219 ;
 220 ; The temp drive (and directory) points to /tmp/. Windows programs fill it
 221 ; with junk, so it is approbiate.
 222 ;
 223 [Drive T]
 224 Path=/tmp
 225 Type=hd
 226 Label=Tmp Drive
 227 Filesystem=win95
 228
 229 ;
 230 ; 'U'ser homedirectory
 231 ;
 232 ; Just in case you want C:\ elsewhere.
 233 ;
 234 [Drive U]
 235 Path=${HOME}
 236 Type=hd
 237 Label=Home
 238 Filesystem=win95
 239
 240 ;
 241 ; CD-'R'OM drive (automounted)
 242 ;
 243 ; The default cdrom drive.
 244 ;
 245 ; If an application (or game) wants a specific CD-ROM you might have to
 246 ; temporary change the Label to the one of the CD itself.
 247 ;
 248 ; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
 249 ;
 250 [Drive R]
 251 Path=/auto/cdrom
 252 Type=cdrom
 253 Label=CD-Rom
 254 Filesystem=win95
 255
 256 ;
 257 ; The drive where the old windows installation resides (it points to the
 258 ; windows/ subdirectory).
 259 ;
 260 ; The Path is modified by the winesetup script.
 261 ;
 262 [Drive W]
 263 Path=/
 264 Type=network
 265 Label=Windows
 266 Filesystem=win95
 267 ;
 268 ; The UNIX Root directory, so all other programs and directories are reachable.
 269 ;
 270 ; type network is used to tell programs to not write here.
 271 ;
 272 [Drive Z]
 273 Path=/
 274 Type=network
 275 Label=ROOT
 276 Filesystem=win95
 277
 278 ;
 279 ; Standard Windows path entries. WINE will not work if they are incorrect.
 280 ;
 281 [wine]
 282 ;
 283 ; The windows/ directory. It must be writeable, for programs write into it.
 284 ;
 285 Windows=c:\windows
 286 ;
 287 ; The windows/system/ directory. It must be writeable, for especially setup
 288 ; programs install dlls in there.
 289 ;
 290 System=c:\windows\system
 291 ;
 292 ; The temp directory. Should be cleaned regulary, since install programs leave
 293 ; junk without end in there.
 294 ;
 295 Temp=t:\
 296 ;
 297 ; The dll search path. It should contain at least:
 298 ; - the windows and the windows/system directory of the user.
 299 ; - the global windows and windows/system directory (from a possible readonly
 300 ;   windows installation either on msdos filesystems or somewhere in the UNIX
 301 ;   directory tree)
 302 ; - any other windows style directories you want to add.
 303 ;
 304 Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
 305 ;
 306 ; Outdated and no longer used. (but needs to be present).
 307 ;
 308 SymbolTableFile=./wine.sym
 309
 310 # <wineconf>
 311
 312 ;
 313 ; Dll loadorder defaults. No need to modify.
 314 ;
 315 [DllDefaults]
 316 EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
 317 DefaultLoadOrder = native, elfdll, so, builtin
 318
 319 ;
 320 ; What 32/16 dlls belong to each other (context wise). No need to modify.
 321 ;
 322 [DllPairs]
 323 kernel  = kernel32
 324 gdi     = gdi32
 325 user    = user32
 326 commdlg = comdlg32
 327 commctrl= comctl32
 328 ver     = version
 329 shell   = shell32
 330 lzexpand= lz32
 331 mmsystem= winmm
 332 msvideo = msvfw32
 333 winsock = wsock32
 334
 335 ;
 336 ; What type of dll to use in their respective loadorder.
 337 ;
 338 [DllOverrides]
 339 kernel32, gdi32, user32 = builtin
 340 kernel, gdi, user       = builtin
 341 toolhelp                = builtin
 342 comdlg32, commdlg       = elfdll, builtin, native
 343 version, ver            = elfdll, builtin, native
 344 shell32, shell          = builtin, native
 345 lz32, lzexpand          = builtin, native
 346 commctrl, comctl32      = builtin, native
 347 wsock32, winsock        = builtin
 348 advapi32, crtdll, ntdll = builtin, native
 349 mpr, winspool           = builtin, native
 350 ddraw, dinput, dsound   = builtin, native
 351 winmm, mmsystem         = builtin
 352 msvideo, msvfw32        = builtin, native
 353 mcicda.drv, mciseq.drv  = builtin, native
 354 mciwave.drv             = builtin, native
 355 mciavi.drv, mcianim.drv = native, builtin
 356 w32skrnl                = builtin
 357 wnaspi32, wow32         = builtin
 358 system, display, wprocs = builtin
 359 wineps                  = builtin
 360
 361 ;
 362 ; Options section. Does not need to be edited.
 363 ;
 364 [options]
 365 ; allocate how much system colors on startup. No need to modify.
 366 AllocSystemColors=100
 367
 368 ;;
 369 ; Font specification. You usually do not need to edit this section.
 370 ;
 371 ; Read documentation/fonts before adding aliases
 372 ;
 373 [fonts]
 374 ; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
 375 ; or nearest match).
 376 Resolution = 96
 377 ; Default font
 378 Default = -adobe-times-
 379
 380 ;
 381 ; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
 382 ; that try to access serial ports.
 383 ;
 384 [serialports]
 385 Com1=/dev/ttyS0
 386 Com2=/dev/ttyS1
 387 Com3=/dev/modem,38400
 388 Com4=/dev/modem
 389
 390 ;
 391 ; parallel port(s) used by "LPT1" etc. Useful for applications that try to
 392 ; access these ports.
 393 ;
 394 [parallelports]
 395 Lpt1=/dev/lp0
 396
 397 ;
 398 ; What spooling program to use on printing.
 399 ; Use "|program" or "filename", where the output will be dumped into.
 400 ;
 401 [spooler]
 402 LPT1:=|lpr
 403 LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
 404 LPT3:=/dev/lp3
 405
 406 ;
 407 ; Allow port access to WINE started by the root user. Useful for some
 408 ; supported devices, but it can make the system unstable.
 409 ; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
 410 ;
 411 [ports]
 412 ;read=0x779,0x379,0x280-0x2a0
 413 ;write=0x779,0x379,0x280-0x2a0
 414
 415 ; debugging, not need to be modified.
 416 [spy]
 417 Exclude=WM_SIZE;WM_TIMER;
 418
 419 ;
 420 ; What names for the registry datafiles, no need to modify.
 421 ;
 422 [Registry]
 423 ; Paths must be given in /dir/dir/file.reg format.
 424 ; Wine will not understand dos file names here...
 425 ;UserFileName=xxx               ; alternate registry file name (user.reg)
 426 ;LocalMachineFileName=xxx       ; (system.reg)
 427
 428 ;
 429 ; Layout/Look modifications. Here you can switch with a single line between
 430 ; windows 3.1 and windows 95 style.
 431 ; This does not change WINE behaviour or reported versions, just the look!
 432 ;
 433 [Tweak.Layout]
 434 ;; WineLook=xxx  (supported styles are 'Win31'(default), 'Win95', 'Win98')
 435 WineLook=Win95
 436
 437 ;
 438 ; What programs to start on WINE startup. (you should probably leave it empty)
 439 ;
 440 [programs]
 441 Default=
 442 Startup=
 443
 444 ; defunct section.
 445 [Console]
 446 ;XtermProg=nxterm
 447 ;InitialRows=25
 448 ;InitialColumns=80
 449 ;TerminalType=nxterm
 450
 451 # </wineconf>
 452
 453