marko10_000
/
wine-wine
forked from Mirrors/wine-wine
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Documentation update.

oldstable
John R. Sheets 2000-12-13 21:52:37 +00:00 committed by Alexandre Julliard
parent e675887129
commit d9e064fd4b
33 changed files with 6137 additions and 1197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
documentation/Makefile.in
View File

@ -4,6 +4,7 @@ SRCDIR = @srcdir@
VPATH = @srcdir@
MODULE = none
BOOKNAME = wine-doc
DB2HTML = $(SRCDIR)/db2html-winehq
EXTRASUBDIRS = samples status
@ -14,14 +15,18 @@ BOOK_SRCS = \
compiling.sgml \
configuring.sgml \
consoles.sgml \
cvs-regression.sgml \
debugger.sgml \
debugging.sgml \
dlls.sgml \
documentation.sgml \
fonts.sgml \
getting.sgml \
i18n.sgml \
implementation.sgml \
installing.sgml \
introduction.sgml \
ole.sgml \
opengl.sgml \
packaging.sgml \
patches.sgml \
@ -42,13 +47,13 @@ all: $(BOOK_TARGETS)
@MAKE_RULES@
$(BOOKNAME)/index.html: $(BOOK_SRCS)
db2html $(BOOKNAME).sgml
$(DB2HTML) $(BOOKNAME).sgml
$(BOOKNAME).pdf: $(BOOK_SRCS)
db2pdf $(BOOKNAME).sgml
db2pdf $(BOOKNAME).sgml > /dev/null 2>&1
$(BOOKNAME).ps: $(BOOK_SRCS)
db2ps $(BOOKNAME).sgml
db2ps $(BOOKNAME).sgml > /dev/null 2>&1
install::
$(INSTALL) -d $(mandir)/man$(prog_manext)

8
documentation/architecture.sgml
View File

@ -5,7 +5,9 @@
<sect1 id="basic-overview">
<title>Basic Overview</title>
<para>Written by Ove Kaaven</para>
<para>
Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
</para>
<para>
With the fundamental architecture of Wine stabilizing, and
@ -1022,11 +1024,11 @@ WSOCK32.DLL: 32-bit sockets APIs
</screen>
</sect2>
</sect1>
</chapter>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

116
documentation/authors.ent 100644
View File

@ -0,0 +1,116 @@
<!-- *** List of author names
*** Allows us to maintain the list and change spam obfuscation
*** From a central location.
*** Use this template for new author attributions:
Written by &; <email>&;</email>
-->
<!-- ** Template for new entries **
<!entity name- "">
<!entity email- "">
-->
<!entity name-jonathan-buzzard "Jonathan Buzzard">
<!entity email-jonathan-buzzard "jab@hex.prestel.co.uk">
<!entity name-david-cuthbert "David A. Cuthbert">
<!entity email-david-cuthbert "dacut@ece.cmu.edu">
<!entity name-huw-davies "Huw D M Davies">
<!entity email-huw-davies "h.davies1@physics.ox.ac.uk">
<!entity name-steven-elliott "Steven Elliott">
<!entity email-steven-elliott "elliotsl@mindspring.com">
<!entity name-albert-den-haan "Albert den Haan">
<!entity email-albert-den-haan "">
<!entity name-james-juran "James Juran">
<!entity email-james-juran "juran@cse.psu.edu">
<!entity name-ove-kaaven "Ove Kåven">
<!entity email-ove-kaaven "ovek@winehq.com">
<!entity name-eric-kohl "Eric Kohl">
<!entity email-eric-kohl "ekohl@abo.rhein-zeitung.de">
<!entity name-alex-korobka "Alex Korobka">
<!entity email-alex-korobka "alex@aikea.ams.sunysb.edu">
<!entity name-marcus-meissner "Marcus Meissner">
<!-- <!entity email-marcus-meissner "msmeissn@cip.informatik.uni-erlangen.de"> -->
<!entity email-marcus-meissner "Marcus.Meissner@caldera.de">
<!entity name-bruce-milner "Bruce Milner">
<!entity email-bruce-milner "">
<!entity name-andreas-mohr "Andreas Mohr">
<!-- <!entity email-andreas-mohr "a.mohr@mailto.de"> -->
<!entity email-andreas-mohr "amohr@codeweavers.com">
<!entity name-gerard-patel "Gerard Patel">
<!entity email-gerard-patel "">
<!entity name-dimitrie-paun "Dimitrie O. Paun">
<!entity email-dimitrie-paun "dimi@cs.toronto.edu">
<!entity name-eric-pouech "Eric Pouech">
<!entity email-eric-pouech "Eric.Pouech@wanadoo.fr">
<!entity name-robert-pouliot "Robert Pouliot">
<!entity email-robert-pouliot "krynos@clic.net">
<!entity name-joseph-pranevich "Joseph Pranevich">
<!entity email-joseph-pranevich "jpranevich@lycos.com">
<!entity name-alex-priem "Alex Priem">
<!entity email-alex-priem "alex@sci.kun.nl">
<!entity name-john-richardson "John Richardson">
<!entity email-john-richardson "jrichard@zko.dec.com">
<!entity name-douglas-ridgway "Douglas Ridgway">
<!entity email-douglas-ridgway "ridgway@winehq.com">
<!entity name-adam-sacarny "Adam Sacarny">
<!entity email-adam-sacarny "magicbox@bestweb.net">
<!entity name-juergen-schmied "Juergen Schmied">
<!entity email-juergen-schmied "juergen.schmied@metronet.de">
<!entity name-john-sheets "John R. Sheets">
<!entity email-john-sheets "jsheets@codeweavers.com">
<!entity name-petr-tomasek "Petr Tomasek">
<!entity email-petr-tomasek "tomasek@etf.cuni.cz">
<!entity name-lionel-ulmer "Lionel Ulmer">
<!entity email-lionel-ulmer "lionel.ulmer@free.fr">
<!entity name-morten-welinder "Morten Welinder">
<!entity email-morten-welinder "">
<!entity name-jeremy-white "Jeremy White">
<!entity email-jeremy-white "jwhite@codeweavers.com">
<!-- *** Coders mentioned in docs, but not doc writers *** -->
<!entity name-francis-beaudet "Francis Beaudet">
<!entity email-francis-beaudet "francis@macadamian.com">
<!entity name-anders-carlsson "Anders Carlsson">
<!entity email-anders-carlsson "anders.carlsson@linux.nu">
<!entity name-aric-stewart "Aric Stewart">
<!entity email-aric-stewart "aric@codeweavers.com">
<!entity name-luc-tourangeau "Luc Tourangeau">
<!entity email-luc-tourangeau "luc@macadamian.com">
<!entity name-koen-deforche "Koen Deforche">
<!entity email-koen-deforche "jozef@kotnet.org">

16
documentation/bugs.sgml
View File

@ -5,7 +5,7 @@
<title>How To Report A Bug</title>
<para>
written by Gerard Patel (???)
Written by &name-gerard-patel; <email>&email-gerard-patel;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/bugreports</filename>)
@ -25,14 +25,14 @@
<orderedlist>
<listitem>
<para>
Your computer *must* have perl on it for this method to
work. To find out if you have perl, run <command>which
perl</command>. If it returns something like
Your computer <emphasis>must</emphasis> have perl on it
for this method to work. To find out if you have perl,
run <command>which perl</command>. If it returns something like
<filename>/usr/bin/perl</filename>, you're in business.
Otherwise, skip on down to "The Hard Way". If you aren't
sure, just keep on going. When you try to run the
script, it will become *very* apparent if you don't have
perl.
script, it will become <emphasis>very</emphasis> apparent
if you don't have perl.
</para>
</listitem>
<listitem>
@ -130,7 +130,7 @@
<parameter>+snoop</parameter> is pretty unstable and
often will crash earlier than a simple
<parameter>+relay</parameter>! If this is the case, then
please use *only* <parameter>+relay</parameter>!! A bug
please use <emphasis>only</emphasis> <parameter>+relay</parameter>!! A bug
report with a crash in <parameter>+snoop</parameter>
code is useless in most cases!
</para>
@ -211,6 +211,6 @@
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

2
documentation/build.sgml
View File

@ -6,6 +6,6 @@
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

160
documentation/compiling.sgml
View File

@ -1,11 +1,169 @@
<chapter id="compiling">
<title>Compiling Wine</title>
<para>How to compile wine, and problems that may arise...</para>
<sect1 id="compiling-wine">
<title>Compiling Wine</title>
<sect2>
<title>Tools required</title>
<para>
<itemizedlist>
<listitem>
<para>
gcc -- 2.7.x required (Wine uses attribute stdcall).
Versions earlier than 2.7.2.3 barf on shellord.c
-- compile without optimizing for that file.
In addition EGCS 1.1.x and GCC 2.95.x are reported
to work fine.
</para>
</listitem>
<listitem>
<para>
flex >= 2.5.1 (required for the debugger and wrc,
and lex won't do)
</para>
</listitem>
<listitem>
<para>
bison (also required for debugger. Don't know whether BSD yacc
would work.)
</para>
</listitem>
<listitem>
<para>
X11 libs and include files
</para>
</listitem>
<listitem>
<para>
Xpm libs and include files
</para>
</listitem>
<listitem>
<para>
texinfo >= 3.11 (optional, to compile the documentation.)
</para>
</listitem>
<listitem>
<para>
autoconf (if you want to remake configure, which is
not normally required)
</para>
</listitem>
<listitem>
<para>
XF86DGA extension (optional, detected by configure,
needed for DirectX support)
</para>
</listitem>
<listitem>
<para>
Open Sound System (optional, detected by configure,
for sound support)
</para>
</listitem>
</itemizedlist>
</para>
<para>
The Red Hat RPMs are gcc-XXX, flex-XXX, XFree86-devel-XXX, xpm-XXX,
and xpm-devel, where XXX is the version number.
</para>
</sect2>
<sect2>
<title>Space required</title>
<para>
You also need about 230 MB of available disk space for compilation.
The compiled libwine.so binary takes around 5 MB of disk space,
which can be reduced to about 1 MB by stripping ('strip wine').
Stripping is not recommended, however, as you can't submit
proper crash reports with a stripped binary any more.
</para>
</sect2>
<sect2>
<title>Common problems</title>
<para>
If you get a repeatable sig11 compiling shellord.c, thunk.c
or other files, try compiling just that file without optimization.
Then you should be able to finish the build.
</para>
</sect2>
<sect2>
<title>OS specific issues</title>
<para>
<itemizedlist>
<listitem>
<para>
FreeBSD -- In order to run Wine, the FreeBSD kernel
needs to be compiled with
<informaltable frame="all">
<tgroup cols="2">
<tbody>
<row>
<entry>options</entry>
<entry>USER_LDT</entry>
</row>
<row>
<entry>options</entry>
<entry>SYSVSHM</entry>
</row>
<row>
<entry>options</entry>
<entry>SYSVSEM</entry>
</row>
<row>
<entry>options</entry>
<entry>SYSVMSG</entry>
</row>
</tbody>
</tgroup>
</informaltable>
If you need help, read the chapter "<ulink url="http://www.freebsd.org/handbook/kernelconfig-building.html">Building and Installing a Custom Kernel</ulink>" in the "<ulink url="http://www.freebsd.org/handbook/">FreeBSD handbook</ulink>. You'll need to be running FreeBSD 3.x or later.
</para>
</listitem>
<listitem>
<para>
SCO Unixware, Openserver -- UW port is supported by SCO.
</para>
</listitem>
<listitem>
<para>
OS/2 -- not a complete port. See <ulink url="http://odin.netlabs.org/ProjectAbout.phtml">Odin</ulink> for a project which uses some Wine code.
</para>
</listitem>
<listitem>
<para>
Solaris x86 2.x -- Needs GNU toolchain (gcc, gas, flex as above, yacc may work) to compile, seems functional (980215).
</para>
</listitem>
<listitem>
<para>
DGUX, HP, Irix, or other Unixes; non-intel Linux.
No ports have been seriously attempted.
For non-intel Unixes, only a winelib port is relevant.
Alignment may be a problem.
</para>
</listitem>
<listitem>
<para>
Macintosh/Rhapsody/BeOS -- no ports have been attempted.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

59
documentation/configuring.sgml
View File

@ -5,7 +5,7 @@
<sect1 id="config">
<title>General Configuration</title>
<para>
Copyright 1999 Adam Sacarny (magicbox@bestweb.net)
Copyright 1999 &name-adam-sacarny; <email>&email-adam-sacarny;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/config</filename>)
@ -515,7 +515,7 @@ winsock = wsock32
</programlisting>
</para>
<para>
For example, to load builtin KERNEL pair (Case doesn't
For example, to load builtin KERNEL pair (case doesn't
matter here):
<programlisting>
kernel,kernel32 = builtin
@ -649,7 +649,7 @@ Alias1 = Foo,--google-,subst
<title>The [serialports], [parallelports], [spooler], and [ports] Sections</title>
<para>
Even though it sounds like a lot of sections, these are
all closely related. They all are for communications and
all closely related. They are all for communications and
parallel ports.
</para>
<para>
@ -678,7 +678,7 @@ Alias1 = Foo,--google-,subst
<programlisting>LptX=/dev/lpY</programlisting>
</para>
<para>
Seem farmiliar? Syntax is just like the COM port setting.
Sounds familiar? Syntax is just like the COM port setting.
Replace <literal>X</literal> with a value from 1-4 as it
is in Windows and <literal>Y</literal> with a value from
0-3 (<literal>Y</literal> is usually the value in windows
@ -714,10 +714,10 @@ Alias1 = Foo,--google-,subst
</para>
<para>
<programlisting>write=0x779,0x379,0x280-0x2a0</programlisting>
Gives direct write access to those IO's. It probably a
Gives direct write access to those IO's. It's probably a
good idea to keep the values of the
<literal>read</literal> and <literal>write</literal>
settings the same. This stuff will only work when you're
settings the same. This stuff will only work when you're
root.
</para>
</sect3>
@ -725,7 +725,7 @@ Alias1 = Foo,--google-,subst
<sect3>
<title>The [spy], [Registry], [tweak.layout], and [programs] Sections</title>
<para>
[spy] is used to Include or exclude debug messages, and to
[spy] is used to include or exclude debug messages, and to
output them to a file. The latter is rarely used. THESE
ARE ALL OPTIONAL AND YOU PROBABLY DON'T NEED TO ADD OR
REMOVE ANYTHING IN THIS SECTION TO YOUR CONFIG.
@ -816,20 +816,19 @@ Alias1 = Foo,--google-,subst
<para>
There is always a chance that things will go wrong. If the
unthinkable happens, try the newsgroup,
<systemitem>comp.emulators.ms-windows.wine</systemitem> Make sure that you have
looked over this document thoroughly, and have also read:
<systemitem>comp.emulators.ms-windows.wine</systemitem>,
or the IRCnet channel <systemitem>#WineHQ</systemitem>.
Make sure that you have looked over this document thoroughly,
and have also read:
</para>
<itemizedlist>
<listitem>
<para><filename>README</filename></para>
</listitem>
<listitem>
<para><filename>documentation/bugreports</filename></para>
</listitem>
<listitem>
<para>
<filename>http://www.westfalen.de/witch/wine-HOWTO.txt</filename>
(Optional but recommended)
<filename>http://www.la-sorciere.de/wine/index.html</filename>
(optional but recommended)
</para>
</listitem>
</itemizedlist>
@ -844,7 +843,7 @@ Alias1 = Foo,--google-,subst
<sect1 id="win95look">
<title>Win95/98 Look</title>
<para>
by ???
Written by &name-david-cuthbert; <email>&email-david-cuthbert;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/win95look</filename>)
@ -887,10 +886,10 @@ WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel
<title>Configuring the x11drv Driver</title>
<para>
written by Ove Kåven
Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/x11drv</filename>)
(Extracted from <filename>wine/documentation/cdrom-labels</filename>)
</para>
<para>
@ -1136,7 +1135,7 @@ WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel
<firstname>Petr</firstname>
<surname>Tomasek</surname>
<affiliation>
<address><email>&lt;tomasek@etf.cuni.cz></email></address>
<address><email>&email-petr-tomasek;</email></address>
</affiliation>
<contrib>Nov 14 1999</contrib>
</author>
@ -1144,7 +1143,7 @@ WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel
<firstname>Andreas</firstname>
<surname>Mohr</surname>
<affiliation>
<address><email>&lt;a.mohr@mailto.de></email></address>
<address><email>&email-andreas-mohr;</email></address>
</affiliation>
<contrib>Jan 25 2000</contrib>
</author>
@ -1153,11 +1152,11 @@ WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel
<title>Drive labels and serial numbers with wine</title>
<para>
by Petr Tomasek &lt;tomasek@etf.cuni.cz>
Written by &name-petr-tomasek; <email>&email-petr-tomasek;</email>
Nov 14 1999
</para>
<para>
changes by Andreas Mohr &lt;a.mohr@mailto.de>
Changes by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
Jan 25 2000
</para>
<para>
@ -1221,9 +1220,9 @@ WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel
</para>
<para>
If you want to give a <literal>Device=</literal> entry
*only* for drive raw sector accesses, but not for reading
the volume info from the device (i.e. you want a
<emphasis>fixed</emphasis>, preconfigured label), you need
<emphasis>only</emphasis> for drive raw sector accesses,
but not for reading the volume info from the device (i.e. you want
a <emphasis>fixed</emphasis>, preconfigured label), you need
to specify <literal>ReadVolInfo=0</literal> to tell Wine to
skip the volume reading.
</para>
@ -1292,7 +1291,9 @@ Filesystem=msdos
<sect1 id="dll-overrides">
<title>Dll Overrides</title>
<para>by Ove Kaaven &lt;ovek@arcticnet.no></para>
<para>
Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/dll-overrides</filename>)
</para>
@ -1350,7 +1351,7 @@ Filesystem=msdos
A native Unix <filename>.so</filename> file, with
calling convention conversion thunks generated on the
fly as the library is loaded. This is mostly useful
for libraries such as "glide" that has exactly the
for libraries such as "glide" that have exactly the
same API on both Windows and Unix.
</para> </listitem>
</varlistentry>
@ -1690,7 +1691,9 @@ Filesystem=msdos
<sect1 id="keyboard">
<title>Keyboard</title>
<para>by Ove Kaaven &lt;ovek@arcticnet.no></para>
<para>
Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/keyboard</filename>)
</para>
@ -1869,6 +1872,6 @@ diff -u the_backup_file_you_made windows/x11drv/keyboard.c > layout.diff
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

