- fix wrong hexadecimal GetLastError() output
[wine] / documentation / packaging.sgml
1 <!-- Wine Packaging guidelines.  This is a rough outline only, 
2      and much of this was up for open debate on wine-devel.  -->
3   
4     <chapter id="pkg-preface"> <title>Preface</title>
5
6         <sect1 id="pkg-authors"> <title>Authors</title>
7
8         <para>
9           Written by &name-marcus-meissner; <email>&email-marcus-meissner;</email>
10           Updated by &name-jeremy-white; <email>&email-jeremy-white;</email>
11           Updated by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
12         </para>
13     </sect1>
14
15     <sect1 id="pkg-date"> <title>Document Revision Date</title>
16
17
18       <para>
19       The information contained in this document is extremely
20       time sensitive.  <emphasis>It is vital that a packager
21       stay current with changes in Wine. </>
22       Changes to this document could be tracked e.g. by viewing its CVS log.
23       Due to Wine's fast development, a recent revision date
24       does not necessarily indicate that this document is 100% on par
25       with what Wine's full installation requirements are
26       (especially whenever lazy developers don't properly update the
27       documentation to include info about new features they implemented).
28       </para>
29       <para>
30       This document was last revised on November 14, 2001.</para>
31
32       </sect1>
33
34     <sect1 id="pkg-terms"> <title>Terms used in this document</title>
35
36         <para>There are several terms and paths used in this
37         document as place holders for configurable values.
38         Those terms are described here.
39         </para>
40
41         <orderedlist>
42             <listitem id=WINECONFDIR><para id=wineconfdir.id><EnVar>WINECONFDIR</EnVar></para>
43                 <para>
44                 <envar>WINECONFDIR</envar> is the user's Wine configuration directory.
45                 This is almost always ~/.wine, but can be overridden
46                 by the user by setting the <EnVar>WINECONFDIR</EnVar> environment
47                 variable.
48                 </para>
49             </listitem>
50
51             <listitem id=PREFIX><para id=prefix.id><EnVar>PREFIX</EnVar></para>
52                 <para>
53                 <envar>PREFIX</envar> is the prefix used when selecting
54                 an installation target.  The current default is /usr.
55                 This results in binary installation into /usr/bin,
56                 library installation into /usr/wine/lib, and so forth.
57                 This value can be overridden by the packager.
58                 In fact, <ulink url="http://www.pathname.com/fhs/">FHS 2.1</ulink>
59                 specifications suggest that a better
60                 prefix is /opt/wine.  Ideally, a packager would also
61                 allow the installer to override this value.
62                 </para>
63             </listitem>
64
65             <listitem id=ETCDIR><para id=etcdir.id><EnVar>ETCDIR</EnVar></para>
66                 <para>
67                 <envar>ETCDIR</envar> is the prefix that Wine uses
68                 to find the global configuration directory.
69                 This can be changed by the configure option sysconfdir.
70                 The current default is /etc.
71                 </para>
72             </listitem>
73
74             <listitem id=WINDOWSDIR><para id=windowsdir.id><EnVar>WINDOWSDIR</EnVar></para>
75                 <para>
76                 <envar>WINDOWSDIR</envar> is an important concept
77                 to Wine.  This directory specifies what directory
78                 corresponds to the root Windows directory
79                 (e.g. C:\WINDOWS).
80                 </para>
81                 <para>
82                 This directory is specified by the user, in
83                 the user's <link linkend=winerc>configuration file</link>.
84                 </para>
85                 <para>
86                 Generally speaking, this directory is either set
87                 to point at an empty directory, or it is set
88                 to point at a Windows partition that has been
89                 mounted through the vfat driver.
90                 </para>
91                 <para>
92                 <emphasis>It is extremely important that the packager
93                 understand the importance of <envar>WINDOWSDIR</envar>
94                 and convey this information and choice to the end
95                 user</emphasis>.
96                 </para>
97             </listitem>
98
99         </orderedlist>
100
101
102     </sect1>
103
104   </chapter>
105
106
107
108     <chapter id="pkg-introduction"> <title>Introduction</title>
109
110     <para>
111         This document attempts to establish guidelines
112         for people making binary packages of Wine.
113     </para>
114
115     <para>
116         It expresses the basic principles that the
117         Wine developers have agreed should be
118         used when building Wine.  
119         It also attempts to highlight the areas
120         where there are different approaches
121         to packaging Wine, so that the packager
122         can understand the different alternatives
123         that have been considered and their rationales.
124     </para>
125
126         <sect1 id="pkg-goals"> <title>Goals</title>
127         <para>
128             An installation from a Wine package should:
129         </para>
130           <itemizedlist>
131
132             <listitem>
133                 <para>
134                 Install quickly and simply.
135                 </para>
136                 <para>
137                 The initial installation should require no user
138                 input.  An rpm -i wine.rpm or apt-get install wine
139                 should suffice for initial installation.
140                 </para>
141             </listitem>
142
143             <listitem>
144                 <para>
145                 Work quickly and simply
146                 </para>
147                 <para>
148                 The user should be able to launch Solitaire
149                 within minutes of downloading the Wine package.
150                 </para>
151             </listitem>
152
153             <listitem>
154               <para>
155               Comply with Filesystem Hierarchy Standard 
156               </para>
157               <para>
158               A Wine installation should, as much as possible, comply
159               with the 
160                 <ulink url="http://www.pathname.com/fhs/">FHS standard</ulink>.
161               </para>
162             </listitem>
163
164             <listitem>
165                 <para>
166                 Preserve flexibility
167                 </para>
168                 <para>
169                 None of the flexibility built into Wine should
170                 be hidden from the end user. 
171                 </para>
172             </listitem>
173
174             <listitem>
175               <para>
176                 Come as preconfigured as possible, so the user does
177                 not need to change any configuration files.
178               </para>
179             </listitem>
180
181             <listitem>
182               <para>Use only as much diskspace as needed per user.</para>
183             </listitem>
184
185             <listitem>
186               <para>
187               Reduce support requirements.
188               </para>
189               <para>
190               A packaged version of Wine should be sufficiently easy
191               to use and have quick and easy access to FAQs and
192               documentation such that requests to the
193               newsgroup and development group go down.
194               Further, it should be easy for users to capture
195               good bug reports.
196               </para>
197             </listitem>
198
199           </itemizedlist>
200
201
202         </sect1>
203
204         <sect1 id="pkg-requirements"> <title>Requirements</title>
205       <para>
206         Successfully installing Wine requires:
207       </para>
208
209         <itemizedlist>
210         <listitem>
211           <para>Much thought and work from the packager (1x)</para>
212         </listitem>
213         <listitem>
214           <para>
215           A configuration file
216           </para>
217           <para>
218           Wine will not run without a configuration file.  Further,
219           no default is currently provided by Wine.  Some packagers may attempt
220           to provide (or dynamically generate) a default configuration
221           file.  Some packagers may wish to
222           rely on winesetup to generate the configuration file.
223           </para>
224         </listitem>
225
226
227             <listitem>
228               <para>
229                 A writeable <filename>C:\</filename> directory
230                 structure on a per-user basis. Applications do dump
231                 <filename>.ini</filename> files into
232                 <filename>c:\windows</filename>, installers dump
233                 <filename>.exe</filename>, <filename>.dll</filename>
234                 and more into <filename>c:\windows</filename> and
235                 subdirectories or into <filename>C:\Program Files</filename>.
236               </para>
237             </listitem>
238
239
240             <listitem>
241               <para>
242                 An initial set of registry entries.
243               </para>
244                 <para>
245                 The current Wine standard is to use the regapi tool
246                 against the 'winedefault.reg' file to generate
247                 a default registry.
248                 </para>
249                 <para>
250                 There are several other choices that could be made;
251                 registries can be imported from a Windows partition.
252                 At this time, Wine does not completely support
253                 a complex multi-user installation ala Windows NT,
254                 but it could fairly readily.
255                 </para>
256             </listitem>
257
258
259             <listitem>
260               <para>
261                 Some special <filename>.dll</filename> and
262                 <filename>.exe</filename> files in the
263                 <filename>windows\system</filename> directory, since
264                 applications directly check for their presence.
265               </para>
266             </listitem>
267           </itemizedlist>
268
269         </sect1>
270
271
272     </chapter>
273
274
275
276
277     <chapter id="pkg-components"><title>Wine Components</title>
278
279     <para>
280         This section lists all files that pertain to Wine.
281     </para>
282
283         <sect1 id="pkg-static"><title>Wine Static and Shareable Files</title>
284
285         <para>
286         At the time of this writing, almost all of the following components
287         are installed through a standard 'make install'
288         of Wine. Exceptions from the rule are noted.
289
290         <caution>
291         <para>
292         It is vital that a packager check for
293         changes in Wine.  This list will likely be out
294         of date by the time this document is committed to CVS.
295         </para>
296         </caution>
297
298         </para>
299
300         <orderedlist>
301
302             <listitem id=binfiles>
303                 <variablelist><title>Executable Files</title>
304
305                   <varlistentry><term><filename>wine</filename></term>
306                     <listitem>
307                     <para>
308                     The main Wine executable.  This program will load
309                     a Windows binary and run it, relying upon
310                     the Wine shared object libraries.
311                     </para>
312                     </listitem>
313                   </varlistentry>
314
315                   <varlistentry><term><filename>wineserver</filename></term>
316                     <listitem>
317                     <para>
318                     The Wine server is critical to Wine; it is the
319                     process that coordinates all shared Windows
320                     resources.
321                     </para>
322                     </listitem>
323                   </varlistentry>
324
325                   <varlistentry><term><filename>winebootup</filename></term>
326                     <listitem>
327                     <para>
328                     Winelib app to be found in programs/.
329                     It'll be called by the winelauncher wine wrapper startup
330                     script for every first-time wine invocation.
331                     Its purpose is to process all Windows startup autorun
332                     mechanisms, such as wininit.ini, win.ini Load=/Run=,
333                     registry keys: RenameFiles/Run/RunOnce*/RunServices*,
334                     Startup folders.
335                     </para>
336                     </listitem>
337                   </varlistentry>
338
339                   <varlistentry><term><filename>wineclipsrv</filename></term>
340                     <listitem>
341                     <para>
342                     The Wine Clipboard Server is a standalone XLib
343                     application whose purpose is to manage the X selection
344                     when Wine exits.
345                     </para>
346                     </listitem>
347                   </varlistentry>
348
349                   <varlistentry><term><filename>winedbg</filename></term>
350                     <listitem>
351                     <para>
352                     Winedbg is the Wine built in debugger.
353                     </para>
354                     </listitem>
355                   </varlistentry>
356
357                   <varlistentry><term><filename>winelauncher</filename></term>
358                     <listitem>
359                     <para>
360                     (not getting installed via make install)
361                     A wine wrapper shell script that intelligently handles
362                     wine invocation by informing the user about what's going
363                     on, among other things.
364                     To be found in tools/ directory.
365                     Use of this wrapper script instead of directly using wine
366                     is strongly encouraged, as it not only improves the user
367                     interface, but also adds important functionality to wine,
368                     such as session bootup/startup actions.
369                     If you intend to use this script, then you might want to
370                     rename the wine executable to e.g. wine.bin and
371                     winelauncher to wine.
372                     the <link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config file.
373                     </para>
374                     </listitem>
375                   </varlistentry>
376
377                   <varlistentry><term><filename>winesetup</filename></term>
378                     <listitem>
379                     <para>
380                     This is a Tcl/Tk based front end that provides
381                     a user friendly tool to edit and configure
382                     the <link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config file.
383                     </para>
384                     </listitem>
385                   </varlistentry>
386
387                   <varlistentry><term><filename>wineshelllink</filename></term>
388                     <listitem>
389                     <para>
390                     This shell script can be called by Wine in order
391                     to propagate Desktop icon and menu creation
392                     requests out to a GNOME or KDE (or other
393                     Window Managers).
394                     </para>
395                     </listitem>
396                   </varlistentry>
397
398                   <varlistentry><term><filename>winebuild</filename></term>
399                     <listitem>
400                     <para>
401                     Winebuild is a tool used for Winelib applications
402                     (and by Wine itself) to allow a developer to
403                     compile a .spec file into a .spec.c file.
404                     </para>
405                     </listitem>
406                   </varlistentry>
407                   <varlistentry><term><filename>wmc</filename></term>
408                     <listitem>
409                     <para>
410                     The wmc tools is the Wine Message Compiler.  It
411                     allows Windows message files to be compiled
412                     into a format usable by Wine.
413                     </para>
414                     </listitem>
415                   </varlistentry>
416                   <varlistentry><term><filename>wrc</filename></term>
417                     <listitem>
418                     <para>
419                     The wrc tool is the Wine Resource Compiler.
420                     It allows Winelib programmers (and Wine itself)
421                     to compile Windows style resource files
422                     into a form usable by Wine.
423                     </para>
424                     </listitem>
425                   </varlistentry>
426                   <varlistentry><term><filename>fnt2bdf</filename></term>
427                     <listitem>
428                     <para>
429                     The fnt2bdf utility extracts fonts from .fnt or
430                     .dll files and stores them in .bdf format files.
431                     </para>
432                     </listitem>
433                   </varlistentry>
434                   <varlistentry><term><filename>dosmod</filename></term>
435                     <listitem>
436                     <para>
437                     DOS Virtual Machine.
438                     </para>
439                     </listitem>
440                   </varlistentry>
441
442                   <varlistentry><term><filename>uninstaller</filename></term>
443                     <listitem>
444                     <para>
445                     (not getting installed via make install)
446                     A Winelib program to uninstall installed Windows programs.
447                     To be found in the programs/ source directory.
448                     This program can be used to uninstall most Windows programs
449                     (just like the Add/Remove Programs item in Windows)
450                     by taking the registry uninstall strings that get created
451                     by installers such as InstallShield or WISE.
452                     In binary packages, it should probably be renamed
453                     to something like wine-uninstaller for consistency's sake.
454                     </para>
455                     </listitem>
456                   </varlistentry>
457
458                 </variablelist>
459             </listitem>
460
461         <listitem id=libfiles>
462         <para> Shared Object Library Files </para>
463
464         <simplelist columns=5>
465
466 <member>libadvapi32.so.1.0</>
467 <member>libavicap32.so.1.0</>
468 <member>libavifil32.so.1.0</>
469 <member>libcomctl32.so.1.0</>
470 <member>libcomdlg32.so.1.0</>
471 <member>libcrtdll.so.1.0</>
472 <member>libdciman32.so.1.0</>
473 <member>libddraw.so.1.0</>
474 <member>libdevenum.so.1.0</>
475 <member>libdinput.so.1.0</>
476 <member>libdplay.so.1.0</>
477 <member>libdplayx.so.1.0</>
478 <member>libdsound.so.1.0</>
479 <member>libgdi32.so.1.0</>
480 <member>libicmp.so.1.0</>
481 <member>libimagehlp.so.1.0</>
482 <member>libimm32.so.1.0</>
483 <member>libjoystick.drv.so.1.0</>
484 <member>libkernel32.so.1.0</>
485 <member>liblz32.so.1.0</>
486 <member>libmapi.so.1.0</>
487 <member>libmcianim.drv.so.1.0</>
488 <member>libmciavi.drv.so.1.0</>
489 <member>libmcicda.drv.so.1.0</>
490 <member>libmciseq.drv.so.1.0</>
491 <member>libmciwave.drv.so.1.0</>
492 <member>libmidimap.drv.so.1.0</>
493 <member>libmpr.so.1.0</>
494 <member>libmsacm.drv.so.1.0</>
495 <member>libmsacm32.so.1.0</>
496 <member>libmsdmo.so.1.0</>
497 <member>libmsimg32.so.1.0</>
498 <member>libmsnet32.so.1.0</>
499 <member>libmsrle32.so.1.0</>
500 <member>libmsvcrt.so.1.0</>
501 <member>libmsvfw32.so.1.0</>
502 <member>libnetapi32.so.1.0</>
503 <member>libntdll.so.1.0</>
504 <member>libodbc32.so.1.0</>
505 <member>libole32.so.1.0</>
506 <member>liboleaut32.so.1.0</>
507 <member>libolecli32.so.1.0</>
508 <member>liboledlg.so.1.0</>
509 <member>libolepro32.so.1.0</>
510 <member>libolesvr32.so.1.0</>
511 <member>libopengl32.so.1.0</>
512 <member>libpsapi.so.1.0</>
513 <member>libqcap.so.1.0</>
514 <member>libquartz.so.1.0</>
515 <member>librasapi32.so.1.0</>
516 <member>libriched32.so.1.0</>
517 <member>librpcrt4.so.1.0</>
518 <member>libserialui.so.1.0</>
519 <member>libsetupapi.so.1.0</>
520 <member>libshdocvw.so.1.0</>
521 <member>libshell32.so.1.0</>
522 <member>libshfolder.so.1.0</>
523 <member>libshlwapi.so.1.0</>
524 <member>libsti.so.1.0</>
525 <member>libtapi32.so.1.0</>
526 <member>libttydrv.so.1.0</>
527 <member>liburl.so.1.0</>
528 <member>liburlmon.so.1.0</>
529 <member>libuser32.so.1.0</>
530 <member>libversion.so.1.0</>
531 <member>libw32skrnl.so.1.0</>
532 <member>libwine.so.1.0</>
533 <member>libwine_unicode.so.1.0</>
534 <member>libwinedos.so.1.0</>
535 <member>libwineoss.drv.so.1.0</>
536 <member>libwineps.so.1.0</>
537 <member>libwininet.so.1.0</>
538 <member>libwinmm.so.1.0</>
539 <member>libwinnls32.so.1.0</>
540 <member>libwinspool.drv.so.1.0</>
541 <member>libwintrust.so.1.0</>
542 <member>libwnaspi32.so.1.0</>
543 <member>libwow32.so.1.0</>
544 <member>libws2_32.so.1.0</>
545 <member>libwsock32.so.1.0</>
546 <member>libx11drv.so.1.0</>
547         </simplelist>
548
549         </listitem>
550
551
552             <listitem id=manfiles>
553             <para> Man Pages</para>
554                 <simplelist columns=1>
555 <member>wine.man</>
556 <member>wine.conf.man</>
557 <member>wmc.man</>
558 <member>wrc.man</>
559         </simplelist>
560
561         </listitem>
562
563
564             <listitem id=includefiles>
565             <para> Include Files</para>
566                 <simplelist columns=5>
567
568 <member>basetsd.h</>
569 <member>cderr.h</>
570 <member>cguid.h</>
571 <member>commctrl.h</>
572 <member>commdlg.h</>
573 <member>compobj.h</>
574 <member>d3d.h</>
575 <member>d3dcaps.h</>
576 <member>d3dtypes.h</>
577 <member>d3dvec.inl</>
578 <member>dde.h</>
579 <member>ddeml.h</>
580 <member>ddraw.h</>
581 <member>digitalv.h</>
582 <member>dinput.h</>
583 <member>dispdib.h</>
584 <member>dlgs.h</>
585 <member>docobj.h</>
586 <member>dplay.h</>
587 <member>dplobby.h</>
588 <member>dsound.h</>
589 <member>guiddef.h</>
590 <member>imagehlp.h</>
591 <member>imm.h</>
592 <member>initguid.h</>
593 <member>instance.h</>
594 <member>lmcons.h</>
595 <member>lzexpand.h</>
596 <member>mapidefs.h</>
597 <member>mcx.h</>
598 <member>mmreg.h</>
599 <member>mmsystem.h</>
600 <member>msacm.h</>
601 <member>ntsecapi.h</>
602 <member>oaidl.h</>
603 <member>objbase.h</>
604 <member>objidl.h</>
605 <member>ocidl.h</>
606 <member>ole2.h</>
607 <member>ole2ver.h</>
608 <member>oleauto.h</>
609 <member>olectl.h</>
610 <member>oledlg.h</>
611 <member>oleidl.h</>
612 <member>poppack.h</>
613 <member>prsht.h</>
614 <member>psapi.h</>
615 <member>pshpack1.h</>
616 <member>pshpack2.h</>
617 <member>pshpack4.h</>
618 <member>pshpack8.h</>
619 <member>ras.h</>
620 <member>regstr.h</>
621 <member>richedit.h</>
622 <member>rpc.h</>
623 <member>servprov.h</>
624 <member>shellapi.h</>
625 <member>shlguid.h</>
626 <member>shlobj.h</>
627 <member>shlwapi.h</>
628 <member>sql.h</>
629 <member>sqlext.h</>
630 <member>sqltypes.h</>
631 <member>storage.h</>
632 <member>tapi.h</>
633 <member>tlhelp32.h</>
634 <member>unknwn.h</>
635 <member>urlmon.h</>
636 <member>ver.h</>
637 <member>vfw.h</>
638 <member>winbase.h</>
639 <member>wincon.h</>
640 <member>wincrypt.h</>
641 <member>windef.h</>
642 <member>windows.h</>
643 <member>windowsx.h</>
644 <member>wine/exception.h</>
645 <member>wine/icmpapi.h</>
646 <member>wine/ipexport.h</>
647 <member>wine/obj_base.h</>
648 <member>wine/obj_cache.h</>
649 <member>wine/obj_channel.h</>
650 <member>wine/obj_clientserver.h</>
651 <member>wine/obj_commdlgbrowser.h</>
652 <member>wine/obj_connection.h</>
653 <member>wine/obj_contextmenu.h</>
654 <member>wine/obj_control.h</>
655 <member>wine/obj_dataobject.h</>
656 <member>wine/obj_dockingwindowframe.h</>
657 <member>wine/obj_dragdrop.h</>
658 <member>wine/obj_enumidlist.h</>
659 <member>wine/obj_errorinfo.h</>
660 <member>wine/obj_extracticon.h</>
661 <member>wine/obj_inplace.h</>
662 <member>wine/obj_marshal.h</>
663 <member>wine/obj_misc.h</>
664 <member>wine/obj_moniker.h</>
665 <member>wine/obj_oleaut.h</>
666 <member>wine/obj_olefont.h</>
667 <member>wine/obj_oleobj.h</>
668 <member>wine/obj_oleundo.h</>
669 <member>wine/obj_oleview.h</>
670 <member>wine/obj_picture.h</>
671 <member>wine/obj_property.h</>
672 <member>wine/obj_propertystorage.h</>
673 <member>wine/obj_queryassociations.h</>
674 <member>wine/obj_shellbrowser.h</>
675 <member>wine/obj_shellextinit.h</>
676 <member>wine/obj_shellfolder.h</>
677 <member>wine/obj_shelllink.h</>
678 <member>wine/obj_shellview.h</>
679 <member>wine/obj_storage.h</>
680 <member>wine/unicode.h</>
681 <member>winerror.h</>
682 <member>wingdi.h</>
683 <member>wininet.h</>
684 <member>winioctl.h</>
685 <member>winnetwk.h</>
686 <member>winnls.h</>
687 <member>winnt.h</>
688 <member>winreg.h</>
689 <member>winresrc.h</>
690 <member>winsock.h</>
691 <member>winsock2.h</>
692 <member>winspool.h</>
693 <member>winsvc.h</>
694 <member>winuser.h</>
695 <member>winver.h</>
696 <member>wnaspi32.h</>
697 <member>wownt32.h</>
698 <member>wtypes.h</>
699 <member>zmouse.h</>
700         </simplelist>
701
702         </listitem>
703
704         <listitem id=docfiles>
705         <para>
706         Documentation files.
707         </para>
708         <para>
709         At the time of this writing, I do not have a
710         definitive list of documentation files to 
711         be installed.  However, they do include 
712         the HTML files generated from the SGML in the Wine CVS tree.
713         </para>
714         </listitem>
715
716
717         </orderedlist>
718
719         </sect1>
720
721
722         <sect1 id="pkg-nonstatic"><title>Dynamic Wine Files</title>
723
724         <para>
725         Wine also generates and depends on a number of dynamic
726         files, including user configuration files and registry files.
727         </para>
728
729         <para>
730         At the time of this writing, there was not a clear
731         consensus of where these files should be located, and how
732         they should be handled.  This section attempts
733         to explain the alternatives clearly.
734         </para>
735
736         <orderedlist>
737
738             <listitem>
739                 <variablelist><title>Configuration File</title>
740                   <varlistentry id=winerc><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/config</filename></term>
741                     <listitem>
742                     <para>
743                     This file is the user local Wine configuration file.
744                     At the time of this writing, if this file exists,
745                     then no other configuration file is loaded.
746                     </para>
747                     </listitem>
748                   </varlistentry>
749
750                   <varlistentry><term>
751                     <filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.conf</filename></term>
752                     <listitem>
753                     <para>
754                     This is the global Wine configuration file.  It
755                     is only used if the user running Wine has
756                     no local configuration file.
757                     </para>
758                     <para>
759                     Some packagers feel that this file should not
760                     be supplied, and that only a wine.conf.default
761                     should be given here.
762                     </para>
763                     <para>
764                     Other packagers feel that this file should
765                     be the predominant file used, and that
766                     users should only shift to a local configuration
767                     file if they need to.  An argument has been
768                     made that the local configuration file
769                     should inherit the global configuration file.
770                     At this time, Wine does not do this;
771                     please refer to the WineHQ discussion
772                     archives for the debate concerning this.
773                     </para>
774                     <para>
775                     This debate is addressed more completely
776                     below, in <link linkend=pkg-strategy endterm=strategy.id></link>.
777                     </para>
778                     </listitem>
779                   </varlistentry>
780                 </variablelist>
781
782             </listitem>
783
784         <listitem>
785
786                 <para>Registry Files</para>
787
788                 <para>
789                 In order to replicate the Windows registry system,
790                 Wine stores registry entries in a series of files.
791
792                 For an excellent overview of this issue, read
793                 this
794                 <ulink url="http://www.winehq.com/News/2000-25.html#FTR">
795                 Wine Weekly News feature.</ulink>
796
797                 </para>
798
799                 <para>
800                 The bottom line is that, at Wine server startup,
801                 Wine loads all registry entries into memory
802                 to create an in memory image of the registry.
803                 The order of files which Wine uses to load
804                 registry entries is extremely important,
805                 as it affects what registry entries are
806                 actually present.  The order is roughly that
807                 .dat files from a Windows partion are loaded,
808                 then global registry settings from <link linkend=ETCDIR endterm=etcdir.id></link>,
809                 and then finally local registry settings are
810                 loaded from <link linkend=WINECONFDIR endterm=wineconfdir.id></link> 
811                 .  As each set are loaded,
812                 they can override the prior entries.  Thus,
813                 the local registry files take precedence.
814                 </para>
815
816                 <para>
817                 Then, at exit (or at periodic intervals),
818                 Wine will write either all registry entries
819                 (or, with the default setting) changed
820                 registry entries to files in the
821                 <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
822                 </para>
823
824                 <variablelist>
825                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename></term>
826                     <listitem>
827                     <para>
828                     This file contains the user's local copy of 
829                     the HKEY_LOCAL_MACHINE registry hive.  In general
830                     use, it will contain only changes made to the
831                     default registry values.
832                     </para>
833                     </listitem>
834                   </varlistentry>
835
836                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename></term>
837                     <listitem>
838                     <para>
839                     This file contains the user's local copy of 
840                     the HKEY_CURRENT_USER registry hive.  In
841                     general use, it will contain only changes made to the
842                     default registry values.
843                     </para>
844                     </listitem>
845                   </varlistentry>
846
847                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/userdef.reg</filename></term>
848                     <listitem>
849                     <para>
850                     This file contains the user's local copy of 
851                     the HKEY_USERS\.Default registry hive.  In
852                     general use, it will contain only changes made to the
853                     default registry values.
854                     </para>
855                     </listitem>
856                   </varlistentry>
857
858                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wine.userreg</filename></term>
859                     <listitem>
860                     <para>
861                     This file is being deprecated.  It is only read
862                     if there is no user.reg or wine.userreg, and
863                     it supplied the contents of HKEY_USERS.
864                     </para>
865                     </listitem>
866                   </varlistentry>
867
868                   <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.systemreg</filename></term>
869                     <listitem>
870                     <para>
871                     This file contains the global values for
872                     HKEY_LOCAL_MACHINE.  The values in this file
873                     can be overridden by the user's local settings.
874                     </para>
875                     <note>
876                     <para>
877                     The location of this directory is hardcoded within
878                     wine, generally to /etc.  This will hopefully be
879                     fixed at some point in the future.
880                     </para>
881                     </note>
882                     </listitem>
883                   </varlistentry>
884
885
886                   <varlistentry><term><filename><link linkend=ETCDIR endterm=etcdir.id></link>/wine.userreg</filename></term>
887                     <listitem>
888                     <para>
889                     This file contains the global values for
890                     HKEY_USERS.  The values in this file
891                     can be overridden by the user's local settings.
892                     This file is likely to be deprecated in
893                     favor of a global wine.userdef.reg that will
894                     only contain HKEY_USERS/.Default.
895                     </para>
896                     </listitem>
897                   </varlistentry>
898
899                 </variablelist>
900
901
902         </listitem>
903
904         <listitem>
905                 <variablelist><title>Other files in <link linkend=WINECONFDIR endterm=wineconfdir.id></link></title>
906                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/wineserver-[hostname]</filename></term>
907                     <listitem>
908                     <para>
909                     This directory contains files used by Wine and the Wineserver
910                     to communicate.  A packager may want to have a facility
911                     for the user to erase files in this directory,
912                     as a crash in the wineserver resulting in a bogus lock
913                     file can render wine unusable.
914                     </para>
915                     </listitem>
916                   </varlistentry>
917
918                   <varlistentry><term><filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/cachedmetrics.[display]</filename></term>
919                     <listitem>
920                     <para>
921                     This file contains font metrics for the given X display.
922                     Generally, this cache is generated once at Wine start time.
923                     </para>
924                     </listitem>
925                   </varlistentry>
926
927                 </variablelist>
928         </listitem>
929
930
931         </orderedlist>
932
933
934         </sect1>
935
936         <sect1 id="pkg-winpartition"><title>Important Files from a Windows Partition</title>
937         <para>
938         Wine has the ability to use files from an installation of the
939         actual Microsoft Windows operating system.  Generally these
940         files are loaded on a VFAT partition that is mounted
941         under Linux.
942         </para>
943         <para>
944         This is probably the most important configuration detail.
945         The use of Windows registry and DLL files dramatically
946         alters the behaviour of Wine.  If nothing else,
947         pacakager have to make this distinction clear
948         to the end user, so that they can intelligently
949         choose their configuration.
950         </para>
951         
952
953         <orderedlist>
954
955             <listitem>
956                 <variablelist><title>Registry Files</title>
957                   <varlistentry><term><filename>[WINDOWSDIR]/system32/system.dat</filename></term>
958                     <listitem>
959                     <para>
960                     </para>
961                     </listitem>
962                   </varlistentry>
963
964                   <varlistentry><term><filename>[WINDOWSDIR]/system32/user.dat</filename></term>
965                     <listitem>
966                     <para>
967                     </para>
968                     </listitem>
969                   </varlistentry>
970
971                   <varlistentry><term><filename>[WINDOWSDIR]/win.ini</filename></term>
972                     <listitem>
973                     <para>
974                     </para>
975                     </listitem>
976                   </varlistentry>
977
978                 </variablelist>
979
980             </listitem>
981
982             <listitem>
983                 <para> 
984                 Windows Dynamic Link Libraries ([WINDOWSDIR]/system32/*.dll)
985                 </para>
986                 <para> 
987                 Wine has the ability to use the actual Windows DLL files
988                 when running an application.  An end user can configure
989                 Wine so that Wine uses some or all of these DLL files
990                 when running a given application.
991                 </para>
992             </listitem>
993
994         </orderedlist>
995
996         </sect1>
997
998     </chapter>
999
1000     <chapter id="pkg-strategy"><title id=strategy.id>Packaging Strategies</title>
1001
1002         <para>
1003         There has recently been a lot of discussion on the Wine
1004         development mailing list about the best way to 
1005         build Wine packages.
1006         </para>
1007         <para>
1008         There was a lot of discussion, and several diverging
1009         points of view.  This section of the document
1010         attempts to present the areas of common agreement,
1011         and also to present the different approaches
1012         advocated on the mailing list.
1013         </para>
1014
1015         <sect1 id="pkg-whatfiles"><title>Distribution of Wine into packages</title>
1016         <para>
1017         The most basic question to ask is given the Wine CVS tree,
1018         what physical files are you, the packager, going to produce?
1019         Are you going to produce only a wine.rpm (as Marcus has done),
1020         or are you going to produce 6 Debian files
1021         (libwine, libwine-dev, wine, wine-doc, wine-utils and winesetuptk) as
1022         Ove has done?
1023         </para>
1024         <para>
1025         At this point, there is no consensus
1026         amongst the wine-devel community on this subject. 
1027         </para>
1028         </sect1>
1029
1030         <sect1 id="pkg-wherefiles"><title>Where to install files</title>
1031         <para>
1032         This question is not really contested.  It will vary
1033         by distribution, and is really up to the packager.
1034         As a guideline, the current 'make install' process
1035         seems to behave such that
1036         if we pick a single <link linkend=PREFIX endterm=prefix.id></link>,
1037         then :
1038         </para>
1039         <orderedlist>
1040         
1041             <listitem>
1042             <para>
1043             all <link linkend=binfiles>binary files</link> go into
1044             <link linkend=PREFIX endterm=prefix.id></link>/bin,
1045             </para>
1046             </listitem>
1047
1048             <listitem>
1049             <para>
1050             all <link linkend=libfiles>library files</link> go into
1051             <link linkend=PREFIX endterm=prefix.id></link>/lib,
1052             </para>
1053             </listitem>
1054
1055             <listitem>
1056             <para>
1057             all <link linkend=includefiles>include files</link> go into
1058             <link linkend=PREFIX endterm=prefix.id></link>/include,
1059             </para>
1060             </listitem>
1061
1062             <listitem>
1063             <para>
1064             all <link linkend=docfiles>documentation files</link> go into
1065             <link linkend=PREFIX endterm=prefix.id></link>/doc/wine,
1066             </para>
1067             </listitem>
1068
1069             <listitem>
1070             <para>
1071             and <link linkend=manfiles>man pages</link> go into
1072             <link linkend=PREFIX endterm=prefix.id></link>/man,
1073             </para>
1074             </listitem>
1075
1076         </orderedlist>
1077
1078         <para>
1079         Refer to the specific information on the Debian package
1080         and the OpenLinux package for specific details on how
1081         those packages are built.
1082         </para>
1083         <para>
1084         You might also want to use the wine wrapper script winelauncher
1085         that can be found in tools/ directory, as it has several important
1086         advantages over directly invoking the wine binary.
1087         See the <link linkend=binfiles>Executable Files</link> section
1088         for details.
1089
1090         <sect2 id=opt><title>The question of /opt/wine</title>
1091         <para>
1092         The FHS 2.1 specification suggests that Wine as a package
1093         should be installed to /opt/wine.  None of the
1094         existing packages follow this guideline (today;
1095         check again tomorrow).
1096         </para>
1097         </sect2>
1098         
1099         </sect1>
1100
1101         <sect1 id="pkg-whattomake"><title>What files to create</title>
1102         <para>
1103         After installing the static and shareable files, the next
1104         question the packager needs to ask is how much dynamic
1105         configuration will be done, and what configuration
1106         files should be created.
1107         </para>
1108         <para>
1109         There are several approaches to this:
1110         <orderedlist>
1111             <listitem>
1112                 <para>
1113                 Rely completely on user file space - install nothing
1114                 </para>
1115                 <para>
1116                 This approach relies upon the new winesetup utility and
1117                 the new ability of Wine to launch winesetup if no configuration file is found.
1118                 The basic concept is that no global configuration files
1119                 are created at install time.
1120                 Instead, Wine configuration files are created on the
1121                 fly by the winesetup program when Wine is invoked.
1122                 Further, winesetup creates default Windows directories
1123                 and paths that are stored completely in
1124                 the user's <link linkend=WINECONFDIR endterm=wineconfdir.id></link>.
1125                 </para>
1126                 <para>
1127                 This approach has the benefit of simplicity in that all
1128                 Wine files are either stored under /opt/wine or under
1129                 ~/.wine.  Further, there is only ever one Wine 
1130                 configuration file.
1131                 </para>
1132                 <para>
1133                 This approach, however, adds another level of complexity.
1134                 It does not allow Wine to run Solitaire 'out of the box';
1135                 the user must run the configuration program first.  Further,
1136                 winesetup requires Tcl/Tk, a requirement not beloved by some.
1137                 Additionally, this approach closes the door on multi
1138                 user configurations and presumes a single user approach.
1139                 </para>
1140             </listitem>
1141
1142
1143             <listitem>
1144                 <para>
1145                 Build a reasonable set of defaults for the global wine.conf,
1146                 facilitate creation of a user's local Wine configuration.
1147                 </para>
1148                 <para>
1149                 This approach, best shown by Marcus, causes the
1150                 installation process to auto scan the system,
1151                 and generate a global wine.conf file with best
1152                 guess defaults.  The OpenLinux packages follow
1153                 this behaviour.
1154                 </para>
1155                 <para>
1156                 The keys to this approach are always putting
1157                 an existing Windows partition into the
1158                 path, and being able to run Solitaire
1159                 right out of the box.
1160                 Another good thing that Marcus does is he
1161                 detects a first time installation and
1162                 does some clever things to improve the
1163                 user's Wine experience.
1164                 </para>
1165                 <para>
1166                 A flaw with this approach, however, is it doesn't
1167                 give the user an obvious way to choose not to
1168                 use a Windows partition.  
1169                 </para>
1170             </listitem>
1171
1172             <listitem>
1173                 <para>
1174                 Build a reasonable set of defaults for the global wine.conf,
1175                 and ask the user if possible
1176                 </para>
1177                 <para>
1178                 This approach, demonstrated by Ove, causes the
1179                 installation process to auto scan the system,
1180                 and generate a global wine.conf file with best
1181                 guess defaults.  Because Ove built a Debian
1182                 package, he was able to further query debconf and
1183                 get permission to ask the user some questions,
1184                 allowing the user to decide whether or not to
1185                 use a Windows partition.
1186                 </para>
1187             </listitem>
1188
1189
1190             </orderedlist>
1191         </para>
1192
1193         </sect1>
1194
1195
1196         <sect1 id="pkg-wineconf"><title>What to put into the wine config file</title>
1197         <para>
1198         The next hard question is what the Wine config should look like.
1199         The current best practices seems to involve using drives from M to Z.
1200         </para>
1201         <caution><para>This isn't done yet!  Fix it, Jer!</para></caution>
1202         </sect1>
1203
1204
1205     </chapter>
1206
1207
1208
1209
1210     <chapter id="pkg-implementation"> <title>Implementation</title>
1211
1212     <sect1 id="pkg-openlinux"><title>OpenLinux Sample</title>
1213
1214           <orderedlist inheritnum="inherit">
1215             <listitem>
1216               <para>Building the package</para>
1217               <para>
1218                 WINE is configured the usual way (depending on your
1219                 build environment). The "prefix" is chosen using your
1220                 application placement policy
1221                 (<filename>/usr/</filename>,
1222                 <filename>/usr/X11R6/</filename>,
1223                 <filename>/opt/wine/</filename> or similar).  The
1224                 configuration files (<filename>wine.conf</filename>,
1225                 <filename>wine.userreg</filename>,
1226                 <filename>wine.systemreg</filename>) are targeted for
1227                 <filename>/etc/wine/</filename> (rationale: FHS 2.0,
1228                 multiple readonly configuration files of a package).
1229               </para>
1230               <para>
1231                 Example (split this into <literal>%build</literal> and
1232                 <literal>%install</literal> section for
1233                 <command>rpm</command>):
1234               </para>
1235               <screen>
1236 CFLAGS=$RPM_OPT_FLAGS \
1237 ./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
1238 make
1239 BR=$RPM_BUILD_ROOT
1240 make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
1241 install -d $BR/etc/wine/
1242 install -m 644 wine.ini $BR/etc/wine/wine.conf
1243
1244 # Put all our dlls in a seperate directory. (this works only if
1245 # you have a buildroot)
1246 install -d $BR/usr/X11R6/lib/wine
1247 mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
1248
1249 # the clipboard server is started on demand.
1250 install -m 755 windows/x11drv/wineclipsrv $BR/usr/X11R6/bin/
1251
1252 # The WINE server is needed.
1253 install -m 755 server/wineserver $BR/usr/X11R6/bin/
1254               </screen>
1255               <para>
1256                 Here we unfortunately do need to create
1257                 <filename>wineuser.reg</filename> and
1258                 <filename>winesystem.reg</filename> from the WINE
1259                 distributed <filename>winedefault.reg</filename>. This
1260                 can be done using <command>./regapi</command> once for
1261                 one example user and then reusing his
1262                 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/user.reg</filename> and
1263                 <filename><link linkend=WINECONFDIR endterm=wineconfdir.id></link>/system.reg</filename> files.
1264                 <note>
1265                   <title>FIXME</title>
1266                   <para>this needs to be done better</para>
1267                 </note>
1268               </para>
1269               <screen>
1270 install -m 644 wine.sytemreg $BR/etc/wine/
1271 install -m 644 wine.userreg $BR/etc/wine/
1272               </screen>
1273               <para>
1274                 There are now a lot of libraries generated by the
1275                 build process, so a seperate library directory should
1276                 be used.
1277               </para>
1278               <screen>
1279 install -d 755 $BR/usr/X11R6/lib/
1280 mv $BR/
1281               </screen>
1282               <para>
1283                 You will need to package the files:
1284               </para>
1285               <screen>
1286 $prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
1287 $prefix/man/man1/wine.1, $prefix/include/wine/*,
1288 $prefix/bin/wineserver, $prefix/bin/wineclipsrv
1289
1290 %config /etc/wine/*
1291 %doc ... choose from the toplevel directory and documentation/
1292               </screen>
1293               <para>
1294                 The post-install script:
1295               </para>
1296               <screen>
1297 if ! grep -q /usr/X11R6/lib/wine /etc/ld.so.conf; then
1298     echo "/usr/X11R6/lib/wine" &gt;&gt; /etc/ld.so.conf
1299 fi
1300 /sbin/ldconfig
1301               </screen>
1302               <para>
1303                 The post-uninstall script:
1304               </para>
1305               <screen>
1306 if [ "$1" = 0 ]; then
1307     perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
1308 fi
1309 /sbin/ldconfig
1310               </screen>
1311             </listitem>
1312             <listitem>
1313               <para>Creating a good default configuration file</para>
1314               <para>
1315                 For the rationales of needing as less input from the
1316                 user as possible arises the need for a very good
1317                 configuration file. The one supplied with WINE is
1318                 currently lacking. We need:
1319               </para>
1320               <itemizedlist>
1321                 <listitem>
1322                   <para>
1323                     [Drive X]:
1324                   </para>
1325                   <itemizedlist>
1326                     <listitem>
1327                       <para>
1328                         A for the floppy. Specify your distribution's
1329                         default floppy mountpoint here.
1330                       </para>
1331                       <programlisting>
1332 Path=/auto/floppy
1333                       </programlisting>
1334                     </listitem>
1335                     <listitem>
1336                       <para>
1337                         C for the <filename>C:\</filename> directory.
1338                         Here we use the user's home directory, for most
1339                         applications do see <filename>C:\</filename>
1340                         as root-writeable directory of every windows
1341                         installation and this basically is it in the
1342                         UNIX-user context.
1343                         </para>
1344                       <programlisting>
1345 Path=${HOME}
1346                       </programlisting>
1347                     </listitem>
1348                     <listitem>
1349                       <para>
1350                         R for the CD-Rom drive. Specify your
1351                         distribution's default CD-ROM drives mountpoint
1352                         here.
1353                         </para>
1354                       <programlisting>
1355 Path=/auto/cdrom
1356                       </programlisting>
1357                     </listitem>
1358                     <listitem>
1359                       <para>
1360                         T for temporary storage. We do use
1361                         <filename>/tmp/</filename> (rationale: between
1362                         process temporary data belongs to
1363                         <filename>/tmp/</filename>, FHS 2.0)
1364                       </para>
1365                     </listitem>
1366                     <listitem>
1367                       <para>
1368                         W for the original Windows installation. This
1369                         drive points to the
1370                         <filename>windows\</filename> subdirectory of
1371                         the original windows installation. This avoids
1372                         problems with renamed
1373                         <filename>windows</filename> directories (as
1374                         for instance <filename>lose95</filename>,
1375                         <filename>win</filename> or
1376                         <filename>sys\win95</filename>). During
1377                         compile/package/install we leave this to be
1378                         <filename>/</filename>, it has to be
1379                         configured after the package install.
1380                       </para>
1381                     </listitem>
1382                     <listitem>
1383                       <para>
1384                         Z for the UNIX Root directory. This avoids any
1385                         problems with "could not find drive for
1386                         current directory" users occasionally complain
1387                         about in the newsgroup and the irc channel. It
1388                         also makes the whole directory structure
1389                         browseable. The type of Z should be network,
1390                         so applications expect it to be readonly.
1391                       </para>
1392                       <programlisting>
1393 Path=/
1394                       </programlisting>
1395                     </listitem>
1396                   </itemizedlist>
1397                 </listitem>
1398                 <listitem>
1399                   <para>
1400                     [wine]:
1401                   </para>
1402                   <screen>
1403   Windows=c:\windows\           (the windows/ subdirectory in the user's
1404                                  home directory)
1405   System=c:\windows\system\     (the windows/system subdirectory in the user's
1406                                  home directory)
1407   Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
1408   ; Using this trick we have in fact two windows installations in one, we
1409   ; get the stuff from the readonly installation and can write to our own.
1410   Temp=t:\                      (the TEMP directory)
1411                   </screen>
1412                 </listitem>
1413                 <listitem>
1414                   <para>[Tweak.Layout]</para>
1415                   <screen>
1416   WineLook=win95                (just the coolest look ;)
1417                   </screen>
1418                 </listitem>
1419                 <listitem>
1420                   <para>
1421                     Possibly modify the [spooler], [serialports] and
1422                     [parallelports] sections.
1423                   </para>
1424                   <note>
1425                     <title>FIXME</title>
1426                     <para>possibly more, including printer stuff.</para>
1427                   </note>
1428                 </listitem>
1429               </itemizedlist>
1430
1431               <para>Add this prepared configuration file to the package.</para>
1432             </listitem>
1433             <listitem>
1434               <para>Installing WINE for the system administrator</para>
1435               <para>
1436                 Install the package using the usual packager
1437                 <command>rpm -i wine.rpm</command>. You may edit
1438                 <filename>/etc/wine/wine.conf</filename>, [Drive W],
1439                 to point to a possible windows installation right
1440                 after the install. That's it.
1441               </para>
1442               <para>
1443                 Note that on Linux you should somehow try to add the
1444                 <option>unhide</option> mount option (see <command>man
1445                   mount</command>) to the CD-ROM entry in
1446                 <filename>/etc/fstab</filename> during package
1447                 install, as several stupid Windows programs mark some
1448                 setup (!) files as hidden (ISO9660) on CD-ROMs, which
1449                 will greatly confuse users as they won't find their
1450                 setup files on the CD-ROMs as they were used on
1451                 Windows systems when <option>unhide</option> is not
1452                 set ;-\ And of course the setup program will complain
1453                 that <filename>setup.ins</filename> or some other mess
1454                 is missing... If you choose to do so, then please make
1455                 this change verbose to the admin.
1456                 Also make sure that the kernel you use includes the Joliet
1457                 CD-ROM support, for the very same reasons as given above
1458                 (no long filenames due to missing Joliet, files not found).
1459               </para>
1460             </listitem>
1461             <listitem>
1462               <para>Installing WINE for the user</para>
1463               <para>
1464                 The user will need to run a setup script before the
1465                 first invocation of WINE. This script should:
1466               </para>
1467
1468
1469               <itemizedlist>
1470                 <listitem>
1471                   <para>
1472                     Copy <filename>/etc/wine/wine.conf</filename> for
1473                     user modification.
1474                   </para>
1475                 </listitem>
1476                 <listitem>
1477                   <para>
1478                     Allow specification of the original windows
1479                     installation to use (which modifies the copied
1480                     <filename>wine.conf</filename> file).
1481                   </para>
1482                 </listitem>
1483                 <listitem>
1484                   <para>
1485                     Create the windows directory structure
1486                     (<filename>c:\windows</filename>,
1487                     <filename>c:\windows\system</filename>,
1488                     <filename>c:\windows\Start Menu\Programs</filename>,
1489                     <filename>c:\Program Files</filename>,
1490                     <filename>c:\Desktop</filename>, etc.)
1491                   </para>
1492                 </listitem>
1493                 <listitem>
1494                   <para>
1495                     Symlink all <filename>.dll</filename> and
1496                     <filename>.exe</filename> files from the original
1497                     windows installation to the
1498                     <filename>windows</filename> directory. Why? Some
1499                     programs reference "%windowsdir%/file.dll" or
1500                     "%systemdir%/file.dll" directly and fail if they
1501                     are not present.
1502                   </para>
1503                   <para>
1504                     This will give a huge number of symlinks, yes.
1505                     However, if an installer later overwrites one of
1506                     those files, it will overwrite the symlink (so
1507                     that the file now lies in the
1508                     <filename>windows/</filename> subdirectory).
1509                   </para>
1510                   <note>
1511                     <title>FIXME</title>
1512                     <para>Not sure this is needed for all files.</para>
1513                   </note>
1514                 </listitem>
1515                 <listitem>
1516                   <para>
1517                     On later invocation the script might want to
1518                     compare regular files in the user's windows
1519                     directories and in the global windows directories
1520                     and replace same files by symlinks (to avoid
1521                     diskspace problems).
1522                   </para>
1523                 </listitem>
1524               </itemizedlist>
1525
1526
1527             </listitem>
1528           </orderedlist>
1529
1530
1531       <sect2 id=sample><title>Sample <filename>wine.ini</filename> for OpenLinux 2.x (outdated, for review purposes only !):</title>
1532
1533 <programlisting>
1534
1535
1536 ;;
1537 ;; MS-DOS drives configuration
1538 ;;
1539 ;; Each section has the following format:
1540 ;; [Drive X]
1541 ;; Path=xxx       (Unix path for drive root)
1542 ;; Type=xxx       (supported types are 'floppy', 'hd', 'cdrom' and 'network')
1543 ;; Label=xxx      (drive label, at most 11 characters)
1544 ;; Serial=xxx     (serial number, 8 characters hexadecimal number)
1545 ;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
1546 ;;   This is the FS Wine is supposed to emulate on a certain
1547 ;;   directory structure.
1548 ;;   Recommended:
1549 ;;   - "win95" for ext2fs, VFAT and FAT32
1550 ;;   - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
1551 ;;   DON'T use "unix" unless you intend to port programs using Winelib !
1552 ;; Device=/dev/xx (only if you want to allow raw device access)
1553 ;;
1554
1555 ;
1556 ;
1557 ; Floppy 'A' and 'B'
1558 ;
1559 ; OpenLinux uses an automounter under /auto/, so we use that too.
1560 ;
1561 [Drive A]
1562 Path=/auto/floppy/
1563 Type=floppy
1564 Label=Floppy
1565 Serial=87654321
1566 Device=/dev/fd0
1567 Filesystem=win95
1568
1569
1570 ; Comment in ONLY if you have a second floppy or the automounter hangs
1571 ; for 5 minutes.
1572 ;
1573 ;[Drive B]
1574 ;Path=/auto/floppy2/
1575 ;Type=floppy
1576 ;Label=Floppy
1577 ;Serial=87654321
1578 ;Device=/dev/fd1
1579 ;Filesystem=win95
1580
1581
1582 ;
1583 ; Drive 'C' links to the user's homedirectory. 
1584
1585 ; This must point to a writeable directory structure (not your readonly
1586 ; mounted DOS partitions!) since programs want to dump stuff into
1587 ; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
1588
1589 ; The basic structure is set up using the config script.
1590 ;
1591 [Drive C]
1592 Path=${HOME}
1593 Type=hd
1594 Label=MS-DOS
1595 Filesystem=win95
1596
1597 ;
1598 ; /tmp/ directory
1599
1600 ; The temp drive (and directory) points to /tmp/. Windows programs fill it
1601 ; with junk, so it is approbiate.
1602 ;
1603 [Drive T]
1604 Path=/tmp
1605 Type=hd
1606 Label=Tmp Drive
1607 Filesystem=win95
1608
1609 ;
1610 ; 'U'ser homedirectory
1611
1612 ; Just in case you want C:\ elsewhere.
1613
1614 [Drive U]
1615 Path=${HOME}
1616 Type=hd
1617 Label=Home
1618 Filesystem=win95
1619
1620 ;
1621 ; CD-'R'OM drive (automounted)
1622
1623 ; The default cdrom drive.
1624 ;
1625 ; If an application (or game) wants a specific CD-ROM you might have to
1626 ; temporary change the Label to the one of the CD itself.
1627 ;
1628 ; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
1629
1630 [Drive R]
1631 Path=/auto/cdrom
1632 Type=cdrom
1633 Label=CD-Rom
1634 Filesystem=win95
1635
1636 ;
1637 ; The drive where the old windows installation resides (it points to the 
1638 ; windows/ subdirectory).
1639
1640 ; The Path is modified by the winesetup script.
1641 ;
1642 [Drive W]
1643 Path=/
1644 Type=network
1645 Label=Windows
1646 Filesystem=win95
1647 ;
1648 ; The UNIX Root directory, so all other programs and directories are reachable.
1649 ;
1650 ; type network is used to tell programs to not write here. 
1651 ;
1652 [Drive Z]
1653 Path=/
1654 Type=network
1655 Label=ROOT
1656 Filesystem=win95
1657
1658 ;
1659 ; Standard Windows path entries. WINE will not work if they are incorrect.
1660 ;
1661 [wine]
1662
1663 ; The windows/ directory. It must be writeable, for programs write into it.
1664 ;
1665 Windows=c:\windows
1666 ;
1667 ; The windows/system/ directory. It must be writeable, for especially setup
1668 ; programs install dlls in there.
1669 ;
1670 System=c:\windows\system
1671 ;
1672 ; The temp directory. Should be cleaned regulary, since install programs leave
1673 ; junk without end in there.
1674 ;
1675 Temp=t:\
1676 ;
1677 ; The dll search path. It should contain at least:
1678 ; - the windows and the windows/system directory of the user.
1679 ; - the global windows and windows/system directory (from a possible readonly
1680 ;   windows installation either on msdos filesystems or somewhere in the UNIX
1681 ;   directory tree)
1682 ; - any other windows style directories you want to add.
1683 ;
1684 Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
1685 ;
1686 ; Outdated and no longer used. (but needs to be present).
1687 ;
1688 SymbolTableFile=./wine.sym
1689
1690 # &lt;wineconf&gt;
1691
1692
1693 ; Dll loadorder defaults. No need to modify.
1694 ;
1695 [DllDefaults]
1696 EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
1697 DefaultLoadOrder = native, elfdll, so, builtin
1698
1699 ;
1700 ; What 32/16 dlls belong to each other (context wise). No need to modify.
1701 ;
1702 [DllPairs]
1703 kernel  = kernel32
1704 gdi     = gdi32
1705 user    = user32
1706 commdlg = comdlg32
1707 commctrl= comctl32
1708 ver     = version
1709 shell   = shell32
1710 lzexpand= lz32
1711 mmsystem= winmm
1712 msvideo = msvfw32
1713 winsock = wsock32
1714
1715 ;
1716 ; What type of dll to use in their respective loadorder.
1717
1718 [DllOverrides]
1719 kernel32, gdi32, user32 = builtin
1720 kernel, gdi, user       = builtin
1721 toolhelp                = builtin
1722 comdlg32, commdlg       = elfdll, builtin, native
1723 version, ver            = elfdll, builtin, native
1724 shell32, shell          = builtin, native
1725 lz32, lzexpand          = builtin, native
1726 commctrl, comctl32      = builtin, native
1727 wsock32, winsock        = builtin
1728 advapi32, crtdll, ntdll = builtin, native
1729 mpr, winspool           = builtin, native
1730 ddraw, dinput, dsound   = builtin, native
1731 winmm, mmsystem         = builtin
1732 msvideo, msvfw32        = builtin, native
1733 mcicda.drv, mciseq.drv  = builtin, native
1734 mciwave.drv             = builtin, native
1735 mciavi.drv, mcianim.drv = native, builtin
1736 w32skrnl                = builtin
1737 wnaspi32, wow32         = builtin
1738 system, display, wprocs = builtin
1739 wineps                  = builtin
1740
1741 ;
1742 ; Options section. Does not need to be edited.
1743 ;
1744 [options]
1745 ; allocate how much system colors on startup. No need to modify.
1746 AllocSystemColors=100
1747
1748 ;;
1749 ; Font specification. You usually do not need to edit this section.
1750
1751 ; Read documentation/fonts before adding aliases
1752 ;
1753 [fonts]
1754 ; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
1755 ; or nearest match).
1756 Resolution = 96
1757 ; Default font
1758 Default = -adobe-times-
1759
1760 ;
1761 ; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
1762 ; that try to access serial ports.
1763
1764 [serialports]
1765 Com1=/dev/ttyS0
1766 Com2=/dev/ttyS1
1767 Com3=/dev/modem,38400
1768 Com4=/dev/modem
1769
1770 ;
1771 ; parallel port(s) used by "LPT1" etc. Useful for applications that try to 
1772 ; access these ports.
1773 ;
1774 [parallelports]
1775 Lpt1=/dev/lp0
1776
1777 ;
1778 ; What spooling program to use on printing.
1779 ; Use "|program" or "filename", where the output will be dumped into.
1780 ;
1781 [spooler]
1782 LPT1:=|lpr
1783 LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
1784 LPT3:=/dev/lp3
1785
1786
1787 ; Allow port access to WINE started by the root user. Useful for some
1788 ; supported devices, but it can make the system unstable.
1789 ; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
1790 ;
1791 [ports]
1792 ;read=0x779,0x379,0x280-0x2a0
1793 ;write=0x779,0x379,0x280-0x2a0
1794
1795 ; debugging, not need to be modified.
1796 [spy]
1797 Exclude=WM_SIZE;WM_TIMER;
1798
1799 ;
1800 ; What names for the registry datafiles, no need to modify.
1801 ;
1802 [Registry]
1803 ; Paths must be given in /dir/dir/file.reg format.
1804 ; Wine will not understand dos file names here...
1805 ;UserFileName=xxx               ; alternate registry file name (user.reg)
1806 ;LocalMachineFileName=xxx       ; (system.reg)
1807
1808 ;
1809 ; Layout/Look modifications. Here you can switch with a single line between
1810 ; windows 3.1 and windows 95 style.
1811 ; This does not change WINE behaviour or reported versions, just the look!
1812 ;
1813 [Tweak.Layout]
1814 ;; WineLook=xxx  (supported styles are 'Win31'(default), 'Win95', 'Win98')
1815 WineLook=Win95
1816
1817 ;
1818 ; What programs to start on WINE startup. (you should probably leave it empty)
1819 ;
1820 [programs]
1821 Default=
1822 Startup=
1823
1824 ; defunct section.
1825 [Console]
1826 ;XtermProg=nxterm
1827 ;InitialRows=25
1828 ;InitialColumns=80
1829 ;TerminalType=nxterm
1830
1831 # &lt;/wineconf&gt;
1832       </programlisting>
1833
1834       </sect2>
1835   </sect1>
1836
1837 </chapter>
1838
1839 <chapter id="pkg-todo"><Title>Work to be done</title>
1840
1841     <para>
1842     In preparing this document, it became clear that there were
1843     still a range of action items to be done in Wine
1844     that would improve this packaging process.
1845     For lack of a better place, I record them here.
1846     <emphasis>This list is almost certain to be obsolete;
1847     check bugzilla for a better list.</emphasis>
1848     </para>
1849
1850     <orderedlist>
1851         <listitem>
1852             <para>
1853             Remove duplication of code between winesetup and
1854             wineconf/wineinstall.
1855             </para>
1856             <para>
1857             Currently, winesetup duplicates all of the code contained 
1858             in wineconf.
1859             </para>
1860             <para>
1861             Instead, wineconf should be improved to generate
1862             the new style config file, and then winesetup should
1863             rely on wineconf to generate the default
1864             configuration file.
1865             </para>
1866             <para>
1867             Similarly, there is functionality such as creating
1868             the default registry files that is now done by
1869             both winesetup and wineinstall.
1870             </para>
1871             <para>
1872             At this time, it seems like the right thing to do
1873             is to break up or parameterize wineinstall, so that
1874             it can be used for single function actions,
1875             and then have winesetup call those functions.
1876             </para>
1877         </listitem>
1878
1879         <listitem>
1880             <para>
1881             Enhance winesetup to support W: drive generation.
1882             </para>
1883             <para>
1884             The best practices convention now seems to be
1885             to generate a set of drives from M: through W:.
1886             At this point, winesetup does not generate
1887             a default wine config file that follows
1888             these conventions. It should.
1889             </para>
1890         </listitem>
1891
1892         <listitem>
1893             <para>
1894             Enhance Wine to allow more dynamic switching
1895             between the use of a real Windows partition
1896             and an empty one.
1897             </para>
1898         </listitem>
1899
1900         <listitem>
1901             <para>
1902             Write a winelauncher utility application.
1903             </para>
1904             <para>
1905             Currently, Wine really requires a user to launch it
1906             from a command line, so that the user can look for
1907             error messages and warnings.  However, eventually, we will
1908             want users to be able to launch Wine from a more
1909             friendly GUI launcher.  The launcher should have the
1910             ability to allow the end user to turn on debugging
1911             messages and capture those traces for bug reporting
1912             purposes.  Also, if we make it possible to
1913             switch between use of a Windows partition or not
1914             automatically, that option should be controlled here.
1915             </para>
1916         </listitem>
1917
1918         <listitem>
1919             <para>
1920             Get Marcus's winesetup facilities into CVS
1921             </para>
1922             <para>
1923             Along the lines of the changes to winesetup,
1924             and the consolidation of wineconf and wineinstall,
1925             we should extract the good stuff from Marcus's
1926             winesetup script, and get it into CVS.
1927             Again, perhaps we should have a set of scripts
1928             that perform discrete functions, or maybe
1929             one script with parameters.
1930             </para>
1931         </listitem>
1932
1933         <listitem>
1934             <para>
1935             Finish this document
1936             </para>
1937             <para>
1938             This document is pretty rough itself.  Many hard
1939             things aren't addressed, and lots of stuff was missed.
1940             </para>
1941         </listitem>
1942     </orderedlist>
1943 </chapter>
1944
1945
1946 <!-- Keep this comment at the end of the file
1947 Local variables:
1948 mode: sgml
1949 sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
1950 End:
1951 -->