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