13
documentation/consoles.sgml
View File

@ -5,7 +5,8 @@
<title>Consoles</title>
<para>
written by (???)
Written by &name-john-richardson; <email>&email-john-richardson;</email>
Maintained by &name-joseph-pranevich; <email>&email-joseph-pranevich;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/console</filename>)
@ -19,7 +20,7 @@
<parameter>-Sxxn</parameter> switch. A
<systemitem>pty</systemitem> is opened and the master goes
to the <filename>xterm</filename> side and the slave is held
by the wine side. The console itself it turned into a few
by the wine side. The console itself is turned into a few
<type>HANDLE32</type>s and is set to the
<varname>STD_*_HANDLES</varname>.
</para>
@ -35,7 +36,7 @@
</para>
<para>
<emphasis>[this paragraph is now out of date]</emphasis> If
the command line console is to be inheirited or a process
the command line console is to be inherited or a process
inherits its parent's console (-- can that happen???), the
console is created at process init time via
<function>PROCESS_InheritConsole</function>. The
@ -90,7 +91,7 @@
processing input. Win32 has line-at-a-time processing,
character processing, and echo. I'm putting together an
intermediate driver that will handle this (and hopefully
won't be any more buggy then the NT4 console
won't be any more buggy than the NT4 console
implementation).
</para>
</sect2>
@ -297,7 +298,7 @@ wine -console ncurses+xterm &lt;application&gt;
<para>
Tell any driver that is interested (ncurses) which
termcap and/or terminfo type to use. The default is
xterm which is appropiate for most uses.
xterm which is appropriate for most uses.
<command>nxterm</command> may give you better
support if you use that terminal. This can also be
changed to "linux" (or "console" on older systems)
@ -381,6 +382,6 @@ wine -console ncurses+xterm &lt;application&gt;
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

172
documentation/cvs-regression.sgml 100644
View File

@ -0,0 +1,172 @@
<chapter id="cvs-regression">
<title>How to do regression testing using Cvs</title>
<para>
written by (???)
</para>
<para>
(Extracted from <filename>wine/documentation/bugreports</filename>)
</para>
<para>
A problem that can happen sometimes is 'it used to work
before, now it doesn't anymore...'. Here is a step by step
procedure to try to pinpoint when the problem occured. This is
<emphasis>NOT</emphasis> for casual users.
</para>
<orderedlist>
<listitem>
<para>
Get the 'full cvs' archive from winehq. This archive is
the cvs tree but with the tags controlling the versioning
system. It's a big file (> 15 meg) with a name like
full-cvs-&lt;last update date> (it's more than 100mb
when uncompressed, you can't very well do this with
small, old computers or slow Internet connections).
</para>
</listitem>
<listitem>
<para>
untar it into a repository directory:
<screen>
cd /home/gerard
tar -zxffull-cvs-2000-05-20.tar.gz
mv wine repository
</screen>
</para>
</listitem>
<listitem>
<para>
extract a new destination directory. This directory must
not be in a subdirectory of the repository else
<command>cvs</command> will think it's part of the
repository and deny you an extraction in the repository:
<screen>
cd /home/gerard
mv wine wine_current (-> this protects your current wine sandbox, if any)
export CVSROOT=/home/gerard/repository
cd /home/gerard
cvs -d $CVSROOT checkout wine
</screen>
</para>
<para>
Note that it's not possible to do a checkout at a given
date; you always do the checkout for the last date where
the full-cvs-xxx snapshot was generated.
</para>
</listitem>
<listitem>
<para>
you will have now in the <filename>~/wine</filename>
directory an image of the cvs tree, on the client side.
Now update this image to the date you want:
<screen>
cd /home/gerard/wine
cvs -d $CVSROOT update -D "1999-06-01"
</screen>
</para>
<para>
The date format is <literal>YYYY-MM-DD</literal>.
</para>
<para>
Many messages will inform you that more recent files have
been deleted to set back the client cvs tree to the date
you asked, for example:
<screen>
cvs update: tsx11/ts_xf86dga2.c is no longer in the repository
</screen>
</para>
<para>
<command>cvs update</command> is not limited to upgrade to
a <emphasis>newer</emphasis> version as I have believed for far too long :-(
</para>
</listitem>
<listitem>
<para>
Now proceed as for a normal update:
</para>
<screen>
./configure
make depend && make
</screen>
<para>
When you have found the exact date when a bug was added to
the cvs tree, use something like :
<screen>
cvs -d $CVSROOT diff -D "1999-07-10" -D "1999-07-12"
</screen>
to get all the differences between the last cvs tree
version known to work and code that first displayed the
misbehavior.
</para>
<note>
<para>
I did not include flags for <command>diff</command>
since they are in my <filename>.cvsrc</filename> file:
</para>
<screen>
cvs -z 3
update -dPA
diff -u
</screen>
</note>
<para>
From this diff file, particularly the file names, and the
<filename>ChangeLog</filename>, it's usually possible to
find the different individual patches that were done at
this time.
</para>
<para>
If any non-programmer reads this, the fastest method to get
at the point where the problem occured is to use a binary
search, that is, if the problem occured in 1999, start at
mid-year, then is the problem is already here, back to 1st
April, if not, to 1st October, and so on.
</para>
</listitem>
<listitem>
<para>
The next step is to start from the last working version
and to dig the individual contributions from
<ulink url="http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/">
http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/</ulink>
(where the Wine patches mailing list is archived)
</para>
<para>
If the patch was done by the Wine maintainer or if it was
sent directly to his mail address without going first through
<ulink url="mailto:wine-patches@winehq.com">wine-patches</ulink>,
you are out of luck as you will never find the patch in
the archive. If it is, it's often possible to apply the
patches one by one to last working cvs snapshot, compile and test.
If you have saved the next candidate as
<filename>/home/gerard/buggedpatch1.txt</filename>:
</para>
<screen>
cd /home/gerard/wine
patch -p 0 &lt; /home/gerard/buggedpatch1.txt
</screen>
<para>
Beware that the committed patch is not always identical to
the patch that the author sent to wine-patches, as
sometimes the Wine maintainer changes things a bit.
</para>
<para>
If you find one patch that is getting the cvs source tree to
reproduce the problem, you have almost won; post the problem on
<systemitem>comp.emulators.windows.wine</systemitem> and there
is a chance that the author will jump in to suggest a fix; or
there is always the possibility to look hard at the patch until
it is coerced to reveal where is the bug :-)
</para>
</listitem>
</orderedlist>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

88
documentation/db2html-winehq 100755
View File

