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