@ -0,0 +1,88 @@
#! /bin/sh
## Customized version of db2html to make it easier to use alternate
## stylesheets. Some versions of db2html support a '-d' option to
## specify this, but not all. We'll explicitly specify that here.
##
## John R. Sheets <jsheets@codeweavers.com>
## Other possible SGML stylesheets (default Debian versions...may be
## different on other distributions).
#DB_STYLESHEET=/usr/lib/sgml/stylesheet/dsssl/docbook/cygnus/cygnus-both.dsl
#DB_STYLESHEET=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl
## Use included default.dsl DSSSL stylesheet unless explicitly overridden with
## the $WINEDOC_STYLESHEET envar.
##
## NOTE: The invoked DSSSL stylesheet *MUST* have an HTML-specific section
## in it; otherwise, jade will spew everything to stdout and fail to use
## the stated stylesheet. Something like this:
##
## <style-specification id="html" use="docbook">
if [ -z "$WINEDOC_STYLESHEET" ]; then
DB_STYLESHEET=../default.dsl
else
DB_STYLESHEET=$WINEDOC_STYLESHEET
fi
output=db2html-dir
TMPDIR=DBTOHTML_OUTPUT_DIR$$
echo TMPDIR is $TMPDIR
echo "Using stylesheet: \"${DB_STYLESHEET}\""
if [ $# -gt 2 ]
then
echo "Usage: `basename $0` [filename.sgml]" >&2
exit 1
fi
if [ $# -eq 1 ]
then
if [ ! -r $1 ]
then
echo Cannot read \"$1\". Exiting. >&2
exit 1
fi
if echo $1 | egrep -i '\.sgml$|\.sgm$' >/dev/null 2>&1
then
# now make sure that the output directory is always a subdirectory
# of the current directory
echo
input_file=`basename $1`
output="`echo $input_file | sed 's,\.sgml$,,;s,\.sgm$,,'`"
echo "input file was called $input_file -- output will be in $output"
echo
fi
fi
mkdir $TMPDIR
SAVE_PWD=`pwd`
if [ $1 = `basename $1` ]; then
echo "working on ../$1"
(cd $TMPDIR; jade -t sgml -ihtml -d ${DB_STYLESHEET}\#html ../$1; cd $SAVE_PWD)
else
echo "working on $1"
(cd $TMPDIR; jade -t sgml -ihtml -d ${DB_STYLESHEET}\#html $1; cd $SAVE_PWD)
fi
if [ $# -eq 1 ]
then
if [ -d ${output}.junk ]
then
/bin/rm -rf ${output}.junk
fi
if [ -d ${output} ]
then
mv $output ${output}.junk
fi
echo "about to rename temporary directory to $output"
mv ${TMPDIR} $output
else
cat $TMPDIR/*
fi
rm -rf $TMPDIR
exit 0

862
documentation/debugger.sgml
View File

File diff suppressed because it is too large Load Diff

843
documentation/debugging.sgml
View File

@ -1,11 +1,8 @@
<chapter id="debugging">
<title>Debugging Wine</title>
<sect1 id="debug-msg">
<title>Debug Messages</title>
<title>Debug Logging</title>
<para>
written by Dimitrie O. Paun <email>dimi@cs.toronto.edu</email>, 28 Mar 1998
Written by &name-dimitrie-paun; <email>&email-dimitrie-paun;</email>, 28 Mar 1998
</para>
<para>
(Extracted from <filename>wine/documentation/debug-msgs</filename>)
@ -36,7 +33,7 @@
</para>
</important>
<sect2>
<sect1 id="dbg-classes">
<title>Debugging classes</title>
<para>
@ -151,9 +148,9 @@
off and certain classes of messages may be completely
disabled at compile time to reduce the size of Wine.
</para>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-channels">
<title>Debugging channels</title>
<para>
@ -202,9 +199,9 @@ dprintf_reg(stddeb, "Could not access key!\n");
WARN(reg, "Could not access key!\n");
</programlisting>
</note>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-using">
<title>How to use it</title>
<para>
@ -216,7 +213,7 @@ WARN(reg, "Could not access key!\n");
....
YYY(xxx, "&lt;message&gt;", ...);
YYY(xxx, "&lt;message>", ...);
</programlisting>
<para>
Some examples from the code:
@ -277,9 +274,9 @@ YYY(xxx, "&lt;message&gt;", ...);
</listitem>
</orderedlist>
</note>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-checking">
<title>Are we debugging?</title>
<para>
@ -310,9 +307,9 @@ if(TRACE_ON(atom)){
used only once!) are used in Wine.
</para>
</note>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-in-memory">
<title>In-memory messages</title>
<para>
@ -338,7 +335,7 @@ dbg_decl_str(name, len);
<para>
print in it with:
<programlisting>
dsprintf(name, "&lt;message&gt;", ...);
dsprintf(name, "&lt;message>", ...);
</programlisting>
which is just like a <function>sprintf</function>
function but instead of a C string as first parameter it
@ -370,13 +367,13 @@ void some_func(tabs)
LPINT16 p = (LPINT16)tabs;
dbg_decl_str(listbox, 256); /* declare the string */
for (i = 0; i &lt; descr-&gt;nb_tabs; i++) {
descr-&gt;tabs[i] = *p++&lt;&lt;1;
for (i = 0; i &lt; descr->nb_tabs; i++) {
descr->tabs[i] = *p++&lt;&lt;1;
if(TRACING(listbox)) /* write in it only if
dsprintf(listbox, "%hd ", descr-&gt;tabs[i]); /* we are gonna output it */
dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
}
TRACE(listbox, "Listbox %04x: settabstops %s",
wnd-&gt;hwndSelf, dbg_str(listbox)); /* output the whole thing */
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
}
</programlisting>
<para>
@ -390,23 +387,23 @@ void some_func(tabs)
LPINT16 p = (LPINT16)tabs;
dbg_decl_str(listbox, 256); /* declare the string */
for (i = 0; i &lt; descr-&gt;nb_tabs; i++) {
descr-&gt;tabs[i] = *p++&lt;&lt;1;
for (i = 0; i &lt; descr->nb_tabs; i++) {
descr->tabs[i] = *p++&lt;&lt;1;
if(TRACING(listbox)) /* write in it only if
dsprintf(listbox, "%hd ", descr-&gt;tabs[i]); /* we are gonna output it */
dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
}
TRACE(listbox, "Listbox %04x: settabstops %s\n",
wnd-&gt;hwndSelf, dbg_str(listbox)); /* output the whole thing */
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
dbg_reset_str(listbox); /* !!!reset the string!!! */
for (i = 0; i &lt; descr-&gt;extrainfo_nr; i++) {
descr-&gt;extrainfo = *p+1;
for (i = 0; i &lt; descr->extrainfo_nr; i++) {
descr->extrainfo = *p+1;
if(TRACING(listbox)) /* write in it only if
dsprintf(listbox,"%3d ",descr-&gt;extrainfo); /* we are gonna output it */
dsprintf(listbox,"%3d ",descr->extrainfo); /* we are gonna output it */
}
TRACE(listbox, "Listbox %04x: extrainfo %s\n",
wnd-&gt;hwndSelf, dbg_str(listbox)); /* output the whole thing */
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
}
</programlisting>
@ -459,9 +456,9 @@ if(YYY(xxx))
</listitem>
</itemizedlist>
</important>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-resource-ids">
<title>Resource identifiers</title>
<para>
@ -497,7 +494,7 @@ LPSTR debugres(const void *id);
returns a string of the form:
</para>
<programlisting>
'&lt;identifier&gt;'
'&lt;identifier>'
</programlisting>
<para>
Thus, to use it, do something on the following lines:
@ -509,9 +506,9 @@ LPSTR debugres(const void *id);
YYY(xxx, "resource is %s", debugres(myresource));
</programlisting>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-param">
<title>The <parameter>--debugmsg</parameter> command line option</title>
<para>
@ -598,9 +595,9 @@ LPSTR debugres(const void *id);
default</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-compiling">
<title>Compiling Out Debugging Messages</title>
<para>
@ -620,9 +617,9 @@ LPSTR debugres(const void *id);
This feature has not been extensively tested--it may subtly
break some things.
</para>
</sect2>
</sect1>
<sect2>
<sect1 id="dbg-notes">
<title>A Few Notes on Style</title>
<para>
@ -632,7 +629,7 @@ LPSTR debugres(const void *id);
output format is the following:
</para>
<screen>
yyy:xxx:fff &lt;message&gt;
yyy:xxx:fff &lt;message>
where:
yyy = the class (fixme, err, warn, trace)
@ -641,7 +638,7 @@ where:
</screen>
<para>
these fields are output automatically. All you have to
provide is the &lt;message&gt; part.
provide is the &lt;message> part.
</para>
<para>
So here are some ideas:
@ -780,777 +777,13 @@ MSG( "Definition of drive %d is incorrect!\n", drive );
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
</sect1>
<sect1 id="wine-debugger">
<title>Using the Wine Debugger</title>
<para>
written by Marcus Meissner <email>msmeissn@cip.informatik.uni-erlangen.de</email>,
additions welcome.
</para>
<para>
(Extracted from <filename>wine/documentation/debugging</filename>)
</para>
<para>
This file describes where to start debugging Wine. If at any
point you get stuck and want to ask for help, please read the
file <filename>documentation/bugreports</filename> for
information on how to write useful bug reports.
</para>
<sect2>
<title>Crashes</title>
<para>
These usually show up like this:
</para>
<screen>
|Unexpected Windows program segfault - opcode = 8b
|Segmentation fault in Windows program 1b7:c41.
|Loading symbols from ELF file /root/wine/wine...
|....more Loading symbols from ...
|In 16 bit mode.
|Register dump:
| CS:01b7 SS:016f DS:0287 ES:0000
| IP:0c41 SP:878a BP:8796 FLAGS:0246
| AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
|Stack dump:
|0x016f:0x878a: 0001 016f ffed 0000 0000 0287 890b 1e5b
|0x016f:0x879a: 01b7 0001 000d 1050 08b7 016f 0001 000d
|0x016f:0x87aa: 000a 0003 0004 0000 0007 0007 0190 0000
|0x016f:0x87ba:
|
|0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
|Backtrace:
|0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
|1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
|2 0x01a7:0x05aa
|3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
|4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
|5 0x013f:0x00ac
|
|0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c): movw %es:0x38(%bx),%dx
</screen>
<para>
Steps to debug a crash. You may stop at any step, but please
report the bug and provide as much of the information
gathered to the newsgroup or the relevant developer as
feasible.
</para>
<orderedlist>
<listitem>
<para>
Get the reason for the crash. This is usually an access to
an invalid selector, an access to an out of range address
in a valid selector, popping a segmentregister from the
stack or the like. When reporting a crash, report this
<emphasis>whole</emphasis> crashdump even if it doesn't
make sense to you.
</para>
<para>
(In this case it is access to an invalid selector, for
<systemitem>%es</systemitem> is <literal>0000</literal>, as
seen in the register dump).
</para>
</listitem>
<listitem>
<para>
Determine the cause of the crash. Since this is usually
a primary/secondary reaction to a failed or misbehaving
Wine function, rerun Wine with <parameter>-debugmsg
+relay</parameter> added to the commandline. This will
generate quite a lot of output, but usually the reason is
located in the last call(s). Those lines usually look like
this:
</para>
<screen>
|Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
^^^^^^^^^ ^ ^^^^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^
| | | | | |Datasegment
| | | | |Return address
| | | |textual parameter
| | |
| | |Argument(s). This one is a win16 segmented pointer.
| |Function called.
|The module, the function is called in. In this case it is KERNEL.
|Ret KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
^^^^^^
|Returnvalue is 16 bit and has the value 4.
</screen>
</listitem>
<listitem>
<para>
If you have found a misbehaving function, try to find out
why it misbehaves. Find the function in the source code.
Try to make sense of the arguments passed. Usually there is
a <function>TRACE(&lt;channel&gt;,"(...)\n");</function> at
the beginning of the function. Rerun wine with
<parameter>-debugmsg +xyz,+relay</parameter> added to the
commandline.
</para>
</listitem>
<listitem>
<para>
Additional information on how to debug using the internal
debugger can be found in
<filename>debugger/README</filename>.
</para>
</listitem>
<listitem>
<para>
If this information isn't clear enough or if you want to
know more about what's happening in the function itself,
try running wine with <parameter>-debugmsg
+all</parameter>, which dumps ALL included debug
information in wine.
</para>
</listitem>
<listitem>
<para>
If even that isn't enough, add more debug output for
yourself into the functions you find relevant. See
<filename>documentation/debug-msgs</filename>. You might
also try to run the program in <command>gdb</command>
instead of using the WINE-debugger. If you do that, use
<parameter>handle SIGSEGV nostop noprint</parameter> to
disable the handling of seg faults inside
<command>gdb</command> (needed for Win16). If you don't use
the <parameter>--desktop</parameter> or
<parameter>--managed</parameter> option, start the WINE
process with <parameter>--sync</parameter>, or chances are
good to get X into an unusable state.
</para>
</listitem>
<listitem>
<para>
You can also set a breakpoint for that function. Start wine
with the <parameter>--debug</parameter> option added to the
commandline. After loading the executable wine will enter
the internal debugger. Use <parameter>break
KERNEL_LSTRLEN</parameter> (replace by function you want
to debug, CASE IS RELEVANT) to set a breakpoint. Then use
<command>continue</command> to start normal
program-execution. Wine will stop if it reaches the
breakpoint. If the program isn't yet at the crashing call
of that function, use <command>continue</command> again
until you are about to enter that function. You may now
proceed with single-stepping the function until you reach
the point of crash. Use the other debugger commands to
print registers and the like.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>Program hangs, nothing happens</title>
<para>
Switch to UNIX shell, get the process-ID using <command>ps -a |
grep wine</command>, and do a <command>kill -HUP
&lt;pid&gt;</command> (without the &lt; and &gt;). Wine will
then enter its internal debugger and you can proceed as
explained above. Also, you can use
<parameter>--debug</parameter> switch and then you can get into
internal debugger by pressing
<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> in
the terminal where you run Wine.
</para>
</sect2>
<sect2>
<title>Program reports an error with a Messagebox</title>
<para>
Sometimes programs are reporting failure using more or
less nondescript messageboxes. We can debug this using the
same method as Crashes, but there is one problem... For
setting up a message box the program also calls Wine
producing huge chunks of debug code.
</para>
<para>
Since the failure happens usually directly before setting up
the Messagebox you can start wine with
<parameter>--debug</parameter> added to the commandline, set a
breakpoint at <function>MessageBoxA</function> (called by win16
and win32 programs) and proceed with
<command>continue</command>. With <parameter>--debugmsg
+all</parameter> Wine will now stop directly before setting
up the Messagebox. Proceed as explained above.
</para>
<para>
You can also run wine using <command>wine -debugmsg +relay
program.exe 2&gt;&1 | less -i</command> and in
<command>less</command> search for <quote>MessageBox</quote>.
</para>
</sect2>
<sect2>
<title>Disassembling programs:</title>
<para>
You may also try to disassemble the offending program to
check for undocumented features and/or use of them.
</para>
<para>
The best, freely available, disassembler for Win16 programs is
<application>Windows Codeback</application>, archivename
<filename>wcbxxx.zip</filename>, which usually can be found in
the <filename>Cica-Mirror</filename> subdirectory on the WINE
ftpsites. (See <filename>ANNOUNCE</filename>).
</para>
<para>
Disassembling win32 programs is possible using
<application>Windows Disassembler 32</application>, archivename
something like <filename>w32dsm87.zip</filename> (or similar)
on <systemitem class="systemname">ftp.winsite.com</systemitem>
and mirrors. The shareware version does not allow saving of
disassembly listings. You can also use the newer (and in the
full version better) <application>Interactive
Disassembler</application> (IDA) from the ftp sites mentioned
at the end of the document. Understanding disassembled code is
mostly a question of exercise.
</para>
<para>
Most code out there uses standard C function entries (for it
is usually written in C). Win16 function entries usually
look like that:
</para>
<programlisting>
push bp
mov bp, sp
... function code ..
retf XXXX &lt;--------- XXXX is number of bytes of arguments
</programlisting>
<para>
This is a <function>FAR</function> function with no local
storage. The arguments usually start at
<literal>[bp+6]</literal> with increasing offsets. Note, that
<literal>[bp+6]</literal> belongs to the
<emphasis>rightmost</emphasis> argument, for exported win16
functions use the PASCAL calling convention. So, if we use
<function>strcmp(a,b)</function> with <parameter>a</parameter>
and <parameter>b</parameter> both 32 bit variables
<parameter>b</parameter> would be at <literal>[bp+6]</literal>
and <parameter>a</parameter> at <literal>[bp+10]</literal>.
</para>
<para>
Most functions make also use of local storage in the stackframe:
</para>
<programlisting>
enter 0086, 00
... function code ...
leave
retf XXXX
</programlisting>
<para>
This does mostly the same as above, but also adds
<literal>0x86</literal> bytes of stackstorage, which is
accessed using <literal>[bp-xx]</literal>. Before calling a
function, arguments are pushed on the stack using something
like this:
</para>
<programlisting>
push word ptr [bp-02] &lt;- will be at [bp+8]
push di &lt;- will be at [bp+6]
call KERNEL.LSTRLEN
</programlisting>
<para>
Here first the selector and then the offset to the passed
string are pushed.
</para>
</sect2>
<sect2>
<title>Sample debugging session:</title>
<para>
Let's debug the infamous Word <filename>SHARE.EXE</filename>
messagebox:
</para>
<screen>
|marcus@jet $ wine winword.exe
| +---------------------------------------------+
| | ! You must leave Windows and load SHARE.EXE|
| | before starting Word. |
| +---------------------------------------------+
</screen>
<screen>
|marcus@jet $ wine winword.exe -debugmsg +relay -debug
|CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
|Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
|CallTo16(func=0127:0070,ds=0927)
|Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
|Ret WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
|CallTo16(func=01d7:001a,ds=0927)
| AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
|Loading symbols: /home/marcus/wine/wine...
|Stopped on breakpoint 1 at 0x01d7:0x001a
|In 16 bit mode.
|Wine-dbg&gt;break MessageBoxA &lt;---- Set Breakpoint
|Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|Wine-dbg&gt;c &lt;---- Continue
|Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
| AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
|CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
|... &lt;----- Much debugoutput
|Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
^^^^^^ Drive 0 (A:)
|Ret KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
^^^^^^ DRIVE_REMOVEABLE
(It is a floppy diskdrive.)
|Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
^^^^^^ Drive 1 (B:)
|Ret KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
^^^^^^ DRIVE_CANNOTDETERMINE
(I don't have drive B: assigned)
|Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
^^^^^^^ Drive 2 (C:)
|Ret KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
^^^^^^ DRIVE_FIXED
(specified as a harddisk)
|Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
^^^^^^ ^^^^^ ^^^^^^^^^
| | |buffer for fname
| |temporary name ~docXXXX.tmp
|Force use of Drive C:.
|Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
|Please check your configuration file if this generates a failure.
</screen>
<para>
Whoops, it even detects that something is wrong!
</para>
<screen>
|Ret KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
^^^^^^ Temporary storage ID
|Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
|filename |OFSTRUCT |open mode:
OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
</screen>
<para>
This fails, since my <medialabel>C:</medialabel> drive is in
this case mounted readonly.
</para>
<screen>
|Ret KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
^^^^^^ HFILE_ERROR16, yes, it failed.
|Call USER.1: MESSAGEBOX(0x0000,0x09278376"Sie mussen Windows verlassen und SHARE.EXE laden bevor Sie Word starten.",0x00000000,0x1030) ret=060f:084f ds=0927
</screen>
<para>
And MessageBox'ed.
</para>
<screen>
|Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|190 { &lt;- the sourceline
In 32 bit mode.
Wine-dbg&gt;
</screen>
<para>
The code seems to find a writeable harddisk and tries to create
a file there. To work around this bug, you can define
<medialabel>C:</medialabel> as a networkdrive, which is ignored
by the code above.
</para>
</sect2>
<sect2>
<title>Debugging Tips</title>
<para>
Here are some useful debugging tips, added by Andreas Mohr:
</para>
<itemizedlist>
<listitem>
<para>
If you have a program crashing at such an early loader phase that you can't
use the Wine debugger normally, but Wine already executes the program's
start code, then you may use a special trick. You should do a
<programlisting>
wine --debugmsg +relay program
</programlisting>
to get a listing of the functions the program calls in its start function.
Now you do a
<programlisting>
wine --debug winfile.exe
</programlisting>
</para>
<para>
This way, you get into <command>Wine-dbg</command>. Now you
can set a breakpoint on any function the program calls in
the start function and just type <userinput>c</userinput>
to bypass the eventual calls of Winfile to this function
until you are finally at the place where this function gets
called by the crashing start function. Now you can proceed
with your debugging as usual.
</para>
</listitem>
<listitem>
<para>
If you try to run a program and it quits after showing an error messagebox,
the problem can usually be identified in the return value of one of the
functions executed before <function>MessageBox()</function>.
That's why you should re-run the program with e.g.
<programlisting>
wine --debugmsg +relay &lt;program name&gt; &&gt;relmsg
</programlisting>
Then do a <command>more relmsg</command> and search for the
last occurrence of a call to the string "MESSAGEBOX". This is a line like
<programlisting>
Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
</programlisting>
In my example the lines before the call to
<function>MessageBox()</function> look like that:
<programlisting>
Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff
CallTo16(func=033f:0072,ds=01ff,0x0000)
Ret KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff
Call KERNEL.96: FREELIBRARY(0x036f) ret=01cf:1043 ds=01ff
CallTo16(func=0367:0072,ds=01ff,0x0000)
Ret KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1043 ds=01ff
Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
CallTo16(func=0317:0072,ds=01ff,0x0000)
Ret KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:105c ds=01ff
Call USER.171: WINHELP(0x02ac,0x01ff05b4 "COMET.HLP",0x0002,0x00000000) ret=01cf:1070 ds=01ff
CallTo16(func=0117:0080,ds=01ff)
Call WPROCS.24: TASK_RESCHEDULE() ret=00a7:0a2d ds=002b
Ret WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=00a7:0a2d ds=002b
Ret USER.171: WINHELP() retval=0x0001 ret=01cf:1070 ds=01ff
Call KERNEL.96: FREELIBRARY(0x01be) ret=01df:3e29 ds=01ff
Ret KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff
Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff
Ret KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff
Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
</programlisting>
</para>
<para>
I think that the call to <function>MessageBox()</function>
in this example is <emphasis>not</emphasis> caused by a
wrong result value of some previously executed function
(it's happening quite often like that), but instead the
messagebox complains about a runtime error at
<literal>0x0004:0x1056</literal>.
</para>
<para>
As the segment value of the address is only
<literal>4</literal>, I think that that is only an internal
program value. But the offset address reveals something
quite interesting: Offset <literal>1056</literal> is
<emphasis>very</emphasis> close to the return address of
<function>FREELIBRARY()</function>:
<programlisting>
Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
^^^^
</programlisting>
</para>
<para>
Provided that segment <literal>0x0004</literal> is indeed segment
<literal>0x1cf</literal>, we now we can use IDA (available at
<ulink url="ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip">
ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip</ulink>) to
disassemble the part that caused the error. We just have to find the address of
the call to <function>FreeLibrary()</function>. Some lines before that the
runtime error occurred. But be careful! In some cases you don't have to
disassemble the main program, but instead some DLL called by it in order to find
the correct place where the runtime error occurred. That can be determined by
finding the origin of the segment value (in this case <literal>0x1cf</literal>).
</para>
</listitem>
<listitem>
<para>
If you have created a relay file of some crashing
program and want to set a breakpoint at a certain
location which is not yet available as the program loads
the breakpoint's segment during execution, you may set a
breakpoint to <function>GetVersion16/32</function> as
those functions are called very often.
</para>
<para>
Then do a <userinput>c</userinput> until you are able to
set this breakpoint without error message.
</para>
</listitem>
<listitem>
<para>
Some useful programs:
</para>
<variablelist>
<varlistentry>
<term>
<application>IDA</application>:
<filename>
<ulink url="ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip">
ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip</ulink>
</filename>
</term>
<listitem>
<para>
*Very* good DOS disassembler ! It's badly needed
for debugging Wine sometimes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<application>XRAY</application>:
<filename>
<ulink url="ftp://ftp.th-darmstadt.de/pub/machines/ms-dos/SimTel/msdos/asmutil/xray15.zip">
ftp://ftp.th-darmstadt.de/pub/machines/ms-dos/SimTel/msdos/asmutil/xray15.zip</ulink>
</filename>
</term>
<listitem>
<para>
Traces DOS calls (Int 21h, DPMI, ...). Use it with
Windows to correct file management problems etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<application>pedump</application>:
<filename>
<ulink url="http://oak.oakland.edu/pub/simtelnet/win95/prog/pedump.zip">
http://oak.oakland.edu/pub/simtelnet/win95/prog/pedump.zip</ulink>
</filename>
</term>
<listitem>
<para>
Dumps the imports and exports of a PE (Portable
Executable) DLL.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Some basic debugger usages:</title>
<para>
After starting your program with
</para>
<screen>
wine -debug myprog.exe
</screen>
<para>
the program loads and you get a prompt at the program
starting point. Then you can set breakpoints:
</para>
<screen>
b RoutineName (by outine name) OR
b *0x812575 (by address)
</screen>
<para>
Then you hit <command>c</command> (continue) to run the
program. It stops at the breakpoint. You can type
</para>
<screen>
step (to step one line) OR
stepi (to step one machine instruction at a time;
here, it helps to know the basic 386
instruction set)
info reg (to see registers)
info stack (to see hex values in the stack)
info local (to see local variables)
list &lt;line number&gt; (to list source code)
x &lt;variable name&gt; (to examine a variable; only works if code
is not compiled with optimization)
x 0x4269978 (to examine a memory location)
? (help)
q (quit)
</screen>
<para>
By hitting <keycap>Enter</keycap>, you repeat the last
command.
</para>
</sect2>
</sect1>
<sect1 id="cvs-regression">
<title>How to do regression testing using Cvs</title>
<para>
written by Gerard Patel (???)
</para>
<para>
(Extracted from <filename>wine/documentation/bugreports</filename>)
</para>
<para>
A problem that can happen sometimes is 'it used to work
before, now it doesn't anymore...'. Here is a step by step
procedure to try to pinpoint when the problem occured. This is
*NOT* for casual users.
</para>
<orderedlist>
<listitem>
<para>
Get the 'full cvs' archive from winehq. This archive is
the cvs tree but with the tags controling the versioning
system. It's a big file (> 15 meg) with a name like
full-cvs-&lt;last update date&gt; (it's more than 100mb
when uncompressed, you can't very well do this with
small, old computers or slow Internet connections).
</para>
</listitem>
<listitem>
<para>
untar it into a repository directory:
<screen>
cd /home/gerard
tar -zxffull-cvs-2000-05-20.tar.gz
mv wine repository
</screen>
</para>
</listitem>
<listitem>
<para>
extract a new destination directory. This directory must
not be in a subdirectory of the repository else
<command>cvs</command> will think it's part of the
repository and deny you an extraction in the repository:
<screen>
cd /home/gerard
mv wine wine_current (-> this protects your current wine sandbox, if any)
export CVSROOT=/home/gerard/repository
cd /home/gerard
cvs -d $CVSROOT checkout wine
</screen>
</para>
<para>
Note that it's not possible to do a checkout at a given
date; you always do the checkout for the last date where
the full-cvs-xxx snapshot was generated.
</para>
</listitem>
<listitem>
<para>
you will have now in the <filename>~/wine</filename>
directory an image of the cvs tree, on the client side.
Now update this image to the date you want:
<screen>
cd /home/gerard/wine
cvs -d $CVSROOT update -D "1999-06-01"
</screen>
</para>
<para>
The date format is <literal>YYYY-MM-DD</literal>.
</para>
<para>
Many messages will inform you that more recent files have
been deleted to set back the client cvs tree to the date
you asked, for example:
<screen>
cvs update: tsx11/ts_xf86dga2.c is no longer in the repository
</screen>
</para>
<para>
<command>cvs update</command> is not limited to upgrade to
a *newer* version as I have believed for far too long :-(
</para>
</listitem>
<listitem>
<para>
Now proceed as for a normal update:
</para>
<screen>
./configure
make depend && make
</screen>
<para>
When you have found the exact date when a bug was added to
the cvs tree, use something like :
<screen>
cvs -d $CVSROOT diff -D "1999-07-10" -D "1999-07-12"
</screen>
to get all the differences between the last cvs tree
version known to work and code that first displayed the
misbehavior.
</para>
<note>
<para>
I did not include flags for <command>diff</command>
since they are in my <filename>.cvsrc</filename> file:
</para>
<screen>
cvs -z 3
update -dPA
diff -u
</screen>
</note>
<para>
From this diff file, particularly the file names, and the
<filename>ChangeLog</filename>, it's usually possible to
find the different individual patches that were done at
this time.
</para>
<para>
If any non-programmer reads this, the fastest method to get
at the point where the problem occured is to use a binary
search, that is, if the problem occured in 1999, start at
mid-year, then is the problem is already here, back to 1st
April, if not, to 1st October, and so on.
</para>
</listitem>
<listitem>
<para>
The next step is to start from the last working version
and to dig the individual contributions from
<ulink url="http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/">
http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/</ulink>
(where the Wine patches mailing list is archived)
</para>
<para>
If the patch was done by the Wine maintainer or if it was
sent directly to his mail address without going first through
<ulink url="mailto:wine-patches@winehq.com">wine-patches</ulink>,
you are out of luck as you will never find the patch in
the archive. If it is, it's often possible to apply the
patches one by one to last working cvs snapshot, compile and test.
If you have saved the next candidate as
<filename>/home/gerard/buggedpatch1.txt</filename>:
</para>
<screen>
cd /home/gerard/wine
patch -p 0 &lt; /home/gerard/buggedpatch1.txt
</screen>
<para>
Beware that the committed patch is not always identical to
the patch that the author sent to wine-patches, as
sometimes the Wine maintainer changes things a bit.
</para>
<para>
If you find one patch that is getting the cvs source tree to
reproduce the problem, you have almost won; post the problem on
<systemitem>comp.emulators.windows.wine</systemitem> and there
is a chance that the author will jump in to suggest a fix; or
there is always the possibility to look hard at the patch until
it is coerced to reveal where is the bug :-)
</para>
</listitem>
</orderedlist>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

72
documentation/default.dsl 100644
View File

@ -0,0 +1,72 @@
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY walsh-style PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
<!ENTITY cygnus-style SYSTEM "/usr/lib/sgml/stylesheet/dsssl/docbook/cygnus/cygnus-both.dsl" CDATA DSSSL>
]>
<style-sheet>
<style-specification id="html" use="docbook">
<style-specification-body>
(define %use-id-as-filename% #t)
(define %html-ext% ".html")
(define %html-header-tags% '())
;;(define %stylesheet% "../../winehq.css")
;;(define %stylesheet-type% "text/css")
(define %shade-verbatim% #t)
(define %section-autolabel% #t)
;; Customize the body tag color attributes
(define %body-attr%
(list
(list "BGCOLOR" "#FFFFFF")
(list "TEXT" "#000000")
(list "LINK" "#a50d0d")
(list "VLINK" "#505050")
(list "ALINK" "#a50d0d")))
;; Change the background color of programlisting and screen, etc.
(define ($shade-verbatim-attr$)
(list
(list "BORDER" "0")
;(list "BGCOLOR" "#E0E0E0") ; light grey
(list "BGCOLOR" "#E0D0D0") ; light grayish red
;(list "BGCOLOR" "#bc8686") ; dark rose
;(list "BGCOLOR" "#FFD39B") ; burlywood1 (tan)
;(list "BGCOLOR" "#FFE7BA") ; wheat1 (light tan)
(list "WIDTH" ($table-width$))))
;; Customize systemitem element to have different formatting, according
;; to which class attribute it contains.
(element systemitem
(let ((class (attribute-string (normalize "class"))))
(cond
((equal? class (normalize "systemname")) ($italic-mono-seq$))
((equal? class (normalize "constant")) ($mono-seq$))
(else ($charseq$)))))
;; Okay, this is a little tricky. By default, it appears that setinfo is
;; completely turned off (with empty-sosofo). The setinfo title is extracted
;; through some other means, so we can ignore it when we process the setinfo
;; below.
;; Process setinfo element
(element setinfo (process-children))
;; Ignore title element -- otherwise it'll appear alongside the releaseinfo
;; element. If we add any other elements to setinfo, we'll have to blank them
;; out here, also.
(element (setinfo title)
(empty-sosofo))
;; Enclose releaseinfo element in italics
(element (setinfo releaseinfo)
; (make element gi: "i"
; (process-children)))
(process-children))
</style-specification-body>
</style-specification>
<external-specification id="docbook" document="walsh-style">
</style-sheet>

105
documentation/dlls.sgml
View File

@ -1,5 +1,5 @@
<chapter id="dlls">
<title>Wine Builtin DLLs</title>
<chapter id="dlls">
<title>Wine Builtin DLLs Overview</title>
<para>A more detailed look at Wine's builtin DLLs...</para>
<sect1 id="common-controls">
@ -11,7 +11,7 @@
</bridgehead>
<para>
written by Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/common_controls</filename>)
@ -180,7 +180,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -205,7 +207,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -230,7 +234,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -255,7 +261,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -280,7 +288,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Alex Priem. &lt;alexp@sci.kun.nl&gt;</para>
<para>
Dummy written by &name-alex-priem; <email>&email-alex-priem;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -305,7 +315,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -334,7 +346,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -359,7 +373,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -378,9 +394,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>
Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;,
Alex Priem &lt;alexp@sci.kun.nl&gt;
<para>
Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>,
&name-alex-priem; <email>&email-alex-priem;</email>
</para>
</listitem>
</varlistentry>
@ -403,16 +419,19 @@
<para>Dummy written by: </para>
<itemizedlist>
<listitem>
<para>Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
<listitem>
<para>Luc Tourangeau &lt;luc@macadamian.com&gt;</para>
<para>&name-luc-tourangeau; <email>&email-luc-tourangeau;</email></para>
</listitem>
<listitem>
<para>Koen Deforche &lt;jozef@kotnet.org&gt;</para>
<para>&name-koen-deforche; <email>&email-koen-deforche;</email></para>
</listitem>
<listitem>
<para>Francis Beaudet &lt;francis@macadamian.com&gt; and the "Corel-Team"</para>
<para>&name-francis-beaudet; <email>&email-francis-beaudet;</email>
and the "Corel Team"</para>
</listitem>
</itemizedlist>
</listitem>
@ -443,7 +462,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -468,7 +489,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -493,7 +516,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -543,8 +568,8 @@
<term>Author:</term>
<listitem>
<para>
Anders Carlsson &lt;anders.carlsson@linux.nu&gt; and
Francis Beaudet &lt;francis@macadamian.com&gt;
&name-anders-carlsson; <email>&email-anders-carlsson;</email> and
&name-francis-beaudet; <email>&email-francis-beaudet;</email>
</para>
</listitem>
</varlistentry>
@ -570,7 +595,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -623,7 +650,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Anders Carlsson &lt;anders.carlsson@linux.nu&gt;</para>
<para>
&name-anders-carlsson; <email>&email-anders-carlsson;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -642,7 +671,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -664,7 +695,9 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -691,8 +724,8 @@
<term>Author:</term>
<listitem>
<para>
Dummy written by Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;,
Alex Priem &lt;alexp@sci.kun.nl&gt;
Written by &name-eric-kohl; <email>&email-eric-kohl;</email> and
&name-alex-priem; <email>&email-alex-priem;</email>
</para>
</listitem>
</varlistentry>
@ -712,13 +745,17 @@
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl., Alex Priem &lt;alexp@sci.kun.nl&gt;</para>
<para>
Written by &name-eric-kohl; <email>&email-eric-kohl;</email> and
&name-alex-priem; <email>&email-alex-priem;</email>, fixes by
&name-aric-stewart; <email>&email-aric-stewart;</email>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Under construction.</para>
<para>Quite usable already.</para>
</listitem>
</varlistentry>
</variablelist>
@ -733,7 +770,7 @@
<listitem>
<para>
Original implementation by Dimitrie O. Paun.
Some minor changes by Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;.
Some minor changes by &name-eric-kohl; <email>&email-eric-kohl;</email>.
</para>
</listitem>
</varlistentry>
@ -798,7 +835,7 @@
</para>
<sect3>
<title>5.1 Dymnamic Storage Array (DSA)</title>
<title>5.1 Dynamic Storage Array (DSA)</title>
<para>
The DSA functions are used to store and manage dynamic
@ -903,6 +940,6 @@
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

18
documentation/documentation.sgml
View File

@ -6,7 +6,7 @@
<title>Writing Wine API Documentation</title>
<para>
written by (???)
Written by &name-douglas-ridgway; <email>&email-douglas-ridgway;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/README.documentation</filename>)
@ -18,7 +18,7 @@
</para>
<screen>
/******************************************************************
* CopyMetaFile32A (GDI32.23)
* CopyMetaFileA (GDI32.23)
*
* Copies the metafile corresponding to hSrcMetaFile to either
* a disk file, if a filename is given, or to a new memory based
@ -32,8 +32,8 @@
*
* Copying to disk returns NULL even if successful.
*/
HMETAFILE32 WINAPI CopyMetaFile32A(
HMETAFILE32 hSrcMetaFile, /* handle of metafile to copy */
HMETAFILE WINAPI CopyMetaFileA(
HMETAFILE hSrcMetaFile, /* handle of metafile to copy */
LPCSTR lpFilename /* filename if copying to a file */
) { ... }
</screen>
@ -46,17 +46,17 @@ CopyMetaFileA(3w) CopyMetaFileA(3w)
NAME
CopyMetaFileA - CopyMetaFile32A (GDI32.23)
CopyMetaFileA (GDI32.23)
SYNOPSIS
HMETAFILE32 CopyMetaFileA
HMETAFILE CopyMetaFileA
(
HMETAFILE32 hSrcMetaFile,
HMETAFILE hSrcMetaFile,
LPCSTR lpFilename
);
PARAMETERS
HMETAFILE32 hSrcMetaFile
HMETAFILE hSrcMetaFile
Handle of metafile to copy.
LPCSTR lpFilename
@ -84,6 +84,6 @@ SEE ALSO
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

6
documentation/fonts.sgml
View File

@ -5,7 +5,7 @@
<title>Fonts</title>
<para>
written by ???
Written by &name-alex-korobka; <email>&email-alex-korobka;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/fonts</filename>)
@ -43,7 +43,7 @@
<para>
Convert <filename>.bdf</filename> files produced by Step
1 into <filename>.pcf</filename> files with
<command>bdftopcf -o &lt;target file&gt; &lt;original bdf-file&gt;</command>.
<command>bdftopcf</command>.
</para>
</listitem>
<listitem>
@ -493,6 +493,6 @@ FontPath "tcp/localhost:7100"
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

328
documentation/getting.sgml 100644
View File

@ -0,0 +1,328 @@
<chapter id="getting-wine">
<title>Getting Wine</title>
<sect1>
<title>The Many Forms of Wine</title>
<para>
The standard Wine distribution includes quite a few different
executables, libraries, and configuration files. All of these
must be set up properly for Wine to work well. This chapter
will guide you through the necessary steps to get Wine
installed on your system.
</para>
<para>
If you are running a distribution of Linux that uses packages
to keep track of installed software, you may be in luck: A
prepackaged version of Wine may already exist for your system.
The first three sections will tell you how to find the latest
Wine packages and get them installed. You should be careful,
though, about mixing packages between different distributions,
and even from different versions of the same distribution.
Often a package will only work on the distribution it's
compiled for. We'll cover <link
linkend="getting-dist-debian">Debian</link>, <link
linkend="getting-dist-redhat">Redhat</link>, and <link
linkend="getting-dist-other">other</link> distributions.
</para>
<para>
If you're not lucky enough to have an available package for
your operating system, or if you'd prefer a newer version of
Wine than already exists as a package, you may have to
download the Wine source code and compile it yourself on your
own machine. Don't worry, it's not too hard to do this,
especially with the many helpful tools that come with Wine.
You don't need any programming experience to compile and
install Wine, although it might be nice to have some minor
UNIX administrative skill. We'll cover how to retrieve and
compile the official source releases from the <link
linkend="getting-source-ftp">FTP archives</link>, and also how
to get the cutting edge up-to-the-minute fresh Wine source
code from <link linkend="getting-source-cvs">CVS (Concurrent
Versions System)</link>. Both processes of source code
installation are similar, and once you master one, you should
have no trouble dealing with the other one.
</para>
<para>
Finally, you may someday need to know how to apply a source
code patch to your version of Wine. Perhaps you've uncovered
a bug in Wine, reported it to the <ulink
url="mailto:wine-devel@winehq.com">Wine mailing list</ulink>,
and received a patch from a developer to hopefully fix the
bug. The last section in this chapter will show you how to
<link linkend="getting-upgrading">safely apply the
patch</link> and revert it if the patch doesn't work.
</para>
</sect1>
<sect1 id="getting-dist-debian">
<title>Getting Wine for a Debian System</title>
<para>
In most cases on a Debian system, you can install Wine with a
single command, as root:
</para>
<screen>
# apt-get install wine
</screen>
<para>
<command>apt-get</command> will connect to a Debian archive
across the Internet (thus, you must be online), then download
the Wine package and install it on your system. End of story.
</para>
<para>
Of course, Debian's pre-packaged version of Wine may not be the
most recent release. If you are running the stable version of
Debian, you may be able to get a slightly newer version of Wine
by grabbing the package from the unstable distribution, although
this may be a little risky, depending on how far the unstable
distribution has diverged from the stable one. You can find a
list of Wine binary packages for the various Debian releases
using the
<ulink url="http://cgi.debian.org/cgi-bin/search_packages.pl?keywords=wine&amp;searchon=names&amp;version=all&amp;release=all">
package search engine</ulink> at <ulink url="http://www.debian.org">
www.debian.org</ulink>.
</para>
<para>
To install a package that's not part of your distribution, you
must use <command>dpkg</command> instead of
<command>apt-get</command>. Since <command>dpkg</command>
doesn't download the file for you, you must do it yourself.
Follow the link on the package search engine to the desired
package, then click on the <guibutton>Go To Download
Page</guibutton> button and follow the instructions. Save the
file to your hard drive, then run <command>dpkg</command> on it.
For example, if you saved the file to your home directory, you
might perform the following actions to install it:
</para>
<screen>
$ su -
<emphasis>&lt;Type in root password></emphasis>
# cd /home/user
# dpkg -i wine_0.0.20000109-3.deb
</screen>
<para>
You may also want to install the
<systemitem>wine-doc</systemitem> package, and if you are
using Wine from the 2.3 distribution (Woody), the
<systemitem>wine-utils</systemitem> package as well.
</para>
</sect1>
<sect1 id="getting-dist-redhat">
<title>Getting Wine for a Redhat System</title>
<para>
Redhat/RPM users can use <ulink url="http://rpmfind.net/linux/RPM/">
rpmfind.net</ulink> to track down available Wine RPM binaries.
<ulink url="http://rpmfind.net/linux/RPM/WByName.html"> This
page</ulink> contains a list of all rpmfind packages that start with
the letter "W", including a few Wine packages
</para>
<!-- *** Should really flesh this out more! Any Redhat-running
*** volunteers?
-->
</sect1>
<sect1 id="getting-dist-other">
<title>Getting Wine for Other Distributions</title>
<para>
The first place you should look if your system isn't Debian or
Redhat is the <ulink
url="http://www.winehq.com/download.html">WineHQ Download
Page</ulink>. This page lists many assorted archives of
binary (precompiled) Wine files.
</para>
<para>
<ulink url="http://ftpsearch.lycos.com/?form=medium">
Lycos FTPSearch</ulink> is another useful resource for
tracking down miscellaneous distribution packages.
</para>
<!-- *** Add other distributions, e.g., Mandrake, SUSE, Slackware *** -->
</sect1>
<sect1 id="getting-source-ftp">
<title>Getting Wine Source Code from the FTP Archive</title>
<para>
If the version of Wine you want does not exist in package form,
you can download the source code yourself and compile it on your
machine. Although this might seem a little intimidating at
first if you've never done it, you'll find that it'll often go
quite smoothly, especially on the newer Linux distributions.
</para>
<para>
The safest way to grab the source is from one of the official
FTP archives. An up to date listing is in the <ulink
url="http://www.winehq.com/source/ANNOUNCE">ANNOUNCE </ulink>
file in the Wine distribution (which you would have if you
already downloaded it). Here is a (possibly out of date) list
of FTP servers carrying Wine:
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="ftp://metalab.unc.edu/pub/Linux/ALPHA/wine/development/">
ftp://metalab.unc.edu/pub/Linux/ALPHA/wine/development/
</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="ftp://tsx-11.mit.edu/pub/linux/ALPHA/Wine/development/">
ftp://tsx-11.mit.edu/pub/linux/ALPHA/Wine/development/
</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="ftp://ftp.infomagic.com/pub/mirrors/linux/sunsite/ALPHA/wine/development/">
ftp://ftp.infomagic.com/pub/mirrors/linux/sunsite/ALPHA/wine/development/
</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="ftp://orcus.progsoc.uts.edu.au/pub/Wine/development/">
ftp://orcus.progsoc.uts.edu.au/pub/Wine/development/
</ulink>
</para>
</listitem>
</itemizedlist>
<para>
The official releases are tagged by date with the format
"Wine-YYYYMMDD.tar.gz". Your best bet is to grab the latest
one.
</para>
<para>
FIXME: Explain how to un-tar, compile, and install Wine from a tarball.
</para>
<para></para>
</sect1>
<sect1 id="getting-source-cvs">
<title>Getting Wine Source Code from CVS</title>
<para>
The official web page for Wine CVS is
<ulink url="http://www.winehq.com/dev.html">
http://www.winehq.com/dev.html</ulink>.
</para>
<para>
First, you need to get a copy of the latest Wine sources
using CVS. You can tell it where to find the source tree by
setting the <envar>CVSROOT</envar> environment variable. You
also have to log in anonymously to the wine CVS server. In
<command>bash</command>, it might look something like this:
</para>
<screen>
$ export CVSROOT=:pserver:cvs@cvs.winehq.com:/home/wine
$ cvs login
Password: cvs
$ cvs checkout wine
</screen>
<para>
That'll pull down the entire Wine source tree from
winehq.com and place it in the current directory (actually
in the 'wine' subdirectory). CVS has a million command line
parameters, so there are many ways to pull down files, from
anywhere in the revision history. Later, you can grab just
the updates:
</para>
<screen>
$ cvs -dP update
</screen>
<para>
<command>cvs update</command> works from inside the source tree.
You don't need the <envar>CVSROOT</envar> environment variable
to run it either. You just have to be inside the source tree.
The <parameter>-d</parameter> and <parameter>-P</parameter>
options make sure your local Wine tree directory structure stays
in sync with the remote repository.
</para>
<para>
After you've made changes, you can create a patch with
<command>cvs diff -u</command>, which sends output to stdout
(the <parameter>-u</parameter> controls the format of the
patch). So, to create an <filename>my_patch.diff</filename>
file, you would do this:
</para>
<screen>
$ cvs diff -u > my_patch.diff
</screen>
<para>
You can call <command>cvs diff</command> from anywhere in the
tree (just like <command>cvs update</command>), and it will
always grab recursively from that point. You can also specify
single files or subdirectories:
</para>
<screen>
$ cvs diff -u dlls/winaspi > my_aspi_patch.diff
</screen>
<para>
Experiment around a little. It's fairly intuitive.
</para>
</sect1>
<sect1 id="getting-upgrading">
<title>Upgrading Wine with a Patch</title>
<para>
If you have the Wine source code, as opposed to a binary
distribution, you have the option of applying patches to the
source tree to fix bugs and add experimental features.
Perhaps you've found a bug, reported it to the <ulink
url="mailto:wine-devel@winehq.com">Wine mailing list</ulink>,
and received a patch file to fix the bug. You can apply the
patch with the <command>patch</command> command, which takes a
streamed patch from <filename>stdin</filename>:
</para>
<screen>
$ cd wine
$ patch -p0 < ../patch_to_apply.diff
</screen>
<para>
To remove the patch, use the <parameter>-R</parameter> option:
</para>
<screen>
$ patch -p0 -R < ../patch_to_apply.diff
</screen>
<para>
If you want to do a test run to see if the patch will apply
successfully (e.g., if the patch was created from an older or
newer version of the tree), you can use the
<parameter>--dry-run</parameter> parameter to run the patch
without writing to any files:
</para>
<screen>
$ patch -p0 --dry-run < ../patch_to_apply.diff
</screen>
<para>
<command>patch</command> is pretty smart about extracting
patches from the middle of a file, so if you save an email with
an inlined patch to a file on your hard drive, you can invoke
patch on it without stripping out the email headers and other
text. <command>patch</command> ignores everything that doesn't
look like a patch.
</para>
<para>
FIXME: Go into more depth about the -p0 option...
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

8
documentation/i18n.sgml
View File

@ -5,12 +5,13 @@
<title>Adding New Languages</title>
<para>
written by Morten Welinder, January 1996.
Written by &name-morten-welinder; <email>&email-morten-welinder;</email>,
January 1996.
</para>
<itemizedlist>
<listitem>
<para>Thereafter revised Februari 1999 by Klaas van Gend</para>
<para>Thereafter revised February 1999 by Klaas van Gend</para>
</listitem>
<listitem>
<para>Revised again May 23, 1999, Klaas van Gend</para>
@ -37,6 +38,7 @@
<member>Japanese</member>
<member>Romanian</member>
<member>Croatian</member>
<member>Slovak</member>
<member>Turkish</member>
<member>Slovanian</member>
</simplelist>
@ -196,6 +198,6 @@
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

8
documentation/implementation.sgml
View File

@ -6,7 +6,7 @@
<title>Builtin DLLs</title>
<para>
written by &lt;juergen.schmied@metronet.de>
Written by &name-juergen-schmied; <email>&email-juergen-schmied;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/internal-dll</filename>)
@ -195,7 +195,7 @@ WORD cmd;
<title>File Handles</title>
<para>
written by (???)
Written by (???)
</para>
<para>
(Extracted from <filename>wine/documentation/filehandles</filename>)
@ -260,7 +260,7 @@ WORD cmd;
<title>Doing A Hardware Trace In Wine</title>
<para>
written by Jonathan Buzzard &lt;jab@hex.prestel.co.uk>
Written by &name-jonathan-buzzard; <email>&email-jonathan-buzzard;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/ioport-trace-hints</filename>)
@ -530,6 +530,6 @@ EOF
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

87
documentation/installing.sgml
View File

@ -1,12 +1,13 @@
<chapter id="installing">
<title>Installing Wine</title>
<title>Installing/compiling Wine</title>
<para>How to install Wine...</para>
<sect1 id="replace-windows">
<sect1 id="replace-windows" xreflabel="--Installing Section--">
<title>WWN #52 Feature: Replacing Windows</title>
<para>
Written by Ove Kåven <email>ovek@winehq.com</email>
Written by &name-ove-kaaven; <email>&email-ove-kaaven;</email>
</para>
<sect2>
@ -197,7 +198,7 @@ Filesystem=win95
<sect1 id="no-windows">
<title>Installing Wine Without Windows</title>
<para>
written by ???
Written by &name-james-juran; <email>&email-james-juran;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/no-windows</filename>)
@ -206,7 +207,7 @@ Filesystem=win95
<para>
A major goal of Wine is to allow users to run Windows programs
without having to install Windows on their machine. Wine
implements the functionality of the main DLL's usually
implements the functionality of the main DLLs usually
provided with Windows. Therefore, once Wine is finished, you
will not need to have windows installed to use Wine.
</para>
@ -259,7 +260,7 @@ Filesystem=win95
<para>
Because Wine is not yet complete, some programs will work
better with native Windows DLL's than with Wine's
better with native Windows DLLs than with Wine's
replacements. Wine has been designed to make this possible.
Here are some tips by Juergen Schmied (and others) on how to
proceed. This assumes that your
@ -275,7 +276,7 @@ Filesystem=win95
<para>
Run the application with <parameter>--debugmsg
+module,+file</parameter> to find out which files are
needed. Copy the required DLL's one by one to the
needed. Copy the required DLLs one by one to the
<filename>C:\windows\system</filename> directory. Do not
copy KERNEL/KERNEL32, GDI/GDI32, or USER/USER32. These
implement the core functionality of the Windows API, and
@ -288,13 +289,13 @@ Filesystem=win95
<filename>wine.conf</filename> or
<filename>.winerc</filename> to specify
<quote>native</quote> before <quote>builtin</quote> for
the Windows DLL's you want to use. For more information
the Windows DLLs you want to use. For more information
about this, see the Wine manpage.
</para>
</listitem>
<listitem>
<para>
Note that some network DLL's are not needed even though
Note that some network DLLs are not needed even though
Wine is looking for them. The Windows
<filename>MPR.DLL</filename> currently does not work; you
must use the internal implementation.
@ -303,7 +304,7 @@ Filesystem=win95
<listitem>
<para>
Copy SHELL/SHELL32 and COMDLG/COMDLG32 COMMCTRL/COMCTL32
only as pairs to your Wine directory (these DLL's are
only as pairs to your Wine directory (these DLLs are
<quote>clean</quote> to use). Make sure you have these
specified in the <quote>[DllPairs]</quote> section of
<filename>wine.conf</filename> or .winerc.
@ -311,18 +312,18 @@ Filesystem=win95
</listitem>
<listitem>
<para>
Be consistent: Use only DLL's from the same Windows version
Be consistent: Use only DLLs from the same Windows version
together.
</para>
</listitem>
<listitem>
<para>
Put <filename>regedit.exe</filename> in the
<filename>C:\windows</filename> directory
(<application>office95</application> imports a
<filename>*.reg</filename> file when it runs with a empty
<filename>C:\windows</filename> directory.
(<application>Office 95</application> imports a
<filename>*.reg</filename> file when it runs with an empty
registry, don't know about
<application>office97</application>).
<application>Office 97</application>).
</para>
</listitem>
<listitem>
@ -338,7 +339,7 @@ Filesystem=win95
<sect1 id="vfat">
<title>Dealing With FAT/VFAT Partitions</title>
<para>
written by Steven Elliott (elliotsl@mindspring.com)
Written by &name-steven-elliott; <email>&email-steven-elliott;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/linux-fat-permissions</filename>)
@ -381,11 +382,11 @@ Type=hd
</para>
<para>
Most modern Linux distributions either detect or allow
existing FAT file systems to be configured so that can be
existing FAT file systems to be configured so that they can be
mounted, in a location such as <filename>/c</filename>,
either persistently (on bootup) or on an as needed basis. In
either case, by default, the permissions will probably be
configured so that they look something like:
configured so that they look like:
</para>
<screen>
<prompt>~></prompt><userinput>cd /c</userinput>
@ -403,7 +404,7 @@ drwxr-xr-x 41 root root 16384 Dec 30 1998 windows</computeroutput>
filesystem.
</para>
<para>
There three major approaches to overcoming the restrictive
There are three major approaches to overcoming the restrictive
permissions mentioned in the previous paragraph:
</para>
<orderedlist>
@ -524,7 +525,7 @@ drwxrwxr-x 41 sle sle 16384 Dec 30 1998 windows</computeroutput>
Shadowing provides a finer granularity of control. Parts of
the original FAT filesystem can be copied so that the
application can safely work with those copied parts while
the application continue to directly read the remaining
the application continues to directly read the remaining
parts. This is done with symbolic links. For example,
consider a system where an application named
<application>AnApp</application> must be able to read and
@ -558,7 +559,8 @@ drwxrwxr-x 41 sle sle 16384 Dec 30 1998 windows</computeroutput>
<sect1 id="scsi-support">
<title>SCSI Support</title>
<para>
written by Bruce Milner; Additions by Andreas Mohr
Written by &name-bruce-milner; <email>&email-bruce-milner;</email>;
Additions by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/aspi</filename>)
@ -586,18 +588,19 @@ THIS MAY TRASH YOUR SYSTEM IF USED CORRECTLY
to it to the SCSI bus.
</para>
<para>
If you use the wrong scsi device in your setup file, you can send
If you use the wrong SCSI device in your setup file, you can send
completely bogus commands to the wrong device - An example would be
formatting your hard drives (assuming the device gave you permission -
if you're running as root, all bets are off).
</para>
<para>
So please make sure that **all** SCSI devices not needed by the program
So please make sure that <emphasis>all</emphasis> SCSI devices not needed by the program
have their permissions set as restricted as possible !
</para>
<para>
Cookbook for setting up scanner: (At least how mine is to work)
(well, for other devices such as CD burners, MO drives, ..., too)
</para>
<sect2>
@ -628,20 +631,27 @@ THIS MAY TRASH YOUR SYSTEM IF USED CORRECTLY
<orderedlist>
<listitem>
<para>
Your scsi card must be supported under linux. This will
not work with an unknown scsi card. Even for cheap'n
Your SCSI card must be supported under linux. This will
not work with an unknown SCSI card. Even for cheap'n
crappy "scanner only" controllers some special Linux
drivers exist on the net.
If you intend to use your IDE device, you need to use the
ide-scsi emulation.
Read
<ulink url="http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html">
http://www.linuxdoc.org/HOWTO/CD-Writing-HOWTO.html</ulink>
for ide-scsi setup instructions.
</para>
</listitem>
<listitem>
<para>
Compile generic scsi drivers into your kernel.
Compile generic SCSI drivers into your kernel.
</para>
</listitem>
<listitem>
<para>
Linux by default uses smaller scsi buffers than Windows.
This seems to be not required any more for newer (2.2.x) kernels:
Linux by default uses smaller SCSI buffers than Windows.
There is a kernel build define <literal>SG_BIG_BUFF</literal> (in
<filename>sg.h</filename>) that is by default set too
low. The SANE project recommends
@ -651,9 +661,11 @@ THIS MAY TRASH YOUR SYSTEM IF USED CORRECTLY
</listitem>
<listitem>
<para>
Make the devices for the scanner (generic scsi devices)
- look at the scsi programming how-to for device
numbering.
Make the devices for the scanner (generic SCSI devices)
- look at the SCSI programming HOWTO at
<ulink url="http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html">
http://www.linuxdoc.org/HOWTO/SCSI-Programming-HOWTO.html</ulink>
for device numbering.
</para>
</listitem>
<listitem>
@ -661,16 +673,17 @@ THIS MAY TRASH YOUR SYSTEM IF USED CORRECTLY
I would recommend making the scanner device writable by
a group. I made a group called
<literal>scanner</literal> and added myself to it.
Running as root increases your risk of sending bad scsi
Running as root increases your risk of sending bad SCSI
commands to the wrong device. With a regular user, you
are better protected.
</para>
</listitem>
<listitem>
<para>
Add a scsi device entry for your particular scanner to
wine.conf. The format is <literal>[scsi
cCtTdD]</literal> where
For Win32 software (WNASPI32), Wine has auto-detection in place.
For Win16 software (WINASPI), you need to add a SCSI device entry
for your particular scanner to wine.conf. The format is
<literal>[scsi cCtTdD]</literal> where
<literal>C=controller</literal>,
<literal>T=target</literal>, <literal>D=LUN</literal>
</para>
@ -727,14 +740,14 @@ ipplus.exe &lt;---> (TWAIN INTERFACE) &lt;---> (TWAIN DATA SOURCE . ASPI) -> WIN
</listitem>
<listitem>
<para>
a Fujitsu M2513A MO drive (640MB) using generic scsi
a Fujitsu M2513A MO drive (640MB) using generic SCSI
drivers. Formatting and ejecting worked perfectly.
Thanks to Uwe Bonnes for access to the hardware ! [AM]
</para>
</listitem>
</itemizedlist>
<para>
I make no warranty to the aspi code. It makes my scanner
I make no warranty to the ASPI code. It makes my scanner
work. Your devices may explode. I have no way of determining
this. I take zero responsibility!
</para>
@ -746,6 +759,6 @@ ipplus.exe &lt;---> (TWAIN INTERFACE) &lt;---> (TWAIN DATA SOURCE . ASPI) -> WIN
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

259
documentation/introduction.sgml 100644
View File

@ -0,0 +1,259 @@
<chapter id="introduction">
<title>Introduction</title>
<sect1 id="what-is-wine">
<title>What is Wine?</title>
<para>
Written by &name-john-sheets; <email>&email-john-sheets;</email>
</para>
<sect2>
<title>Windows and Linux</title>
<!-- general description of wine, what does it do? -->
<para>
Many people have faced the frustration of owning software that
won't run on their computer. With the recent popularity of
Linux, this is happening more and more often because of
differing operating systems. Your Windows software won't run
on Linux, and your Linux software won't run in Windows.
</para>
<para>
A common solution to this problem is to install both operating
systems on the same computer, as a <quote>dual boot</quote>
system. If you want to write a document in MS Word, you can
boot up in Windows; if you want to run the GnuCash, the GNOME
financial application, you can shut down your Windows session
and reboot into Linux. The problem with this is that you
can't do both at the same time. Each time you switch back and
forth between MS Word and GnuCash, you have to reboot again.
This can get tiresome quickly.
</para>
<para>
Life would be so much easier if you could run all your
applications on the same system, regardless of whether they
are written for Windows or for Linux. On Windows, this isn't
really possible.
<footnote>
<para>
Technically, if you have two networked computers, one
running Windows and the other running Linux, and if you
have some sort of X server software running on the Windows
system, you can export Linux applications onto the Windows
system. Unfortunately, most decent win32 X servers are
commercial products, many of which cost quite a lot.
However, this doesn't solve the problem if you only own
one computer system.
</para>
</footnote>
However, Wine makes it possible to run native Windows
applications alongside native Linux applications on a Linux
(or Solaris) system. You can share desktop space between MS
Word and GnuCash, overlapping their windows, iconizing them,
and even running them from the same launcher.
</para>
</sect2>
<sect2>
<title>Emulation versus Native Linking</title>
<!-- emulator vs. Winelib -->
<para>
Wine is a UNIX implementation of the win32 libraries,
written from scratch by hundreds of volunteer developers and
released under an open source license. Anyone can download
and read through the source code, and fix bugs that arise.
The Wine community is full of richly talented programmers
who have spent thousands of hours of personal time on
improving Wine so that it works well with the win32
<firstterm>Applications Programming Interface</firstterm>
(API), and keeps pace with new developments from Microsoft.
</para>
<para>
Wine can run applications in two discrete ways: as
pre-compiled Windows binaries, or as natively compiled X11
(X Window System) applications. The former method uses
emulation to connect a Windows application to the Wine
libraries. You can run your Windows application directly
with the emulator, by installing through Wine or by simply
copying the Windows executables onto your Linux system.
</para>
<para>
The other way to run Windows applications with Wine requires
that you have the source code for the application. Instead
of compiling it with native Windows compilers, you can
compile it with a native Linux compiler --
<command>gcc</command> for example -- and link in the Wine
Libraries as you would with any other native UNIX
application. These natively linked applications are
referred to as Winelib applications.
</para>
<para>
The Wine Users Guide will focus on running precompiled
Windows applications using the Wine emulator.
<ulink url="http://wine.codeweavers.com/docs/winelib-user/">
The Winelib Users Guide</ulink> will cover Winelib
applications.
</para>
<!-- the development model -->
<para>
</para>
</sect2>
</sect1>
<!-- *** Not really useful as is, but may be able to recycle this elsewhere...
<sect1 id="getting-started">
<title>Getting started</title>
<para>
Written by &name-john-sheets; <email>&email-john-sheets;</email>
</para>
<para>
Wine can be pretty intimidating at first. The Wine
distribution consists of over two thousand files and half a
million lines of source code
<footnote>
<para>Crudely calculated from running <command>find . | wc
-l</command> and <command>cat `find . -name "*.c"` | wc
-l</command>, respectively, from a fresh CVS checkout.</para>
</footnote>,
and is probably one of the steepest learning curves in the
open source world. This chapter will give you a crash course
in the important topics you need to know to get started with
running Wine applications.
</para>
</sect1>
-->
<sect1 id="wine-stats">
<title>Wine Requirements and Features</title>
<para>
Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
</para>
<sect2 id="system-requirements">
<title>System requirements</title>
<para>
In order to run Wine, you need the following:
</para>
<para>
<itemizedlist>
<listitem>
<para>
a computer ;-) Wine: only PCs >= i386 are supported at
the moment. Winelib: other platforms might be
supported, but can be tricky.
</para>
</listitem>
<listitem>
<para>
a UNIX-like operating system such as Linux, *BSD,
Solaris x86
</para>
</listitem>
<listitem>
<para>
>= 16MB of RAM. Everything below is pretty much
unusable. >= 64 MB is needed for a "good" execution.
</para>
</listitem>
<listitem>
<para>
an X11 window system (XFree86 etc.). Wine is prepared
for other graphics display drivers, but writing
support is not too easy. The text console display
driver is nearly usable.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2 id="wine-capabilities">
<title>Wine capabilities</title>
<para>
Now that you hopefully managed to fulfill the requirements
mentioned above, we tell you what Wine is able to do/support:
</para>
<para>
<itemizedlist>
<listitem>
<para>
Support for executing DOS, Win 3.x and Win9x/NT/Win2000
programs (most of Win32's controls are supported)
</para>
</listitem>
<listitem>
<para>
Optional use of external vendor DLLs (e.g. original
Windows DLLs)
</para>
</listitem>
<listitem>
<para>
X11-based graphics display (remote display to any X
terminal possible), text mode console
</para>
</listitem>
<listitem>
<para>
Desktop-in-a-box or mixable windows
</para>
</listitem>
<listitem>
<para>
Pretty advanced DirectX support for games
</para>
</listitem>
<listitem>
<para>
Good support for sound, alternative input devices
</para>
</listitem>
<listitem>
<para>
Printing: supports native Win16 printer drivers,
Internal PostScript driver
</para>
</listitem>
<listitem>
<para>
Modems, serial devices are supported
</para>
</listitem>
<listitem>
<para>
Winsock TCP/IP networking
</para>
</listitem>
<listitem>
<para>
ASPI interface (SCSI) support for scanners, CD writers,
...
</para>
</listitem>
<listitem>
<para>
Unicode support, relatively advanced language support
</para>
</listitem>
<listitem>
<para>
Wine debugger and configurable trace logging messages
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

397
documentation/ole.sgml 100644
View File

@ -0,0 +1,397 @@
<chapter id="ole">
<title>COM/OLE in Wine</title>
<sect1 id="ole-architecture">
<title>COM/OLE Architecture in Wine</title>
<para>
The section goes into detail about how COM/OLE2 are
implemented in Wine.
</para>
</sect1>
<sect1 id="ole-binary">
<title>Using Binary OLE components in Wine</title>
<para>
This section describes how to import pre-compiled COM/OLE
components...
</para>
</sect1>
<sect1 id="com-writing">
<title>Writing OLE Components for Wine</title>
<para>
Based on the comments in <filename>wine/include/wine/obj_base.h</filename>.
</para>
<para>
This section describes how to create your own natively
compiled COM/OLE components.
</para>
<sect2>
<title>Macros to define a COM interface</title>
<para>
The goal of the following set of definitions is to provide a
way to use the same header file definitions to provide both
a C interface and a C++ object oriented interface to COM
interfaces. The type of interface is selected automatically
depending on the language but it is always possible to get
the C interface in C++ by defining CINTERFACE.
</para>
<para>
It is based on the following assumptions:
</para>
<itemizedlist>
<listitem>
<para>
all COM interfaces derive from IUnknown, this should not
be a problem.
</para>
</listitem>
<listitem>
<para>
the header file only defines the interface, the actual
fields are defined separately in the C file implementing
the interface.
</para>
</listitem>
</itemizedlist>
<para>
The natural approach to this problem would be to make sure
we get a C++ class and virtual methods in C++ and a
structure with a table of pointer to functions in C.
Unfortunately the layout of the virtual table is compiler
specific, the layout of g++ virtual tables is not the same
as that of an egcs virtual table which is not the same as
that generated by Visual C+. There are workarounds to make
the virtual tables compatible via padding but unfortunately
the one which is imposed to the WINE emulator by the Windows
binaries, i.e. the Visual C++ one, is the most compact of
all.
</para>
<para>
So the solution I finally adopted does not use virtual
tables. Instead I use inline non virtual methods that
dereference the method pointer themselves and perform the
call.
</para>
<para>
Let's take Direct3D as an example:
</para>
<programlisting>#define ICOM_INTERFACE IDirect3D
#define IDirect3D_METHODS \
ICOM_METHOD1(HRESULT,Initialize, REFIID,) \
ICOM_METHOD2(HRESULT,EnumDevices, LPD3DENUMDEVICESCALLBACK,, LPVOID,) \
ICOM_METHOD2(HRESULT,CreateLight, LPDIRECT3DLIGHT*,, IUnknown*,) \
ICOM_METHOD2(HRESULT,CreateMaterial,LPDIRECT3DMATERIAL*,, IUnknown*,) \
ICOM_METHOD2(HRESULT,CreateViewport,LPDIRECT3DVIEWPORT*,, IUnknown*,) \
ICOM_METHOD2(HRESULT,FindDevice, LPD3DFINDDEVICESEARCH,, LPD3DFINDDEVICERESULT,)
#define IDirect3D_IMETHODS \
IUnknown_IMETHODS \
IDirect3D_METHODS
ICOM_DEFINE(IDirect3D,IUnknown)
#undef ICOM_INTERFACE
#ifdef ICOM_CINTERFACE
// *** IUnknown methods *** //
#define IDirect3D_QueryInterface(p,a,b) ICOM_CALL2(QueryInterface,p,a,b)
#define IDirect3D_AddRef(p) ICOM_CALL (AddRef,p)
#define IDirect3D_Release(p) ICOM_CALL (Release,p)
// *** IDirect3D methods *** //
#define IDirect3D_Initialize(p,a) ICOM_CALL1(Initialize,p,a)
#define IDirect3D_EnumDevices(p,a,b) ICOM_CALL2(EnumDevice,p,a,b)
#define IDirect3D_CreateLight(p,a,b) ICOM_CALL2(CreateLight,p,a,b)
#define IDirect3D_CreateMaterial(p,a,b) ICOM_CALL2(CreateMaterial,p,a,b)
#define IDirect3D_CreateViewport(p,a,b) ICOM_CALL2(CreateViewport,p,a,b)
#define IDirect3D_FindDevice(p,a,b) ICOM_CALL2(FindDevice,p,a,b)
#endif</programlisting>
<para>
Comments:
</para>
<para>
The ICOM_INTERFACE macro is used in the ICOM_METHOD macros
to define the type of the 'this' pointer. Defining this
macro here saves us the trouble of having to repeat the
interface name everywhere. Note however that because of the
way macros work, a macro like ICOM_METHOD1 cannot use
'ICOM_INTERFACE##_VTABLE' because this would give
'ICOM_INTERFACE_VTABLE' and not 'IDirect3D_VTABLE'.
</para>
<para>
ICOM_METHODS defines the methods specific to this
interface. It is then aggregated with the inherited methods
to form ICOM_IMETHODS.
</para>
<para>
ICOM_IMETHODS defines the list of methods that are
inheritable from this interface. It must be written manually
(rather than using a macro to generate the equivalent code)
to avoid macro recursion (which compilers don't like).
</para>
<para>
The ICOM_DEFINE finally declares all the structures
necessary for the interface. We have to explicitly use the
interface name for macro expansion reasons again. Inherited
methods are inherited in C by using the IDirect3D_METHODS
macro and the parent's Xxx_IMETHODS macro. In C++ we need
only use the IDirect3D_METHODS since method inheritance is
taken care of by the language.
</para>
<para>
In C++ the ICOM_METHOD macros generate a function prototype
and a call to a function pointer method. This means using
once 't1 p1, t2 p2, ...' and once 'p1, p2' without the
types. The only way I found to handle this is to have one
ICOM_METHOD macro per number of parameters and to have it
take only the type information (with const if necessary) as
parameters. The 'undef ICOM_INTERFACE' is here to remind
you that using ICOM_INTERFACE in the following macros will
not work. This time it's because the ICOM_CALL macro
expansion is done only once the 'IDirect3D_Xxx' macro is
expanded. And by that time ICOM_INTERFACE will be long gone
anyway.
</para>
<para>
You may have noticed the double commas after each parameter
type. This allows you to put the name of that parameter
which I think is good for documentation. It is not required
and since I did not know what to put there for this example
(I could only find doc about IDirect3D2), I left them blank.
</para>
<para>
Finally the set of 'IDirect3D_Xxx' macros is a standard set
of macros defined to ease access to the interface methods in
C. Unfortunately I don't see any way to avoid having to
duplicate the inherited method definitions there. This time
I could have used a trick to use only one macro whatever the
number of parameters but I prefered to have it work the same
way as above.
</para>
<para>
You probably have noticed that we don't define the fields we
need to actually implement this interface: reference count,
pointer to other resources and miscellaneous fields. That's
because these interfaces are just that: interfaces. They may
be implemented more than once, in different contexts and
sometimes not even in Wine. Thus it would not make sense to
impose that the interface contains some specific fields.
</para>
</sect2>
<sect2>
<title>Bindings in C</title>
<para>
In C this gives:
</para>
<programlisting>typedef struct IDirect3DVtbl IDirect3DVtbl;
struct IDirect3D {
IDirect3DVtbl* lpVtbl;
};
struct IDirect3DVtbl {
HRESULT (*fnQueryInterface)(IDirect3D* me, REFIID riid, LPVOID* ppvObj);
ULONG (*fnAddRef)(IDirect3D* me);
ULONG (*fnRelease)(IDirect3D* me);
HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
};
#ifdef ICOM_CINTERFACE
// *** IUnknown methods *** //
#define IDirect3D_QueryInterface(p,a,b) (p)->lpVtbl->fnQueryInterface(p,a,b)
#define IDirect3D_AddRef(p) (p)->lpVtbl->fnAddRef(p)
#define IDirect3D_Release(p) (p)->lpVtbl->fnRelease(p)
// *** IDirect3D methods *** //
#define IDirect3D_Initialize(p,a) (p)->lpVtbl->fnInitialize(p,a)
#define IDirect3D_EnumDevices(p,a,b) (p)->lpVtbl->fnEnumDevice(p,a,b)
#define IDirect3D_CreateLight(p,a,b) (p)->lpVtbl->fnCreateLight(p,a,b)
#define IDirect3D_CreateMaterial(p,a,b) (p)->lpVtbl->fnCreateMaterial(p,a,b)
#define IDirect3D_CreateViewport(p,a,b) (p)->lpVtbl->fnCreateViewport(p,a,b)
#define IDirect3D_FindDevice(p,a,b) (p)->lpVtbl->fnFindDevice(p,a,b)
#endif</programlisting>
<para>
Comments:
</para>
<para>
IDirect3D only contains a pointer to the IDirect3D
virtual/jump table. This is the only thing the user needs to
know to use the interface. Of course the structure we will
define to implement this interface will have more fields but
the first one will match this pointer.
</para>
<para>
The code generated by ICOM_DEFINE defines both the structure
representing the interface and the structure for the jump
table. ICOM_DEFINE uses the parent's Xxx_IMETHODS macro to
automatically repeat the prototypes of all the inherited
methods and then uses IDirect3D_METHODS to define the
IDirect3D methods.
</para>
<para>
Each method is declared as a pointer to function field in
the jump table. The implementation will fill this jump table
with appropriate values, probably using a static variable,
and initialize the lpVtbl field to point to this variable.
</para>
<para>
The IDirect3D_Xxx macros then just derefence the lpVtbl
pointer and use the function pointer corresponding to the
macro name. This emulates the behavior of a virtual table
and should be just as fast.
</para>
<para>
This C code should be quite compatible with the Windows
headers both for code that uses COM interfaces and for code
implementing a COM interface.
</para>
</sect2>
<sect2>
<title>Bindings in C++</title>
<para>
And in C++ (with gcc's g++):
</para>
<programlisting>typedef struct IDirect3D: public IUnknown {
private: HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
public: inline HRESULT Initialize(REFIID a) { return ((IDirect3D*)t.lpVtbl)->fnInitialize(this,a); };
private: HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
public: inline HRESULT EnumDevices(LPD3DENUMDEVICESCALLBACK a, LPVOID b)
{ return ((IDirect3D*)t.lpVtbl)->fnEnumDevices(this,a,b); };
private: HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
public: inline HRESULT CreateLight(LPDIRECT3DLIGHT* a, IUnknown* b)
{ return ((IDirect3D*)t.lpVtbl)->fnCreateLight(this,a,b); };
private: HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
public: inline HRESULT CreateMaterial(LPDIRECT3DMATERIAL* a, IUnknown* b)
{ return ((IDirect3D*)t.lpVtbl)->fnCreateMaterial(this,a,b); };
private: HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
public: inline HRESULT CreateViewport(LPDIRECT3DVIEWPORT* a, IUnknown* b)
{ return ((IDirect3D*)t.lpVtbl)->fnCreateViewport(this,a,b); };
private: HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
public: inline HRESULT FindDevice(LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b)
{ return ((IDirect3D*)t.lpVtbl)->fnFindDevice(this,a,b); };
};</programlisting>
<para>
Comments:
</para>
<para>
In C++ IDirect3D does double duty as both the virtual/jump
table and as the interface definition. The reason for this
is to avoid having to duplicate the mehod definitions: once
to have the function pointers in the jump table and once to
have the methods in the interface class. Here one macro can
generate both. This means though that the first pointer,
t.lpVtbl defined in IUnknown, must be interpreted as the
jump table pointer if we interpret the structure as the
interface class, and as the function pointer to the
QueryInterface method, t.fnQueryInterface, if we interpret
the structure as the jump table. Fortunately this gymnastic
is entirely taken care of in the header of IUnknown.
</para>
<para>
Of course in C++ we use inheritance so that we don't have to
duplicate the method definitions.
</para>
<para>
Since IDirect3D does double duty, each ICOM_METHOD macro
defines both a function pointer and a non-virtual inline
method which dereferences it and calls it. This way this
method behaves just like a virtual method but does not
create a true C++ virtual table which would break the
structure layout. If you look at the implementation of these
methods you'll notice that they would not work for void
functions. We have to return something and fortunately this
seems to be what all the COM methods do (otherwise we would
need another set of macros).
</para>
<para>
Note how the ICOM_METHOD generates both function prototypes
mixing types and formal parameter names and the method
invocation using only the formal parameter name. This is the
reason why we need different macros to handle different
numbers of parameters.
</para>
<para>
Finally there is no IDirect3D_Xxx macro. These are not
needed in C++ unless the CINTERFACE macro is defined in
which case we would not be here.
</para>
<para>
This C++ code works well for code that just uses COM
interfaces. But it will not work with C++ code implement a
COM interface. That's because such code assumes the
interface methods are declared as virtual C++ methods which
is not the case here.
</para>
</sect2>
<sect2>
<title>Implementing a COM interface.</title>
<para>
This continues the above example. This example assumes that
the implementation is in C.
</para>
<programlisting>typedef struct _IDirect3D {
void* lpVtbl;
// ...
} _IDirect3D;
static ICOM_VTABLE(IDirect3D) d3dvt;
// implement the IDirect3D methods here
int IDirect3D_fnQueryInterface(IDirect3D* me)
{
ICOM_THIS(IDirect3D,me);
// ...
}
// ...
static ICOM_VTABLE(IDirect3D) d3dvt = {
ICOM_MSVTABLE_COMPAT_DummyRTTIVALUE
IDirect3D_fnQueryInterface,
IDirect3D_fnAdd,
IDirect3D_fnAdd2,
IDirect3D_fnInitialize,
IDirect3D_fnSetWidth
};</programlisting>
<para>
Comments:
</para>
<para>
We first define what the interface really contains. This is
the _IDirect3D structure. The first field must of course be
the virtual table pointer. Everything else is free.
</para>
<para>
Then we predeclare our static virtual table variable, we
will need its address in some methods to initialize the
virtual table pointer of the returned interface objects.
</para>
<para>
Then we implement the interface methods. To match what has
been declared in the header file they must take a pointer to
a IDirect3D structure and we must cast it to an _IDirect3D
so that we can manipulate the fields. This is performed by
the ICOM_THIS macro.
</para>
<para>
Finally we initialize the virtual table.
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

47
documentation/opengl.sgml
View File

@ -1,15 +1,16 @@
<chapter id="opengl">
<title>Wine and OpenGL</title>
<para>
written by Lionel Ulmer &lt;lionel.ulmer@free.fr>, last modification : 2000/06/13
</para>
<para>
<para>
Written by &name-lionel-ulmer; <email>&email-lionel-ulmer;</email>,
last modification : 2000/06/13
</para>
<para>
(Extracted from <filename>wine/documentation/opengl</filename>)
</para>
</para>
<sect1 id="opengl-required">
<title>I What is needed to have OpenGL support in Wine</title>
<title>What is needed to have OpenGL support in Wine</title>
<para>
Basically, if you have a Linux OpenGL ABI compliant libGL
@ -29,7 +30,7 @@
</para>
<sect2>
<title>I.1 Header files</title>
<title>Header files</title>
<para>
The needed header files to build OpenGL support in Wine are :
@ -67,7 +68,7 @@
</sect2>
<sect2>
<title>I.2 OpenGL library thread-safety</title>
<title>OpenGL library thread-safety</title>
<para>
After that, the script checks if the OpenGL library relies
@ -96,7 +97,7 @@
</sect2>
<sect2>
<title>I.3 OpenGL library itself</title>
<title>OpenGL library itself</title>
<para>
To check for the presence of 'libGL' on the system, the
@ -107,7 +108,7 @@
</sect2>
<sect2>
<title>I.4 glXGetProcAddressARB function</title>
<title>glXGetProcAddressARB function</title>
<para>
The core of Wine's OpenGL implementation (at least for all
@ -130,7 +131,7 @@
</sect1>
<sect1 id="opengl-configure">
<title>II How to configure</title>
<title>How to configure</title>
<para>
Configuration is quite easy : once OpenGL support has been
@ -156,7 +157,7 @@ DesktopDoubleBuffered = Y
</sect1>
<sect1 id="opengl-works">
<title>III How it all works</title>
<title>How it all works</title>
<para>
The core OpenGL function calls are the same between Windows
@ -191,7 +192,7 @@ DesktopDoubleBuffered = Y
</para>
<sect2>
<title>III.1 The Windowing system integration</title>
<title>The Windowing system integration</title>
<para>
This integration is done at two levels :
@ -222,7 +223,7 @@ DesktopDoubleBuffered = Y
</sect2>
<sect2>
<title>III.2 The thunks</title>
<title>The thunks</title>
<para>
The thunks are the Wine code that does the calling
@ -315,10 +316,10 @@ DesktopDoubleBuffered = Y
</sect1>
<sect1 id="opengl-problems">
<title>IV Known problems - shortcomings</title>
<title>Known problems - shortcomings</title>
<sect2>
<title>IV.1 Missing GLU32.DLL</title>
<title>Missing GLU32.DLL</title>
<para>
GLU is a library that is layered upon OpenGL. There is a
@ -338,7 +339,7 @@ DesktopDoubleBuffered = Y
</sect2>
<sect2>
<title>IV.2 OpenGL not detected at configure time</title>
<title>OpenGL not detected at configure time</title>
<para>
See section (I) for a detailed explanation of the
@ -347,7 +348,7 @@ DesktopDoubleBuffered = Y
</sect2>
<sect2>
<title>IV.3 When running an OpenGL application, the screen flickers</title>
<title>When running an OpenGL application, the screen flickers</title>
<para>
See section (II) for how to create the context
@ -356,11 +357,11 @@ DesktopDoubleBuffered = Y
</sect2>
<sect2>
<title>IV.4 Wine gives me the following error message : </title>
<title>Wine gives me the following error message : </title>
<screen>
Extension defined in the OpenGL library but NOT in opengl_ext.c...
Please report (lionel.ulmer@free.fr) !
Please report (&email-lionel-ulmer;) !
</screen>
<para>
@ -398,12 +399,12 @@ Please report (lionel.ulmer@free.fr) !
<para>
If you have this, run with <parameter>--debugmsg
+opengl</parameter> and send me
<email>lionel.ulmer@free.fr</email> the TRACE.
<email>&email-lionel-ulmer;</email> the TRACE.
</para>
</sect2>
<sect2>
<title>IV.5 <filename>libopengl32.so</filename> is built but it is still not working</title>
<title><filename>libopengl32.so</filename> is built but it is still not working</title>
<para>
This may be caused by some missing functions required by
@ -453,6 +454,6 @@ gcc dummy.c -L/usr/local/lib -lwine -lopengl32
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

1291
documentation/packaging.sgml
View File

File diff suppressed because it is too large Load Diff

77
documentation/patches.sgml
View File

@ -1,11 +1,78 @@
<chapter id="patches">
<title>Submitting Patches</title>
<para>How to create patches, and where to send them...</para>
</chapter>
<chapter id="patches">
<title>Submitting Patches</title>
<para>
Written by &name-albert-den-haan; <email>&email-albert-den-haan;</email>
</para>
<sect1 id="patch-format">
<title>Patch Format</title>
<para>
Your patch should include:
</para>
<itemizedlist>
<listitem>
<para>
a description of what was wrong and what is now better
(and now broken :).
</para>
</listitem>
<listitem>
<para>
your contact information ( Name/Handle and e-mail )
</para>
</listitem>
<listitem>
<para>
the patch in <command>diff -u</command> format (it happens...)
</para>
</listitem>
</itemizedlist>
<para>
<command>cvs diff -u</command> works great for the common case
where a file is edited. However, if you add or remove a file
<command>cvs diff</command> will not report that correctly so
make sure you explicitly take care of this rare case.
</para>
<para>
For additions: mention that you have some new files and
include them as either separate attachments or by appending
<command>diff -Nu</command> of them to any <command>cvs diff
-u</command> output you may have.
</para>
<para>
For removals, list the files.
</para>
</sect1>
<sect1 id="patch-quality">
<title>Quality Assurance</title>
<para>
(Or, "How do I get Alexandre to apply my patch quickly so I
can build on it and it will not go stale?")
</para>
<para>
Make sure your patch applies to the current CVS head
revisions. If a bunch of patches are commited to CVS that may
affect whether your patch will apply cleanly then verify that
your patch does apply! <command>cvs update</command> is your
friend!
</para>
<para>
Save yourself some embarasment and run your patched code
against more than just your current test example. Experience
will tell you how much effort to apply here.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

6
documentation/porting.sgml
View File

@ -236,8 +236,8 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
<title>Running & Compiling WINE in OS/2</title>
<para>
written by Robert Pouliot &lt;krynos@clic.net&gt;, January 9, 1997
Written by &name-robert-pouliot; <email>&email-robert-pouliot;</email>,
January 9, 1997
</para>
<para>
(Extracted from <filename>wine/documentation/wine_os2</filename>)
@ -390,6 +390,6 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

15
documentation/printing.sgml
View File

@ -6,15 +6,14 @@
<title>Printing</title>
<para>
written by (???)
Written by &name-huw-davies; <email>&email-huw-davies;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/printing</filename>)
</para>
<para>
Printing in Wine can be done in one of two ways. Both of which are very
alpha.
Printing in Wine can be done in one of two ways. Both of which are pretty alpha.
</para>
<orderedlist>
<listitem>
@ -30,8 +29,8 @@
<para>
Note that at the moment WinPrinters (cheap, dumb printers that require
the host computer to explicitly control the head) will not work. It is
unclear whether they ever will.
the host computer to explicitly control the head) will not work with
their Windows printer drivers. It is unclear whether they ever will.
</para>
<sect2>
@ -93,7 +92,7 @@ LPT1:=foo.ps LPT2:=|lpr
<title>The Wine PostScript Driver</title>
<para>
written by Huw Davies <email>h.davies1@physics.ox.ac.uk</email>
Written by &name-huw-davies; <email>&email-huw-davies;</email>
</para>
<para>
(Extracted from <filename>wine/documentation/psdriver</filename>)
@ -251,7 +250,7 @@ ppdfile=/somewhere/file.ppd
Please contact me if you want to help so that we can avoid duplication.
</para>
<para>
Huw Davies <email>h.davies1@physics.ox.ac.uk</email>
&name-huw-davies; <email>&email-huw-davies;</email>
</para>
</sect2>
</sect1>
@ -260,6 +259,6 @@ ppdfile=/somewhere/file.ppd
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

2
documentation/registry.sgml
View File

@ -102,7 +102,7 @@
</sect2>
<sect2>
<title>Wine registry data filesr</title>
<title>Wine registry data files</title>
<para>
In the user's home directory, there is a subdirectory named

361
documentation/running.sgml
View File

@ -1,18 +1,373 @@
<chapter id="running">
<title>Running Wine</title>
<para>Explain the command-line options you can use to run Wine</para>
<para>
Written by &name-john-sheets; <email>&email-john-sheets;</email>
</para>
<sect1 id="running-wine">
<title>How to run Wine</title>
<para>
The first thing you need to do is...
Wine is a very complicated piece of software with many ways to
adjust how it runs. With very few exceptions, you can
activate the same set of features through the <link
linkend="configuring">configuration file </link> as you can
with command-line parameters. In this chapter, we'll briefly
discuss these parameters, and match them up with their
corresponding configuration variables.
</para>
<para>
You can invoke the <command>wine --help</command> command to
get a listing of all Wine's command-line parameters:
</para>
<para>
<screen>
Usage: ./wine [options] program_name [arguments]
Options:
--config name Specify config file to use
--debugmsg name Turn debugging-messages on or off
--desktop geom Use a desktop window of the given geometry
--display name Use the specified display
--dll name Enable or disable built-in DLLs
--dosver x.xx DOS version to imitate (e.g. 6.22)
Only valid with --winver win31
--help,-h Show this help message
--language xx Set the language (one of Br,Ca,Cs,Cy,Da,De,En,Eo,Es,Fi,Fr,Ga,Gd,Gv,
Hr,Hu,It,Ja,Ko,Kw,Nl,No,Pl,Pt,Sk,Sv,Ru,Wa)
--managed Allow the window manager to manage created windows
--synchronous Turn on synchronous display mode
--version,-v Display the Wine version
--winver Version to imitate (win95,nt40,win31,nt2k,win98,nt351,win30,win20)
</screen>
</para>
<para>
You can specify as many options as you want, if any.
Typically, you will want to have your configuration file set
up with a sensible set of defaults; in this case, you can run
<command>wine</command> without explicitly listing any
options. In rare cases, you might want to override certain
parameters on the command line. If you find yourself using
the same long set of command options with certain
applications, you might find it easier to work with multiple
config files, using the <link
linkend="config-parameter"><parameter>--config</parameter>
parameter</link> to specify a non-default configuration.
</para>
<para>
After the options, you should put the name of the file you
want <command>wine</command> to execute. If the executable is
in the <parameter>Path</parameter> parameter in the
configuration file, you can simply give the executable file
name. However, if the executable is not in
<parameter>Path</parameter>, you must give the full path to
the executable (in Windows format, not UNIX format!). For
example, given a <parameter>Path</parameter> of the following:
</para>
<screen>
[wine]
"Path"="c:\windows;c:\windows\system;e:\;e:\test;f:\"
</screen>
<para>
You could run the file
<filename>c:\windows\system\foo.exe</filename> with:
</para>
<screen>
<prompt>$</prompt> <userinput>wine foo.exe</userinput>
</screen>
<para>
However, you would have to run the file
<filename>c:\myapps\foo.exe</filename> with this command:
</para>
<screen>
<prompt>$</prompt> <userinput>wine c:\myapps\foo.exe</userinput>
</screen>
<para>
Finally, if you want to pass any parameters to your windows
application, you can list them at the end, just after the
executable name. Thus, to run the imaginary
<command>foo.exe</command> Windows application with its
<parameter>/advanced</parameter> mode parameter, while
invoking Wine in <link
linkend="managed-parameter"><parameter>--managed</parameter>
mode</link>, you would do something like this:
</para>
<screen>
<prompt>$</prompt> <userinput>wine --managed foo.exe /advanced</userinput>
</screen>
<para>
In other words, options that affect Wine should come
<emphasis>before</emphasis> the Windows program name, while
options that affect the Windows program should come
<emphasis>after</emphasis> it.
</para>
</sect1>
<sect1 id="command-line-options">
<title>Command-Line Options</title>
<sect2 id="config-parameter">
<title>--config</title>
<para>
The <parameter>--config</parameter> parameter allows you to
specify which configuration file you want to use for the
current invocation of <command>wine</command>. For example,
if you like to run a specific application or set of
applications with a different array of options than your
normal defaults, you might set up a different config file
for them, and use the <parameter>--config</parameter> option
to make use of it.
</para>
<para>
The default value of <parameter>--config</parameter> is
<filename>~/.winerc</filename>. This value is hardwired
into the Wine source code. In future versions of Wine, the
default may change to <filename>~/.wine/conf</filename>.
</para>
</sect2>
<sect2>
<title>--debugmsg [channels]</title>
<para>
Wine isn't perfect, and many Windows applications still
don't run without bugs under Wine (but then, many of them
don't run without bugs under native Windows either!). To
make it easier for people to track down the causes behind
each bug, Wine provides a number of <firstterm>debug
channels</firstterm> that you can tap into.
</para>
<para>
Each debug channel, when activated, will trigger logging
messages to be displayed to the console where you invoked
<command>wine</command>. From there you can redirect the
messages to a file and examine it at your leisure. But be
forewarned! Some debug channels can generate incredible
volumes of log messages. Among the most prolific offenders
are <parameter>relay</parameter> which spits out a log
message every time a win32 function is called,
<parameter>win</parameter> which tracks windows message
passing, and of course <parameter>all</parameter> which is
an alias for every single debug channel that exists. For a
complex application, your debug logs can easily top 1 MB and
higher. A <parameter>relay</parameter> trace can often
generate more than 10 MB of log messages, depending on how
long you run the application. Logging does slow down Wine
quite a bit, so don't use <parameter>--debugmsg</parameter>
unless you really do want log files.
</para>
<para>
Within each debug channel, you can further specify a
<firstterm>message class</firstterm>, to filter out the
different severities of errors. The four message classes
are:
<simplelist type="inline">
<member><parameter>trace</parameter></member>
<member><parameter>fixme</parameter></member>
<member><parameter>warn</parameter></member>
<member><parameter>err</parameter></member>
</simplelist>.
</para>
<para>
To turn on a debug channel, use the form
<parameter>class+channel</parameter>. To turn it off, use
<parameter>class-channel</parameter>. To list more than one
channel in the same <parameter>--debugmsg</parameter>
option, separate them with commas. For example, to request
<parameter>warn</parameter> class messages in the
<parameter>heap</parameter> debug channel, you could invoke
<command>wine</command> like this:
</para>
<screen>
<prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
</screen>
<para>
If you leave off the message class, <command>wine</command>
will display messages from all four classes for that channel:
</para>
<screen>
<prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
</screen>
<para>
If you wanted to see log messages for everything except the
relay channel, you might do something like this:
</para>
<screen>
<prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
</screen>
<para>
Here is a master list of all the debug channels and classes
in Wine. More channels might be added to (or subtracted
from) later versions.
</para>
<screen>
all accel advapi animate aspi atom avifile bitblt
bitmap caret cdrom class clipboard clipping combo comboex
comm commctrl commdlg console crtdll cursor datetime dc
ddeml ddraw debug debugstr delayhlp dialog dinput dll
dosfs dosmem dplay driver dsound edit elfdll enhmetafile
event exec file fixup font gdi global graphics
header heap hook hotkey icmp icon imagehlp imagelist
imm int int10 int16 int17 int19 int21 int31
io ipaddress joystick key keyboard ldt listbox listview
local mci mcianim mciavi mcicda mcimidi mciwave mdi
menu message metafile midi mmaux mmio mmsys mmtime
module monthcal mpr msacm msg msvideo nativefont nonclient
ntdll odbc ole opengl pager palette pidl print
process profile progress prop propsheet psapi psdrv ras
rebar reg region relay resource richedit scroll segment
seh selector sendmsg server setupapi setupx shell snoop
sound static statusbar storage stress string syscolor system
tab tape tapi task text thread thunk timer
toolbar toolhelp tooltips trackbar treeview ttydrv tweak typelib
updown ver virtual vxd wave win win16drv win32
wing wininet winsock winspool wnet x11 x11drv
</screen>
<para>
For more details about debug channels, check out the
<ulink url="http://wine.codeweavers.com/docs/wine-devel/">
The Wine Developer's Guide</ulink>.
</para>
</sect2>
<sect2>
<title>--desktop [geometry]</title>
<para>
By default, <command>wine</command> runs applications on
your regular desktop. Wine application windows intermingle
with native X11 applications. Windows overlap each other,
and you can resize them in relation to each other.
Normally, when you minimize Wine windows, they collapse into
a small icon at the lower left corner of your desktop,
circumventing the behavior of your other non-Wine windows.
However, if you're running in <link linkend="managed-parameter">
--managed mode</link>, your Wine applications will minimize
just like your other windows.
</para>
<para>
Sometimes, you may want to restrict Wine windows to a
smaller area of your desktop. This is what the
<parameter>--desktop</parameter> option controls. Whenever
you pass this option to <command>wine</command>, it will
create a window of that size and use that as Wine's desktop
instead of borrowing the regular desktop space. Wine will
then place the application window inside the new desktop
window. If you minimize the application, it will iconize to
the bottom left corner of its own desktop window.
</para>
<para>
The <parameter>--desktop</parameter> option geometry info in
the standard X11 geometry format, e.g., "640x480" for a
desktop window 640 pixels wide and 480 pixels high. You can
also in theory specify the coordinates of the upper left
corner of the desktop window, but your window manager may
choose to override that request. The following invocation
would open a new 640 x 480 desktop window at coordinates
(10, 25):
<screen>
<prompt>$</prompt> <userinput>wine --desktop 640x480+10+25 foo.exe</userinput>
</screen>
</para>
<para>
More commonly, you'll leave off the starting coordinates,
and only use the height and width:
<screen>
<prompt>$</prompt> <userinput>wine --desktop 640x480 foo.exe</userinput>
</screen>
</para>
</sect2>
<sect2>
<title>--display</title>
<para>
By default, wine will display its windows on whichever X
Display you have in the <envar>$DISPLAY</envar> environment
variable. Often, <envar>$DISPLAY</envar> is set to
<literal>:0</literal>, which sends all windows to the
primary video monitor on the current host machine.
</para>
<para>
To send windows to a different monitor on the same system,
you could change <literal>:0</literal> to a different
number, for example <literal>:1</literal> to send output to
the second monitor. You can also specify other systems. If
you were logged into the system <systemitem
class="systemname">alpha</systemitem>, but wanted wine to
run on another system on the network, <systemitem
class="systemname">beta</systemitem>, you might use a
<envar>$DISPLAY</envar> of <literal>beta:0</literal>.
</para>
<para>
You can also declare display values on the wine command
line, using the <parameter>--display</parameter> option.
The last example above might look like this:
</para>
<programlisting>
<prompt>$</prompt> wine --display="beta:0" foo.exe
</programlisting>
</sect2>
<sect2>
<title>--dll</title>
<para>
</para>
</sect2>
<sect2>
<title>--dosver</title>
<para>
</para>
</sect2>
<sect2>
<title>--help</title>
<para>
</para>
</sect2>
<sect2>
<title>--language</title>
<para>
</para>
</sect2>
<sect2 id="managed-parameter">
<title>--managed</title>
<para>
</para>
</sect2>
<sect2>
<title>--synchronous</title>
<para>
</para>
</sect2>
<sect2>
<title>--version</title>
<para>
</para>
</sect2>
<sect2>
<title>--winver</title>
<para>
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
End:
-->

4
documentation/tools.sgml
View File

@ -5,7 +5,7 @@
<title>bin2res</title>
<para>
written by juergen.schmied@debitel.net (11/99)
Written by &name-juergen-schmied; <email>&email-juergen-schmied;</email> (11/99)
</para>
<para>
(Extracted from <filename>wine/documentation/resources</filename>)
@ -89,6 +89,6 @@ bash-2.03# ../../tools/bin2res -d bin shres.rc
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->

141
documentation/wine-doc.sgml
View File

@ -1,23 +1,31 @@
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!doctype set PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity running SYSTEM "running.sgml">
<!-- *** Include list of authors *** -->
<!entity % authors SYSTEM "authors.ent">
%authors;
<!-- *** Entities for Wine User Guide *** -->
<!entity introduction SYSTEM "introduction.sgml">
<!entity getting SYSTEM "getting.sgml">
<!entity installing SYSTEM "installing.sgml">
<!entity configuring SYSTEM "configuring.sgml">
<!entity registry SYSTEM "registry.sgml">
<!entity running SYSTEM "running.sgml">
<!entity bugs SYSTEM "bugs.sgml">
<!-- *** Not currently used (???) *** -->
<!entity fonts SYSTEM "fonts.sgml">
<!entity printing SYSTEM "printing.sgml">
<!-- *** Entities for Wine Developer Guide *** -->
<!entity compiling SYSTEM "compiling.sgml">
<!entity debugging SYSTEM "debugging.sgml">
<!entity documentation SYSTEM "documentation.sgml">
<!entity patches SYSTEM "patches.sgml">
<!entity i18n SYSTEM "i18n.sgml">
<!entity porting SYSTEM "porting.sgml">
<!entity packaging SYSTEM "packaging.sgml">
<!entity architecture SYSTEM "architecture.sgml">
<!entity ole SYSTEM "ole.sgml">
<!entity debugger SYSTEM "debugger.sgml">
<!entity consoles SYSTEM "consoles.sgml">
<!entity implementation SYSTEM "implementation.sgml">
@ -25,70 +33,95 @@
<!entity build SYSTEM "build.sgml">
<!entity tools SYSTEM "tools.sgml">
<!entity dlls SYSTEM "dlls.sgml">
<!entity status SYSTEM "status.sgml">
<!entity cvs-regression SYSTEM "cvs-regression.sgml">
<!-- *** Entities for Wine Developer Guide *** -->
<!entity winelib-user SYSTEM "winelib-user.sgml">
<!-- *** Entities for Wine Packager Guide *** -->
<!entity packaging SYSTEM "packaging.sgml">
]>
<book id="index">
<bookinfo>
<set id="index">
<setinfo>
<title>Wine Documentation</title>
</bookinfo>
<preface id="preface">
<title>Notes About this Document</title>
<para>
The following documentation has been extracted from the Wine
source tree, from the <filename>wine/documentation</filename>
directory. So far, no new content has been added aside from
marking it up for DocBook and a few minor tweaks to smooth
that process. All credit should go to the original authors,
who are attributed according the the "written by" comments
in those files. If I've missed anyone, please contact
<email>John R. Sheets &lt;jsheets@codeweavers.com></email>
</para>
</preface>
<releaseinfo>
<emphasis>
The following documentation has been extracted from the Wine
source tree, from the <filename>wine/documentation</filename>
directory. All credit should go to the original authors, who
are attributed according the the "written by" comments in
those files. Additional content has also been added.
</emphasis>
</releaseinfo>
</setinfo>
<part id="part-one">
<title>Using Wine</title>
<!-- *** Wine User Guide *** -->
<book id="index-user">
<bookinfo>
<title>Wine User Guide</title>
</bookinfo>
&introduction;
&getting;
&running;
&installing;
&configuring;
&running;
&bugs;
<!--
&fonts;
&printing;
-->
</book>
</part>
<!-- *** Wine Developer Guide *** -->
<book id="index-developer">
<bookinfo>
<title>Wine Developer's Guide</title>
</bookinfo>
<part id="part-two">
<title>Developing Wine</title>
<part id="part-one">
<title>Developing Wine</title>
&compiling;
&debugger;
&documentation;
&patches;
&i18n;
&tools;
</part>
&compiling;
&debugging;
&documentation;
&patches;
&i18n;
&porting;
<part id="part-two">
<title>Wine Architecture</title>
&architecture;
&debugging;
&ole;
&opengl;
&build;
&dlls;
</part>
</part>
<part>
<title>Advanced Topics</title>
&implementation;
&porting;
&consoles;
&cvs-regression;
</part>
</book>
<part id="part-three">
<title>Distributing Wine</title>
<!-- *** Winelib User Guide *** -->
&winelib-user;
<!-- *** Wine Packager Guide *** -->
<book id="index-pkg">
<bookinfo>
<title>Wine Packagers Guide</title>
</bookinfo>
&packaging;
</part>
<part id="part-four">
<title>Wine Architecture</title>
&architecture;
&debugger;
&consoles;
&implementation;
&opengl;
&build;
&tools;
&dlls;
</part>
</book>
</book>
</set>

46
documentation/winehq.dsl 100644
View File

@ -0,0 +1,46 @@
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY walsh-style PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
<!ENTITY cygnus-style SYSTEM "/usr/lib/sgml/stylesheet/dsssl/docbook/cygnus/cygnus-both.dsl" CDATA DSSSL>
]>
<style-sheet>
<style-specification id="html" use="docbook">
<style-specification-body>
(define %use-id-as-filename% #t)
(define %html-ext% ".shtml")
(define %html-header-tags% '())
(define %stylesheet% "../../winehq.css")
(define %stylesheet-type% "text/css")
(define %shade-verbatim% #t)
(define %section-autolabel% #t)
;; Define new HTML headers
(define ($html-body-start$)
(make sequence
(make formatting-instruction data: "&#60!--")
(literal "#include file=\"header.html\" ")
(make formatting-instruction data: "-->")))
(define ($html-body-end$)
(make sequence
(make formatting-instruction data: "&#60!--")
(literal "#include file=\"footer.html\" ")
(make formatting-instruction data: "-->")))
;; Customize the body tag attributes
(define %body-attr%
(list
(list "BGCOLOR" "#555555")
(list "TEXT" "#000000")
(list "LINK" "#0000FF")
(list "VLINK" "#840084")
(list "ALINK" "#0000FF")))
</style-specification-body>
</style-specification>
<external-specification id="docbook" document="walsh-style">
</style-sheet>

1706
documentation/winelib-user.sgml 100644
View File

File diff suppressed because it is too large Load Diff