ReceiveTempSMS
/
Sweden-Number
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Converted Wine documentation to SGML format.

This commit is contained in:
John R. Sheets 2000-08-08 01:24:00 +00:00 committed by Alexandre Julliard
parent c4fac7867e
commit 1e8e5ba829
59 changed files with 11404 additions and 6230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Make.rules.in
View File

@ -238,7 +238,7 @@ Makefile: Makefile.in $(TOPSRCDIR)/configure
man: $(C_SRCS) man: $(C_SRCS)
for i in $(C_SRCS); do $(C2MAN) -L -o $(TOPOBJDIR)/documentation/man3w -S3w $(DIVINCL) -D__WINE__ $(MANSPECS) $$i; done for i in $(C_SRCS); do $(C2MAN) -L -o $(TOPOBJDIR)/documentation/man3w -S3w $(DIVINCL) -D__WINE__ $(MANSPECS) $$i; done
html: $(C_SRCS) doc-html: $(C_SRCS)
for i in $(C_SRCS); do $(C2MAN) -L -o $(TOPOBJDIR)/documentation/html -Th -iwindows.h $(DIVINCL) -D__WINE__ $(MANSPECS) $$i; done for i in $(C_SRCS); do $(C2MAN) -L -o $(TOPOBJDIR)/documentation/html -Th -iwindows.h $(DIVINCL) -D__WINE__ $(MANSPECS) $$i; done
# Rule for linting # Rule for linting

30
documentation/.cvsignore
View File

@ -1,23 +1,13 @@
*.aux
*.dvi
*.junk
*.log
*.tex
DBTOHTML_OUTPUT_DIR*
Makefile Makefile
wine.aux wine-doc
wine-doc.pdf
wine-doc.ps
wine-doc.rtf
wine.conf.man wine.conf.man
wine.cp
wine.cps
wine.dvi
wine.fn
wine.fns
wine.html
wine.info
wine.info-1
wine.info-2
wine.ky
wine.log
wine.man wine.man
wine.pg
wine.texi
wine.toc
wine.tp
wine.tps
wine.vr
wine.vrs
wine_toc.html

87
documentation/Makefile.in
View File

@ -3,52 +3,52 @@ TOPOBJDIR = ..
SRCDIR = @srcdir@ SRCDIR = @srcdir@
VPATH = @srcdir@ VPATH = @srcdir@
MODULE = none MODULE = none
BOOKNAME = wine-doc
INCLUDES = \
AUTHORS \
LICENSE \
WARRANTY
SOURCES = \
wine.texinfo \
$(INCLUDES)
INFOFILES = \
wine.info \
wine.info-1 \
wine.info-2
HTMLFILES = \
wine_toc.html \
wine.html
DVIFILES = wine.dvi
EXTRASUBDIRS = samples status EXTRASUBDIRS = samples status
all: $(INFOFILES) $(DVIFILES) $(HTMLFILES) BOOK_SRCS = \
architecture.sgml \
bugs.sgml \
build.sgml \
compiling.sgml \
configuring.sgml \
consoles.sgml \
debugger.sgml \
debugging.sgml \
dlls.sgml \
documentation.sgml \
fonts.sgml \
i18n.sgml \
implementation.sgml \
installing.sgml \
opengl.sgml \
packaging.sgml \
patches.sgml \
porting.sgml \
printing.sgml \
registry.sgml \
running.sgml \
tools.sgml \
wine-doc.sgml
info: $(INFOFILES) BOOK_TARGETS = \
$(BOOKNAME)/index.html \
$(BOOKNAME).pdf \
$(BOOKNAME).ps
dvi: $(DVIFILES) all: $(BOOK_TARGETS)
html: $(HTMLFILES)
@MAKE_RULES@ @MAKE_RULES@
$(INFOFILES): $(SOURCES) $(BOOKNAME)/index.html: $(BOOK_SRCS)
makeinfo $(SRCDIR)/wine.texinfo db2html $(BOOKNAME).sgml
$(DVIFILES): $(SOURCES) $(BOOKNAME).pdf: $(BOOK_SRCS)
texi2dvi $(SRCDIR)/wine.texinfo db2pdf $(BOOKNAME).sgml
$(HTMLFILES): $(SOURCES) $(BOOKNAME).ps: $(BOOK_SRCS)
makeinfo -E wine.texi $(SRCDIR)/wine.texinfo db2ps $(BOOKNAME).sgml
texi2html wine.texi
$(INCLUDES):
$(RM) $(INCLUDES)
for i in $(INCLUDES); do $(LN_S) $(TOPSRCDIR)/$$i $$i || exit 1; done
install:: install::
$(INSTALL) -d $(mandir)/man$(prog_manext) $(INSTALL) -d $(mandir)/man$(prog_manext)
@ -62,19 +62,8 @@ uninstall::
$(RM) $(mandir)/man$(prog_manext)/wine.$(prog_manext) $(RM) $(mandir)/man$(prog_manext)/wine.$(prog_manext)
$(RM) $(mandir)/man$(conf_manext)/wine.conf.$(conf_manext) $(RM) $(mandir)/man$(conf_manext)/wine.conf.$(conf_manext)
# Not done by default because of makeinfo bugs
install_info: $(INFOFILES)
[ -d $(infodir) ] || mkdir -p $(infodir)
for i in $(INFOFILES); do $(INSTALL_DATA) $$i $(infodir)/$$i; done
uninstall_info:
for i in $(INFOFILES); do $(RM) $(infodir)/$$i; done
clean:: clean::
$(RM) $(INFOFILES) $(DVIFILES) $(INCLUDES) $(RM) *.aux *.dvi *.tex *.log $(BOOKNAME).pdf $(BOOKNAME).ps
$(RM) wine.aux wine.cp wine.cps wine.fn wine.fns wine.ky wine.log \ $(RM) -r $(BOOKNAME) html man3w *.junk DBTOHTML_OUTPUT_DIR*
wine.pg wine.toc wine.tp wine.tps wine.vr wine.vrs \
wine.texi
$(RM) -r man3w
### Dependencies: ### Dependencies:

105
documentation/README.documentation
View File

@ -1,105 +0,0 @@
Wine Documentation README
Wine Man Page
The man page for Wine is in this directory. It is installed by 'make
install'.
Wine Reference Manual
Texinfo source for preliminary comprehensive documentation is in
this directory. Use 'make info' in this directory to generate the GNU
info version, 'make dvi' to generate the DVI version (hit 'r' to
ignore errors), or 'make all' for both. It is not installed by
default.
Wine API documentation
Do a 'make manpages' in the Wine toplevel directory to generate the
API manpages from the Wine source, or 'make man' in any source
subdirectory to generate manpages from only that directory. Only
functions mentioned in Wine spec files will be documented; the
specific .spec files checked are set by the MANSPECS variable in
Make.rules. The manpages will be generated into
[documentation/man3w]. For HTML formatted manpages, do 'make
htmlpages' from the toplevel, or 'make html' from any
subdirectory. HTML formatted pages are generated into
[documentation/html]. You will need c2man as modified for Wine,
available as source or binary from ftp://ftp.winehq.com/pub/wine/.
The man pages are not installed by 'make install'.
Other READMEs
Other informational files are in this directory as well as scattered
through the source tree.
Other resources:
Usenet: news:comp.emulators.ms-windows.wine
WWW: http://www.winehq.com/
Writing Wine API Documentation
To improve the documentation of the Wine API, just add comments to the
existing source. For example,
/******************************************************************
* CopyMetaFile32A (GDI32.23)
*
* Copies the metafile corresponding to hSrcMetaFile to either
* a disk file, if a filename is given, or to a new memory based
* metafile, if lpFileName is NULL.
*
* RETURNS
*
* Handle to metafile copy on success, NULL on failure.
*
* BUGS
*
* Copying to disk returns NULL even if successful.
*/
HMETAFILE32 WINAPI CopyMetaFile32A(
HMETAFILE32 hSrcMetaFile, /* handle of metafile to copy */
LPCSTR lpFilename /* filename if copying to a file */
) { ... }
becomes, after processing with c2man and nroff -man,
CopyMetaFileA(3w) CopyMetaFileA(3w)
NAME
CopyMetaFileA - CopyMetaFile32A (GDI32.23)
SYNOPSIS
HMETAFILE32 CopyMetaFileA
(
HMETAFILE32 hSrcMetaFile,
LPCSTR lpFilename
);
PARAMETERS
HMETAFILE32 hSrcMetaFile
Handle of metafile to copy.
LPCSTR lpFilename
Filename if copying to a file.
DESCRIPTION
Copies the metafile corresponding to hSrcMetaFile to
either a disk file, if a filename is given, or to a new
memory based metafile, if lpFileName is NULL.
RETURNS
Handle to metafile copy on success, NULL on failure.
BUGS
Copying to disk returns NULL even if successful.
SEE ALSO
GetMetaFileA(3w), GetMetaFileW(3w), CopyMetaFileW(3w),
PlayMetaFile(3w), SetMetaFileBitsEx(3w), GetMetaFileBit-
sEx(3w)

38
documentation/accelerators
View File

@ -1,38 +0,0 @@
Some notes concerning accelerators.
There are _three_ differently sized accelerator structures exposed to the
user. The general layout is:
BYTE fVirt;
WORD key;
WORD cmd;
We now have three different appearances:
- Accelerators in NE resources. These have a size of 5 byte and do not have
any padding. This is also the internal layout of the global handle HACCEL
(16 and 32) in Windows 95 and WINE. Exposed to the user as Win16 global
handles HACCEL16 and HACCEL32 by the Win16/Win32 API.
- Accelerators in PE resources. These have a size of 8 byte. Layout is:
BYTE fVirt;
BYTE pad0;
WORD key;
WORD cmd;
WORD pad1;
They are exposed to the user only by direct accessing PE resources.
- Accelerators in the Win32 API. These have a size of 6 byte. Layout is:
BYTE fVirt;
BYTE pad0;
WORD key;
WORD cmd;
These are exposed to the user by the CopyAcceleratorTable and
CreateAcceleratorTable in the Win32 API.
Why two types of accelerators in the Win32 API? We can only guess, but
my best bet is that the Win32 resource compiler can/does not handle struct
packing. Win32 ACCEL is defined using #pragma(2) for the compiler but without
any packing for RC, so it will assume #pragma(4).
Findings researched by Uwe Bonnes, Ulrich Weigand and Marcus Meissner.

1032
documentation/architecture.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

92
documentation/aspi
View File

@ -1,92 +0,0 @@
This file describes setting up the Windows ASPI interface.
Warning/Warning/Warning!!!!!!
=============================
THIS MAY TRASH YOUR SYSTEM IF USED INCORRECTLY
THIS MAY TRASH YOUR SYSTEM IF USED CORRECTLY
Now that I have said that. ASPI is a direct link to SCSI devices from
windows programs. ASPI just forwards the SCSI commands that programs send
to it to the SCSI bus.
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).
So please make sure that **all** SCSI devices that the program won't need
have their permissions set as restricted as possible !
Cookbook for setting up scanner: (At least how mine is to work)
================================
Windows requirements:
=====================
0) The scanner software needs to use the "Adaptec" compatible drivers
(ASPI). At least with Mustek, they allow you the choice of using
the builtin card or the "Adaptec (AHA)" compatible drivers. This will not
work any other way.
Software that accesses the scanner via a DOS ASPI driver (e.g. ASPI2DOS)
is supported, too. [AM]
1) You probably need a real windows install of the software to set the
LUN's/SCSI id's up correctly. I'm not exactly sure.
LINUX requirements:
============================================================
0) 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.
1) Compile generic scsi drivers into your kernel.
2) Linux by default uses smaller scsi buffers than Windows. There is a
kernel build define SG_BIG_BUFF (in sg.h) that is by default set too low.
The SANE project recommends 130560 and this seems to work just fine. This
does require a kernel rebuild.
3) Make the devices for the scanner (generic scsi devices) - look at the scsi
programming how-to for device numbering.
4) I would recommend making the scanner device writable by a group.
I made a group called "scanner" and added myself to it. Running as root
increases your risk of sending bad scsi commands to the wrong device. With
a regular user, you are better protected.
5) Add a scsi device entry for your particular scanner to wine.conf.
The format is [scsi cCtTdD] where C=controller, T=target, D=LUN
ex. I set mine up as controller 0, Target 6, LUN 0.
[scsi c0t6d0]
Device=/dev/sgi
Yours will vary with your particular SCSI setup.
General Information:
====================
The mustek scanner I have was shipped with a package "ipplus". This
program uses the TWAIN driver specification to access scanners.
(TWAIN MANAGER)
ipplus.exe <---> (TWAIN INTERFACE) <---> (TWAIN DATA SOURCE . ASPI) -> WINASPI
NOTES/BUGS:
===========
The biggest is that it only works under linux at the moment.
The ASPI code has only been tested with:
- a Mustek 800SP with a Buslogic controller under Linux [BM]
- a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
accessed via DOSASPI.
Note that I had color problems, though (barely readable result) [AM]
- 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]
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!
Bruce Milner
Additions by Andreas Mohr

210
documentation/bugreports
View File

@ -1,210 +0,0 @@
How To Report A Bug
-------------------
There are two ways for you to make a bug report. One uses a simple perl
script, and is recommended if you don't want to spend a lot of time
producing the report. It is designed for use by just about anyone, from
the newest of newbies to advanced developers. You can also make a bug
report the hard way -- advanced developers will probably prefer this.
A. The Easy Way
1) Your computer *must* have perl on it for this method to work. To
find out if you have perl, run:
which perl
If it returns something like "/usr/bin/perl", 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.
2) Change directory to <dirs to wine>/tools
3) Type in "./bug_report.pl" and follow the directions.
4) Post a message to the comp.emulators.ms-windows.wine newsgroup with the
"Nice Formatted Report" attatched. If possible, upload the full debug
output to a web/ftp server and provide the address in your message.
B. The Hard Way:
Some simple advice on making your bug report more useful (and thus more
likely to get answered and fixed):
1) Post as much information as possible.
This means we need more information than a simple
"MS Word crashes whenever I run it. Do you know why?"
Include at least the following information:
- Version of Wine you're using (run 'wine -v')
- Operating system you're using, what distribution (if any), and what
version
- Compiler and version (run 'gcc -v')
- Windows version, if installed
- Program you're trying to run, its version number, and a URL for
where the program can be obtained (if available)
- Command line you used to start wine
- Any other information you think may be relevant or helpful, such as
X server version in case of X problems, libc version etc.
2) Re-run the program with the -debugmsg +relay option
(i.e., 'wine -debugmsg +relay sol.exe').
If Wine crashes while running your program, it is important that we
have this information to have a chance at figuring out what is causing
the crash. This can put out quite a lot (several MB) of information,
though, so it's best to output it to a file. When the Wine-dbg> prompt
appears, type 'quit'.
You might want to try +relay,+snoop instead of +relay, but please note
that +snoop is pretty unstable and often will crash earlier than a
simple +relay !
If this is the case, then please use *only* +relay !!
A bug report with a crash in +snoop code is useless in most cases !
To get the trace output, use the following commands:
all shells:
echo quit|wine -debugmsg +relay [other_options] program_name >& filename.out; tail -n 100 filename.out > report_file
(This will print wine's debug msgs only to the file and then
auto-quit. It's probably a good idea to use this command, since wine
prints out so many debug msgs that they flood the terminal, eating CPU.)
tcsh and other csh-like shells:
wine -debugmsg +relay [other_options] program_name |& tee filename.out
tail -100 filename.out > report_file
bash and other sh-like shells:
wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out
tail -100 filename.out > report_file
'report_file' will now contain the last hundred lines of the debugging
output, including the register dump and backtrace, which are the most
important pieces of information. Please do not delete this part, even
if you don't understand what it means.
3) Post your report to the newsgroup comp.emulators.ms-windows.wine
In your post, include all of the information from part 1), and insert
the text from the output file in part 2). If you do this, your chances
of receiving some sort of helpful response should be very good.
4) Questions and comments
If after reading this document there is something you couldn't figure
out, or think could be explained better, or that should have been
included, please post to comp.emulators.ms-windows.wine to let us know
how this document can be improved.
How to do regression testing using Cvs
-------------------------------------
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.
1) 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-<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)
2) untar it into a repository directory :
cd /home/gerard
tar -zxffull-cvs-2000-05-20.tar.gz
mv wine repository
3) extract a new destination directory
This directory must not be in a subdirectory of the repository else
cvs will think it's part of the repository and deny you an extraction
in the repository :
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
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.
4) you will have now in the ~/wine directory an image of the cvs tree,
on the client side.
Now update this image to the date you want :
cd /home/gerard/wine
cvs -d $CVSROOT update -D "1999-06-01"
The date format is YYYY-MM-DD.
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 :
cvs update: tsx11/ts_xf86dga2.c is no longer in the repository
Cvs update is not limited to upgrade to a *newer* version as
I have believed for far too long :-(
5) Now proceed as for a normal update :
./configure
make depend && make
When you have found the exact date when a bug was
added to Cvs, use something like :
cvs -d $CVSROOT diff -D "1999-07-10" -D "1999-07-12"
to get all the differences between the last cvs version
known to work and code that first displayed the misbehavior.
[ I did not include flags for diff since they are in my .cvsrc file :
cvs -z 3
update -dPA
diff -u
]
From this diff file, particularly the file names, and the
ChangeLog, it's usually possible to find the different individual
patches that were done at this time.
If any non-programmer reads this, the fasted 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 avril, if not,
to 1st october, and so on.
6) The next step is to start from the last working version
and to dig the individual contributions from
http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/
(where the Wine patches mailing list is archived)
If the patch was done by the Wine maintainer or if it was
sent directly to his mail address without going first through
wine-patches, 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, compile and test. If you have saved
the next candidate as /home/gerard/buggedpatch1.txt :
cd /home/gerard/wine
patch -p 0 </home/gerard/buggedpatch1.txt
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.
If you find one patch that is getting the Cvs to reproduce the problem,
you have almost won; post the problem on
comp.emulators.windows.wine
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 :-)

216
documentation/bugs.sgml Normal file
View File

@ -0,0 +1,216 @@
<chapter id="bugs">
<title>Finding and Reporting Bugs</title>
<sect1 id="bug-reporting">
<title>How To Report A Bug</title>
<para>
written by Gerard Patel (???)
</para>
<para>
(Extracted from <filename>wine/documentation/bugreports</filename>)
</para>
<para>
There are two ways for you to make a bug report. One uses a
simple perl script, and is recommended if you don't want to
spend a lot of time producing the report. It is designed for
use by just about anyone, from the newest of newbies to
advanced developers. You can also make a bug report the hard
way -- advanced developers will probably prefer this.
</para>
<sect2>
<title>The Easy Way</title>
<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
<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.
</para>
</listitem>
<listitem>
<para>
Change directory to <filename>&lt;dirs to
wine>/tools</filename>
</para>
</listitem>
<listitem>
<para>
Type in <command>./bug_report.pl</command> and follow
the directions.
</para>
</listitem>
<listitem>
<para>
Post a message to the
<systemitem>comp.emulators.ms-windows.wine</systemitem>
newsgroup with the "Nice Formatted Report" attatched. If
possible, upload the full debug output to a web/ftp
server and provide the address in your message.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>The Hard Way</title>
<para>
Some simple advice on making your bug report more useful
(and thus more likely to get answered and fixed):
</para>
<orderedlist>
<listitem>
<para>Post as much information as possible.</para>
<para>
This means we need more information than a simple "MS
Word crashes whenever I run it. Do you know why?"
Include at least the following information:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>Version of Wine you're using (run <command>wine
-v</command>)</para>
</listitem>
<listitem>
<para>
Operating system you're using, what distribution (if
any), and what version
</para>
</listitem>
<listitem>
<para>Compiler and version (run <command>gcc -v</command>)</para>
</listitem>
<listitem>
<para>Windows version, if installed</para>
</listitem>
<listitem>
<para>
Program you're trying to run, its version number,
and a URL for where the program can be obtained (if
available)
</para>
</listitem>
<listitem>
<para>Command line you used to start wine</para>
</listitem>
<listitem>
<para>
Any other information you think may be relevant or
helpful, such as X server version in case of X
problems, libc version etc.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Re-run the program with the <parameter>--debugmsg
+relay</parameter> option (i.e., <command>wine
--debugmsg +relay sol.exe</command>).
</para>
<para>
If Wine crashes while running your program, it is
important that we have this information to have a chance
at figuring out what is causing the crash. This can put
out quite a lot (several MB) of information, though, so
it's best to output it to a file. When the <prompt>Wine-dbg></prompt>
prompt appears, type <userinput>quit</userinput>.
</para>
<para>
You might want to try
<parameter>+relay,+snoop</parameter> instead of
<parameter>+relay</parameter>, but please note that
<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
report with a crash in <parameter>+snoop</parameter>
code is useless in most cases!
</para>
<para>
To get the trace output, use the following commands:
</para>
<variablelist>
<varlistentry>
<term>all shells:</term>
<listitem>
<screen>
<prompt>$ </prompt>echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out;
<prompt>$ </prompt>tail -n 100 filename.out > report_file
</screen>
<para>
(This will print wine's debug messages only to the file and then
auto-quit. It's probably a good idea to use this command, since wine
prints out so many debug msgs that they flood the terminal, eating CPU.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>tcsh and other csh-like shells:</term>
<listitem>
<screen>
<prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out;
<prompt>$ </prompt>tail -100 filename.out > report_file
</screen>
</listitem>
</varlistentry>
<varlistentry>
<term>bash and other sh-like shells:</term>
<listitem>
<screen>
<prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out;
<prompt>$ </prompt>tail -100 filename.out > report_file
</screen>
</listitem>
</varlistentry>
</variablelist>
<para>
<filename>report_file</filename> will now contain the
last hundred lines of the debugging output, including
the register dump and backtrace, which are the most
important pieces of information. Please do not delete
this part, even if you don't understand what it means.
</para>
</listitem>
<listitem>
<para>
Post your report to the newsgroup
<systemitem>comp.emulators.ms-windows.wine</systemitem>
</para>
<para>
In your post, include all of the information from part
1), and insert the text from the output file in part 2).
If you do this, your chances of receiving some sort of
helpful response should be very good.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>Questions and comments</title>
<para>
If after reading this document there is something you
couldn't figure out, or think could be explained better, or
that should have been included, please post to
<systemitem>comp.emulators.ms-windows.wine</systemitem> to
let us know how this document can be improved.
</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" "")
End:
-->

11
documentation/build.sgml Normal file
View File

@ -0,0 +1,11 @@
<chapter id="build">
<title>The Wine Build System</title>
<para>How the Wine build system works, and how to tweak it...</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
End:
-->

70
documentation/cdrom-labels
View File

@ -1,70 +0,0 @@
Drive labels and serial numbers with wine
-----------------------------------------
Until now, your only possibility of specifying drive volume labels
and serial numbers was to set them manually in the wine config file.
By now, wine can read them directly from the device as well. This may be
useful for many Win 9x games or for setup programs distributed on CD-ROMs
that check for volume label.
WHAT'S SUPPORTED ?
* FAT systems (types 'hd' and 'floppy'): reads labels and serial num's.
* Iso9660 ('cdrom'): reads labels only.
HOW TO SET UP ?
Reading labels and serial numbers just works automagically if
you specify a 'Device=' line in the [Drive X] section in your wine.conf.
Note that the device has to exist and must be accessible if you do this,
though.
If you don't do that, then you should give fixed 'Label=' or 'Serial=' entries
in wine.conf, as Wine returns these entries instead if no device is given.
If they don't exist, then Wine will return default values (label "Drive X"
and serial 12345678).
Now a seldom needed one:
If you want to give a 'Device=' entry *only* for drive raw sector accesses, but
not for reading the volume info from the device (i.e. you want a *fixed*,
preconfigured label), you need to specify 'ReadVolInfo=0' to tell Wine to skip
the volume reading.
EXAMPLES
*** Simple example of cdrom and floppy; labels will be read from the device on
both cdrom and floppy; serial numbers on floppy only:
[Drive A]
Path=/mnt/floppy
Type=floppy
Device=/dev/fd0
Filesystem=msdos
[Drive R]
Path=/mnt/cdrom
Type=cdrom
Device=/dev/hda1
Filesystem=win95
*** CD-ROM. We want to override the label:
[Drive J]
Path=/mnt/cdrom
Type=cdrom
Label=X234GCDSE
; note that the device isn't really needed here as we have a fixed label
Device=/dev/cdrom
Filesystem=msdos
TODO / OPEN ISSUES
- The cdrom label can be read only if the data track of the disk resides in
the first track and the cdrom is iso9660.
- Better checking for FAT superblock (it now check's only one byte).
- Support for labels/serial num's WRITING.
- Can the label be longer than 11 chars? (iso9660 has 32 chars).
- What about reading ext2 volume label? ....
Petr Tomasek changes by: Andreas Mohr
<tomasek@etf.cuni.cz> <a.mohr@mailto.de>
Nov 14 1999 Jan 25 2000

439
documentation/common_controls
View File

@ -1,439 +0,0 @@
COMMON CONTROLS
their development status
and their UNDOCUMENTED features and functions
-----------------------------------------------------
1. Introduction
---------------
The information provided herein is based on the dll version 4.72 which
is included in MS Internet Explorer 4.01.
All information about common controls should be collected in this document.
All Wine programmers are encouraged to add their knowledge to this document.
2. General Information
----------------------
Further information about common controls can be found in the MS Platform SDK
and the MS Internet Client SDK (most recent). Information from these SDK's
will NOT be repeated here. Only information which can NOT be found in these
SDK's will be collected here. Some information in the SDK's mentioned above
is (intentionally???) WRONG. Corrections to wrong information will be
collected here too.
2.1 Structure sizes of different common control versions
--------------------------------------------------------
The common controls have been continously improved in the past. Some of the
orignal structures had to be extended and their size changed. Most of the
common control structures include their size as the first parameter. If
a control gets the wrong size in a message or function a failure is very
likely to occur. To avoid this, MS defined new constants that reflect the
structure size of older COMCTL32.DLL versions. The following list shows the
structure size constants that are currently defined in the original
COMCTL32.DLL.
NOTE: Some stuctures are NOT defined in wine's COMCTL32 yet.
HDITEM_V1_SIZE:
The size of the HDITEM structure in version 4.00.
LVCOLUMN_V1_SIZE:
The size of the LVCOLUMN structure in version 4.00.
LVHITTESTINFO_V1_SIZE:
The size of the LVHITTESTINFO structure in version 4.00.
LVITEM_V1_SIZE:
The size of the LVITEM structure in version 4.00.
NMLVCUSTOMDRAW_V3_SIZE:
The size of the NMLVCUSTOMDRAW structure in version 4.70.
NMTTDISPINFO_V1_SIZE:
The size of the NMTTDISPINFO structure in version 4.00.
NMTVCUSTOMDRAW_V3_SIZE:
The size of the NMTVCUSTOMDRAW structure in version 4.70.
PROPSHEETHEADER_V1_SIZE:
The size of the PROPSHEETHEADER structure in version 4.00.
PROPSHEETPAGE_V1_SIZE:
The size of the PROPSHEETPAGE structure in version 4.00.
REBARBANDINFO_V3_SIZE:
The size of the REBARBANDINFO structure in version 4.70.
TTTOOLINFO_V1_SIZE:
The size of the TOOLINFO structure in version 4.00.
TVINSERTSTRUCT_V1_SIZE:
The size of the TVINSERTSTRUCT structure in version 4.00.
3. Controls
-----------
This paragraph describes the development status of the common controls.
3.1 Animation Control
---------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.2 Combo Box Ex Control
------------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.3 Date and Time Picker Control
--------------------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.4 Drag List Box Control
-------------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.5 Flat Scroll Bar Control
---------------------------
Author:
Dummy written by Alex Priem. <alexp@sci.kun.nl>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.6 Header Control
------------------
Author:
Eric Kohl <ekohl@abo.rhein-zeitung.de>
Status:
Almost finished.
Unicode notifications are not supported (WM_NOTIFYFORMAT).
Order array not supported.
3.7 Hot Key Control
-------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.8 Image List (no control)
---------------------------
Author:
Eric Kohl <ekohl@abo.rhein-zeitung.de>
Status:
Almost finished.
3.9 IP Address Control
----------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Alex Priem <alexp@sci.kun.nl>
Status:
Under construction.
3.10 List View Control
----------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Luc Tourangeau <luc@macadamian.com>
Koen Deforche <jozef@kotnet.org>
Francis Beaudet <francis@macadamian.com> and the "Corel-Team"
Status:
Under construction.
Notes:
Basic data structure with related messages are supported.
No painting supported yet.
3.11 Month Calendar Control
---------------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.12 Native font control
------------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Dummy control. No functionality.
Notes:
Author needed!! Any volunteers??
3.13 Pager Control
------------------
Author:
Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
Status:
Under construction.
Many missing features.
Notes:
Author needed!! Any volunteers??
3.14 Progress Bar Control
-------------------------
Author:
Original implementation by Dimitrie O. Paun.
Fixes and improvements by Eric Kohl.
Status:
Finished!
3.15 Property Sheet
-------------------
Author:
Anders Carlsson <anders.carlsson@linux.nu>
Francis Beaudet <francis@macadamian.com>
Status:
Development in progress.
Notes:
Tab control must be implemented first.
3.16 Rebar Control (Cool Bar)
-----------------------------
Author:
Eric Kohl <ekohl@abo.rhein-zeitung.de>
Status:
Development in progress.
Many bugs and missing features.
Notes:
Author needed!! Any volunteers??
3.17 Status Bar Control
-----------------------
Author:
Original implementation by Bruce Milner.
Fixes and improvements by Eric Kohl.
Status:
Almost finished.
Notes:
Tooltip integration is almost complete.
3.18 Tab Control
----------------
Author:
Anders Carlsson <anders.carlsson@linux.nu>
Status:
Development in progress.
3.19 Toolbar Control
--------------------
Author:
Eric Kohl <ekohl@abo.rhein-zeitung.de>
Status:
Development in progress.
Basic functionality is almost done. (dll version 4.0)
3.20 Tooltip Control
--------------------
Author:
Eric Kohl <ekohl@abo.rhein-zeitung.de>
Status:
Almost finished.
Notes:
Unicode support is incomplete (WM_NOTIFYFORMAT).
3.21 Trackbar Control
---------------------
Author:
Dummy written by Eric Kohl <ekohl@abo.rhein-zeitung.de>
Alex Priem <alexp@sci.kun.nl>
Status:
Under construction.
3.22 Tree View Control
----------------------
Author:
Dummy written by Eric Kohl.
Alex Priem <alexp@sci.kun.nl>
Status:
Under construction.
3.23 Updown Control
-------------------
Author:
Original implementation by Dimitrie O. Paun.
Some minor changes by Eric Kohl <ekohl@abo.rhein-zeitung.de>.
Status:
Unknown.
Notes:
Have a look at controls/updown.c for a list of bugs and missing
features.
The status is unknown, because I did not have a close look at this
control. One test-program looked quite good, but in Win95's
cdplayer.exe the control does not show at all.
Any volunteers??
4. Additional Information
-------------------------
Has to be written...
5. Undocumented features
------------------------
There are quite a lot of undocumented functions like:
- DSA (Dynamic Storage Array) functions.
- DPA (Dynamic Pointer Array) functions.
- MRU ("Most Recently Used" List) functions.
- other unknown functions.
Have a look at relay32/comctl32.spec.
5.1 Dymnamic Storage Array (DSA)
---------------------------------
The DSA functions are used to store and manage dynamic arrays of fixed size
memory blocks. They are used by TASKMAN.EXE, Explorer, IE4 and other
Programs and DLL's that are "parts of the Windows Operating System".
The implementation should be complete.
Have a look at the source code to get more information.
5.2 Dynamic Pointer Array (DPA)
------------------------------------
Similar to the DSA functions, but they just store pointers. They are used by
Explorer, IE4 and other Programs and DLL's that are "parts of the Windows
Operating System". The implementation should be complete.
Have a look at the source code to get more information.
5.3 "Most Recently Used" - List (MRU)
-------------------------------------
Only stubs are implemented to keep Explorer from bailing out.
No more information available at this time!
5.4 MenuHelp
------------
Has to be written...
5.5 GetEffectiveClientRect
--------------------------
Has to be written...
5.6 ShowHideMenuCtl
-------------------
The official documentation provided by MS is incomplete.
lpInfo:
...
Both values of the first pair must be the handle to the applications main
menu.
...
5.7 Other undocumented functions
--------------------------------
Several other undocumented functions are used by IE4.
String functions:
(will be written...)
6. Epilogue
-----------
You see, much work has still to be done. If you are interested in writing
a control send me an e-mail. If you like to fix bugs or add some
functionality send an e-mail to the author of the control.
Eric Kohl <ekohl@abo.rhein-zeitung.de>

11
documentation/compiling.sgml Normal file
View File

@ -0,0 +1,11 @@
<chapter id="compiling">
<title>Compiling Wine</title>
<para>How to compile wine, and problems that may arise...</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
End:
-->

463
documentation/config
View File

@ -1,463 +0,0 @@
Copyright 1999 Adam Sacarny (magicbox@bestweb.net)
1. WHAT IS THE WINE CONFIG FILE?
The Wine config file stores various settings for Wine. These include:
Drives and Information about them
Directory Settings
Port Settings
The Wine look and feel
Wine's DLL Usage
2. HOW DO I MAKE ONE?
This section will guide you through the process of making a config file. Take a
look at the file <dirs to wine>/wine.ini
It is organized by section.
Name | Needed? | What it does
----------------------------------------------------------------
[Drive X] | yes | Sets up drives recognized by wine
[wine] | yes | Settings for wine directories
[DllDefaults] | recmd | Defaults for loading DLL's
[DllPairs] | recmd | Sanity checkers for DLL's
[DllOverrides] | recmd | Overides defaults for DLL loading
[options] | no | No one seems to know
[fonts] | yes | Font appearance and recognition
[serialports] | no | COM ports seen by wine
[parallelports] | no | LPT ports seen by wine
[spooler] | no | Print spooling
[ports] | no | Direct port access
[spy] | no | What to do with certain debug messages
[Registry] | no | Specifies locations of windows registry files
[tweak.layout] | recmd | Appearance of wine
[programs] | no | Programs to be run automatically
[Console] | no | Console settings
Recmd-Recommended
2.1 THE [Drive X] SECTION
It should be pretty self explanatory, but here is an in-depth tutorial about
them.
There are up to 6 lines for each drive in Wine.
[Drive X]
The above line begins the section for a drive whose letter is X.
Path=/dir/to/path
This path is where the drive will begin. When Wine is browsing in drive X, it
will see the files that are in the directory "/dir/to/path". Don't forget to
leave off the trailing slash!
Type=floppy|hd|cdrom|network <--- the |'s mean Type=<one of the options>
Sets up the type of drive Wine will see it as. Type must equal one of the four
"floppy", "hd", "cdrom", or "network". They are self-explanatory.
Label=blah
Defines the drive label. Generally only needed for programs that look for a
special CD-ROM. Info on finding the lable is in <dirs to
wine>/documentation/cdrom-labels. The label may be up to 11 characters.
Serial=deadbeef
Tells Wine the serial number of the drive. A few programs with intense
protection for pirating might need this, but otherwise don't use it. Up to 8
characters and hexadecimal.
Filesystem=msdos|win95|unix
Sets up the way Wine looks at files on the drive.
msdos -> Case insensitive filesystem. Alike to DOS and Windows 3.x.
8.3 is the maximum length of files (eightdot.123) - longer ones will be
truncated. (NOTE: this is a very bad choice if you plan on running apps
that use long filenames. win95 should work fine with apps that were
designed to run under the msdos system. In other words, you might not
want to use this.)
win95 -> Case insensitive. Alike to Windows 9x/NT 4. This is the long
filename filesystem you are probably used to working with. The
filesystem of choice for most applications to be run under wine.
PROBABLY THE ONE YOU WANT
unix -> Case sensitive. This filesystem has almost no use (Windows apps
expect case insensitive filenames). Try it if you dare, but win95 is a
much better choice.
Device=/dev/xx
Use this ONLY for floppy and cdrom devices. Using it on Extended2 partitions can
have dire results (When a windows app tries to do a lowlevel write, they do it
in a FAT way -- FAT does not mix with Extended2).
NOTE: This setting is not really important, almost all apps will have no
problem if it remains unspecified. For CD-ROMs you might want to add it to get
automatic label detection, though. If you are unsure about specifying device
names, just leave out this setting for your drives.
Here is a setup for Drive X, a generic hard drive:
[Drive X]
Path=/dos-a
Type=hd
Label=Hard Drive
Filesystem=win95
This is a setup for Drive X, a generic CD-ROM drive:
[Drive X]
Path=/dos-d
Type=cdrom
Label=Total Annihilation
Filesystem=win95
Device=/dev/hdc
And here is a setup for Drive X, a generic floppy drive:
[Drive X]
Type=floppy
Path=/mnt/floppy
Label=Floppy Drive
Serial=87654321
Filesystem=win95
Device=/dev/fd0
2.2 THE [wine] SECTION
The [wine] section of the configuration file contains information wine uses for
directories. When specifying the directories for the settings, make them as they
would appear in wine. If your drive C has a Path of /dos, and your windows
directory is located in /dos/windows, Windows=c:\windows.
Windows=c:\windows
Sets up the windows directory. Make one if you don't have windows. NO TRAILING
SLASH (NOT C:\windows\)!
System=c:\windows\system
Sets up where the windows system files are. Should reside in the directory used
for the "Windows" setting. If you don't have windows then this is where the
system files will go. NO TRAILING SLASH!
Temp=c:\temp
This should be the directory you want your temp files stored in. YOU MUST HAVE
WRITE ACCESS TO IT.
Path=c:\windows;c:\windows\system;c:\blanco
Behaves like the PATH setting on unix boxes. When wine is run like "wine
sol.exe", if sol.exe resides in a directory specified in the "Path" setting,
wine will run it (Of course, if sol.exe resides in the current directory, wine
will run that one). Make sure it always has your windows directory and system
directory (For this setup, it must have c:\windows;c:\windows\system).
SymbolTableFile=wine.sym
Sets up the symbol table file for the wine debugger. You probably don't need to
fiddle with this. May be useful if your wine is stripped.
printer=off|on
Tells wine whether to allow printer drivers and printing to work. Using these
things are pretty alpha, so you might want to watch out. Some people might find
it useful, however. If you're not planning on working on printing, don't even
add this to your wine.ini (It probably isn't already in it). Check out the
[spooler] and [parallelports] sections too.
2.3 INTRODUCTION TO DLL SECTIONS
There are a few things you will need to know before configuring the DLL sections
in your wine configuration file.
2.3.1 WINDOWS DLL PAIRS
Most windows DLL's have a win16 (Windows 3.x) and win32 (Windows 9x/NT)
form. The combination of the win16 and win32 DLL versions are called
the "DLL pair". This is a list of the most common pairs:
Win16 | Win32 | Native*
-----------------------------
KERNEL | KERNEL32 | No!
USER | USER32 | No!
SHELL | SHELL32 | Yes
GDI | GDI32 | No!
COMMDLG | COMDLG32 | Yes
VER | VERSION | Yes
*-Is it possible to use native dll with wine?(See next section)
2.3.2 DIFFERENT FORMS OF DLL'S
There are a few different forms of DLL's wine can load:
native -> The DLL's that are included with windows. Many windows
DLL's can be loaded in their native form. Many times these
native versions work better than their non-Microsoft equivalent
-- other times they don't.
elfdll -> ELF encapsulated windows DLL's. This is currently
experimental (Not working yet).
so -> Native ELF libraries. Will not work yet.
builtin -> The most common form of DLL loading. This is what you
will use if the DLL is error-prone in native form (KERNEL for
example), you don't have the native DLL, or you just want to be
Microsoft-free.
2.4 THE [DllDefaults] SECTION
These settings provide wine's default handling of DLL loading.
EXTRA_LD_LIBRARY_PATH=/dirs
The directory specified here is appended to the normal search path for certain
forms of DLL's (elfdll and .so).
DefaultLoadOrder = native, elfdll, so, builtin
This setting is a comma-delimited list of which order to attempt loading DLL's.
If the first option fails, it will try the second, and so on. The order
specified above is probably the best in most conditions.
2.5 THE [DllPairs] SECTION
This section is optional, but strongly recommended. If you try to use native
SHELL32, but builtin SHELL, you could have some big problems (native and
builtin/so/elfdll do certain things in different ways). Using different forms of
a pair is a *very*, **very** bad idea. By specifying DLL pairs here, wine will
print out a message if you use different forms of a pair.
You shouldn't need to change anything in this section, the following should work
fine in all cases:
[DllPairs]
kernel = kernel32
gdi = gdi32
user = user32
commdlg = comdlg32
commctrl= comctl32
ver = version
shell = shell32
lzexpand= lz32
winsock = wsock32
2.6 THE [DllOverrides] SECTION
The format for this section is the same for each line:
<DLL>{,<DLL>,<DLL>...} = <FORM>{,<FORM>,<FORM>...}
For example, to load builtin KERNEL pair (Case doesn't matter here):
kernel,kernel32 = builtin
To load the native COMMDLG pair, but if that doesn't work try builtin:
commdlg,comdlg32 = native,builtin
To load the native COMCTL32:
comctl32 = native
Here is a good generic setup (As it is defined in wine.ini that was included
with your wine package):
[DllOverrides]
kernel32, gdi32, user32 = builtin
kernel, gdi, user = builtin
toolhelp = builtin
comdlg32, commdlg = elfdll, builtin, native
version, ver = elfdll, builtin, native
shell32, shell = builtin, native
lz32, lzexpand = builtin, native
commctrl, comctl32 = builtin, native
wsock32, winsock = builtin
advapi32, crtdll, ntdll = builtin, native
mpr, winspool = builtin, native
ddraw, dinput, dsound = builtin, native
winmm, w32skrnl, msvfw32= builtin
wnaspi32, wow32 = builtin
system, display, wprocs = builtin
wineps = builtin
NOTE: You see that elfdll or so is the first option for a few of these dll's.
This will fail for you, but you won't notice it as wine will just use the second
or third option.
2.7 THE [options] SECTION
No one seems to know what this section is...
AllocSystemColors=100
System colors to allocate? Just leave it at 100.
2.8 THE [fonts] SECTION
This section sets up wine's font handling.
Resolution = 96
Since the way X handles fonts is different from the way Windows does, wine uses
a special mechanism to deal with them. It must scale them using the number
defined in the "Resolution" setting. 60-120 are reasonable values, 96 is a nice
in the middle one. If you have the real windows fonts available (<dirs to
wine>/documentation/ttfserver and fonts), this parameter will not be as
important. Of course, it's always good to get your X fonts working acceptably in
wine.
Default = -adobe-times-
The default font wine uses. Fool around with it if you'd like.
OPTIONAL:
The "Alias" setting allows you to map an X font to a font used in wine. This is
good for apps that need a special font you don't have, but a good replacement
exists. The syntax is like so:
AliasX = [Fake windows name],[Real X name]<,optional "masking" section>
Pretty straightforward. Replace "AliasX" with "Alias0", then "Alias1" and so on.
The fake windows name is the name that the font will be under a windows app in
wine. The real X name is the font name as seen by X (Run "xfontsel").
The optional "masking" section allows you to utilize the fake windows name you
define. If it is not used, then wine will just try to extract the fake windows
name itself and not use the value you enter.
Here is an example of an alias without masking. The font will show up in windows
apps as "Google". When defining an alias in a config file, forget about my
comment text (The "<-- blah" stuff)
Alias0 = Foo,--google- <-- Note the no spaces after the " = ". Important!
Here is an example with masking enabled. The font will show up as "Foo" in
windows apps.
Alias1 = Foo,--google-,subst
For more info check out <dirs to wine>/documentation/fonts
2.9 THE [serialports], [parallelports], [spooler], AND [ports] SECTIONS
Even though it sounds like a lot of sections, these are all closely related.
They all are for communications and parallel ports.
The [serialports] section tells wine what serial ports it is allowed to use.
ComX=/dev/cuaY
Replace X with the number of the COM port in Windows (1-8) and Y with the
number of it in X (Usually the number of the port in Windows minus 1). ComX can
actually equal any device (/dev/modem is acceptable). It is not always necessary
to define any COM ports (An optional setting). Here is an example:
Com1=/dev/cua0
Use as many of these as you like in the section to define all of the COM ports
you need.
The [parallelports] section sets up any parallel ports that will be allowed
access under wine.
LptX=/dev/lpY
Seem farmiliar? Syntax is just like the COM port setting. Replace X with a value
from 1-4 as it is in Windows and Y with a value from 0-3 (Y is usually the value
in windows minus 1, just like for COM ports). You don't always need to define a
parallel port (AKA, it's optional). As with the other section, LptX can equal
any device (Maybe /dev/printer). Here is an example:
Lpt1=/dev/lp0
The [spooler] section will inform wine where to spool print jobs. Use this if
you want to try printing. Wine docs claim that spooling is "rather primitive" at
this time, so it won't work perfectly. IT IS OPTIONAL
The only setting you use in this section works to map a port (LPT1, for example)
to a file or a command. Here is an example, mapping LPT1 to the file "out.ps":
LPT1:=out.ps
The following command maps printing jobs to LPT1 to the command "lpr". Notice
the |:
LPT1:=|lpr
The [ports] section is usually useful only for people who need direct port
access for programs requiring dongles or scanners. IF YOU DON'T NEED IT, DON'T
USE IT!
read=0x779,0x379,0x280-0x2a0
Gives direct read access to those IO's.
write=0x779,0x379,0x280-0x2a0
Gives direct write access to those IO's. It probably a good idea to keep the
values of the "read" and "write" settings the same. This stuff will only work
when you're root.
2.10 THE [spy], [Registry], [tweak.layout], and [programs] SECTIONS
[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.
File=/blanco
Sets the logfile for wine. Set to CON to log to standard out. THIS IS RARELY
USED
Exclude=WM_SIZE;WM_TIMER;
Excludes debug messages about WM_SIZE and WM_TIMER in the logfile.
Include=WM_SIZE;WM_TIMER;
Includes debug messages about WM_SIZE and WM_TIMER in the logfile.
[Registry] can be used to tell wine where your old windows registry files exist. This
section is completely optional and useless to people using wine without an existing
windows installation.
UserFileName=/dirs/to/user.reg
The location of your old user.reg file.
LocalMachineFileName=/dirs/to/system.reg
The location of your old system.reg file.
[tweak.layout] is devoted to wine's look. There is only one setting for it.
WineLook=win31|win95|win98
Will change the look of wine from Windows 3.1 to Windows 95. "win98" behaves
just like "win95" most of the time.
[programs] can be used to say what programs run under special conditions.
Default=/program/to/execute.exe
Sets the program to be run if wine is started without specifying a program.
Startup=/program/to/execute.exe
Sets the program to automatically be run at startup every time.
3. WHERE DO I PUT IT?
The wine config file can go in two places.
/usr/local/etc/wine.conf <--- A systemwide config file, used for anyone
who doesn't have their own.
$HOME/.winerc <--- Your own config file, that only is used for your
user.
So copy the file you made to be the wine.conf to /usr/local/etc/wine.conf or
$HOME/.winerc for wine to recognize it.
4. WHAT IF IT DOESN'T WORK?
There is always a chance that things will go wrong. If the unthinkable happens,
try the newsgroup, comp.emulators.ms-windows.wine
Make sure that you have looked over this document thoroughly, and have also
read:
README
documentation/bugreports
http://www.westfalen.de/witch/wine-HOWTO.txt (Optional but recommended)
If indeed it looks like you've done your research, be prepared for helpful
suggestions. If you haven't, brace yourself for heaving flaming.

1874
documentation/configuring.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

177
documentation/console
View File

@ -1,177 +0,0 @@
Console - First Pass
--------------------
Consoles are just xterms created with the -Sxxn switch.
A pty is opened and the master goes to the xterm side
and the slave is held by the wine side. The console
itself it turned into a few HANDLE32s and is set
to the STD_*_HANDLES.
It is possible to use the WriteFile and ReadFile commands
to write to a win32 console. To accomplish this, all K32OBJs
that support I/O have a read and write function pointer.
So, WriteFile calls K32OBJ_WriteFile which calls the K32OBJ's
write function pointer, which then finally calls write.
[this paragraph is now out of date]
If the command line console is to be inheirited or
a process inherits its parent's console (-- can that happen???),
the console is created at process init time via PROCESS_InheritConsole.
The 0, 1, and 2 file descriptors are duped to be the
STD_*_HANDLES in this case. Also in this case a flag is set
to indicate that the console comes from the parent process or
command line.
If a process doesn't have a console at all, its
pdb->console is set to NULL. This helps indicate when
it is possible to create a new console (via AllocConsole).
When FreeConsole is called, all handles that the process has
open to the console are closed. Like most k32objs, if the
console's refcount reaches zero, its k32obj destroy function
is called. The destroy kills the xterm if one was open.
Also like most k32 objects, we assume that (K32OBJ) header is the
first field so the casting (from K32OBJ *to CONSOLE *)
works correctly.
FreeConsole is called on process exit (in ExitProcess) if
pdb->console is not NULL.
BUGS
----
Console processes do not inherit their parent's handles. I think
there needs to be two cases, one where they have to inherit
the stdin/stdout/stderr from unix, and one where they have to
inherit from another windows app.
SetConsoleMode -- UNIX only has ICANON and various ECHOs
to play around with for 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 implementation).
================================================================
experimentation with NT4 yields that:
WriteFile
---------
o does not truncate file on 0 length write
o 0 length write or error on write changes numcharswritten to 0
o 0 length write returns TRUE
o works with console handles
_lwrite
-------
o does truncate/expand file at current position on 0 length write
o returns 0 on a zero length write
o works with console handles (typecasted)
WriteConsole
------------
o expects only console handles
SetFilePointer
--------------
o returns -1 (err 6) when used with a console handle
FreeConsole
-----------
o even when all the handles to it are freed, the win32 console
stays visible, the only way I could find to free it
was via the FreeConsole
Is it possible to interrupt win32's FileWrite? I'm not sure.
It may not be possible to interrupt any system calls.
DOS (Generic) Console Support
-----------------------------
I. Command Line Configuration
DOS consoles must be configured either on the command line or in a dot
resource file (.console). A typical configuration consists of a string
of driver keywords separated by plus ('+') signs. To change the
configuration on the command-line, use the -console switch.
For example:
wine -console ncurses+xterm <apllication>
Possible drivers:
tty - Generic text-only support. Supports redirection.
ncurses - Full-screen graphical support with color.
xterm - Load a new window to display the console in. Also
supports resizing windows.
II. Wine.conf Configuration
In the wine.conf file, you can create a section called [console] that
contains configuration options that are respected by the assorted
console drivers.
Current Options:
XtermProg=<program>
Use this program instead of xterm. This eliminates the need for a
recompile. See the table below for a comparison of various
terminals.
InitialRows=<number>
Attempt to start all drivers with this number of rows. This
causes xterms to be resized, for instance.
Note: This information is passed on the command-line with the
-g switch.
InitialColumns=<number>
Attempt to start all drivers with this number of columns. This
causes xterms to be resized, for instance.
Note: This information is passed on the command-line with the
-g switch.
TerminalType=<name>
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. "nxterm" may give you better support
if you use that terminal. This can also be changed to
"linux" (or "console" on older systems) if you manage to hack
the ability to write to the console into this driver.
III. Terminal Types
There are a large number of potential terminals that can be used with
Wine, depending on what you are trying to do. Unfortunately, I am still
looking for the "best" driver combination.
Note that 'slave' is required for use in Wine, currently.
Program | Color? | Resizing? | Slave?
-----------------------------------------
xterm N Y Y
nxterm Y N Y
rxvt Y ? N
(linux console) Y N ?
As X terminals typically use a 24x80 screen resolution rather than the
typical 25x80 one, it is necessary to resize the screen to allow a DOS
program to work full-screen. There is a wine.conf option to work
around this in some cases but run-time resizing will be disabled.

386
documentation/consoles.sgml Normal file
View File

@ -0,0 +1,386 @@
<chapter id="consoles">
<title>Consoles in Wine</title>
<sect1 id="wine-consoles">
<title>Consoles</title>
<para>
written by (???)
</para>
<para>
(Extracted from <filename>wine/documentation/console</filename>)
</para>
<sect2>
<title>Console - First Pass</title>
<para>
Consoles are just xterms created with the
<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
<type>HANDLE32</type>s and is set to the
<varname>STD_*_HANDLES</varname>.
</para>
<para>
It is possible to use the <function>WriteFile</function> and
<function>ReadFile</function> commands to write to a win32
console. To accomplish this, all <type>K32OBJ</type>s that
support I/O have a read and write function pointer. So,
<function>WriteFile</function> calls
<function>K32OBJ_WriteFile</function> which calls the
<type>K32OBJ</type>'s write function pointer, which then
finally calls <function>write</function>.
</para>
<para>
<emphasis>[this paragraph is now out of date]</emphasis> If
the command line console is to be inheirited 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
<literal>0</literal>, <literal>1</literal>, and
<literal>2</literal> file descriptors are duped to be the
<varname>STD_*_HANDLES</varname> in this case. Also in this
case a flag is set to indicate that the console comes from
the parent process or command line.
</para>
<para>
If a process doesn't have a console at all, its
<varname>pdb-&gt;console</varname> is set to
<constant>NULL</constant>. This helps indicate when it is
possible to create a new console (via
<function>AllocConsole</function>).
</para>
<para>
When <function>FreeConsole</function> is called, all handles that the process has
open to the console are closed. Like most <type>K32OBJ</type>s, if the
console's refcount reaches zero, its <type>K32OBJ</type> destroy function
is called. The destroy kills the xterm if one was open.
</para>
<para>
Also like most k32 objects, we assume that
(<type>K32OBJ</type>) header is the first field so the
casting (from <type>K32OBJ*</type>to <type>CONSOLE*</type>)
works correctly.
</para>
<para>
<function>FreeConsole</function> is called on process exit
(in <function>ExitProcess</function>) if
<varname>pdb-&gt;console</varname> is not
<constant>NULL</constant>.
</para>
</sect2>
<sect2>
<title>BUGS</title>
<para>
Console processes do not inherit their parent's handles. I
think there needs to be two cases, one where they have to
inherit the <filename>stdin</filename> /
<filename>stdout</filename> / <filename>stderr</filename>
from unix, and one where they have to inherit from another
windows app.
</para>
<para>
<function>SetConsoleMode</function> -- UNIX only has
<constant>ICANON</constant> and various
<constant>ECHO</constant>s to play around with for
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
implementation).
</para>
</sect2>
<sect2>
<title>Experimentation</title>
<para>
experimentation with NT4 yields that:
</para>
<variablelist>
<varlistentry>
<term><function>WriteFile</function></term>
<listitem>
<itemizedlist>
<listitem>
<para>does not truncate file on 0 length write</para>
</listitem>
<listitem>
<para>
0 length write or error on write changes
<varname>numcharswritten</varname> to
<literal>0</literal>
</para>
</listitem>
<listitem>
<para>0 length write returns <constant>TRUE</constant></para>
</listitem>
<listitem>
<para>works with console handles</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><function>_lwrite</function></term>
<listitem>
<itemizedlist>
<listitem>
<para>does truncate/expand file at current position on 0 length write</para>
</listitem>
<listitem>
<para>returns 0 on a zero length write</para>
</listitem>
<listitem>
<para>works with console handles (typecasted)</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><function>WriteConsole</function></term>
<listitem>
<itemizedlist>
<listitem>
<para>expects only console handles</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><function>SetFilePointer</function></term>
<listitem>
<itemizedlist>
<listitem>
<para>returns -1 (err 6) when used with a console handle</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><function>FreeConsole</function></term>
<listitem>
<itemizedlist>
<listitem>
<para>
even when all the handles to it are freed, the
win32 console stays visible, the only way I could
find to free it was via the <function>FreeConsole</function>
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<para>
Is it possible to interrupt win32's
<function>FileWrite</function>? I'm not sure. It may not be
possible to interrupt any system calls.
</para>
</sect2>
<sect2>
<title>DOS (Generic) Console Support</title>
<sect3>
<title>I. Command Line Configuration</title>
<para>
DOS consoles must be configured either on the command line
or in a dot resource file (<filename>.console</filename>).
A typical configuration consists of a string of driver
keywords separated by plus ('+') signs. To change the
configuration on the command-line, use the
<parameter>-console</parameter> switch.
</para>
<para>
For example:
</para>
<screen>
wine -console ncurses+xterm &lt;application&gt;
</screen>
<para>
Possible drivers:
</para>
<variablelist>
<varlistentry>
<term>tty:</term>
<listitem>
<para>Generic text-only support. Supports redirection.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ncurses:</term>
<listitem>
<para>Full-screen graphical support with color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>xterm:</term>
<listitem>
<para>
Load a new window to display the console in. Also
supports resizing windows.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>II. <filename>wine.conf</filename> Configuration</title>
<para>
In the <filename>wine.conf</filename> file, you can create
a section called [console] that contains configuration
options that are respected by the assorted console
drivers.
</para>
<para>
Current Options:
</para>
<variablelist>
<varlistentry>
<term>XtermProg=&lt;program&gt;</term>
<listitem>
<para>
Use this program instead of
<command>xterm</command>. This eliminates the need
for a recompile. See the table below for a
comparison of various terminals.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>InitialRows=&lt;number&gt;</term>
<listitem>
<para>
Attempt to start all drivers with this number of
rows. This causes xterms to be resized, for
instance.
</para>
<note>
<para>
This information is passed on the command-line
with the <parameter>-g</parameter> switch.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>InitialColumns=&lt;number&gt;</term>
<listitem>
<para>
Attempt to start all drivers with this number of
columns. This causes xterms to be resized, for
instance.
</para>
<note>
<para>
This information is passed on the command-line
with the <parameter>-g</parameter> switch.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>TerminalType=&lt;name&gt;</term>
<listitem>
<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.
<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)
if you manage to hack the ability to write to the
console into this driver.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>III. Terminal Types</title>
<para>
There are a large number of potential terminals that can
be used with Wine, depending on what you are trying to do.
Unfortunately, I am still looking for the "best" driver
combination.
</para>
<note>
<para>
'slave' is required for use in Wine, currently.
</para>
</note>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Program</entry>
<entry>Color?</entry>
<entry>Resizing?</entry>
<entry>Slave?</entry>
</row>
</thead>
<tfoot>
<row>
<entry>(linux console)</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>?</entry>
</row>
</tfoot>
<tbody>
<row>
<entry>xterm</entry>
<entry>N</entry>
<entry>Y</entry>
<entry>Y</entry>
</row>
<row>
<entry>nxterm</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>Y</entry>
</row>
<row>
<entry>rxvt</entry>
<entry>Y</entry>
<entry>?</entry>
<entry>N</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
As X terminals typically use a 24x80 screen resolution
rather than the typical 25x80 one, it is necessary to
resize the screen to allow a DOS program to work
full-screen. There is a <filename>wine.conf</filename>
option to work around this in some cases but run-time
resizing will be disabled.
</para>
</sect3>
</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" "")
End:
-->

470
documentation/debug-msgs
View File

@ -1,470 +0,0 @@
Note: The new debugging interface can be considered to be stable,
with the exception of the in-memory message construction functions.
However, there is still a lot of work to be done to polish
things up. To make my life easier, please follow the guidelines
described in this document.
Read this document before writing new code. DO NOT USE fprintf
(or printf) to output things. Also, instead of writing
FIXMEs in the source, output a FIXME message if you can.
IMPORTANT: at the end of the document, there is a "Style Guide"
for debugging messages. Please read it.
28 Mar 1998, Dimitrie O. Paun <dimi@cs.toronto.edu>
Debugging classes
-----------------
There are 4 types (or classes) of debugging messages:
FIXME -- Messages in this class relate to behavior of Wine that does
not correspond to standard Windows behavior and that should
be fixed.
Examples: stubs, semi-implemented features, etc.
ERR -- Messages in this class relate to serious errors in Wine.
This sort of messages are close to asserts -- that is,
you should output an error message when the code detects a
condition which should not happen. In other words, important
things that are not warnings (see below), are errors.
Examples: unexpected change in internal state, etc.
WARN -- These are warning messages. You should report a warning when
something unwanted happen but the function behaves properly.
That is, output a warning when you encounter something
unexpected (ex: could not open a file) but the function deals
correctly with the situation (that is, according to the docs).
If you do not deal correctly with it, output a fixme.
Examples: fail to access a resource required by the app, etc.
TRACE -- These are detailed debugging messages that are mainly useful
to debug a component. These are usually turned off.
Examples: everything else that does not fall in one of the
above mentioned categories and the user does not
need to know about it.
The user has the capability to turn on or off messages of a particular
type. You can expect the following patterns of usage (but note that
any combination is possible):
-- when you debug a component, all types (TRACE,WARN,ERR,FIXME)
will be enabled.
-- during the pre-alpha (maybe alpha) stage of Wine, most likely
the TRACE class will be disabled by default, but all others
(WARN,ERR,FIXME) will be enabled by default.
-- when Wine will become stable, most likely the TRACE and WARN
classes will be disabled by default, but all ERRs and FIXMEs
will be enabled.
-- in some installations that want the smallest footprint
and where the debug information is of no interest,
all classes may be disabled by default.
Of course, the user will have the runtime ability to override these
defaults. However, this ability may be turned off and certain classes
of messages may be completely disabled at compile time to reduce the
size of Wine.
Debugging channels
------------------
Also, we divide the debugging messages on a component basis. Each
component is assigned a debugging channel. The identifier of the
channel must be a valid C identifier but note that it may also be a
reserved word like int or static.
Examples of debugging channels:
reg, updown, string
We will refer to a generic channel as xxx.
Note: for those who know the old interface, the channel/type is
what followed the _ in the dprintf_xxx statements.
For example, to output a message on the debugging channel
reg in the old interface you would had to write:
dprintf_reg(stddeb, "Could not access key!\n");
In the new interface, we drop the stddeb as it is implicit.
However, we add an orthogonal piece of information to the
message: its class. This is very important as it will allow
us to selectively turn on or off certain messages based on the
type of information they report. For this reason it is essential
to choose the right class for the message.
Anyhow, suppose we figured that this message should belong
in the WARN class, so in the new interface, you write:
WARN(reg, "Could not access key!\n");
---
How to use it
-------------
So, to output a message (class YYY) on channel xxx, do:
#include "debug.h"
....
YYY(xxx, "<message>", ...);
Some examples from the code:
#include "debug.h"
...
TRACE(crtdll, "CRTDLL_setbuf(file %p buf %p)", file, buf);
WARN(aspi, "Error opening device errno=%d", save_error);
If you need to declare a new debugging channel, use it in your code
and then do:
%tools/make_debug
in the root directory of Wine.
Note that this will result in almost complete recompilation of Wine.
Notes:
1. Please pay attention to which class you assign the message.
There are only 4 classes, so it is not hard. The reason
it is important to get it right is that too much information
is no information. For example, if you put things into the
WARN class that should really be in the TRACE class, the
output will be too big and this will force the user to
turn warnings off. But this way he will fail to see the important
ones. Also, if you put warnings into the TRACE class lets say,
he will most likely miss those because usually the TRACE class
is turned off. A similar argument can be made if you mix any
other two classes.
2. All lines should end with a newline.If you can NOT output
everything that you want in the line with only one statement,
then you need to build the string in memory.
Please read the section below "In-memory messages" on the
preferred way to do it. PLEASE USE THAT INTERFACE TO BUILD
MESSAGES IN MEMORY. The reason is that we are not sure that
we like it and having everything in one format will facilitate
the (automatic) translation to a better interface.
Are we debugging?
-----------------
To test whether the debugging output of class yyy on channel xxx is
enabled, use:
TRACE_ON to test if TRACE is enabled
WARN_ON to test if WARN is enabled
FIXME_ON to test if FIXME is enabled
ERR_ON to test if ERR is enabled
Examples:
if(TRACE_ON(atom)){
...blah...
}
Note that you should normally need to test only if TRACE_ON. At present,
none of the other 3 tests (except for ERR_ON which is used only once!)
are used in Wine.
In-memory messages
------------------
If you NEED to build the message from multiple calls, you need to
build it in memory. To do that, you should use the following
interface:
- declare a string (where you are allowed to declare C variables)
as follows:
dbg_decl_str(name, len);
where name is the name of the string (you should use the channel
name on which you are going to output it)
- print in it with:
dsprintf(name, "<message>", ...);
which is just like a sprintf function but instead of a C string as
first parameter it takes the name you used to declare it.
- obtain a pointer to the string with:
dbg_str(name)
- reset the string (if you want to reuse it with):
dbg_reset_str(name);
Example (modified from the code):
void some_func(tabs)
{
INT32 i;
LPINT16 p = (LPINT16)tabs;
dbg_decl_str(listbox, 256); /* declare the string */
for (i = 0; i < descr->nb_tabs; i++) {
descr->tabs[i] = *p++<<1;
if(TRACING(listbox)) /* write in it only if
dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
}
TRACE(listbox, "Listbox %04x: settabstops %s",
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
}
If you need to use it two times in the same scope do like this:
void some_func(tabs)
{
INT32 i;
LPINT16 p = (LPINT16)tabs;
dbg_decl_str(listbox, 256); /* declare the string */
for (i = 0; i < descr->nb_tabs; i++) {
descr->tabs[i] = *p++<<1;
if(TRACING(listbox)) /* write in it only if
dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
}
TRACE(listbox, "Listbox %04x: settabstops %s\n",
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
dbg_reset_str(listbox); /* !!!reset the string!!! */
for (i = 0; i < descr->extrainfo_nr; i++) {
descr->extrainfo = *p+1;
if(TRACING(listbox)) /* write in it only if
dsprintf(listbox,"%3d ",descr->extrainfo); /* we are gonna output it */
}
TRACE(listbox, "Listbox %04x: extrainfo %s\n",
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
}
IMPORTANT NOTE:
As I already stated, I do not think this will be the ultimate interface
for building in-memory debugging messages. In fact, I do have better ideas
which I hope to have time to implement for the next release. For this
reason, please try not to use it. However, if you need to output a line
in more than one dprintf_xxx calls, then USE THIS INTERFACE. DO NOT use
other methods. This way, I will easily translate everything to the new
interface (when it will become available). So, if you need to use it,
then follow the following guidelines:
-- wrap calls to dsprintf with a
if(YYY(xxx))
dsprintf(xxx,...);
Of course, if the call to dsprintf is made from within a function
which you know is called only if YYY(xxx) is true
(say you call it only like this:
if(YYY(xxx))
print_some_debug_info();
)
then you need not (and should not) wrap calls to dsprintf with
the before mentioned if.
-- name the string EXACTLY like the debugging channel on which
is going to be output. Please see the above example.
Resource identifiers
--------------------
Resource identifiers can be either strings or numbers. To make life a bit
easier for outputting this beasts (and to help you avoid the need to build
the message in memory), I introduced a new function called:
debugres
The function is defined in debugstr.h
and has the following prototype:
LPSTR debugres(const void *id);
It takes a pointer to the resource id and returns a nicely formatted
string of the identifier.
It the high word of the pointer is 0, then it assumes that the
identifier is a number and thus returns a string of the form:
#xxxx
where xxxx are 4 hex-digits representing the low word of id.
It the high word of the pointer is not 0, then it assumes that the
identifier is a string and thus returns a string of the form:
'<identifier>'
Thus, to use it, do something on the following lines:
#include "debug.h"
...
YYY(xxx, "resource is %s", debugres(myresource));
The -debugmsg command line option
---------------------------------
So, the -debugmsg command line option has been changed as follows:
- the new syntax is: -debugmsg [yyy]#xxx[,[yyy1]#xxx1]*
where # is either + or -
- when the optional class argument (yyy) is not present,
then the statement will enable(+)/disable(-) all messages for
the given channel (xxx) on all classes. For example:
-debugmsg +reg,-file
enables all messages on the reg channel and disables all
messages on the file channel.
This is same as the old semantics.
- when the optional class argument (yyy) is present,
then the statement will enable(+)/disable(-) messages for
the given channel (xxx) only on the given class. For example:
-debugmsg trace+reg,warn-file
enables trace messages on the reg channel and disables warning
messages on the file channel.
- also, the pseudo-channel all is also supported and it has the
intuitive semantics:
-debugmsg +all -- enables all debug messages
-debugmsg -all -- disables all debug messages
-debugmsg yyy+all -- enables debug messages for class yyy on all
channels.
-debugmsg yyy-all -- disables debug messages for class yyy on all
channels.
So, for example:
-debugmsg warn-all -- disables all warning messages.
Also, note that at the moment:
- the fixme and err classes are enabled by default
- the trace and warn classes are disabled by default
Compiling Out Debugging Messages
--------------------------------
To compile out the debugging messages, provide configure with the
following options:
--disable-debug -- turns off TRACE, WARN, and FIXME (and DUMP).
--disable-trace -- turns off TRACE only.
This will result in an executable that, when stripped, is about 15%-20%
smaller. Note, however, that you will not be able to effectively debug
Wine without these messages.
This feature has not been extensively tested--it may subtly break some
things.
A Few Notes on Style
--------------------
This new scheme makes certain things more consistent but there is still
room for improvement by using a common style of debug messages. Before
I continue, let me note that the output format is the following:
yyy:xxx:fff <message>
where:
yyy = the class (fixme, err, warn, trace)
xxx = the channel (atom, win, font, etc)
fff = the function name
these fields are output automatically. All you have to provide is
the <message> part.
So here are some ideas:
* do NOT include the name of the function: it is included automatically
* if you want to output the parameters of the function, do it as the first
thing and include them in parenthesis, like this:
YYY(xxx, "(%d,%p,etc)...\n", par1, par2, ...);
* for stubs, you should output a FIXME message. I suggest this style:
FIXME(xxx, "(%x,%d...): stub\n", par1, par2, ...);
That is, you output the parameters, then a : and then a string
containing the word "stub". I've seen "empty stub", and others, but I
think that just "stub" suffices.
* output 1 and ONLY 1 line per message. That is, the format string should
contain only 1 \n and it should always appear at the end of the string.
(there are many reasons for this requirement, one of them is that each
debug macro adds things to the beginning of the line)
* if you want to name a value, use = and NOT :. That is, instead of
saying:
FIXME(xxx, "(fd: %d, file: %s): stub\n", fd, name);
say:
FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
use : to separate categories.
* try to avoid the style:
FIXME(xxx,
"(fd=%d, file=%s): stub\n", fd, name);
but use:
FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
The reason is that if you want to grep for things, you would search for
FIXME but in the first case there is no additional information available,
where in the second one, there is (e.g. the word stub)
* if you output a string s that might contain control characters,
or if s may be null, use debugstr_a (for ASCII strings, or
debugstr_w for Unicode strings) to convert s to a C string, like
this:
HANDLE32 WINAPI YourFunc(LPCSTR s)
{
FIXME(xxx, "(%s): stub\n", debugstr_a(s));
}
* if you want to output a resource identifier, use debugres to
convert it to a string first, like this:
HANDLE32 WINAPI YourFunc(LPCSTR res)
{
FIXME(xxx, "(res=%s): stub\n", debugres(s));
}
if the resource identifier is a SEGPTR, use PTR_SEG_TO_LIN to get a
liner pointer first:
HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type )
{
[...]
TRACE(resource, "module=%04x name=%s type=%s\n",
hModule, debugres(PTR_SEG_TO_LIN(name)),
debugres(PTR_SEG_TO_LIN(type)) );
[...]
}
* for messages intended for the user (specifically those that report
errors in wine.conf), use the MSG macro. Use it like a printf:
MSG( "Definition of drive %d is incorrect!\n", drive );
However, note that there are _very_ few valid uses of this macro.
Most messages are debugging messages, so chances are you will not
need to use this macro. Grep the source to get an idea where it
is appropriate to use it.
* for structure dumps, use the DUMP macro. Use it like a printf,
just like the MSG macro. Similarly, there are only a few valid
uses of this macro. Grep the source to see when to use it.

847
documentation/debugger.sgml Normal file
View File

@ -0,0 +1,847 @@
<chapter id="debugger">
<title>The Wine Debugger</title>
<sect1 id="dbg-intro">
<title>I Introduction</title>
<para>
written by Eric Pouech (???) (Last updated: 6/14/2000)
</para>
<para>
(Extracted from <filename>wine/documentation/winedbg</filename>)
</para>
<sect2>
<title>I.1 Processes and threads: in underlying OS and in Windows</title>
<para>
Before going into the depths of debugging in Wine, here's
a small overview of process and thread handling in Wine.
It has to be clear that there are two different beasts:
processes/threads from the Unix point of view and
processes/threads from a Windows point of view.
</para>
<para>
Each Windows' thread is implemented as a Unix process (under
Linux using the <function>clone</function> syscall), meaning
that all threads of a same Windows' process share the same
(unix) address space.
</para>
<para>
In the following:
</para>
<itemizedlist>
<listitem>
<para><varname>W-process</varname> means a process in Windows' terminology</para>
</listitem>
<listitem>
<para><varname>U-process</varname> means a process in Unix' terminology</para>
</listitem>
<listitem>
<para><varname>W-thread</varname> means a thread in Windows' terminology</para>
</listitem>
</itemizedlist>
<para>
A <varname>W-process</varname> is made of one or several
<varname>W-threads</varname>. Each
<varname>W-thread</varname> is mapped to one and only one
<varname>U-process</varname>. All
<varname>U-processes</varname> of a same
<varname>W-process</varname> share the same address space.
</para>
<para>
Each Unix process can be identified by two values:
</para>
<itemizedlist>
<listitem>
<para>the Unix process id (<varname>upid</varname> in the following)</para>
</listitem>
<listitem>
<para>the Windows's thread id (<varname>tid</varname>)</para>
</listitem>
</itemizedlist>
<para>
Each Windows' process has also a Windows' process id
(<varname>wpid</varname> in the following). It must be clear
that <varname>upid</varname> and <varname>wpid</varname> are
different and shall not be used instead of the other.
</para>
<para>
<varname>Wpid</varname> and <varname>tid</varname> are
defined (Windows) system wide. They must not be confused
with process or thread handles which, as any handle, is an
indirection to a system object (in this case process or
thread). A same process can have several different handles
on the same kernel object. The handles can be defined as
local (the values is only valid in a process), or system
wide (the same handle can be used by any
<varname>W-process</varname>).
</para>
</sect2>
<sect2>
<title>I.2 Wine, debugging and WineDbg</title>
<para>
When talking of debugging in Wine, there are at least two
levels to think of:
</para>
<itemizedlist>
<listitem>
<para>the Windows' debugging API.</para>
</listitem>
<listitem>
<para>the Wine integrated debugger, dubbed
<command>WineDbg</command>.</para>
</listitem>
</itemizedlist>
<para>
Wine implements most the the Windows' debugging API (the
part in KERNEL32, not the one in
<filename>IMAGEHLP.DLL</filename>), and allows any program
(emulated or WineLib) using that API to debug a
<varname>W-process</varname>.
</para>
<para>
<command>WineDbg</command> is a WineLib application making
use of this API to allow debugging both any Wine or WineLib
applications as well as Wine itself (kernel and all DLLs).
</para>
</sect2>
</sect1>
<sect1 id="dbg-modes">
<title>II WineDbg's modes of invocation</title>
<sect2>
<title>II.1 Starting a process</title>
<para>
Any application (either a Windows' native executable, or a
WineLib application) can be run through
<command>WineDbg</command>. Command line options and tricks
are the same as for wine:
</para>
<screen>
winedbg telnet.exe
winedbg "hl.exe -windowed"
</screen>
</sect2>
<sect2>
<title>II.2 Attaching</title>
<para>
<command>WineDbg</command> can also be launched without any
command line argument: <command>WineDbg</command> is started
without any attached process. You can get a list of running
<varname>W-processes</varname> (and their
<varname>wpid</varname>'s) using the <command>walk
process</command> command, and then, with the
<command>attach</command> command, pick up the
<varname>wpid</varname> of the <varname>W-process</varname>
you want to debug. This is (for now) a neat feature for the
following reasons:
</para>
<itemizedlist>
<listitem>
<para>you can debug an already started application</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>II.3 On exception</title>
<para>
When something goes wrong, Windows tracks this as an
exception. Exceptions exist for segmentation violation,
stack overflow, division by zero...
</para>
<para>
When an exception occurs, Wine checks if the <varname>W-process</varname> is
debugged. If so, the exception event is sent to the
debugger, which takes care of it: end of the story. This
mechanism is part of the standard Windows' debugging API.
</para>
<para>
If the <varname>W-process</varname> is not debugged, Wine
tries to launch a debugger. This debugger (normally
<command>WineDbg</command>, see III Configuration for more
details), at startup, attaches to the
<varname>W-process</varname> which generated the exception
event. In this case, you are able to look at the causes of
the exception, and either fix the causes (and continue
further the execution) or dig deeper to understand what went
wrong.
</para>
<para>
If <command>WineDbg</command> is the standard debugger, the
<command>pass</command> and <command>cont</command> commands
are the two ways to let the process go further for the
handling of the exception event.
</para>
<para>
To be more precise on the way Wine (and Windows) generates
exception events, when a fault occurs (segmentation
violation, stack overflow...), the event is first sent to
the debugger (this is known as a first chance exception).
The debugger can give two answers:
</para>
<variablelist>
<varlistentry>
<term>continue:</term>
<listitem>
<para>
the debugger had the ability to correct what's
generated the exception, and is now able to continue
process execution.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>pass:</term>
<listitem>
<para>
the debugger couldn't correct the cause of the
first chance exception. Wine will now try to walk
the list of exception handlers to see if one of them
can handle the exception. If no exception handler is
found, the exception is sent once again to the
debugger to indicate the failure of the exception
handling.
</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
since some of Wine's code uses exceptions and
<function>try/catch</function> blocks to provide some
functionality, <command>WineDbg</command> can be entered
in such cases with segv exceptions. This happens, for
example, with <function>IsBadReadPtr</function> function.
In that case, the <command>pass</command> command shall be
used, to let the handling of the exception to be done by
the <function>catch</function> block in
<function>IsBadReadPtr</function>.
</para>
</note>
</sect2>
<sect2>
<title>II.4 Quitting</title>
<para>
Unfortunately, Windows doesn't provide a detach kind of API,
meaning that once you started debugging a process, you must
do so until the process dies. Killing (or stopping/aborting)
the debugger will also kill the debugged process. This will
be true for any Windows' debugging API compliant debugger,
starting with <command>WineDbg</command>.
</para>
</sect2>
</sect1>
<sect1 id="dbg-config">
<title>III Configuration</title>
<sect2>
<title>III.1 Registry configuration</title>
<para>
The Windows' debugging API uses a registry entry to know
with debugger to invoke when an unhandled exception
occurs (see II.3 for some details). Two values in key
</para>
<programlisting>
"MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
</programlisting>
<para>
Determine the behavior:
</para>
<variablelist>
<varlistentry>
<term>Debugger:</term>
<listitem>
<para>
this is the command line used to launch the debugger
(it uses two <function>printf</function> formats
(<literal>%ld</literal>) to pass context dependent
information to the debugger). You should put here a
complete path to your debugger
(<command>WineDbg</command> can of course be used, but
any other Windows' debugging API aware debugger will
do).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Auto:</term>
<listitem>
<para>
if this value is zero, a message box will ask the
user if he/she wishes to launch the debugger when an
unhandled exception occurs. Otherwise, the debugger
is automatically started.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
A regular Wine registry looks like:
</para>
<programlisting>
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
"Auto"=dword:00000001
"Debugger"="/usr/local/bin/winedbg %ld %ld"
</programlisting>
<note>
<title>Note 1</title>
<para>
creating this key is mandatory. Not doing so will not
fire the debugger when an exception occurs.
</para>
</note>
<note>
<title>Note 2</title>
<para>
<command>wineinstall</command> sets up this correctly.
However, due to some limitation of the registry installed,
if a previous Wine installation exists, it's safer to
remove the whole
</para>
<programlisting>
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
</programlisting>
<para>
key before running again <command>wineinstall</command> to
regenerate this key.
</para>
</note>
</sect2>
<sect2>
<title>III.2 WineDbg configuration</title>
<para>
<command>WineDbg</command> can be configured thru a number
of options. Those options are stored in the registry, on a
per user basis. The key is (in *my* registry)
</para>
<programlisting>
[eric\\Software\\Wine\\WineDbg]
</programlisting>
<para>
Those options can be read/written while inside
<command>WineDbg</command>, as part of the debugger
expressions. To refer to one of this option, its name must
be prefixed by a <literal>$</literal> sign. For example,
</para>
<programlisting>
set $BreakAllThreadsStartup = 1
</programlisting>
<para>
sets the option <varname>BreakAllThreadsStartup</varname> to
<literal>TRUE</literal>.
</para>
<para>
All the options are read from the registry when
<command>WineDbg</command> starts (if no corresponding value
is found, a default value is used), and are written back to
the registry when <command>WineDbg</command> exits (hence,
all modifications to those options are automatically saved
when <command>WineDbg</command> terminates).
</para>
<para>
Here's the list of all options:
</para>
<sect3>
<title>III.2.1 Controling when the debugger is entered</title>
<variablelist>
<varlistentry>
<term><varname>BreakAllThreadsStartup</varname></term>
<listitem>
<para>
Set to <literal>TRUE</literal> if at all threads
start-up the debugger stops set to
<literal>FALSE</literal> if only at the first thread
startup of a given process the debugger stops.
<literal>FALSE</literal> by default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BreakOnCritSectTimeOut</varname></term>
<listitem>
<para>
Set to <literal>TRUE</literal> if the debugger stops
when a critical section times out (5 minutes);
<literal>TRUE</literal> by default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BreakOnAttach</varname></term>
<listitem>
<para>
Set to <literal>TRUE</literal> if when
<command>WineDbg</command> attaches to an existing
process after an unhandled exception,
<command>WineDbg</command> shall be entered on the
first attach event. Since the attach event is
meaningless in the context of an exception event
(the next event which is the exception event is of
course relevant), that option is likely to be
<literal>FALSE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BreakOnFirstChance</varname></term>
<listitem>
<para>
An exception can generate two debug events. The
first one is passed to the debugger (known as a
first chance) just after the exception. The debugger
can then decides either to resume execution (see
<command>WineDbg</command>'s <command>cont</command>
command) or pass the exception up to the exception
handler chain in the program (if it exists)
(<command>WineDbg</command> implements this thru the
<command>pass</command> command). If none of the
exception handlers takes care of the exception, the
exception event is sent again to the debugger (known
as last chance exception). You cannot pass on a last
exception. When the
<varname>BreakOnFirstChance</varname> exception is
<literal>TRUE</literal>, then winedbg is entered for
both first and last chance execptions (to
<literal>FALSE</literal>, it's only entered for last
chance exceptions).
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>III.2.2 Output handling</title>
<variablelist>
<varlistentry>
<term><varname>ConChannelMask</varname></term>
<listitem>
<para>
Mask of active debugger output channels on console
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>StdChannelMask</varname></term>
<listitem>
<para>
Mask of active debugger output channels on <filename>stderr</filename>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>UseXTerm</varname></term>
<listitem>
<para>
Set to <literal>TRUE</literal> if the debugger uses
its own <command>xterm</command> window for console
input/output. Set to <literal>FALSE</literal> if
the debugger uses the current Unix console for
input/output
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Those last 3 variables are jointly used in two generic ways:
</para>
<orderedlist>
<listitem>
<para>default</para>
<programlisting>
ConChannelMask = DBG_CHN_MESG (1)
StdChannelMask = 0
UseXTerm = 1
</programlisting>
<para>
In this case, all input/output goes into a specific
<command>xterm</command> window (but all debug
messages <function>TRACE</function>,
<function>WARN</function>... still goes to tty where
wine is run from).
</para>
</listitem>
<listitem>
<para>
to have all input/output go into the tty where Wine
was started from (to be used in a X11-free
environment)
</para>
<screen>
ConChannelMask = 0
StdChannelMask = DBG_CHN_MESG (1)
UseXTerm = 1
</screen>
</listitem>
</orderedlist>
<para>
Those variables also allow, for example for debugging
purposes, to use:
</para>
<screen>
ConChannelMask = 0xfff
StdChannelMask = 0xfff
UseXTerm = 1
</screen>
<para>
This allows to redirect all <function>WineDbg</function>
output to both tty Wine was started from, and
<command>xterm</command> debugging window. If Wine (or
<command>WineDbg</command>) was started with a redirection
of <filename>stdout</filename> and/or
<filename>stderr</filename> to a file (with for
example &gt;& shell redirect command), you'll get in that
file both outputs. It may be interesting to look in the
relay trace for specific values which the process segv'ed
on.
</para>
</sect3>
<sect3>
<title>III.2.2 Context information</title>
<variablelist>
<varlistentry>
<term><varname>ThreadId</varname></term>
<listitem>
<para>ID of the <varname>W-thread</varname> currently
examined by the debugger</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ProcessId</varname></term>
<listitem>
<para>ID of the <varname>W-thread</varname> currently
examined by the debugger</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&lt;registers></term>
<listitem>
<para>All CPU registers are also available</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The <varname>ThreadId</varname> and
<varname>ProcessId</varname> variables can be handy to set
conditional breakpoints on a given thread or process.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="dbg-commands">
<title>IV WineDbg commands</title>
<sect2>
<title>IV.1 Misc</title>
<screen>
abort aborts the debugger
quit exits the debugger
attach N attach to a W-process (N is its ID). IDs can be
obtained thru walk process command
</screen>
<screen>
help prints some help on the commands
help info prints some help on info commands
</screen>
<screen>
mode 16 switch to 16 bit mode
mode 32 switch to 32 bit mode
</screen>
</sect2>
<sect2>
<title>IV.2 Flow control</title>
<screen>
cont continue execution until next breakpoint or exception.
pass pass the exception event up to the filter chain.
step continue execution until next C line of code (enters
function call)
next continue execution until next C line of code (doesn't
enter function call)
stepi execute next assembly instruction (enters function
call)
nexti execute next assembly instruction (doesn't enter
function call)
finish do nexti commands until current function is exited
</screen>
<para>
cont, step, next, stepi, nexti can be postfixed by a
number (N), meaning that the command must be executed N
times.
</para>
</sect2>
<sect2>
<title>IV.3 Breakpoints, watch points</title>
<screen>
enable N enables (break|watch)point #N
disable N disables (break|watch)point #N
delete N deletes (break|watch)point #N
cond N removes any a existing condition to (break|watch)point N
cond N &lt;expr&gt; adds condition &lt;expr&gt; to (break|watch)point N. &lt;expr&gt;
will be evaluated each time the breakpoint is hit. If
the result is a zero value, the breakpoint isn't
triggered
break * N adds a breakpoint at address N
break &lt;id&gt; adds a breakpoint at the address of symbol &lt;id&gt;
break &lt;id&gt; N adds a breakpoint at the address of symbol &lt;id&gt; (N ?)
break N adds a breakpoint at line N of current source file
break adds a breakpoint at current $pc address
watch * N adds a watch command (on write) at address N (on 4 bytes)
watch &lt;id&gt; adds a watch command (on write) at the address of
symbol &lt;id&gt;
info break lists all (break|watch)points (with state)
</screen>
</sect2>
<sect2>
<title>IV.4 Stack manipulation</title>
<screen>
bt print calling stack of current thread
up goes up one frame in current thread's stack
up N goes up N frames in current thread's stack
dn goes down one frame in current thread's stack
dn N goes down N frames in current thread's stack
frame N set N as the current frame
info local prints information on local variables for current
function
</screen>
</sect2>
<sect2>
<title>IV.5 Directory & source file manipulation</title>
<screen>
show dir
dir &lt;pathname&gt;
dir
symbolfile &lt;pathname&gt;
</screen>
<screen>
list lists 10 source lines from current position
list - lists 10 source lines before current position
list N lists 10 source lines from line N in current file
list &lt;path&gt;:N lists 10 source lines from line N in file &lt;path&gt;
list &lt;id&gt; lists 10 source lines of function &lt;id&gt;
list * N lists 10 source lines from address N
</screen>
<para>
You can specify the end target (to change the 10 lines
value) using the ','. For example:
</para>
<screen>
list 123, 234 lists source lines from line 123 up to line 234 in
current file
list foo.c:1,56 lists source lines from line 1 up to 56 in file foo.c
</screen>
</sect2>
<sect2>
<title>IV.6 Displaying</title>
<para>
A display is an expression that's evaluated and printed
after the execution of any <command>WineDbg</command>
command.
</para>
<screen>
display lists the active displays
info display (same as above command)
display &lt;expr&gt; adds a display for expression &lt;expr&gt;
display /fmt &lt;expr&gt; adds a display for expression &lt;expr&gt;. Printing
evaluated &lt;expr&gt; is done using the given format (see
print command for more on formats)
del display N deletes display #N
undisplay N (same as del display)
</screen>
</sect2>
<sect2>
<title>IV.7 Disassembly</title>
<screen>
disas disassemble from current position
disas &lt;expr&gt; disassemble from address &lt;expr&gt;
disas &lt;expr&gt;,&lt;expr&gt;disassembles code between addresses specified by
the two &lt;expr&gt;
</screen>
</sect2>
<sect2>
<title>IV.8 Information on Wine's internals</title>
<screen>
info class &lt;id&gt; prints information on Windows's class &lt;id&gt;
walk class lists all Windows' class registered in Wine
info share lists all the dynamic libraries loaded the debugged
program (including .so files, NE and PE DLLs)
info module N prints information on module of handle N
walk module lists all modules loaded by debugged program
info queue N prints information on Wine's queue N
walk queue lists all queues allocated in Wine
info regs prints the value of CPU register
info segment N prints information on segment N
info segment lists all allocated segments
info stack prints the values on top of the stack
info map lists all virtual mappings used by the debugged
program
info wnd N prints information of Window of handle N
walk wnd lists all the window hierarchy starting from the
desktop window
walk wnd N lists all the window hierarchy starting from the
window of handle N
walk process lists all w-processes in Wine session
walk thread lists all w-threads in Wine session
walk modref (no longer avail)
</screen>
</sect2>
<sect2>
<title>IV.9 Memory (reading, writing, typing)</title>
<screen>
x &lt;expr&gt; examines memory at &lt;expr&gt; address
x /fmt &lt;expr&gt; examines memory at &lt;expr&gt; address using format /fmt
print &lt;expr&gt; prints the value of &lt;expr&gt; (possibly using its type)
print /fmt &lt;expr&gt; prints the value of &lt;expr&gt; (possibly using its
type)
set &lt;lval&gt;=&lt;expr&gt; writes the value of &lt;expr&gt; in &lt;lval&gt;
whatis &lt;expr&gt; prints the C type of expression &lt;expr&gt;
</screen>
<para>
<filename>/fmt</filename> is either <filename>/&lt;letter&gt;</filename> or
<filename>/&lt;count&gt;&lt;letter&gt;</filename> letter can be
</para>
<screen>
s =&gt; an ASCII string
u =&gt; an Unicode UTF16 string
i =&gt; instructions (disassemble)
x =&gt; 32 bit unsigned hexadecimal integer
d =&gt; 32 bit signed decimal integer
w =&gt; 16 bit unsigned hexadecimal integer
c =&gt; character (only printable 0x20-0x7f are actually
printed)
b =&gt; 8 bit unsigned hexadecimal integer
</screen>
</sect2>
</sect1>
<sect1 id="dbg-others">
<title>V Other debuggers</title>
<sect2>
<title>V.1 Using other Unix debuggers</title>
<para>
You can also use other debuggers (like
<command>gdb</command>), but you must be aware of a few
items:
</para>
<para>
You need to attach the unix debugger to the correct unix
process (representing the correct windows thread) (you can
"guess" it from a <command>ps fax</command> for example:
When running the emulator, usually the first two
<varname>upids</varname> are for the Windows' application
running the desktop, the first thread of the application is
generally the third <varname>upid</varname>; when running a
WineLib program, the first thread of the application is
generally the first <varname>upid</varname>)
</para>
<note>
<para>
Even if latest <command>gdb</command> implements the
notion of threads, it won't work with Wine because the
thread abstraction used for implementing Windows' thread
is not 100% mapped onto the linux posix threads
implementation. It means that you'll have to spawn a
different <command>gdb</command> session for each Windows'
thread you wish to debug.
</para>
</note>
</sect2>
<sect2>
<title>V.2 Using other Windows debuggers</title>
<para>
You can use any Windows' debugging API compliant debugger
with Wine. Some reports have been made of success with
VisualStudio debugger (in remote mode, only the hub runs
in Wine). GoVest fully runs in Wine.
</para>
</sect2>
<sect2>
<title>V.3 Main differences between winedbg and regular Unix debuggers</title>
<!-- FIXME: convert this into a table -->
<screen>
+----------------------------------+---------------------------------+
| WineDbg | gdb |
+----------------------------------+---------------------------------+
|WineDbg debugs a Windows' process:|gdb debugs a Windows' thread: |
|+ the various threads will be |+ a separate gdb session is |
| handled by the same WineDbg | needed for each thread of |
| session | Windows' process |
|+ a breakpoint will be triggered |+ a breakpoint will be triggered |
| for any thread of the w-process | only for the w-thread debugged |
+----------------------------------+---------------------------------+
|WineDbg supports debug information|gdb supports debug information |
|from: |from: |
|+ stabs (standard Unix format) |+ stabs (standard Unix format) |
|+ Microsoft's C, CodeView, .DBG | |
+----------------------------------+---------------------------------+
</screen>
</sect2>
</sect1>
<sect1 id="dbg-limits">
<title>VI Limitations</title>
<para>
16 bit processes are not supported (but calls to 16 bit code
in 32 bit applications are).
</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" "")
End:
-->

381
documentation/debugging
View File

@ -1,381 +0,0 @@
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
documentation/bugreports for information on how to write useful bug
reports.
Crashes
=======
These usually show up like this:
|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
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 feasonable.
1. 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 WHOLE crashdump even if it doesn't make sense to you.
(In this case it is access to an invalid selector, for %es is 0000, as
seen in the register dump).
2. Determine where the reason came from.
Since this is usually a primary/secondary reaction to a failed or
misbehaving Wine function, rerun Wine with "-debugmsg +relay" (without ")
added to the commandline. This will get rather much output, but usually
the reason is located in the last call(s). Those lines usually look like
this:
|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.
3. 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 'TRACE(<channel>,"(...)\n");'
at the beginning of the function. Rerun wine with
"-debugmsg +xyz,+relay" added to the commandline.
4. Additional information on how to debug using the internal debugger can be
found in debugger/README.
5. If those information isn't clear enough or if you want to know more about
what's happening in the function itself, try running wine with "-debugmsg
+all", which dumps ALL included debug information in wine.
6. If that isn't enough add more debug output for yourself into the
functions you find relevant. See documentation/debug-msgs.
You might also try to run the program in gdb instead of using the
WINE-debugger. If you do that, use "handle SIGSEGV nostop noprint"
to disable the handling of seg faults inside gdb (needed for Win16).
If you don't use the "-desktop" or "-managed" option,
start the WINE process with "-sync", or chances are good to get X into
an unusable state.
7. You can also set a breakpoint for that function. Start wine with the
"-debug" option added to the commandline. After loading the executable
wine will enter the internal debugger. Use "break KERNEL_LSTRLEN"
(replace by function you want to debug, CASE IS RELEVANT.) to set a
breakpoint. Then use "continue" 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 "continue" 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.
Program hangs, nothing happens
==============================
Switch to UNIX shell, get the process-ID using "ps -a|grep wine", and do a
"kill -HUP <pid>" (without " and <>). Wine will then enter its internal
debugger and you can proceed as explained above. Also, you can use -debug
switch and then you can get into internal debugger by pressing Ctrl-C in
the terminal where you run Wine.
Program reports an error with a Messagebox
==========================================
Sometimes programs are reporting failure using a 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.
Since the failure happens usually directly before setting up the Messagebox
you can start wine with "-debug" added to the commandline, set a breakpoint
at "MessageBoxA" (called by win16 and win32 programs) and proceed with
"continue". With "-debugmsg +all" Wine will now stop directly before
setting up the Messagebox. Proceed as explained above.
You can also run wine using "wine -debugmsg +relay program.exe 2>&1|less -i"
and in less search for messagebox.
Disassembling programs:
=======================
You may also try to disassemble the offending program to check for
undocumented features and/or use of them.
The best, freely available, disassembler for Win16 programs is
Windows Codeback, archivename wcbxxx.zip, which usually can be found
in the Cica-Mirror subdirectory on the WINE ftpsites. (See ANNOUNCE).
Disassembling win32 programs is possible using the Windows Disassembler 32,
archivename something like w32dsm87.zip (or similar) on ftp.winsite.com
and mirrors. The shareware version does not allow saving of disassembly
listings.
You can also use the newer (and in the full version better) Interactive
Disassembler (IDA) from the ftp sites mentioned at the end of the document.
Understanding disassembled code is mostly a question of exercise.
Most code out there uses standard C function entries (for it is usually
written in C). Win16 function entries usually look like that:
| push bp
| mov bp, sp
| ... function code ..
| retf XXXX <--------- XXXX is number of bytes of arguments
This is a FAR function with no local storage. The arguments usually start
at [bp+6] with increasing offsets. Note, that [bp+6] belongs to the RIGHTMOST
argument, for exported win16 functions use the PASCAL calling convention.
So, if we use strcmp(a,b) with a and b both 32 bit variables b would be at
[bp+6] and a at [bp+10].
Most functions make also use of local storage in the stackframe:
| enter 0086, 00
| ... function code ...
| leave
| retf XXXX
This does mostly the same as above, but also adds 0x86 bytes of
stackstorage, which is accessed using [bp-xx].
Before calling a function, arguments are pushed on the stack using something
like this:
| push word ptr [bp-02] <- will be at [bp+8]
| push di <- will be at [bp+6]
| call KERNEL.LSTRLEN
Here first the selector and then the offset to the passed string are pushed.
Sample debugging session:
=========================
Let's debug the infamous Word SHARE.EXE messagebox:
|marcus@jet $ wine winword.exe
| +---------------------------------------------+
| | ! You must leave Windows and load SHARE.EXE|
| | before starting Word. |
| +---------------------------------------------+
|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>break MessageBoxA <---- Set Breakpoint
|Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|Wine-dbg>c <---- 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)
|... <----- 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.
Whoops, it even detects that something is wrong!
|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
This fails, since my C: drive is in this case mounted readonly.
|Ret KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
^^^^^^ HFILE_ERROR16, yes, it failed.
|Call USER.1: MESSAGEBOX(0x0000,0x09278376"Sie müssen Windows verlassen und SHARE.EXE laden bevor Sie Word starten.",0x00000000,0x1030) ret=060f:084f ds=0927
And MessageBox'ed.
|Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|190 { <- the sourceline
In 32 bit mode.
Wine-dbg>
The code seems to find a writeable harddisk and tries to create a file
there. To work around this bug, you can define C: as a networkdrive,
which is ignored by the code above.
Written by Marcus Meissner <msmeissn@cip.informatik.uni-erlangen.de>,
additions welcome.
-------
Here are some useful debugging tips, added by Andreas Mohr:
a) 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
wine -debugmsg +relay program
to get a listing of the functions the program calls in its start function.
Now you do a
wine -debug winfile.exe
This way, you get into Wine-dbg. Now you can set a breakpoint on any
function the program calls in the start function and just type "c" 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.
b) 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 MessageBox().
That's why you should re-run the program with e.g.
wine -debugmsg +relay <program name> &>relmsg
Then do a "more relmsg" and search for the last occurrence of a call to the string "MESSAGEBOX".
This is a line like
Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
In my example the lines before the call to MessageBox() look like that:
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
I think that the call to MessageBox() in this example is _not_ 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 0x0004:0x1056.
As the segment value of the address is only "4", I think that that is
only an internal program value. But the offset address reveals something
quite interesting:
Offset 1056 is _very_ close to the return address of FREELIBRARY():
Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
^^^^
Provided that segment 0x0004 is indeed
segment 0x1cf, we now we can use IDA (available at
ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip)
to disassemble the part that caused the error. We just have to find
the address of the call to FreeLibrary(). 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 0x1cf).
c) 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 GetVersion16/32 as those functions are called
very often.
Then do a "c" until you are able to set this breakpoint without error message.
d) Some useful programs:
IDA: ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip
*Very* good DOS disassembler ! It's badly needed for debugging Wine sometimes.
XRAY: ftp://ftp.th-darmstadt.de/pub/machines/ms-dos/SimTel/msdos/asmutil/xray15.zip
Traces DOS calls (Int 21h, DPMI, ...). Use it with Windows to correct
file management problems etc.
pedump: http://oak.oakland.edu/pub/simtelnet/win95/prog/pedump.zip
Dumps the imports and exports of a PE (Portable Executable) DLL.
Some basic debugger usages:
===========================
After starting you program with
wine -debug myprog.exe
the program loads and you get a prompt at the program starting point.
Then you can set breakpoints:
b RoutineName (by outine name) OR
b *0x812575 (by address)
Then you hit 'c' (continue) to run the program. It stops at
the breakpoint. You can type
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 <line number> (to list source code)
x <variable name> (to examine a variable; only works if code
is not compiled with optimization)
x 0x4269978 (to examine a memory location)
? (help)
q (quit)
By hitting Enter, you repeat the last command.

1556
documentation/debugging.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

501
documentation/distributors
View File

@ -1,501 +0,0 @@
A small WINE distribution guide.
While packaging WINE for one of the Linux distributions I came across
several points which have not been clarified yet. Particularly a how-to
for WINE packaging distributors is missing. This document tries to give
a brief overview over the rationales I thought up and how I tried to
implement it.
(While the examples use "rpm" most of this stuff can be applied to other
packagers too.)
NOTE THAT YOU SHOULD RECHECK THIS FILE EVERY TWO MONTHS OR SO
(diff -uN comes to my mind here...).
We'll be adding stuff constantly here in order to improve the Wine
environment !
1. Rationales
A WINE install should:
a. Not have a world writeable directory (-tree).
b. Require only as much user input as needed. It would be very good if it
would not require any at all. Just let the system administrator do "rpm
-i wine.rpm" and let any user be able to run "wine sol.exe" instantly.
c. Give the user as much flexibility as possible to install his own
applications, do his own configuring etc.
d. Come as preconfigured as possible, so the user does not need to change
any configuration files.
e. Use only as much diskspace as needed per user.
A WINE install needs:
f. A writeable C:\ directory structure on a per user basis. Applications do
dump .ini files into c:\windows, installers dump .exe, .dll and more into
c:\windows\ and subdirectories or into C:\Program Files\.
g. The .exe and .dll from a global read-only Windows installation to be
found by applications.
h. Some special .dll and .exe files in the windows\system directory, since
applications directly check for their presence.
i. Some special program environment.
2. Implementation
2.1 Building the package
WINE is configured the usual way (depending on your buildenvironment).
The "prefix" is chosen using your application placement policy
(/usr/,/usr/X11R6/, /opt/wine/ or similar). The configuration files
(wine.conf, wine.userreg, wine.systemreg) are targeted for /etc/wine/
(rationale: FHS 2.0, multiple readonly configuration files of a package).
Example (split this into %build and %install section for rpm):
CFLAGS=$RPM_OPT_FLAGS \
./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
make
BR=$RPM_BUILD_ROOT
make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
install -d $BR/etc/wine/
install -m 644 wine.ini $BR/etc/wine/wine.conf
# Put all our dlls in a seperate directory. (this works only if
# you have a buildroot)
install -d $BR/usr/X11R6/lib/wine
mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
# the clipboard server is started on demand.
install -m 755 windows/x11drv/wineclipsrv $BR/usr/X11R6/bin/
# The WINE server is needed.
install -m 755 server/wineserver $BR/usr/X11R6/bin/
Here we unfortunately do need to create wineuser.reg and winesystem.reg
from the WINE distributed winedefault.reg. This can be done using
./regapi once for one example user and then reusing his .wine/user.reg
and .wine/system.reg files. [FIXME: this needs to be done better]
install -m 644 wine.systemreg $BR/etc/wine/
install -m 644 wine.userreg $BR/etc/wine/
There are now a lot of libraries generated by the build process, so a
seperate library directory should be used.
install -d 755 $BR/usr/X11R6/lib/
mv $BR/
You will need to package the files:
$prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
$prefix/man/man1/wine.1, $prefix/include/wine/*,
$prefix/bin/wineserver, $prefix/bin/wineclipsrv
%config /etc/wine/*
%doc ... choose from the toplevel directory and documentation/
The Post install script:
if ! grep -q /usr/X11R6/lib/wine /etc/ld.so.conf; then
echo "/usr/X11R6/lib/wine" >> /etc/ld.so.conf
fi
/sbin/ldconfig
The post uninstall script:
if [ "$1" = 0 ]; then
perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
fi
/sbin/ldconfig
2.2 Creating a good default configuration file
For the rationales of needing as less input from the user as possible
arises the need for a very good configuration file. The one supplied
with WINE is currently lacking. We need:
- [Drive X]:
+ A for the floppy. Specify your distributions default floppy mountpoint
here. (Path=/auto/floppy)
+ C for the C:\ directory. Here we use the users homedirectory, for most
applications do see C:\ as root-writeable directory of every windows
installation and this basically is it in the UNIX-user context.
(Path=${HOME})
+ R for the CD-Rom drive. Specify your distributions default CD-ROM drives
mountpoint here. (Path=/auto/cdrom)
+ T for temporary storage. We do use /tmp/ (rationale: between process
temporary data belongs to /tmp/, FHS 2.0)
+ W for the original Windows installation. This drive points to the
windows\ subdirectory of the original windows installation. This avoids
problems with renamed 'windows' directories (as for instance 'lose95',
'win' or 'sys\win95'). During compile/package/install we leave this
to be '/', it has to be configured after the package install.
+ Z for the UNIX Root directory (Path=/). This avoids any problems with
"could not find drive for current directory" users occasionaly complain
about in the newsgroup and the ircchannel. It also makes the whole
directory structure browseable. The type of Z should be network, so
applications expect it to be readonly.
- [wine]:
Windows=c:\windows\ (the windows/ subdirectory in the users
homedirectory)
System=c:\windows\system\ (the windows/system subdirectory in the users
homedirectory)
Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
; Using this trick we have in fact two windows installations in one, we
; get the stuff from the readonly installation and can write to our own.
Temp=t:\ (the TEMP directory)
- [Tweak.Layout]
WineLook=win95 (just the coolest look ;)
- Possibly modify the [spooler], [serialports] and [parallelports] sections.
(FIXME: possibly more, including printer stuff)
Add this prepared configuration file to the package.
2.3 Installing WINE for the system administrator
Install the package using the usual packager "rpm -i wine.rpm".
You may edit /etc/wine/wine.conf, [Drive W], to point to a possible windows
installation right after the install. Thats it.
Note that on Linux you should somehow try to add the "unhide" mount option
(-> "man mount") to the CD-ROM entry in /etc/fstab during package install,
as several stupid Windows programs mark some setup (!) files
as hidden (ISO9660) on CD-ROMs, which will greatly confuse users
as they won't find their setup files on the CD-ROMs as they were
used on Windows systems when "unhide" is not set ;-\
And of course the setup program will complain that "setup.ins" or some other
mess is missing...
If you choose to do so, then please make this change verbose to the admin.
2.4 Installing WINE for the user
The user will need to run a setup script before the first invocation of
WINE. This script should:
- Copy /etc/wine/wine.conf for user modification.
- Allow specification of the original windows installation to use (which
modifies the copied wine.conf file).
- Create the windows directory structure (c:\windows,c:\windows\system,
c:\windows\Start Menu\Programs,c:\Program Files,c:\Desktop,...)
(FIXME: Not sure this is needed for all files:)
- Symlink all .dll and .exe files from the original windows installation to
the windows directory. Why? Some program reference "%windowsdir%/file.dll"
or "%systemdir%/file.dll" directly and fail if they are not present.
This will give a huge number of symlinks, yes. However, if an installer
later overwrites on of those files, it will overwrite the symlink (so
that the file now lies in the windows/ subdirectory).
- On later invocation the script might want to compare regular files in
the users windows directories and in the global windows directories and
replace same files by symlinks (to avoid diskspace problems).
Done.
This procedure requires:
- Much thought and work from the packager (1x)
- No work for the sysadmin. Well except one "rpm -i" and possible one edit
of the configuration file.
- Some or no work from the user, except running the per-user setup script
once.
=> It scales well and suffices most of the rationales.
Marcus Meissner <Marcus.Meissner@caldera.de>
----------------------------------------------------------------
Sample wine.ini for OpenLinux 2.x:
;;
;; MS-DOS drives configuration
;;
;; Each section has the following format:
;; [Drive X]
;; Path=xxx (Unix path for drive root)
;; Type=xxx (supported types are 'floppy', 'hd', 'cdrom' and 'network')
;; Label=xxx (drive label, at most 11 characters)
;; Serial=xxx (serial number, 8 characters hexadecimal number)
;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
;; This is the FS Wine is supposed to emulate on a certain
;; directory structure.
;; Recommended:
;; - "win95" for ext2fs, VFAT and FAT32
;; - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
;; DON'T use "unix" unless you intend to port programs using Winelib !
;; Device=/dev/xx (only if you want to allow raw device access)
;;
;
;
; Floppy 'A' and 'B'
;
; OpenLinux uses an automounter under /auto/, so we use that too.
;
[Drive A]
Path=/auto/floppy/
Type=floppy
Label=Floppy
Serial=87654321
Device=/dev/fd0
Filesystem=win95
;
; Comment in ONLY if you have a second floppy or the automounter hangs
; for 5 minutes.
;
;[Drive B]
;Path=/auto/floppy2/
;Type=floppy
;Label=Floppy
;Serial=87654321
;Device=/dev/fd1
;Filesystem=win95
;
; Drive 'C' links to the users homedirectory.
;
; This must point to a writeable directory structure (not your readonly
; mounted DOS partitions!) since programs want to dump stuff into
; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
;
; The basic structure is set up using the config script.
;
[Drive C]
Path=${HOME}
Type=hd
Label=MS-DOS
Filesystem=win95
;
; /tmp/ directory
;
; The temp drive (and directory) points to /tmp/. Windows programs fill it
; with junk, so it is approbiate.
;
[Drive T]
Path=/tmp
Type=hd
Label=Tmp Drive
Filesystem=win95
;
; 'U'ser homedirectory
;
; Just in case you want C:\ elsewhere.
;
[Drive U]
Path=${HOME}
Type=hd
Label=Home
Filesystem=win95
;
; CD-'R'OM drive (automounted)
;
; The default cdrom drive.
;
; If an application (or game) wants a specific CD-ROM you might have to
; temporary change the Label to the one of the CD itself.
;
; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
;
[Drive R]
Path=/auto/cdrom
Type=cdrom
Label=CD-Rom
Filesystem=win95
;
; The drive where the old windows installation resides (it points to the
; windows/ subdirectory).
;
; The Path is modified by the winesetup script.
;
[Drive W]
Path=/
Type=network
Label=Windows
Filesystem=win95
;
; The UNIX Root directory, so all other programs and directories are reachable.
;
; type network is used to tell programs to not write here.
;
[Drive Z]
Path=/
Type=network
Label=ROOT
Filesystem=win95
;
; Standard Windows path entries. WINE will not work if they are incorrect.
;
[wine]
;
; The windows/ directory. It must be writeable, for programs write into it.
;
Windows=c:\windows
;
; The windows/system/ directory. It must be writeable, for especially setup
; programs install dlls in there.
;
System=c:\windows\system
;
; The temp directory. Should be cleaned regulary, since install programs leave
; junk without end in there.
;
Temp=t:\
;
; The dll search path. It should contain at least:
; - the windows and the windows/system directory of the user.
; - the global windows and windows/system directory (from a possible readonly
; windows installation either on msdos filesystems or somewhere in the UNIX
; directory tree)
; - any other windows style directories you want to add.
;
Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
;
; Outdated and no longer used. (but needs to be present).
;
SymbolTableFile=./wine.sym
# <wineconf>
;
; Dll loadorder defaults. No need to modify.
;
[DllDefaults]
EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
DefaultLoadOrder = native, elfdll, so, builtin
;
; What 32/16 dlls belong to each other (context wise). No need to modify.
;
[DllPairs]
kernel = kernel32
gdi = gdi32
user = user32
commdlg = comdlg32
commctrl= comctl32
ver = version
shell = shell32
lzexpand= lz32
mmsystem= winmm
msvideo = msvfw32
winsock = wsock32
;
; What type of dll to use in their respective loadorder.
;
[DllOverrides]
kernel32, gdi32, user32 = builtin
kernel, gdi, user = builtin
toolhelp = builtin
comdlg32, commdlg = elfdll, builtin, native
version, ver = elfdll, builtin, native
shell32, shell = builtin, native
lz32, lzexpand = builtin, native
commctrl, comctl32 = builtin, native
wsock32, winsock = builtin
advapi32, crtdll, ntdll = builtin, native
mpr, winspool = builtin, native
ddraw, dinput, dsound = builtin, native
winmm, mmsystem = builtin
msvideo, msvfw32 = builtin, native
mcicda.drv, mciseq.drv = builtin, native
mciwave.drv = builtin, native
mciavi.drv, mcianim.drv = native, builtin
w32skrnl = builtin
wnaspi32, wow32 = builtin
system, display, wprocs = builtin
wineps = builtin
;
; Options section. Does not need to be edited.
;
[options]
; allocate how much system colors on startup. No need to modify.
AllocSystemColors=100
;;
; Font specification. You usually do not need to edit this section.
;
; Read documentation/fonts before adding aliases
;
[fonts]
; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
; or nearest match).
Resolution = 96
; Default font
Default = -adobe-times-
;
; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
; that try to access serial ports.
;
[serialports]
Com1=/dev/ttyS0
Com2=/dev/ttyS1
Com3=/dev/modem,38400
Com4=/dev/modem
;
; parallel port(s) used by "LPT1" etc. Useful for applications that try to
; access these ports.
;
[parallelports]
Lpt1=/dev/lp0
;
; What spooling program to use on printing.
; Use "|program" or "filename", where the output will be dumped into.
;
[spooler]
LPT1:=|lpr
LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
LPT3:=/dev/lp3
;
; Allow port access to WINE started by the root user. Useful for some
; supported devices, but it can make the system unstable.
; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
;
[ports]
;read=0x779,0x379,0x280-0x2a0
;write=0x779,0x379,0x280-0x2a0
; debugging, not need to be modified.
[spy]
Exclude=WM_SIZE;WM_TIMER;
;
; What names for the registry datafiles, no need to modify.
;
[Registry]
; Paths must be given in /dir/dir/file.reg format.
; Wine will not understand dos file names here...
;UserFileName=xxx ; alternate registry file name (user.reg)
;LocalMachineFileName=xxx ; (system.reg)
;
; Layout/Look modifications. Here you can switch with a single line between
; windows 3.1 and windows 95 style.
; This does not change WINE behaviour or reported versions, just the look!
;
[Tweak.Layout]
;; WineLook=xxx (supported styles are 'Win31'(default), 'Win95', 'Win98')
WineLook=Win95
;
; What programs to start on WINE startup. (you should probably leave it empty)
;
[programs]
Default=
Startup=
; defunct section.
[Console]
;XtermProg=nxterm
;InitialRows=25
;InitialColumns=80
;TerminalType=nxterm
# </wineconf>

216
documentation/dll-overrides
View File

@ -1,216 +0,0 @@
DLL overrides
-------------
The wine.conf directives [DllDefaults] and [DllOverrides] are the
subject of some confusion. The overall purpose of most of these
directives are clear enough, though - given a choice, should Wine use
its own built-in DLLs, or should it use .DLL files found in an
existing Windows installation? This document explains how this feature
works.
DLL types
native
A "native" DLL is a .DLL file written for the real Microsoft
Windows.
builtin
A "builtin" DLL is a Wine DLL. These can either be a part of
libwine.so, or more recently, in a special .so file that Wine
is able to load on demand.
elfdll
An "elfdll" is a Wine .so file with a special Windows-like file
structure that is as close to Windows as possible, and that can
also seamlessly link dynamically with "native" DLLs, by using
special ELF loader and linker tricks. Bertho Stultiens did some
work on this, but this feature has not yet been merged back
into Wine (because of political reasons and lack of time), so
this DLL type does not exist in the official Wine at this time.
In the meantime, the "builtin" DLL type gained some of the
features of elfdlls (such as dynamic loading), so it's possible
that "elfdll" functionality will be folded into "builtin" at
some point.
so
A native Unix .so 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 same API on both Windows and Unix.
The [DllDefaults] section
EXTRA_LD_LIBRARY_PATH
This specifies the location of the Wine's DLL .so files. Wine
will search this path when trying to locate a DLL of the type
"builtin" or "elfdll". (This does not apply to libwine.so,
since libwine.so is not a DLL in this sense.)
DefaultLoadOrder
This specifies in what order Wine should search for available
DLL types, if the DLL in question was not found in the
[DllOverrides] section.
The [DllPairs] section
At one time, there was a section called [DllPairs] in the default
configuration file, but this has been obsoleted because the pairing
information has now been embedded into Wine itself. (The purpose of
this section was merely to be able to issue warnings if the user
attempted to pair codependent 16-bit/32-bit DLLs of different types.)
If you still have this in your wine.conf or .winerc, you may safely
delete it.
The [DllOverrides] section
This section specifies how you want specific DLLs to be handled, in
particular whether you want to use "native" DLLs or not, if you have
some from a real Windows configuration. Because builtins do not mix
seamlessly with native DLLs yet, certain DLL dependencies may be
problematic, but workarounds exist in Wine for many popular DLL
configurations. Also see WWN's [16]Status Page to figure out how well
your favorite DLL is implemented in Wine.
It is of course also possible to override these settings by explictly
using Wine's --dll command-line option (see the man page for details).
Some hints for choosing your optimal configuration (listed by
16/32-bit DLL pair):
krnl386, kernel32
Native versions of these will never work, so don't try. Leave
at builtin.
gdi, gdi32
Graphics Device Interface. No effort has been made at trying to
run native GDI. Leave at builtin.
user, user32
Window management and standard controls. It was possible to use
Win95's native versions at some point (if all other DLLs that
depend on it, such as comctl32 and comdlg32, were also run
native). However, this is no longer possible after the Address
Space Separation, so leave at builtin.
ntdll
NT kernel API. Although badly documented, the native version of
this will never work. Leave at builtin.
w32skrnl
Win32s (for Win3.x). Native version will probably never work.
Leave at builtin.
wow32
Win16 support library for NT. Native version will probably
never work. Leave at builtin.
system
Win16 kernel stuff. Will never work native. Leave at builtin.
display
Display driver. Definitely leave at builtin.
toolhelp
Tool helper routines. This is rarely a source of problems.
Leave at builtin.
ver, version
Versioning. Seldom useful to mess with.
advapi32
Registry and security features. Trying the native version of
this may or may not work.
commdlg, comdlg32
Common Dialogs, such as color picker, font dialog, print
dialog, open/save dialog, etc. It is safe to try native.
commctrl, comctl32
Common Controls. This is toolbars, status bars, list controls,
the works. It is safe to try native.
shell, shell32
Shell interface (desktop, filesystem, etc). Being one of the
most undocumented pieces of Windows, you may have luck with the
native version, should you need it.
winsock, wsock32
Windows Sockets. The native version will not work under Wine,
so leave at builtin.
icmp
ICMP routines for wsock32. As with wsock32, leave at builtin.
mpr
The native version may not work due to thunking issues. Leave
at builtin.
lzexpand, lz32
Lempel-Ziv decompression. Wine's builtin version ought to work
fine.
winaspi, wnaspi32
Advanced SCSI Peripheral Interface. The native version will
probably never work. Leave at builtin.
crtdll
C Runtime library. The native version will easily work better
than Wine's on this one.
winspool.drv
Printer spooler. You are not likely to have more luck with the
native version.
ddraw
DirectDraw/Direct3D. Since Wine does not implement the DirectX
HAL, the native version will not work at this time.
dinput
DirectInput. Running this native may or may not work.
dsound
DirectSound. It may be possible to run this native, but don't
count on it.
dplay/dplayx
DirectPlay. Native ought to work best on this, if at all.
mmsystem, winmm
Multimedia system. The native version is not likely to work.
Leave at builtin.
msacm, msacm32
Audio Compression Manager. Builtin works best, if you set
msacm.drv to the same.
msvideo, msvfw32
Video for Windows. It is safe (and recommended) to try native.
mcicda.drv
CD Audio MCI driver.
mciseq.drv
MIDI Sequencer MCI driver (.MID playback).
mciwave.drv
Wave audio MCI driver (.WAV playback).
mciavi.drv
AVI MCI driver (.AVI video playback). Best to use native.
mcianim.drv
Animation MCI driver.
msacm.drv
Audio Compression Manager. Set to same as msacm32.
midimap.drv
MIDI Mapper.
wprocs
This is a pseudo-DLL used by Wine for thunking purposes. A
native version of this doesn't exist.
Have fun...
- Ove Kåven

175
documentation/dlls
View File

@ -1,175 +0,0 @@
WINE/WINDOWS DLLS
This document mainly deals with the status of current DLL support by
Wine. The Wine ini file currently supports settings to change the
load order of DLLs. The load order depends on several issues, which
results in different settings for various DLLs.
Pros of Native DLLs
-------------------
Native DLLs of course guarantee 100% compatibility for routines they
implement. For example, using the native USER DLL would maintain a
virtually perfect and Windows 95-like look for window borders, dialog
controls, and so on. Using the built-in WINE version of this library,
on the other hand, would produce a display that does not precisely
mimic that of Windows 95. Such subtle differences can be engendered
in other important DLLs, such as the common controls library COMMCTRL
or the common dialogs library COMMDLG, when built-in WINE DLLs outrank
other types in load order.
More significant, less aesthetically-oriented problems can result if
the built-in WINE version of the SHELL DLL is loaded before the native
version of this library. SHELL contains routines such as those used by
installer utilities to create desktop shortcuts. Some installers might
fail when using WINE's built-in SHELL.
Cons of Native DLLs
-------------------
Not every application performs better under native DLLs. If a library
tries to access features of the rest of the system that are not fully
implemented in Wine, the native DLL might work much worse than the
corresponding built-in one, if at all. For example, the native Windows
GDI library must be paired with a Windows display driver, which of
course is not present under Intel Unix and WINE.
Finally, occassionally built-in WINE DLLs implement more features than
the corresponding native Windows DLLs. Probably the most important
example of such behavior is the integration of Wine with X provided by
WINE's built-in USER DLL. Should the native Windows USER library take
load-order precedence, such features as the ability to use the
clipboard or drag-and- drop between Wine windows and X windows will be
lost.
Deciding Between Native and Built-In DLLs
-----------------------------------------
Clearly, there is no one rule-of-thumb regarding which load-order to
use. So, you must become familiar with:
* what specific DLLs do
* which other DLLs or features a given library interacts with
and use this information to make a case-by-case decision.
Load Order for DLLs
-------------------
Using the DLL sections from the wine configuration file, the load
order can be tweaked to a high degree. In general it is advised not to
change the settings of the configuration file. The default
configuration specifies the right load order for the most important
DLLs.
The default load order follows this algorithm: for all DLLs which have
a fully-functional Wine implementation, or where the native DLL is
known not to work, the built-in library will be loaded first. In all
other cases, the native DLL takes load-order precedence.
The DefaultLoadOrder from the [DllDefaults] section specifies for all
DLLs which version to try first. See manpage for explanation of the
arguments.
The [DllOverrides] section deals with DLLs, which need a
different-from-default treatment.
The [DllPairs] section is for DLLs, which must be loaded in pairs. In
general, these are DLLs for either 16-bit or 32-bit applications. In
most cases in Windows, the 32-bit version cannot be used without its
16-bit counterpart. For WINE, it is customary that the 16-bit
implementations rely on the 32-bit implementations and cast the
results back to 16-bit arguments. Changing anything in this section is
bound to result in errors.
For the future, Wine implemetation of Windows DLL seems to head
towards unifying the 16 and 32 bit DLLs wherever possible, resulting
in larger DLLs. They are stored in the dlls/ subdirectory using the
16-bit name. For large DLLs, a split might be discussed.
Understanding What DLLs Do
--------------------------
The following list briefly describes each of the DLLs commonly found
in Windows whose load order may be modified during the configuration
and compilation of WINE.
(See also ./DEVELOPER-HINTS or the dlls/ subdirectory to see which
DLLs are currently being rewritten for wine)
ADVAPI32.DLL: 32-bit application advanced programming interfaces
like crypto, systeminfo, security and eventlogging
AVIFILE.DLL: 32-bit application programming interfaces for the
Audio Video Interleave (AVI) Windows-specific
Microsoft audio-video standard
COMMCTRL.DLL: 16-bit common controls
COMCTL32.DLL: 32-bit common controls
COMDLG32.DLL: 32-bit common dialogs
COMMDLG.DLL: 16-bit common dialogs
COMPOBJ.DLL: OLE 16- and 32-bit compatibility libraries
CRTDLL.DLL: Microsoft C runtime
DCIMAN.DLL: 16-bit
DCIMAN32.DLL: 32-bit display controls
DDEML.DLL: DDE messaging
D3D*.DLL DirectX/Direct3D drawing libraries
DDRAW.DLL: DirectX drawing libraries
DINPUT.DLL: DirectX input libraries
DISPLAY.DLL: Display libraries
DPLAY.DLL, DPLAYX.DLL: DirectX playback libraries
DSOUND.DLL: DirectX audio libraries
GDI.DLL: 16-bit graphics driver interface
GDI32.DLL: 32-bit graphics driver interface
IMAGEHLP.DLL: 32-bit IMM API helper libraries (for PE-executables)
IMM32.DLL: 32-bit IMM API
IMGUTIL.DLL:
KERNEL32.DLL 32-bit kernel DLL
KEYBOARD.DLL: Keyboard drivers
LZ32.DLL: 32-bit Lempel-Ziv or LZ file compression
used by the installshields (???).
LZEXPAND.DLL: LZ file expansion; needed for Windows Setup
MMSYSTEM.DLL: Core of the Windows multimedia system
MOUSE.DLL: Mouse drivers
MPR.DLL: 32-bit Windows network interface
MSACM.DLL: Core of the Addressed Call Mode or ACM system
MSACM32.DLL: Core of the 32-bit ACM system
Audio Compression Manager ???
MSNET32.DLL 32-bit network APIs
MSVFW32.DLL: 32-bit Windows video system
MSVIDEO.DLL: 16-bit Windows video system
OLE2.DLL: OLE 2.0 libraries
OLE32.DLL: 32-bit OLE 2.0 components
OLE2CONV.DLL: Import filter for graphics files
OLE2DISP.DLL, OLE2NLS.DLL: OLE 2.1 16- and 32-bit interoperability
OLE2PROX.DLL: Proxy server for OLE 2.0
OLE2THK.DLL: Thunking for OLE 2.0
OLEAUT32.DLL 32-bit OLE 2.0 automation
OLECLI.DLL: 16-bit OLE client
OLECLI32.DLL: 32-bit OLE client
OLEDLG.DLL: OLE 2.0 user interface support
OLESVR.DLL: 16-bit OLE server libraries
OLESVR32.DLL: 32-bit OLE server libraries
PSAPI.DLL: Proces Status API libraries
RASAPI16.DLL: 16-bit Remote Access Services libraries
RASAPI32.DLL: 32-bit Remote Access Services libraries
SHELL.DLL: 16-bit Windows shell used by Setup
SHELL32.DLL: 32-bit Windows shell (COM object?)
TAPI/TAPI32/TAPIADDR: Telephone API (for Modems)
W32SKRNL: Win32s Kernel ? (not in use for Win95 and up!)
WIN32S16.DLL: Application compatibility for Win32s
WIN87EM.DLL: 80387 math-emulation libraries
WINASPI.DLL: Advanced SCSI Peripheral Interface or ASPI libraries
WINDEBUG.DLL Windows debugger
WINMM.DLL: Libraries for multimedia thunking
WING.DLL: Libraries required to "draw" graphics
WINSOCK.DLL: Sockets APIs
WINSPOOL.DLL: Print spooler libraries
WNASPI32.DLL: 32-bit ASPI libraries
WSOCK32.DLL: 32-bit sockets APIs
Credits
-------
Based upon various messages on wine-devel especially by Ulrich Weigand.
Adapted by Michele Petrovski and Klaas van Gend.

908
documentation/dlls.sgml Normal file
View File

@ -0,0 +1,908 @@
<chapter id="dlls">
<title>Wine Builtin DLLs</title>
<para>A more detailed look at Wine's builtin DLLs...</para>
<sect1 id="common-controls">
<title>Common Controls</title>
<!-- FIXME: Huh? Subtitle element not available here?!? -->
<bridgehead renderas="sect3">
Their development status and their UNDOCUMENTED features and functions
</bridgehead>
<para>
written by Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;
</para>
<para>
(Extracted from <filename>wine/documentation/common_controls</filename>)
</para>
<sect2>
<title>1. Introduction</title>
<para>
The information provided herein is based on the dll version
4.72 which is included in MS Internet Explorer 4.01.
</para>
<para>
All information about common controls should be collected in this document.
</para>
<para>
All Wine programmers are encouraged to add their knowledge to this document.
</para>
</sect2>
<sect2>
<title>2. General Information</title>
<para>
Further information about common controls can be found in
the MS Platform SDK and the MS Internet Client SDK (most
recent). Information from these SDK's will NOT be repeated
here. Only information which can NOT be found in these SDK's
will be collected here. Some information in the SDK's
mentioned above is (intentionally???) WRONG. Corrections to
wrong information will be collected here too.
</para>
<sect3>
<title>2.1 Structure sizes of different common control versions</title>
<para>
The common controls have been continously improved in the
past. Some of the orignal structures had to be extended
and their size changed. Most of the common control
structures include their size as the first parameter. If a
control gets the wrong size in a message or function a
failure is very likely to occur. To avoid this, MS defined
new constants that reflect the structure size of older
<filename>COMCTL32.DLL</filename> versions. The following
list shows the structure size constants that are currently
defined in the original <filename>COMCTL32.DLL</filename>.
</para>
<note>
<para>
Some stuctures are NOT defined in wine's COMCTL32 yet.
</para>
</note>
<variablelist>
<varlistentry>
<term><varname>HDITEM_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the <structname>HDITEM</structname>
structure in version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LVCOLUMN_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>LVCOLUMN</structname> structure in
version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LVHITTESTINFO_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>LVHITTESTINFO</structname> structure in
version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LVITEM_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the <structname>LVITEM</structname>
structure in version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>NMLVCUSTOMDRAW_V3_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>NMLVCUSTOMDRAW</structname> structure in
version 4.70.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>NMTTDISPINFO_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>NMTTDISPINFO</structname> structure in
version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>NMTVCUSTOMDRAW_V3_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>NMTVCUSTOMDRAW</structname> structure in
version 4.70.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PROPSHEETHEADER_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>PROPSHEETHEADER</structname> structure
in version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PROPSHEETPAGE_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>PROPSHEETPAGE</structname> structure in
version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>REBARBANDINFO_V3_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>REBARBANDINFO</structname> structure in
version 4.70.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>TTTOOLINFO_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>TOOLINFO</structname> structure in
version 4.00.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>TVINSERTSTRUCT_V1_SIZE</varname>:</term>
<listitem>
<para>The size of the
<structname>TVINSERTSTRUCT</structname> structure in
version 4.00.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2>
<title>3. Controls</title>
<para>
This section describes the development status of the common controls.
</para>
<sect3>
<title>3.1 Animation Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term> Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.2 Combo Box Ex Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.3 Date and Time Picker Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.4 Drag List Box Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.5 Flat Scroll Bar Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Alex Priem. &lt;alexp@sci.kun.nl&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.6 Header Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<itemizedlist>
<listitem>
<para>Almost finished.</para>
</listitem>
<listitem>
<para>Unicode notifications are not supported (WM_NOTIFYFORMAT).</para>
</listitem>
<listitem>
<para>Order array not supported.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.7 Hot Key Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.8 Image List (no control)</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Almost finished.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.9 IP Address Control</title>
<variablelist>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Under construction.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.10 List View Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by: </para>
<itemizedlist>
<listitem>
<para>Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
<listitem>
<para>Luc Tourangeau &lt;luc@macadamian.com&gt;</para>
</listitem>
<listitem>
<para>Koen Deforche &lt;jozef@kotnet.org&gt;</para>
</listitem>
<listitem>
<para>Francis Beaudet &lt;francis@macadamian.com&gt; and the "Corel-Team"</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Under construction.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>
Basic data structure with related messages are
supported. No painting supported yet.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.11 Month Calendar Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.12 Native font control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Dummy control. No functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.13 Pager Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl. &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>
Under construction. Many missing features.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.14 Progress Bar Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>
Original implementation by Dimitrie O. Paun. Fixes
and improvements by Eric Kohl.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Finished!</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.15 Property Sheet</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>
Anders Carlsson &lt;anders.carlsson@linux.nu&gt; and
Francis Beaudet &lt;francis@macadamian.com&gt;
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Development in progress.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Tab control must be implemented first.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.16 Rebar Control (Cool Bar)</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Development in progress. Many bugs and missing features.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Author needed!! Any volunteers??</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.17 Status Bar Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>
Original implementation by Bruce Milner. Fixes and
improvements by Eric Kohl.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Almost finished.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Tooltip integration is almost complete.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.18 Tab Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Anders Carlsson &lt;anders.carlsson@linux.nu&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Development in progress.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.19 Toolbar Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>
Development in progress. Basic functionality is
almost done. (dll version 4.0)
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.20 Tooltip Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Almost finished.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
<para>Unicode support is incomplete
(<constant>WM_NOTIFYFORMAT</constant>).</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.21 Trackbar Control</title>
<variablelist>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Under construction.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.22 Tree View Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>Dummy written by Eric Kohl., Alex Priem &lt;alexp@sci.kun.nl&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Under construction.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>3.23 Updown Control</title>
<variablelist>
<varlistentry>
<term>Author:</term>
<listitem>
<para>
Original implementation by Dimitrie O. Paun.
Some minor changes by Eric Kohl &lt;ekohl@abo.rhein-zeitung.de&gt;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status:</term>
<listitem>
<para>Unknown.</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<title>Notes</title>
<para>
Have a look at <filename>controls/updown.c</filename>
for a list of bugs and missing features.
</para>
<para>
The status is unknown, because I did not have a close
look at this control. One test-program looked quite
good, but in Win95's <filename>cdplayer.exe</filename>
the control does not show at all.
</para>
<para>
Any volunteers??
</para>
</note>
</sect3>
</sect2>
<sect2>
<title>4. Additional Information</title>
<para>
Has to be written...
</para>
</sect2>
<sect2>
<title>5. Undocumented features</title>
<para>
There are quite a lot of undocumented functions like:
</para>
<itemizedlist>
<listitem>
<para>DSA (Dynamic Storage Array) functions.</para>
</listitem>
<listitem>
<para>DPA (Dynamic Pointer Array) functions.</para>
</listitem>
<listitem>
<para>MRU ("Most Recently Used" List) functions.</para>
</listitem>
<listitem>
<para>other unknown functions.</para>
</listitem>
</itemizedlist>
<para>
Have a look at <filename>relay32/comctl32.spec</filename>.
</para>
<sect3>
<title>5.1 Dymnamic Storage Array (DSA)</title>
<para>
The DSA functions are used to store and manage dynamic
arrays of fixed size memory blocks. They are used by
<filename>TASKMAN.EXE</filename>, Explorer, IE4 and other
Programs and DLL's that are "parts of the Windows
Operating System". The implementation should be complete.
</para>
<para>
Have a look at the source code to get more information.
</para>
</sect3>
<sect3>
<title>5.2 Dynamic Pointer Array (DPA)</title>
<para>
Similar to the DSA functions, but they just store
pointers. They are used by Explorer, IE4 and other
Programs and DLL's that are "parts of the Windows
Operating System". The implementation should be complete.
</para>
<para>
Have a look at the source code to get more information.
</para>
</sect3>
<sect3>
<title>5.3 "Most Recently Used" - List (MRU)</title>
<para>
Only stubs are implemented to keep Explorer from bailing out.
</para>
<para>
No more information available at this time!
</para>
</sect3>
<sect3>
<title>5.4 MenuHelp</title>
<para>
Has to be written...
</para>
</sect3>
<sect3>
<title>5.5 GetEffectiveClientRect</title>
<para>
Has to be written...
</para>
</sect3>
<sect3>
<title>5.6 ShowHideMenuCtl</title>
<para>
The official documentation provided by MS is incomplete.
</para>
<variablelist>
<varlistentry>
<term><varname>lpInfo</varname>:</term>
<listitem>
<blockquote>
<para>
Both values of the first pair must be the handle
to the applications main menu.
</para>
</blockquote>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title>5.7 Other undocumented functions</title>
<para>
Several other undocumented functions are used by IE4.
</para>
<para>
String functions: (will be written...)
</para>
</sect3>
</sect2>
<sect2>
<title>6. Epilogue</title>
<para>
You see, much work has still to be done. If you are
interested in writing a control send me an e-mail. If you
like to fix bugs or add some functionality send an e-mail to
the author of the control.
</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" "")
End:
-->

89
documentation/documentation.sgml Normal file
View File

@ -0,0 +1,89 @@
<chapter id="documentation">
<title>Documenting Wine</title>
<para>How to help out with the Wine documentation effort...</para>
<sect1 id="api-docs">
<title>Writing Wine API Documentation</title>
<para>
written by (???)
</para>
<para>
(Extracted from <filename>wine/documentation/README.documentation</filename>)
</para>
<para>
To improve the documentation of the Wine API, just add
comments to the existing source. For example,
</para>
<screen>
/******************************************************************
* CopyMetaFile32A (GDI32.23)
*
* Copies the metafile corresponding to hSrcMetaFile to either
* a disk file, if a filename is given, or to a new memory based
* metafile, if lpFileName is NULL.
*
* RETURNS
*
* Handle to metafile copy on success, NULL on failure.
*
* BUGS
*
* Copying to disk returns NULL even if successful.
*/
HMETAFILE32 WINAPI CopyMetaFile32A(
HMETAFILE32 hSrcMetaFile, /* handle of metafile to copy */
LPCSTR lpFilename /* filename if copying to a file */
) { ... }
</screen>
<para>
becomes, after processing with <command>c2man</command> and
<command>nroff -man</command>,
</para>
<screen>
CopyMetaFileA(3w) CopyMetaFileA(3w)
NAME
CopyMetaFileA - CopyMetaFile32A (GDI32.23)
SYNOPSIS
HMETAFILE32 CopyMetaFileA
(
HMETAFILE32 hSrcMetaFile,
LPCSTR lpFilename
);
PARAMETERS
HMETAFILE32 hSrcMetaFile
Handle of metafile to copy.
LPCSTR lpFilename
Filename if copying to a file.
DESCRIPTION
Copies the metafile corresponding to hSrcMetaFile to
either a disk file, if a filename is given, or to a new
memory based metafile, if lpFileName is NULL.
RETURNS
Handle to metafile copy on success, NULL on failure.
BUGS
Copying to disk returns NULL even if successful.
SEE ALSO
GetMetaFileA(3w), GetMetaFileW(3w), CopyMetaFileW(3w),
PlayMetaFile(3w), SetMetaFileBitsEx(3w), GetMetaFileBit-
sEx(3w)
</screen>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
End:
-->

31
documentation/filehandles
View File

@ -1,31 +0,0 @@
DOS treats the first 5 file handles as special cases. They map directly
to stdin, stdout, stderr, stdaux and stdprn. Windows 16 inherits this
behavoir, and in fact, win16 handles are interchangable with DOS handles.
Some nasty windows programs even do this!
Windows32 issues file handles starting from 1, on the grounds that
most GUI processes don't need a stdin, out, etc.
The wine handle code is implemented in the Win32 style, and the Win16
functions use two macros to convert to and from the two types.
The macros are defined in file.h as follows.:
#define HFILE16_TO_HFILE32(handle) \
(((handle)==0) ? GetStdHandle(STD_INPUT_HANDLE) : \
((handle)==1) ? GetStdHandle(STD_OUTPUT_HANDLE) : \
((handle)==2) ? GetStdHandle(STD_ERROR_HANDLE) : \
((handle)>0x400) ? handle : \
(handle)-5)
#define HFILE32_TO_HFILE16(handle) ({ HFILE32 hnd=handle; \
((hnd==HFILE_ERROR32) ? HFILE_ERROR16 : \
((handle>0x400) ? handle : \
(HFILE16)hnd+5); })
WARNING: be careful not to use the macro HFILE16_TO_HFILE32 on
functions with side-effects, as it will cause them to be evaluated
several times. This could be considered a bug, but the use of this
macro is limited enough not to need a rewrite.
NOTE: The 0x400 special case above deals with LZW filehandles (see
misc/lzexpand.c).

184
documentation/fonts
View File

@ -1,184 +0,0 @@
Note:
=====
The fnt2bdf utility is included with Wine. It can be found in the tools
directory.
Links to the other tools mentioned in this document can be found on wine
headquarters: http://www.winehq.com/tools.html
How To Convert Windows Fonts
============================
If you have access to a Windows installation you should use
fnt2bdf utility (found in the 'tools)' directory to convert
bitmap fonts (VGASYS.FON, SSERIFE.FON, and SERIFE.FON) into
the format that the X Window System can recognize.
Step 1. Extract bitmap fonts with 'fnt2bdf'.
Step 2. Convert .bdf files produced by Step 1 into
.pcf files with 'bdftopcf'.
Step 3. Copy .pcf files to the font server directory which
is usually /usr/lib/X11/fonts/misc (you will probably
need superuser privileges). If you want to create a new
font directory you will need to add it to the font path.
Step 4. Run 'mkfontdir' for the directory you copied fonts to.
If you are already in X you should run 'xset fp rehash'
to make X server aware of the new fonts.
Step 5. Edit WINE.CONF file to remove aliases for the fonts
you've just installed.
WINE can get by without these fonts but 'the look and feel'
may be quite different. Also, some applications try to load
their custom fonts on the fly (WinWord 6.0) and since WINE does
not implement this yet it instead prints out something like;
STUB: AddFontResource( SOMEFILE.FON )
You can convert this file too. Note that .FON file may not hold
any bitmap fonts and fnt2bdf will fail if this is the case. Also
note that although the above message will not disappear WINE will
work around the problem by using the font you extracted from the
SOMEFILE.FON. fnt2bdf will only work for Windows 3.1 fonts. It
will not work for TrueType fonts.
What to do with TrueType fonts? There are several commercial
font tools that can convert them to the Type1 format but the
quality of the resulting fonts is far from stellar. The other
way to use them is to get a font server capable of rendering
TrueType (Caldera has one, there also is the free Xfstt in
Linux/X11/fonts on sunsite and mirrors, if you're on FreeBSD you
can use the port in /usr/ports/x11-servers/Xfstt. And there is
xfsft which uses the freetype library, see documentation/ttfserver).
However, there is a possibility of the native TrueType support
via FreeType renderer in the future (hint, hint :-)
How To Add Font Aliases To WINE.CONF
====================================
Many Windows applications assume that fonts included in original Windows 3.1
distribution are always present. By default Wine creates a number of aliases
that map them on the existing X fonts:
Windows font ...is mapped to... X font
"MS Sans Serif" -> "-adobe-helvetica-"
"MS Serif" -> "-bitstream-charter-"
"Times New Roman" -> "-adobe-times-"
"Arial" -> "-adobe-helvetica-"
There is no default alias for the "System" font. Also, no aliases are
created for the fonts that applications install at runtime. The recommended
way to deal with this problem is to convert the missing font (see above).
If it proves impossible, like in the case with TrueType fonts, you can force
the font mapper to choose a closely related X font by adding an alias to the
[fonts] section. Make sure that the X font actually exists (with xfontsel
tool).
AliasN = [Windows font], [X font] <, optional "mask X font" flag>
Example:
Alias0 = System, --international-, subst
Alias1 = ...
...
Comments:
* There must be no gaps in the sequence {0, ..., N} otherwise all aliases
after the first gap won't be read.
* Usually font mapper translates X font names into font names visible to
Windows programs in the following fashion:
X font ...will show up as... Extracted name
--international-... -> "International"
-adobe-helvetica-... -> "Helvetica"
-adobe-utopia-... -> "Utopia"
-misc-fixed-... -> "Fixed"
-...
-sony-fixed-... -> "Sony Fixed"
-...
Note that since -misc-fixed- and -sony-fixed- are different fonts
Wine modified the second extracted name to make sure Windows programs
can distinguish them because only extracted names appear in the font
selection dialogs.
* "Masking" alias replaces the original extracted name so that in the
example case we will have the following mapping:
--international- -> "System"
"Nonmasking" aliases are transparent to the user and they do not
replace extracted names.
Wine discards an alias when it sees that the native X font is
available.
* If you do not have access to Windows fonts mentioned in the first
paragraph you should try to substitute the "System" font with
nonmasking alias. 'xfontsel' will show you the fonts available to
X.
Alias.. = System, ...bold font without serifs
Also, some Windows applications request fonts without specifying the
typeface name of the font. Font table starts with Arial in most Windows
installations, however X font table starts with whatever is the first line
in the fonts.dir. Therefore WINE uses the following entry to determine
which font to check first.
Example:
Default = -adobe-times-
Comments:
It is better to have a scalable font family (bolds and italics included)
as the default choice because mapper checks all available fonts until
requested height and other attributes match perfectly or the end of the
font table is reached. Typical X installations have scalable fonts in
the ../fonts/Type1 and ../fonts/Speedo directories.
How To Manage Cached Font Metrics
=================================
WINE stores detailed information about available fonts in the ~/.wine/.cachedmetrics
file. You can copy it elsewhere and add this entry to the [fonts] section
in your WINE.CONF:
FontMetrics = <file with metrics>
If WINE detects changes in the X font configuration it will rebuild font
metrics from scratch and then it will overwrite ~/.wine/.cachedmetrics with
the new information. This process can take a while.
Too Small Or Too Large Fonts
============================
Windows programs may ask WINE to render a font with the height specified
in points. However, point-to-pixel ratio depends on the real physical size
of your display (15", 17", etc...). X tries to provide an estimate of that
but it can be quite different from the actual size. You can change this
ratio by adding the following entry to the [fonts] section:
Resolution = <integer value>
In general, higher numbers give you larger fonts. Try to experiment with
values in the 60 - 120 range. 96 is a good starting point.
"FONT_Init: failed to load ..." Messages On Startup
===================================================
The most likely cause is a broken fonts.dir file in one of your font
directories. You need to rerun 'mkfontdir' to rebuild this file. Read
its manpage for more information. If you can't run mkfontdir on this machine
as you are not root, use "xset -fp xxx" to remove the broken font path.

498
documentation/fonts.sgml Normal file
View File

@ -0,0 +1,498 @@
<chapter id="fonts">
<title>Dealing with Fonts</title>
<sect1 id="windows-fonts">
<title>Fonts</title>
<para>
written by ???
</para>
<para>
(Extracted from <filename>wine/documentation/fonts</filename>)
</para>
<para>
<note>
<para>
The <command>fnt2bdf</command> utility is included with
Wine. It can be found in the <filename>tools</filename>
directory. Links to the other tools mentioned in this
document can be found on wine headquarters:
<ulink url="http://www.winehq.com/tools.html">http://www.winehq.com/tools.html</ulink>
</para>
</note>
</para>
<sect2>
<title>How To Convert Windows Fonts</title>
<para>
If you have access to a Windows installation you should use
<command>fnt2bdf</command> utility (found in the
<filename>tools</filename> directory) to convert bitmap
fonts (<filename>VGASYS.FON</filename>,
<filename>SSERIFE.FON</filename>, and
<filename>SERIFE.FON</filename>) into the format that the X
Window System can recognize.
</para>
<orderedlist>
<listitem>
<para>Extract bitmap fonts with <command>fnt2bdf</command>.</para>
</listitem>
<listitem>
<para>
Convert <filename>.bdf</filename> files produced by Step
1 into <filename>.pcf</filename> files with
<command>bdftopcf</command>.
</para>
</listitem>
<listitem>
<para>
Copy <filename>.pcf</filename> files to the font server
directory which is usually
<filename>/usr/lib/X11/fonts/misc</filename> (you will
probably need superuser privileges). If you want to
create a new font directory you will need to add it to
the font path.
</para>
</listitem>
<listitem>
<para>
Run <command>mkfontdir</command> for the directory you
copied fonts to. If you are already in X you should run
<command>xset fp rehash</command> to make X server aware
of the new fonts.
</para>
</listitem>
<listitem>
<para>
Edit the <filename>wine.conf</filename> file to remove
aliases for the fonts you've just installed.
</para>
</listitem>
</orderedlist>
<para>
WINE can get by without these fonts but 'the look and feel'
may be quite different. Also, some applications try to load
their custom fonts on the fly (WinWord 6.0) and since WINE
does not implement this yet it instead prints out something
like;
</para>
<screen>
STUB: AddFontResource( SOMEFILE.FON )
</screen>
<para>
You can convert this file too. Note that
<filename>.FON</filename> file may not hold any bitmap
fonts and <command>fnt2bdf</command> will fail if this is
the case. Also note that although the above message will not
disappear WINE will work around the problem by using the
font you extracted from the
<filename>SOMEFILE.FON</filename>.
<command>fnt2bdf</command> will only work for Windows 3.1
fonts. It will not work for TrueType fonts.
</para>
<para>
What to do with TrueType fonts? There are several commercial
font tools that can convert them to the Type1 format but the
quality of the resulting fonts is far from stellar. The
other way to use them is to get a font server capable of
rendering TrueType (Caldera has one, there also is the free
<command>xfstt</command> in
<filename>Linux/X11/fonts</filename> on sunsite and mirrors,
if you're on FreeBSD you can use the port in
<filename>/usr/ports/x11-servers/Xfstt</filename>. And
there is <command>xfsft</command> which uses the freetype
library, see <filename>documentation/ttfserver</filename>).
</para>
<para>
However, there is a possibility of the native TrueType
support via FreeType renderer in the future (hint, hint :-)
</para>
</sect2>
<sect2>
<title>How To Add Font Aliases To <filename>wine.conf</filename></title>
<para>
Many Windows applications assume that fonts included in
original Windows 3.1 distribution are always present. By
default Wine creates a number of aliases that map them on
the existing X fonts:
</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Windows font</entry>
<entry>...is mapped to...</entry>
<entry>X font</entry>
</row>
</thead>
<tbody>
<row>
<entry>"MS Sans Serif"</entry>
<entry align="center">-&gt;</entry>
<entry>"-adobe-helvetica-"</entry>
</row>
<row>
<entry>"MS Serif"</entry>
<entry align="center">-&gt;</entry>
<entry>"-bitstream-charter-"</entry>
</row>
<row>
<entry>"Times New Roman"</entry>
<entry align="center">-&gt;</entry>
<entry>"-adobe-times-"</entry>
</row>
<row>
<entry>"Arial"</entry>
<entry align="center">-&gt;</entry>
<entry>"-adobe-helvetica-"</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
There is no default alias for the "System" font. Also, no
aliases are created for the fonts that applications install
at runtime. The recommended way to deal with this problem
is to convert the missing font (see above). If it proves
impossible, like in the case with TrueType fonts, you can
force the font mapper to choose a closely related X font by
adding an alias to the [fonts] section. Make sure that the
X font actually exists (with <command>xfontsel</command>
tool).
</para>
<screen>
AliasN = [Windows font], [X font] &lt;, optional "mask X font" flag&gt;
</screen>
<para>
Example:
</para>
<screen>
Alias0 = System, --international-, subst
Alias1 = ...
...
</screen>
<para>
Comments:
</para>
<itemizedlist>
<listitem>
<para>
There must be no gaps in the sequence <literal>{0, ...,
N}</literal> otherwise all aliases after the first gap
won't be read.
</para>
</listitem>
<listitem>
<para>
Usually font mapper translates X font names into font
names visible to Windows programs in the following
fashion:
</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>X font</entry>
<entry>...will show up as...</entry>
<entry>Extracted name</entry>
</row>
</thead>
<tbody>
<row>
<entry>--international-...</entry>
<entry align="center">-&gt;</entry>
<entry>"International"</entry>
</row>
<row>
<entry>-adobe-helvetica-...</entry>
<entry align="center">-&gt;</entry>
<entry>"Helvetica"</entry>
</row>
<row>
<entry>-adobe-utopia-...</entry>
<entry align="center">-&gt;</entry>
<entry>"Utopia"</entry>
</row>
<row>
<entry>-misc-fixed-...</entry>
<entry align="center">-&gt;</entry>
<entry>"Fixed"</entry>
</row>
<row>
<entry>-...</entry>
<entry align="center">-&gt;</entry>
<entry></entry>
</row>
<row>
<entry>-sony-fixed-...</entry>
<entry align="center">-&gt;</entry>
<entry>"Sony Fixed"</entry>
</row>
<row>
<entry>-...</entry>
<entry align="center">-&gt;</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Note that since <literal>-misc-fixed-</literal> and
<literal>-sony-fixed-</literal> are different fonts Wine
modified the second extracted name to make sure Windows
programs can distinguish them because only extracted
names appear in the font selection dialogs.
</para>
</listitem>
<listitem>
<para>
"Masking" alias replaces the original extracted name so
that in the example case we will have the following
mapping:
</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>X font</entry>
<entry>...is masked to...</entry>
<entry>Extracted name</entry>
</row>
</thead>
<tbody>
<row>
<entry>--international-...</entry>
<entry align="center">-&gt;</entry>
<entry>"System"</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
"Nonmasking" aliases are transparent to the user and
they do not replace extracted names.
</para>
<para>
Wine discards an alias when it sees that the native X
font is available.
</para>
</listitem>
<listitem>
<para>
If you do not have access to Windows fonts mentioned in
the first paragraph you should try to substitute the
"System" font with nonmasking alias. The
<command>xfontsel</command> application will show you
the fonts available to X.
</para>
<screen>
Alias.. = System, ...bold font without serifs
</screen>
</listitem>
</itemizedlist>
<para>
Also, some Windows applications request fonts without
specifying the typeface name of the font. Font table starts
with Arial in most Windows installations, however X font
table starts with whatever is the first line in the
<filename>fonts.dir</filename>. Therefore WINE uses the
following entry to determine which font to check first.
</para>
<para>
Example:
</para>
<screen>
Default = -adobe-times-
</screen>
<para>
Comments:
</para>
<para>
It is better to have a scalable font family (bolds and
italics included) as the default choice because mapper
checks all available fonts until requested height and other
attributes match perfectly or the end of the font table is
reached. Typical X installations have scalable fonts in the
<filename>../fonts/Type1</filename> and
<filename>../fonts/Speedo</filename> directories.
</para>
</sect2>
<sect2>
<title>How To Manage Cached Font Metrics</title>
<para>
WINE stores detailed information about available fonts in
the <filename>~/.wine/.cachedmetrics</filename> file. You
can copy it elsewhere and add this entry to the [fonts]
section in your <filename>wine.conf</filename>:
</para>
<screen>
FontMetrics = &lt;file with metrics&gt;
</screen>
<para>
If WINE detects changes in the X font configuration it will
rebuild font metrics from scratch and then it will overwrite
<filename>~/.wine/.cachedmetrics</filename> with the new
information. This process can take a while.
</para>
</sect2>
<sect2>
<title>Too Small Or Too Large Fonts</title>
<para>
Windows programs may ask WINE to render a font with the
height specified in points. However, point-to-pixel ratio
depends on the real physical size of your display (15",
17", etc...). X tries to provide an estimate of that but it
can be quite different from the actual size. You can change
this ratio by adding the following entry to the [fonts]
section:
</para>
<screen>
Resolution = &lt;integer value&gt;
</screen>
<para>
In general, higher numbers give you larger fonts. Try to
experiment with values in the 60 - 120 range. 96 is a good
starting point.
</para>
</sect2>
<sect2>
<title>"FONT_Init: failed to load ..." Messages On Startup</title>
<para>
The most likely cause is a broken
<filename>fonts.dir</filename> file in one of your font
directories. You need to rerun <command>mkfontdir</command>
to rebuild this file. Read its manpage for more information.
If you can't run <command>mkfontdir</command> on this
machine as you are not root, use <command>xset -fp
xxx</command> to remove the broken font path.
</para>
</sect2>
</sect1>
<sect1 id="ttfont-server">
<title>Setting up a TrueType Font Server</title>
<para>
written by ???
</para>
<para>
(Extracted from <filename>wine/documentation/ttfserver</filename>)
</para>
<para>
Follow these instructions to set up a TrueType font server on your system.
</para>
<orderedlist>
<listitem>
<para>Get <filename>freetype-1.0.full.tar.gz</filename></para>
</listitem>
<listitem>
<para>Read docs, unpack, configure and install</para>
</listitem>
<listitem>
<para>Test the library, e.g. <command>ftview 20 /dosc/win95/fonts/times</command></para>
</listitem>
<listitem>
<para>Get <filename>xfsft-beta1e.linux-i586</filename></para>
</listitem>
<listitem>
<para>
Install it and start it when booting, e.g. in an
rc-script. The manpage for <command>xfs</command>
applies.
</para>
</listitem>
<listitem>
<para>Follow the hints given by <email>williamc@dai.ed.ac.uk</email></para>
</listitem>
<listitem>
<para>
I got <command>xfsft</command> from
<ulink url="http://www.dcs.ed.ac.uk/home/jec/progindex.html">http://www.dcs.ed.ac.uk/home/jec/progindex.html</ulink>.
I have it running all the time. Here is
<filename>/usr/X11R6/lib/X11/fs/config</filename>:
</para>
<programlisting>
clone-self = on
use-syslog = off
catalogue = /c/windows/fonts
error-file = /usr/X11R6/lib/X11/fs/fs-errors
default-point-size = 120
default-resolutions = 75,75,100,100
</programlisting>
<para>
Obviously <filename>/c/windows/fonts</filename> is where
my Windows fonts on my Win95 <medialabel>C:</medialabel>
drive live; could be e.g.
<filename>/mnt/dosC/windows/system</filename> for Win31.
In <filename>/c/windows/fonts/fonts.scale</filename> I
have
</para>
<programlisting>
14
arial.ttf -monotype-arial-medium-r-normal--0-0-0-0-p-0-iso8859-1
arialbd.ttf -monotype-arial-bold-r-normal--0-0-0-0-p-0-iso8859-1
arialbi.ttf -monotype-arial-bold-o-normal--0-0-0-0-p-0-iso8859-1
ariali.ttf -monotype-arial-medium-o-normal--0-0-0-0-p-0-iso8859-1
cour.ttf -monotype-courier-medium-r-normal--0-0-0-0-p-0-iso8859-1
courbd.ttf -monotype-courier-bold-r-normal--0-0-0-0-p-0-iso8859-1
courbi.ttf -monotype-courier-bold-o-normal--0-0-0-0-p-0-iso8859-1
couri.ttf -monotype-courier-medium-o-normal--0-0-0-0-p-0-iso8859-1
times.ttf -monotype-times-medium-r-normal--0-0-0-0-p-0-iso8859-1
timesbd.ttf -monotype-times-bold-r-normal--0-0-0-0-p-0-iso8859-1
timesbi.ttf -monotype-times-bold-i-normal--0-0-0-0-p-0-iso8859-1
timesi.ttf -monotype-times-medium-i-normal--0-0-0-0-p-0-iso8859-1
symbol.ttf -monotype-symbol-medium-r-normal--0-0-0-0-p-0-microsoft-symbol
wingding.ttf -microsoft-wingdings-medium-r-normal--0-0-0-0-p-0-microsoft-symbol
</programlisting>
<para>
In <filename>/c/windows/fonts/fonts.dir</filename> I have
exactly the same.
</para>
<para>
In <filename>/usr/X11R6/lib/X11/XF86Config</filename> I have
</para>
<programlisting>
FontPath "tcp/localhost:7100"
</programlisting>
<para>
in front of the other <literal>FontPath</literal> lines.
That's it! As an interesting by-product of course, all
those web pages which specify Arial come up in Arial in
Netscape ...
</para>
</listitem>
<listitem>
<para>
Shut down X and restart (and debug errors you did while
setting up everything).
</para>
</listitem>
<listitem>
<para>Test with e.g <command>xlsfont | grep arial</command></para>
</listitem>
</orderedlist>
<para>
Hope this helps...
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
End:
-->

135
documentation/how-to-port
View File

@ -1,135 +0,0 @@
What is this?
------------
This note is a short description of
* How to port Wine to your favourite operating system
* Why you probably shouldn't use "#ifdef MyOS"
* What to do instead.
This document does not say a thing about how to port Wine to non-386
operating systems, though. You would need a CPU emulator. Let's get
Wine into a better shape on 386 first, OK?
Why "#ifdef MyOS" is probably a mistake.
---------------------------------------
Operating systems change. Maybe yours doesn't have the "foo.h"
header, but maybe a future version will have it. If you want
to "#include <foo.h>", it doesn't matter what operating system
you are using; it only matters whether "foo.h" is there.
Furthermore, operating systems change names or "fork" into
several ones. An "#ifdef MyOs" will break over time.
If you use the feature of Autoconf, the Gnu auto-configuration
utility wisely, you will help future porters automatically
because your changes will test for _features_, not names of
operating systems. A feature can be many things:
* existance of a header file
* existance of a library function
* existance of libraries
* bugs in header files, library functions, the compiler, ...
* (you name it)
You will need Gnu Autoconf, which you can get from your
friendly Gnu mirror. This program takes Wine's "configure.in"
file and produces a "configure" shell script that users use to
configure Wine to their system.
There _are_ exceptions to the "avoid #ifdef MyOS" rule. Wine,
for example, needs the internals of the signal stack -- that
cannot easily be described in terms of features.
Let's now turn to specific porting problems and how to solve
them.
MyOS doesn't have the `foo.h' header!
------------------------------------
This first step is to make Autoconf check for this header.
In configure.in you add a segment like this in the section
that checks for header files (search for "header files"):
AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
If your operating system supports a header file with the
same contents but a different name, say bar.h, add a check
for that also.
Now you can change
#include <foo.h>
to
#ifdef HAVE_FOO_H
#include <foo.h>
#elif defined (HAVE_BAR_H)
#include <bar.h>
#endif
If your system doesn't have a corresponding header file even
though it has the library functions being used, you might
have to add an "#else" section to the conditional. Avoid
this if you can.
You will also need to add "#undef HAVE_FOO_H" (etc.) to
include/config.h.in
Finish up with "make configure" and "./configure".
MyOS doesn't have the `bar' function!
------------------------------------
A typical example of this is the `memmove'. To solve this
problem you would add `memmove' to the list of functions
that Autoconf checks for. In configure.in you search for
AC_CHECK_FUNCS and add `memmove'. (You will notice that
someone already did this for this particular function.)
Secondly, you will also need to add "#undef HAVE_BAR"
to include/config.h.in
The next step depends on the nature of the missing function.
Case 1: It's easy to write a complete implementation of the
function. (`memmove' belongs to this case.)
You add your implementation in misc/port.c surrounded by
"#ifndef HAVE_MEMMOVE" and "#endif".
You might have to add a prototype for your function. If so,
include/miscemu.h might be the place. Don't forget to protect
that definition by "#ifndef HAVE_MEMMOVE" and "#endif" also!
Case 2: A general implementation is hard, but Wine is only using
a special case.
An example is the various "wait" calls used in SIGNAL_child
from loader/signal.c. Here we have a multi-branch case on
features:
#ifdef HAVE_THIS
...
#elif defined (HAVE_THAT)
...
#elif defined (HAVE_SOMETHING_ELSE)
...
#endif
Note that this is very different from testing on operating
systems. If a new version of your operating systems comes
out and adds a new function, this code will magically start
using it.
Finish up with "make configure" and "./configure".

202
documentation/i18n.sgml Normal file
View File

@ -0,0 +1,202 @@
<chapter id="i18n">
<title>Internationalization</title>
<sect1 id="adding-languages">
<title>Adding New Languages</title>
<para>
written by Morten Welinder, January 1996.
</para>
<itemizedlist>
<listitem>
<para>Thereafter revised Februari 1999 by Klaas van Gend</para>
</listitem>
<listitem>
<para>Revised again May 23, 1999, Klaas van Gend</para>
</listitem>
<listitem>
<para>Updated May 26, 2000, Zoran Dzelajlija</para>
</listitem>
</itemizedlist>
<para>
(Extracted from <filename>wine/documentation/languages</filename>)
</para>
<para>
This file documents the necessary procedure for adding a new
language to the list of languages that Wine can display system
menus and forms in. Currently at least the following languages
are still missing:
<simplelist columns="5" type="horiz">
<member>Bulgarian</member>
<member>Chinese</member>
<member>Greek</member>
<member>Icelandic</member>
<member>Japanese</member>
<member>Romanian</member>
<member>Croatian</member>
<member>Slovak</member>
<member>Turkish</member>
<member>Slovanian</member>
</simplelist>
</para>
<note>
<para>
<emphasis>I hope I got all the places where changes are
needed. If you see any place missing from the list,
submit a patch to this file please. Also note that
re-organization of the source code might change the list of
places.</emphasis>
</para>
</note>
<para>
To add a new language you need to be able to translate the
relatively few texts, of course. You will need very little
knowledge of programming, so you have almost no excuses for
not adding your language, right? We should easily be able to
support 20 languages within a few months, get going! Apart
from re-compilation it'll take you about an hour or two.
</para>
<para>
To add a new language to the list of languages that Wine can
handle you must...
</para>
<orderedlist>
<listitem>
<para>Find the language ID in
<filename>include/winnls.h</filename>.</para>
</listitem>
<listitem>
<para>
Look in <filename>ole/ole2nls.c</filename> if your
language is already incorporated in the <varname>static
const struct NLS_langlocale</varname>. If not: find the
appropriate entries in
<filename>include/winnls.h</filename> and add them to the
list.
</para>
</listitem>
<listitem>
<para>
Edit the parameters defined in
<filename>ole/nls/*.nls</filename> to fit your local
habits and language.
</para>
</listitem>
<listitem>
<para>
Edit <filename>documentation/wine.man.in</filename>
(search for <parameter>-language</parameter>) to show the
new language abbreviation.
</para>
</listitem>
<listitem>
<para>
Edit <filename>misc/main.c</filename> variable
<varname>Languages</varname> to contain the new language
abbreviation and language ID. Also edit
<structname>struct option_table</structname> in
<filename>misc/options.c</filename> to show the new
abbreviation.
</para>
</listitem>
<listitem>
<para>
Edit <filename>include/options.h</filename>
<type>enum</type> <varname>WINE_LANGUAGE</varname> to have
a member called <literal>LANG_XX</literal> where
<literal>XX</literal> is the new abbreviation.
</para>
</listitem>
<listitem>
<para>
Create a new file
<filename>dlls/commdlg/cdlg_XX.rc</filename> (where
<literal>XX</literal> is your language abbreviation)
containing all menus. Your best bet is to copy
<filename>cdlg_En.rc</filename> and start translating.
There is no real need to know how the internal structure
of the file, as you only need to translate the text within
quotes.
</para>
<para>
In menus, the character "&amp;" means that the next
character will be highlighted and that pressing that
letter will select the item. You should place these
"&amp;" characters suitably for your language, not just
copy the positions from (say) English. In particular,
items within one menu should have different highlighted
letters.
</para>
</listitem>
<listitem>
<para>
Edit <filename>dlls/commdlg/rsrc.rc</filename> to contain
an <symbol>#include</symbol> statement for your
<filename>cdlg_XX.rc</filename> file.
</para>
</listitem>
<listitem>
<para>
Repeat steps 6 and 7 again for:
<itemizedlist>
<listitem>
<para>
<filename>dlls/shell32/shell32_XX.rc</filename> and
<filename>shres.rc</filename>
</para>
</listitem>
<listitem>
<para>
<filename>resources/sysres_XX.rc</filename> and
<filename>user32.rc</filename>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
Re-configure, re-make dependencies, and re-make Wine.
</para>
</listitem>
<listitem>
<para>
Check your new menus and forms; when they're not ok, go
back to 6) and adapt the sizes, etc.
</para>
</listitem>
<listitem>
<para>
Several of the winelib based programs in the subdirectory
programs also have internationalisation support. See the
appropriate files there for reference.
</para>
</listitem>
<listitem>
<para>Edit
<filename>documentation/internationalisation</filename> to
show the new status.</para>
</listitem>
<listitem>
<para>
Submit patches for inclusion in the next Wine release, see
file <filename>./ANNOUNCE</filename> for details about
where to submit.
</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" "")
End:
-->

535
documentation/implementation.sgml Normal file
View File

@ -0,0 +1,535 @@
<chapter id="implementation">
<title>Low-level Implementation</title>
<para>Details of Wine's Low-level Implementation...</para>
<sect1 id="builtin-dlls">
<title>Builtin DLLs</title>
<para>
written by &lt;juergen.schmied@metronet.de>
</para>
<para>
(Extracted from <filename>wine/documentation/internal-dll</filename>)
</para>
<para>
This document describes some points you should know before
implementing the internal counterparts to external DLL's.
Only 32 bit DLL's are considered.
</para>
<sect2>
<title>1. The LibMain function</title>
<para>
This is the way to do some initializing when a process or
thread is attached to the dll. The function name is taken
from a <filename>*.spec</filename> file line:
</para>
<programlisting>
init YourFunctionName
</programlisting>
<para>
Then, you have to implement the function:
</para>
<programlisting>
BOOL32 WINAPI YourLibMain(HINSTANCE32 hinstDLL,
DWORD fdwReason, LPVOID lpvReserved)
{ if (fdwReason==DLL_PROCESS_ATTACH)
{ ...
}
....
}
</programlisting>
</sect2>
<sect2>
<title>2. Using functions from other built-in DLL's</title>
<para>
The problem here is, that you can't know if you have to call
the function from the internal or the external DLL. If you
just call the function you will get the internal
implementation. If the external DLL is loaded the executed
program will use the external DLL and you the internal one.
When you -as an example- fill an iconlist placed in the
internal DLL the application won't get the icons from the
external DLL.
</para>
<para>
To work around this, you should always use a pointer to call
such functions:
</para>
<programlisting>
/* definition of the pointer type*/
void (CALLBACK* pDLLInitComctl)();
/* getting the function address this should be done in the
LibMain function when called with DLL_PROCESS_ATTACH*/
BOOL32 WINAPI Shell32LibMain(HINSTANCE32 hinstDLL, DWORD fdwReason,
LPVOID lpvReserved)
{ HINSTANCE32 hComctl32;
if (fdwReason==DLL_PROCESS_ATTACH)
{ /* load the external / internal DLL*/
hComctl32 = LoadLibrary32A("COMCTL32.DLL");
if (hComctl32)
{ /* get the function pointer */
pDLLInitComctl=GetProcAddress32(hComctl32,"InitCommonControlsEx");
/* check it */
if (pDLLInitComctl)
{ /* use it */
pDLLInitComctl();
}
/* free the DLL / decrease the ref count */
FreeLibrary32(hComctl32);
}
else
{ /* do some panic*/
ERR(shell,"P A N I C error getting functionpointers\n");
exit (1);
}
}
....
</programlisting>
</sect2>
<sect2>
<title>3. Getting resources from a <filename>*.rc</filename> file linked to the DLL</title>
<para>
&lt; If you know how, write some lines&gt;
</para>
</sect2>
</sect1>
<sect1 id="accel-impl">
<title>Accelerators</title>
<para>
Findings researched by Uwe Bonnes, Ulrich Weigand and Marcus Meissner.
</para>
<para>
(Extracted from <filename>wine/documentation/accelerators</filename>)
</para>
<para>
Some notes concerning accelerators.
</para>
<para>
There are <emphasis>three</emphasis> differently sized
accelerator structures exposed to the user. The general layout
is:
</para>
<programlisting>
BYTE fVirt;
WORD key;
WORD cmd;
</programlisting>
<para>
We now have three different appearances:
</para>
<orderedlist>
<listitem>
<para>
Accelerators in NE resources. These have a size of 5 byte
and do not have any padding. This is also the internal
layout of the global handle <type>HACCEL</type> (16 and
32) in Windows 95 and WINE. Exposed to the user as Win16
global handles <type>HACCEL16</type> and
<type>HACCEL32</type> by the Win16/Win32 API.
</para>
</listitem>
<listitem>
<para>
Accelerators in PE resources. These have a size of 8 byte.
Layout is:
</para>
<programlisting>
BYTE fVirt;
BYTE pad0;
WORD key;
WORD cmd;
WORD pad1;
</programlisting>
<para>
They are exposed to the user only by direct accessing PE
resources.
</para>
</listitem>
<listitem>
<para>
Accelerators in the Win32 API. These have a size of 6
bytes. Layout is:
</para>
<programlisting>
BYTE fVirt;
BYTE pad0;
WORD key;
WORD cmd;
</programlisting>
<para>
These are exposed to the user by the
<function>CopyAcceleratorTable</function> and
<function>CreateAcceleratorTable</function> functions in
the Win32 API.
</para>
</listitem>
</orderedlist>
<para>
Why two types of accelerators in the Win32 API? We can only
guess, but my best bet is that the Win32 resource compiler
can/does not handle struct packing. Win32 <type>ACCEL</type>
is defined using <function>#pragma(2)</function> for the
compiler but without any packing for RC, so it will assume
<function>#pragma(4)</function>.
</para>
</sect1>
<sect1 id="file-handles">
<title>File Handles</title>
<para>
written by (???)
</para>
<para>
(Extracted from <filename>wine/documentation/filehandles</filename>)
</para>
<para>
DOS treats the first 5 file handles as special cases. They
map directly to <filename>stdin</filename>,
<filename>stdout</filename>, <filename>stderr</filename>,
<filename>stdaux</filename> and <filename>stdprn</filename>.
Windows 16 inherits this behavior, and in fact, win16 handles
are interchangable with DOS handles. Some nasty windows
programs even do this!
</para>
<para>
Windows32 issues file handles starting from
<literal>1</literal>, on the grounds that most GUI processes
don't need a <filename>stdin</filename>,
<filename>stdout</filename>, etc.
</para>
<para>
The Wine handle code is implemented in the Win32 style, and
the Win16 functions use two macros to convert to and from the
two types.
</para>
<para>
The macros are defined in <filename>file.h</filename> as follows:
</para>
<programlisting>
#define HFILE16_TO_HFILE32(handle) \
(((handle)==0) ? GetStdHandle(STD_INPUT_HANDLE) : \
((handle)==1) ? GetStdHandle(STD_OUTPUT_HANDLE) : \
((handle)==2) ? GetStdHandle(STD_ERROR_HANDLE) : \
((handle)>0x400) ? handle : \
(handle)-5)
#define HFILE32_TO_HFILE16(handle) ({ HFILE32 hnd=handle; \
((hnd==HFILE_ERROR32) ? HFILE_ERROR16 : \
((handle>0x400) ? handle : \
(HFILE16)hnd+5); })
</programlisting>
<warning>
<para>
Be careful not to use the macro
<function>HFILE16_TO_HFILE32</function> on functions with
side-effects, as it will cause them to be evaluated several
times. This could be considered a bug, but the use of this
macro is limited enough not to need a rewrite.
</para>
</warning>
<note>
<para>
The <literal>0x400</literal> special case above deals with
LZW filehandles (see <filename>misc/lzexpand.c</filename>).
</para>
</note>
</sect1>
<sect1 id="hardware-trace">
<title>Doing A Hardware Trace In Wine</title>
<para>
written by Jonathan Buzzard &lt;jab@hex.prestel.co.uk>
</para>
<para>
(Extracted from <filename>wine/documentation/ioport-trace-hints</filename>)
</para>
<para>
The primary reason to do this is to reverse engineer a
hardware device for which you don't have documentation, but
can get to work under Wine.
</para>
<para>
This lot is aimed at parallel port devices, and in particular
parallel port scanners which are now so cheap they are
virtually being given away. The problem is that few
manufactures will release any programming information which
prevents drivers being written for Sane, and the traditional
technique of using DOSemu to produce the traces does not work
as the scanners invariably only have drivers for Windows.
</para>
<para>
Please note that I have not been able to get my scanner
working properly (a UMAX Astra 600P), but a couple of people
have reported success with at least the Artec AS6e scanner. I
am not in the process of developing any driver nor do I intend
to, so don't bug me about it. My time is now spent writing
programs to set things like battery save options under Linux
on Toshiba laptops, and as such I don't have any spare time
for writing a driver for a parallel port scanner etc.
</para>
<para>
Presuming that you have compiled and installed wine the first
thing to do is is to enable direct hardware access to your
parallel port. To do this edit <filename>wine.conf</filename>
(usually in <filename>/usr/local/etc</filename>) and in the
ports section add the following two lines
</para>
<programlisting>
read=0x378,0x379,0x37a,0x37c,0x77a
write=0x378,x379,0x37a,0x37c,0x77a
</programlisting>
<para>
This adds the necessary access required for SPP/PS2/EPP/ECP
parallel port on LPT1. You will need to adjust these number
accordingly if your parallel port is on LPT2 or LPT0.
</para>
<para>
When starting wine use the following command line, where
<literal>XXXX</literal> is the program you need to run in
order to access your scanner, and <literal>YYYY</literal> is
the file your trace will be stored in:
</para>
<programlisting>
wine -debugmsg +io XXXX 2&gt; &gt;(sed 's/^[^:]*:io:[^ ]* //' &gt; YYYY)
</programlisting>
<para>
You will need large amounts of hard disk space (read hundreds
of megabytes if you do a full page scan), and for reasonable
performance a really fast processor and lots of RAM.
</para>
<para>
You might well find the log compression program that <email>David
Campbell campbell@torque.net</email> wrote helpful in
reducing the size of the log files. This can be obtained by
the following command:
</para>
<programlisting>
sh ioport-trace-hints
</programlisting>
<para>
This should extract <filename>shrink.c</filename> (which is
located at the end of this file. Compile the log compression
program by:
</para>
<programlisting>
cc shrink.c -o shrink
</programlisting>
<para>
Use the <command>shrink</command> program to reduce the
physical size of the raw log as follows:
</para>
<programlisting>
cat log | shrink &gt; log2
</programlisting>
<para>
The trace has the basic form of
</para>
<programlisting>
XXXX &gt; YY @ ZZZZ:ZZZZ
</programlisting>
<para>
where <literal>XXXX</literal> is the port in hexidecimal being
accessed, <literal>YY</literal> is the data written (or read)
from the port, and <literal>ZZZZ:ZZZZ</literal> is the address
in memory of the instruction that accessed the port. The
direction of the arrow indicates whether the data was written
or read from the port.
</para>
<programlisting>
&gt; data was written to the port
&lt; data was read from the port
</programlisting>
<para>
My basic tip for interperating these logs is to pay close
attention to the addresses of the IO instructions. Their
grouping and sometimes proximity should reveal the presence of
subroutines in the driver. By studying the different versions
you should be able to work them out. For example consider the
following section of trace from my UMAX Astra 600P
</para>
<programlisting>
0x378 &gt; 55 @ 0297:01ec
0x37a &gt; 05 @ 0297:01f5
0x379 &lt; 8f @ 0297:01fa
0x37a &gt; 04 @ 0297:0211
0x378 &gt; aa @ 0297:01ec
0x37a &gt; 05 @ 0297:01f5
0x379 &lt; 8f @ 0297:01fa
0x37a &gt; 04 @ 0297:0211
0x378 &gt; 00 @ 0297:01ec
0x37a &gt; 05 @ 0297:01f5
0x379 &lt; 8f @ 0297:01fa
0x37a &gt; 04 @ 0297:0211
0x378 &gt; 00 @ 0297:01ec
0x37a &gt; 05 @ 0297:01f5
0x379 &lt; 8f @ 0297:01fa
0x37a &gt; 04 @ 0297:0211
0x378 &gt; 00 @ 0297:01ec
0x37a &gt; 05 @ 0297:01f5
0x379 &lt; 8f @ 0297:01fa
0x37a &gt; 04 @ 0297:0211
0x378 &gt; 00 @ 0297:01ec
0x37a &gt; 05 @ 0297:01f5
0x379 &lt; 8f @ 0297:01fa
0x37a &gt; 04 @ 0297:0211
</programlisting>
<para>
As you can see their is a repeating structure starting at
address <literal>0297:01ec</literal> that consists of four io
accesses on the parallel port. Looking at it the first io
access writes a changing byte to the data port the second
always writes the byte <literal>0x05</literal> to the control
port, then a value which always seems to
<literal>0x8f</literal> is read from the status port at which
point a byte <literal>0x04</literal> is written to the control
port. By studying this and other sections of the trace we can
write a C routine that emulates this, shown below with some
macros to make reading/writing on the parallel port easier to
read.
</para>
<programlisting>
#define r_dtr(x) inb(x)
#define r_str(x) inb(x+1)
#define r_ctr(x) inb(x+2)
#define w_dtr(x,y) outb(y, x)
#define w_str(x,y) outb(y, x+1)
#define w_ctr(x,y) outb(y, x+2)
/*
* Seems to be sending a command byte to the scanner
*
*/
int udpp_put(int udpp_base, unsigned char command)
{
int loop,value;
w_dtr(udpp_base, command);
w_ctr(udpp_base, 0x05);
for (loop=0;loop&lt;10;loop++)
if (((value=r_str(udpp_base)) & 0x80)!=0x00) {
w_ctr(udpp_base, 0x04);
return value & 0xf8;
}
return (value & 0xf8) | 0x01;
}
</programlisting>
<para>
For the UMAX Astra 600P only seven such routines exist (well
14 really, seven for SPP and seven for EPP). Whether you
choose to disassemble the driver at this point to verify the
routines is your own choice. If you do, the address from the
trace should help in locating them in the disassembly.
</para>
<para>
You will probably then find it useful to write a script/perl/C
program to analyse the logfile and decode them futher as this
can reveal higher level grouping of the low level routines.
For example from the logs from my UMAX Astra 600P when decoded
futher reveal (this is a small snippet)
</para>
<programlisting>
start:
put: 55 8f
put: aa 8f
put: 00 8f
put: 00 8f
put: 00 8f
put: c2 8f
wait: ff
get: af,87
wait: ff
get: af,87
end: cc
start:
put: 55 8f
put: aa 8f
put: 00 8f
put: 03 8f
put: 05 8f
put: 84 8f
wait: ff
</programlisting>
<para>
From this it is easy to see that <varname>put</varname>
routine is often grouped together in five successive calls
sending information to the scanner. Once these are understood
it should be possible to process the logs further to show the
higher level routines in an easy to see format. Once the
highest level format that you can derive from this process is
understood, you then need to produce a series of scans varying
only one parameter between them, so you can discover how to
set the various parameters for the scanner.
</para>
<para>
The following is the <filename>shrink.c</filename> program.
</para>
<programlisting>
cat &gt; shrink.c &lt;&lt;EOF
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
void
main (void)
{
char buff[256], lastline[256];
int count;
count = 0;
lastline[0] = 0;
while (!feof (stdin))
{
fgets (buff, sizeof (buff), stdin);
if (strcmp (buff, lastline) == 0)
{
count++;
}
else
{
if (count &gt; 1)
fprintf (stdout, "# Last line repeated %i times #\n", count);
fprintf (stdout, "%s", buff);
strcpy (lastline, buff);
count = 1;
}
}
}
EOF
</programlisting>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
End:
-->

751
documentation/installing.sgml Normal file
View File

@ -0,0 +1,751 @@
<chapter id="installing">
<title>Installing Wine</title>
<para>How to install Wine...</para>
<sect1 id="replace-windows">
<title>WWN #52 Feature: Replacing Windows</title>
<para>
Written by Ove Kåven <email>ovek@winehq.com</email>
</para>
<sect2>
<title>Installation Overview</title>
<para>
A Windows installation consists of many different parts.
</para>
<itemizedlist>
<listitem>
<para>
Registry. Many keys are supposed to exist and contain
meaningful data, even in a newly-installed Windows.
</para>
</listitem>
<listitem>
<para>
Directory structure. Applications expect to find and/or
install things in specific predetermined locations. Most
of these directories are expected to exist. But unlike
Unix directory structures, most of these locations are
not hardcoded, and can be queried via the Windows API
and the registry. This places additional requirements on
a Wine installation.
</para>
</listitem>
<listitem>
<para>
System DLLs. In Windows, these usually reside in the
<filename>system</filename> (or
<filename>system32</filename>) directories. Some Windows
applications check for their existence in these
directories before attempting to load them. While Wine
is able to load its own internal DLLs
(<filename>.so</filename> files) when the application
asks for a DLL, Wine does not simulate the existence of
nonexisting files.
</para>
</listitem>
</itemizedlist>
<para>
While the users are of course free to set up everything
themselves, the Wine team will make the automated Wine
installation script, <filename>tools/wineinstall</filename>,
do everything we find necessary to do; running the
conventional <command>configure && make depend && make && make
install</command> cycle is thus not recommended, unless
you know what you're doing. At the moment,
<filename>tools/wineinstall</filename> is able to create a
configuration file, install the registry, and create the
directory structure itself.
</para>
</sect2>
<sect2>
<title>The Registry</title>
<para>
The default registry is in the file
<filename>winedefault.reg</filename>. It contains directory
paths, class IDs, and more; it must be installed before most
<filename>INSTALL.EXE</filename> or
<filename>SETUP.EXE</filename> applications will work. The
registry is covered in more detail in an earlier article.
</para>
</sect2>
<sect2>
<title>Directory Structure</title>
<para>
Here's the fundamental layout that Windows applications and
installers expect. Without it, they seldom operate
correctly.
</para>
<informaltable frame="none">
<tgroup cols="5">
<tbody>
<row>
<entry>C:\</entry>
<entry></entry><entry></entry><entry></entry>
<entry>Root directory of primary disk drive</entry>
</row>
<row>
<entry></entry>
<entry>Windows\</entry>
<entry></entry><entry></entry>
<entry>Windows directory, containing .INI files, accessories, etc</entry>
</row>
<row>
<entry></entry><entry></entry>
<entry valign="middle">System\</entry>
<entry></entry>
<entry><literallayout>Win3.x/95/98/ME directory for common DLLs
WinNT/2000 directory for common 16-bit DLLs</literallayout></entry>
</row>
<row>
<entry></entry><entry></entry>
<entry>System32\</entry>
<entry></entry>
<entry>WinNT/2000 directory for common 32-bit DLLs</entry>
</row>
<row>
<entry></entry><entry></entry>
<entry>Start Menu\</entry>
<entry></entry>
<entry>Program launcher directory structure</entry>
</row>
<row>
<entry></entry><entry></entry><entry></entry>
<entry>Programs\</entry>
<entry>Program launcher links (.LNK files) to applications</entry>
</row>
<row>
<entry></entry>
<entry>Program Files\</entry>
<entry></entry><entry></entry>
<entry>Application binaries (.EXE and .DLL files)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Wine emulates drives by placing their virtual drive roots to
user-configurable points in the Unix filesystem, so it's
your choice where <medialabel>C:</medialabel>'s root should
be (<filename>tools/wineinstall</filename> will even ask
you). If you choose, say, <filename>/var/wine</filename>, as
the root of your virtual drive <medialabel>C</medialabel>,
then you'd put this in your <filename>wine.conf</filename>:
</para>
<programlisting>
[Drive C]
Path=/var/wine
Type=hd
Label=MS-DOS
Filesystem=win95
</programlisting>
<para>
With this configuration, what windows apps think of as
"c:\windows\system" would map to
<filename>/var/wine/windows/system</filename> in the UNIX
filesystem. Note that you need to specify
<literal>Filesystem=win95</literal>, NOT
<literal>Filesystem=unix</literal>, to make Wine simulate a
Windows-compatible (case-insensitive) filesystem, otherwise
most apps won't work.
</para>
</sect2>
<sect2>
<title>System DLLs</title>
<para>
The Wine team has determined that it is necessary to create
fake DLL files to trick many applications that check for
file existence to determine whether a particular feature
(such as Winsock and its TCP/IP networking) is available. If
this is a problem for you, you can create empty files in the
<filename>system</filename> directory to make the
application think it's there, and Wine's built-in DLL will
be loaded when the application actually asks for it.
(Unfortunately, <filename>tools/wineinstall</filename> does
not create such empty files itself.)
</para>
<para>
Applications sometimes also try to inspect the version
resources from the physical files (for example, to determine
the DirectX version). Empty files will not do in this case,
it is rather necessary to install files with complete
version resources. This problem is currently being worked
on. In the meantime, you may still need to grab some real
DLL files to fool these apps with.
</para>
<para>
And there are of course DLLs that wine does not currently
implement very well (or at all). If you do not have a real
Windows you can steal necessary DLLs from, you can always
get some from a DLL archive such as
<ulink url="http://solo.abac.com/dllarchive/">http://solo.abac.com/dllarchive/</ulink>.
</para>
</sect2>
</sect1>
<sect1 id="no-windows">
<title>Installing Wine Without Windows</title>
<para>
written by ???
</para>
<para>
(Extracted from <filename>wine/documentation/no-windows</filename>)
</para>
<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
provided with Windows. Therefore, once Wine is finished, you
will not need to have windows installed to use Wine.
</para>
<para>
Wine has already made enough progress that it may be possible
to run your target applications without Windows installed. If
you want to try it, follow these steps:
</para>
<orderedlist>
<listitem>
<para>
Create empty <filename>C:\windows</filename>,
<filename>C:\windows\system</filename>,
<filename>C:\windows\Start Menu</filename>, and
<filename>C:\windows\Start Menu\Programs</filename>
directories. Do not point Wine to a
<filename>Windows</filename> directory full of old
installations and a messy registry. (Wine creates a
special registry in your <filename >home</filename>
directory, in <filename>$HOME/.wine/*.reg</filename>.
Perhaps you have to remove these files).
</para>
</listitem>
<listitem>
<para>
Point <medialabel>[Drive C]</medialabel> in
<filename>wine.conf</filename> or
<filename>.winerc</filename> to where you want
<filename>C:</filename> to be. Refer to the Wine man page
for more information. Remember to use
<userinput>filesystem=win95</userinput>!
</para>
</listitem>
<listitem>
<para>
Use <filename>tools/wineinstall</filename> to compile Wine
and install the default registry. Or if you prefer to do
it yourself, compile <filename>programs/regapi</filename>,
and run: <command>programs/regapi/regapi setValue &lt;
winedefault.reg</command>
</para>
</listitem>
<listitem>
<para>
Run and/or install your applications.
</para>
</listitem>
</orderedlist>
<para>
Because Wine is not yet complete, some programs will work
better with native Windows DLL's 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
<filename>C:\windows</filename> directory in the configuration
file does not point to a native Windows installation but is in
a separate Unix file system. (For instance, <quote>C:\windows</quote> is
really subdirectory <quote>windows</quote> located in
<quote>/home/ego/wine/drives/c</quote>).
</para>
<itemizedlist>
<listitem>
<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
<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
the Wine internal versions must be used.
</para>
</listitem>
<listitem>
<para>
Edit the <quote>[DllOverrides]</quote> section of
<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
about this, see the Wine manpage.
</para>
</listitem>
<listitem>
<para>
Note that some network DLL's 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.
</para>
</listitem>
<listitem>
<para>
Copy SHELL/SHELL32 and COMDLG/COMDLG32 COMMCTRL/COMCTL32
only as pairs to your Wine directory (these DLL's 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.
</para>
</listitem>
<listitem>
<para>
Be consistent: Use only DLL's 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
registry, don't know about
<application>office97</application>).
</para>
</listitem>
<listitem>
<para>
Also add <filename>winhelp.exe</filename> and
<filename>winhlp32.exe</filename> if you want to be able
to browse through your programs' help function.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="vfat">
<title>Dealing With FAT/VFAT Partitions</title>
<para>
written by Steven Elliott (elliotsl@mindspring.com)
</para>
<para>
(Extracted from <filename>wine/documentation/linux-fat-permissions</filename>)
</para>
<para>
This document describes how FAT and
VFAT file system permissions work in Linux
with a focus on configuring them for Wine.
</para>
<sect2>
<title>Introduction</title>
<para>
Linux is able to access DOS and Windows file systems using
either the FAT (older 8.3 DOS filesystems) or VFAT (newer
Windows 95 or later long filename filesystems) modules.
Mounted FAT or VFAT filesystems provide the primary means
for which existing applications and their data are accessed
through Wine for dual boot (Linux + Windows) systems.
</para>
<para>
Wine maps mounted FAT filesystems, such as
<filename>/c</filename>, to driver letters, such as
<quote>c:</quote>, as indicated by the
<filename>wine.conf</filename> file. The following excerpt
from a <filename>wine.conf</filename> file does this:
</para>
<programlisting>
[Drive C]
Path=/c
Type=hd
</programlisting>
<para>
Although VFAT filesystems are preferable to FAT filesystems
for their long filename support the term <quote>FAT</quote>
will be used throughout the remainder of this document to
refer to FAT filesystems and their derivatives. Also,
<quote>/c</quote> will be used as the FAT mount point in
examples throughout this document.
</para>
<para>
Most modern Linux distributions either detect or allow
existing FAT file systems to be configured so that 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:
</para>
<screen>
<prompt>~></prompt><userinput>cd /c</userinput>
<prompt>/c></prompt><userinput>ls -l</userinput>
<computeroutput>-rwxr-xr-x 1 root root 91 Oct 10 17:58 autoexec.bat
-rwxr-xr-x 1 root root 245 Oct 10 17:58 config.sys
drwxr-xr-x 41 root root 16384 Dec 30 1998 windows</computeroutput>
</screen>
<para>
where all the files are owned by "root", are in the "root"
group and are only writable by "root"
(<literal>755</literal> permissions). This is restrictive in
that it requires that Wine be run as root in order for
applications to be able to write to any part of the
filesystem.
</para>
<para>
There three major approaches to overcoming the restrictive
permissions mentioned in the previous paragraph:
</para>
<orderedlist>
<listitem>
<para>
Run <application>Wine</application> as root
</para>
</listitem>
<listitem>
<para>
Mount the FAT filesystem with less restrictive
permissions
</para>
</listitem>
<listitem>
<para>
Shadow the FAT filesystem by completely or partially
copying it
</para>
</listitem>
</orderedlist>
<para>
Each approach will be discussed in the following sections.
</para>
</sect2>
<sect2>
<title>Running Wine as root</title>
<para>
Running Wine as root is the easiest and most thorough way of giving
applications that Wine runs unrestricted access to FAT files systems.
Running wine as root also allows applications to do things unrelated
to FAT filesystems, such as listening to ports that are less than
1024. Running Wine as root is dangerous since there is no limit to
what the application can do to the system.
</para>
</sect2>
<sect2>
<title>Mounting FAT filesystems</title>
<para>
The FAT filesystem can be mounted with permissions less restrictive
than the default. This can be done by either changing the user that
mounts the FAT filesystem or by explicitly changing the permissions
that the FAT filesystem is mounted with. The permissions are
inherited from the process that mounts the FAT filesystem. Since the
process that mounts the FAT filesystem is usually a startup script
running as root the FAT filesystem inherits root's permissions. This
results in the files on the FAT filesystem having permissions similar
to files created by root. For example:
</para>
<screen>
<prompt>~></prompt><userinput>whoami</userinput>
<computeroutput>root</computeroutput>
<prompt>~></prompt><userinput>touch root_file</userinput>
<prompt>~></prompt><userinput>ls -l root_file</userinput>
<computeroutput></computeroutput>-rw-r--r-- 1 root root 0 Dec 10 00:20 root_file
</screen>
<para>
which matches the owner, group and permissions of files seen
on the FAT filesystem except for the missing 'x's. The
permissions on the FAT filesystem can be changed by changing
root's umask (unset permissions bits). For example:
</para>
<screen>
<prompt>~></prompt><userinput>umount /c</userinput>
<prompt>~></prompt><userinput>umask</userinput>
<computeroutput>022</computeroutput>
<prompt>~></prompt><userinput>umask 073</userinput>
<prompt>~></prompt><userinput>mount /c</userinput>
<prompt>~></prompt><userinput>cd /c</userinput>
<prompt>/c></prompt><userinput>ls -l</userinput>
<computeroutput>-rwx---r-- 1 root root 91 Oct 10 17:58 autoexec.bat
-rwx---r-- 1 root root 245 Oct 10 17:58 config.sys
drwx---r-- 41 root root 16384 Dec 30 1998 windows</computeroutput>
</screen>
<para>
Mounting the FAT filesystem with a umask of
<literal>000</literal> gives all users complete control over
it. Explicitly specifying the permissions of the FAT
filesystem when it is mounted provides additional control.
There are three mount options that are relevant to FAT
permissions: <literal>uid</literal>, <literal>gid</literal>
and <literal>umask</literal>. They can each be specified
when the filesystem is manually mounted. For example:
</para>
<screen>
<prompt>~></prompt><userinput>umount /c</userinput>
<prompt>~></prompt><userinput>mount -o uid=500 -o gid=500 -o umask=002 /c</userinput>
<prompt>~></prompt><userinput>cd /c</userinput>
<prompt>/c></prompt><userinput>ls -l</userinput>
<computeroutput>-rwxrwxr-x 1 sle sle 91 Oct 10 17:58 autoexec.bat
-rwxrwxr-x 1 sle sle 245 Oct 10 17:58 config.sys
drwxrwxr-x 41 sle sle 16384 Dec 30 1998 windows</computeroutput>
</screen>
<para>
which gives "sle" complete control over
<filename>/c</filename>. The options listed above can be
made permanent by adding them to the
<filename>/etc/fstab</filename> file:
</para>
<screen>
<prompt>~></prompt><userinput>grep /c /etc/fstab</userinput>
<computeroutput>/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1</computeroutput>
</screen>
<para>
Note that the umask of <literal>002</literal> is common in
the user private group file permission scheme. On FAT file
systems this umask assures that all files are fully
accessible by all users in the specified group
(<literal>gid</literal>).
</para>
</sect2>
<sect2>
<title>Shadowing FAT filesystems</title>
<para>
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
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
write to the <filename>c:\windows</filename> and
<filename>c:\AnApp</filename> directories as well as have
read access to the entire FAT filesystem. On this system
the FAT filesystem has default permissions which should not
be changed for security reasons or can not be changed due to
lack of root access. On this system a shadow directory
might be set up in the following manner:
</para>
<screen>
<prompt>~></prompt><userinput>cd /</userinput>
<prompt>/></prompt><userinput>mkdir c_shadow</userinput>
<prompt>/></prompt><userinput>cd c_shadow</userinput>
<prompt>/c_shadow></prompt><userinput>ln -s /c_/* .</userinput>
<prompt>/c_shadow></prompt><userinput>rm windows AnApp</userinput>
<prompt>/c_shadow></prompt><userinput>cp -R /c_/{windows,AnApp} .</userinput>
<prompt>/c_shadow></prompt><userinput>chmod -R 777 windows AnApp</userinput>
<prompt>/c_shadow></prompt><userinput>perl -p -i -e 's|/c$|/c_shadow|g' /usr/local/etc/wine.conf</userinput>
</screen>
<para>
The above gives everyone complete read and write access to
the <filename>windows</filename> and
<filename>AnApp</filename> directories while only root has
write access to all other directories.
</para>
</sect2>
</sect1>
<sect1 id="scsi-support">
<title>SCSI Support</title>
<para>
written by Bruce Milner; Additions by Andreas Mohr
</para>
<para>
(Extracted from <filename>wine/documentation/aspi</filename>)
</para>
<para>
This file describes setting up the Windows ASPI interface.
</para>
<para>
<warning>
<title>Warning/Warning/Warning!!!!!!</title>
<para>
<screen>
THIS MAY TRASH YOUR SYSTEM IF USED INCORRECTLY
THIS MAY TRASH YOUR SYSTEM IF USED CORRECTLY
</screen>
</para>
</warning>
</para>
<para>
Now that I have said that. ASPI is a direct link to SCSI devices from
windows programs. ASPI just forwards the SCSI commands that programs send
to it to the SCSI bus.
</para>
<para>
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
have their permissions set as restricted as possible !
</para>
<para>
Cookbook for setting up scanner: (At least how mine is to work)
</para>
<sect2>
<title>Windows requirements</title>
<orderedlist>
<listitem>
<para>
The scanner software needs to use the "Adaptec"
compatible drivers (ASPI). At least with Mustek, they
allow you the choice of using the builtin card or the
"Adaptec (AHA)" compatible drivers. This will not work
any other way. Software that accesses the scanner via a
DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM]
</para>
</listitem>
<listitem>
<para>
You probably need a real windows install of the software
to set the LUN's/SCSI id's up correctly. I'm not exactly
sure.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>LINUX requirements:</title>
<orderedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
Compile generic scsi drivers into your kernel.
</para>
</listitem>
<listitem>
<para>
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
<literal>130560</literal> and this seems to work just
fine. This does require a kernel rebuild.
</para>
</listitem>
<listitem>
<para>
Make the devices for the scanner (generic scsi devices)
- look at the scsi programming how-to for device
numbering.
</para>
</listitem>
<listitem>
<para>
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
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
<literal>C=controller</literal>,
<literal>T=target</literal>, <literal>D=LUN</literal>
</para>
<para>
For example, I set mine up as controller <literal>0</literal>,
Target <literal>6</literal>, LUN <literal>0</literal>.
<programlisting>
[scsi c0t6d0]
Device=/dev/sgi
</programlisting>
Yours will vary with your particular SCSI setup.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>General Information</title>
<para>
The mustek scanner I have was shipped with a package
"ipplus". This program uses the TWAIN driver specification
to access scanners.
</para>
<para>
(TWAIN MANAGER)
</para>
<para>
<programlisting>
ipplus.exe &lt;---> (TWAIN INTERFACE) &lt;---> (TWAIN DATA SOURCE . ASPI) -> WINASPI
</programlisting>
</para>
</sect2>
<sect2>
<title>NOTES/BUGS</title>
<para>
The biggest is that it only works under linux at the moment.
</para>
<para>
The ASPI code has only been tested with:
</para>
<itemizedlist>
<listitem>
<para>
a Mustek 800SP with a Buslogic controller under Linux [BM]
</para>
</listitem>
<listitem>
<para>
a Siemens Nixdorf 9036 with Adaptec AVA-1505 under Linux
accessed via DOSASPI. Note that I had color problems,
though (barely readable result) [AM]
</para>
</listitem>
<listitem>
<para>
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
work. Your devices may explode. I have no way of determining
this. I take zero responsibility!
</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" "")
End:
-->

75
documentation/internal-dll
View File

@ -1,75 +0,0 @@
This document describes some points you should know before implementing
the internal counterparts to external DLL's. Only 32 bit DLL's
are considered.
1. The LibMain function
-----------------------
This is the way to do some initializing when a process or thread is attached
to the dll. The function name is taken from a *.spec file line:
init YourFunctionName
then, you have to implement the function:
BOOL32 WINAPI YourLibMain(HINSTANCE32 hinstDLL,
DWORD fdwReason, LPVOID lpvReserved)
{ if (fdwReason==DLL_PROCESS_ATTACH)
{ ...
}
....
}
2. Using functions from other built-in DLL's
--------------------------------------------
The problem here is, that you can't know if you have to call the function from
the internal or the external DLL. If you just call the function you will get
the internal implementation. If the external DLL is loaded the executed program
will use the external DLL and you the internal one.
When you -as an example- fill an iconlist placed in the internal DLL the
application won't get the icons from the external DLL.
To work around this, you should always use a pointer to call such functions:
/* definition of the pointer type*/
void (CALLBACK* pDLLInitComctl)();
/* getting the function address this should be done in the
LibMain function when called with DLL_PROCESS_ATTACH*/
BOOL32 WINAPI Shell32LibMain(HINSTANCE32 hinstDLL, DWORD fdwReason,
LPVOID lpvReserved)
{ HINSTANCE32 hComctl32;
if (fdwReason==DLL_PROCESS_ATTACH)
{ /* load the external / internal DLL*/
hComctl32 = LoadLibrary32A("COMCTL32.DLL");
if (hComctl32)
{ /* get the function pointer */
pDLLInitComctl=GetProcAddress32(hComctl32,"InitCommonControlsEx");
/* check it */
if (pDLLInitComctl)
{ /* use it */
pDLLInitComctl();
}
/* free the DLL / decrease the ref count */
FreeLibrary32(hComctl32);
}
else
{ /* do some panic*/
ERR(shell,"P A N I C error getting functionpointers\n");
exit (1);
}
}
....
3. Getting resources from a *.rc file linked to the DLL
-------------------------------------------------------
< If you know how, write some lines>
----------
<juergen.schmied@metronet.de>

350
documentation/internals
View File

@ -1,350 +0,0 @@
KERNEL MODULE
=============
...
GDI MODULE
==========
1. X Windows System interface
-----------------------------
The X libraries used to implement X clients (such as Wine) do not work
properly if multiple threads access the same display concurrently. It is
possible to compile the X libraries to perform their own synchronization
(initiated by calling XInitThreads()). However, Wine does not use this
approach. Instead Wine performs its own synchronization py putting a
wrapper around every X call that is used. This wrapper protects library
access with a critical section, and also arranges things so that X
libraries compiled without -D_REENTRANT (eg. with global errno variable)
will work with Wine.
To make this scheme work, all calls to X must use the proper wrapper
functions (or do their own synchronization that is compatible with the
wrappers). The wrapper for a function X...() is calles TSX...() (for
"Thread Safe X ..."). So for example, instead of calling XOpenDisplay()
in the code, TSXOpenDisplay() must be used. Likewise, X include files
that contain function prototypes are wrapped, so that eg. "ts_xutil.h"
must be included rather than <X11/Xutil.h>. It is important that this
scheme is used everywhere to avoid the introduction of nondeterministic
and hard-to-find errors in Wine.
The code for the thread safe X wrappers is contained in the tsx11/
directory and in include/ts*.h. To use a new (ie. not previously used) X
function in Wine, a new wrapper must be created. The wrappers are
generated (semi-)automatically from the X11R6 includes using the
tools/make_X11wrappers perl script. In simple cases it should be enough
to add the name of the new function to the list in tsx11/X11_calls; if
this does not work the wrapper must be added manually to the
make_X11wrappers script. See comments in tsx11/X11_calls and
tools/make_X11wrappers for further details.
USER MODULE
===========
USER implements windowing and messaging subsystems. It also
contains code for common controls and for other miscellaneous
stuff (rectangles, clipboard, WNet, etc). Wine USER code is
located in windows/, controls/, and misc/ directories.
1. Windowing subsystem
----------------------
windows/win.c
windows/winpos.c
Windows are arranged into parent/child hierarchy with one
common ancestor for all windows (desktop window). Each window
structure contains a pointer to the immediate ancestor (parent
window if WS_CHILD style bit is set), a pointer to the sibling
(returned by GetWindow(..., GW_NEXT)), a pointer to the owner
window (set only for popup window if it was created with valid
hwndParent parameter), and a pointer to the first child
window (GetWindow(.., GW_CHILD)). All popup and non-child windows
are therefore placed in the first level of this hierarchy and their
ancestor link (wnd->parent) points to the desktop window.
Desktop window - root window
| \ `-.
| \ `-.
popup -> wnd1 -> wnd2 - top level windows
| \ `-. `-.
| \ `-. `-.
child1 child2 -> child3 child4 - child windows
Horizontal arrows denote sibling relationship, vertical lines
- ancestor/child. To summarize, all windows with the same immediate
ancestor are sibling windows, all windows which do not have desktop
as their immediate ancestor are child windows. Popup windows behave
as topmost top-level windows unless they are owned. In this case the
only requirement is that they must precede their owners in the top-level
sibling list (they are not topmost). Child windows are confined to the
client area of their parent windows (client area is where window gets
to do its own drawing, non-client area consists of caption, menu, borders,
intrinsic scrollbars, and minimize/maximize/close/help buttons).
Another fairly important concept is "z-order". It is derived from
the ancestor/child hierarchy and is used to determine "above/below"
relationship. For instance, in the example above, z-order is
child1->popup->child2->child3->wnd1->child4->wnd2->desktop. Current
active window ("foreground window" in Win32) is moved to the front
of z-order unless its top-level ancestor owns popup windows.
All these issues are dealt with (or supposed to be) in windows/winpos.c
with SetWindowPos() being the primary interface to the window manager.
Wine specifics: in default and managed mode each top-level window
gets its own X counterpart with desktop window being basically a
fake stub. In desktop mode, however, only desktop window has an X
window associated with it. Also, SetWindowPos() should eventually be
implemented via Begin/End/DeferWindowPos() calls and not the other way
around.
1.1 Visible region, clipping region and update region
windows/dce.c
windows/winpos.c
windows/painting.c
________________________
|_________ | A and B are child windows of C
| A |______ |
| | | |
|---------' | |
| | B | |
| | | |
| `------------' |
| C |
`------------------------'
Visible region determines which part of the window is not obscured
by other windows. If a window has the WS_CLIPCHILDREN style then all
areas below its children are considered invisible. Similarily, if
the WS_CLIPSIBLINGS bit is in effect then all areas obscured by its
siblings are invisible. Child windows are always clipped by the
boundaries of their parent windows.
B has a WS_CLIPSIBLINGS style:
. ______
: | |
| ,-----' |
| | B | - visible region of B
| | |
: `------------'
When the program requests a display context (DC) for a window it
can specify an optional clipping region that further restricts the
area where the graphics output can appear. This area is calculated
as an intersection of the visible region and a clipping region.
Program asked for a DC with a clipping region:
______
,--|--. | . ,--.
,--+--' | | : _: |
| | B | | => | | | - DC region where the painting will
| | | | | | | be visible
`--|-----|---' : `----'
`-----'
When the window manager detects that some part of the window
became visible it adds this area to the update region of this
window and then generates WM_ERASEBKGND and WM_PAINT messages.
In addition, WM_NCPAINT message is sent when the uncovered area
intersects a nonclient part of the window. Application must reply
to the WM_PAINT message by calling BeginPaint()/EndPaint() pair of
functions. BeginPaint() returns a DC that uses accumulated update
region as a clipping region. This operation cleans up invalidated
area and the window will not receive another WM_PAINT until the
window manager creates a new update region.
A was moved to the left:
________________________ ... / C update region
|______ | : .___ /
| A |_________ | => | ...|___|..
| | | | | : | |
|------' | | | : '---'
| | B | | | : \
| | | | : \
| `------------' | B update region
| C |
`------------------------'
Windows maintains a display context cache consisting of entries that
include DC itself, window to which it belongs, and an optional clipping
region (visible region is stored in the DC itself). When an API call
changes the state of the window tree, window manager has to go through
the DC cache to recalculate visible regions for entries whose windows
were involved in the operation. DC entries (DCE) can be either private
to the window, or private to the window class, or shared between all
windows (Windows 3.1 limits the number of shared DCEs to 5).
1.2
2. Messaging subsystem
----------------------
windows/queue.c
windows/message.c
Each Windows task/thread has its own message queue - this is where
it gets messages from. Messages can be generated on the fly
(WM_PAINT, WM_NCPAINT, WM_TIMER), they can be created by the system
(hardware messages), they can be posted by other tasks/threads
(PostMessage), or they can be sent by other tasks/threads (SendMessage).
Message priority:
First the system looks for sent messages, then for posted messages,
then for hardware messages, then it checks if the queue has the
"dirty window" bit set, and, finally, it checks for expired
timers. See windows/message.c.
From all these different types of messages, only posted messages go
directly into the private message queue. System messages (even in
Win95) are first collected in the system message queue and then
they either sit there until Get/PeekMessage gets to process them
or, as in Win95, if system queue is getting clobbered, a special
thread ("raw input thread") assigns them to the private
queues. Sent messages are queued separately and the sender sleeps
until it gets a reply. Special messages are generated on the fly
depending on the window/queue state. If the window update region is
not empty, the system sets the QS_PAINT bit in the owning queue and
eventually this window receives a WM_PAINT message (WM_NCPAINT too
if the update region intersects with the non-client area). A timer
event is raised when one of the queue timers expire. Depending on
the timer parameters DispatchMessage either calls the callback
function or the window procedure. If there are no messages pending
the task/thread sleeps until messages appear.
There are several tricky moments (open for discussion) -
a) System message order has to be honored and messages should be
processed within correct task/thread context. Therefore when
Get/PeekMessage encounters unassigned system message and this
message appears not to be for the current task/thread it should
either skip it (or get rid of it by moving it into the private
message queue of the target task/thread - Win95, AFAIK) and
look further or roll back and then yield until this message
gets processed when system switches to the correct context
(Win16). In the first case we lose correct message ordering, in
the second case we have the infamous synchronous system message
queue. Here is a post to one of the OS/2 newsgroup I found to
be relevant:
" Here's the problem in a nutshell, and there is no good solution.
Every possible solution creates a different problem.
With a windowing system, events can go to many different windows.
Most are sent by applications or by the OS when things relating to
that window happen (like repainting, timers, etc.)
Mouse input events go to the window you click on (unless some window
captures the mouse).
So far, no problem. Whenever an event happens, you put a message on
the target window's message queue. Every process has a message
queue. If the process queue fills up, the messages back up onto the
system queue.
This is the first cause of apps hanging the GUI. If an app doesn't
handle messages and they back up into the system queue, other apps
can't get any more messages. The reason is that the next message in
line can't go anywhere, and the system won't skip over it.
This can be fixed by making apps have bigger private message queues.
The SIQ fix does this. PMQSIZE does this for systems without the SIQ
fix. Applications can also request large queues on their own.
Another source of the problem, however, happens when you include
keyboard events. When you press a key, there's no easy way to know
what window the keystroke message should be delivered to.
Most windowing systems use a concept known as "focus". The window
with focus gets all incoming keyboard messages. Focus can be changed
from window to window by apps or by users clicking on winodws.
This is the second source of the problem. Suppose window A has focus.
You click on window B and start typing before the window gets focus.
Where should the keystrokes go? On the one hand, they should go to A
until the focus actually changes to B. On the other hand, you
probably want the keystrokes to go to B, since you clicked there
first.
OS/2's solution is that when a focus-changing event happens (like
clicking on a window), OS/2 holds all messages in the system queue
until the focus change actually happens. This way, subsequent
keystrokes go to the window you clicked on, even if it takes a while
for that window to get focus.
The downside is that if the window takes a real long time to get focus
(maybe it's not handling events, or maybe the window losing focus
isn't handling events), everything backs up in the system queue and
the system appears hung.
There are a few solutions to this problem.
One is to make focus policy asynchronous. That is, focus changing has
absolutely nothing to do with the keyboard. If you click on a window
and start typing before the focus actually changes, the keystrokes go
to the first window until focus changes, then they go to the second.
This is what X-windows does.
Another is what NT does. When focus changes, keyboard events are held
in the system message queue, but other events are allowed through.
This is "asynchronous" because the messages in the system queue are
delivered to the application queues in a different order from that
with which they were posted. If a bad app won't handle the "lose
focus" message, it's of no consequence - the app receiving focus will
get its "gain focus" message, and the keystrokes will go to it.
The NT solution also takes care of the application queue filling up
problem. Since the system delivers messages asynchronously, messages
waiting in the system queue will just sit there and the rest of the
messages will be delivered to their apps.
The OS/2 SIQ solution is this: When a focus-changing event happens,
in addition to blocking further messages from the application queues,
a timer is started. When the timer goes off, if the focus change has
not yet happened, the bad app has its focus taken away and all
messages targetted at that window are skipped. When the bad app
finally handles the focus change message, OS/2 will detect this and
stop skipping its messages.
As for the pros and cons:
The X-windows solution is probably the easiest. The problem is that
users generally don't like having to wait for the focus to change
before they start typing. On many occasions, you can type and the
characters end up in the wrong window because something (usually heavy
system load) is preventing the focus change from happening in a timely
manner.
The NT solution seems pretty nice, but making the system message queue
asynchronous can cause similar problems to the X-windows problem.
Since messages can be delivered out of order, programs must not assume
that two messages posted in a particular order will be delivered in
that same order. This can break legacy apps, but since Win32 always
had an asynchronous queue, it is fair to simply tell app designers
"don't do that". It's harder to tell app designers something like
that on OS/2 - they'll complain "you changed the rules and our apps
are breaking."
The OS/2 solution's problem is that nothing happens until you try to
change window focus, and then wait for the timeout. Until then, the
bad app is not detected and nothing is done." (by David Charlap)
b) Intertask/interthread SendMessage. The system has to inform the
target queue about the forthcoming message, then it has to carry
out the context switch and wait until the result is available.
Win16 stores necessary parameters in the queue structure and then
calls DirectedYield() function. However, in Win32 there could be
several messages pending sent by preemptively executing threads,
and in this case SendMessage has to build some sort of message
queue for sent messages. Another issue is what to do with messages
sent to the sender when it is blocked inside its own SendMessage.

223
documentation/ioport-trace-hints
View File

@ -1,223 +0,0 @@
cat > /dev/null <<EOF
The above line is necessary, leave it alone!!
--------------------------------------------------------------------
DOING A HARDWARE TRACE IN WINE
------------------------------
The primary reason to do this is to reverse engineer a hardware device
for which you don't have documentation, but can get to work under Wine.
This lot is aimed at parallel port devices, and in particular parallel port
scanners which are now so cheap they are virtually being given away. The
problem is that few manufactures will release any programming information which
prevents drivers being written for Sane, and the traditional technique of using
DOSemu to produce the traces does not work as the scanners invariably only have
drivers for Windows.
Please note that I have not been able to get my scanner working properly (a
UMAX Astra 600P), but a couple of people have reported success with at least
the Artec AS6e scanner. I am not in the process of developing any driver nor do
I intend to, so don't bug me about it. My time is now spent writting programs
to set things like battery save options under Linux on Toshiba laptops, ans as
such I don't have any spare time for writting a driver for a parallel port
scanner etc.
Presuming that you have compiled and installed wine the first thing to do is is
to enable direct hardware access to your parallel port. To do this edit
wine.conf (usually in /usr/local/etc) and in the ports section add the
following two lines
read=0x378,0x379,0x37a,0x37c,0x77a
write=0x378,x379,0x37a,0x37c,0x77a
This adds the necessary access required for SPP/PS2/EPP/ECP parallel port on
LPT1. You will need to adjust these number accordingly if your parallel port is
on LPT2 or LPT0.
When starting wine use the following command line, where XXXX is the program
you need to run in order to access your scanner, and YYYY is the file your
trace will be stored in:
wine -debugmsg +io XXXX 2> >(sed 's/^[^:]*:io:[^ ]* //' > YYYY)
You will need large amounts of hard disk space (read hundreds of megabytes if
you do a full page scan), and for reasonable performance a really fast
processor and lots of RAM.
You might well find the log compression program that David Campbell
<campbell@torque.net> wrote helpfull in reducing the size of the log files.
This can be obtained by the following command:
sh ioport-trace-hints
This should extract shrink.c (which is located at the end of this file. Compile
the log compression program by:
cc shrink.c -o shrink
Use the shrink program to reduce the physical size of the raw log as follows:
cat log | shrink > log2
The trace has the basic form of
XXXX > YY @ ZZZZ:ZZZZ
where XXXX is the port in hexidecimal being accessed, YY is the data written
(or read) from the port, and ZZZZ:ZZZZ is the address in memory of the
instruction that accessed the port. The direction of the arrow indicates
whether the data was written or read from the port.
> data was written to the port
< data was read from the port
My basic tip for interperating these logs is to pay close attention to the
addresses of the IO instructions. There grouping and sometimes proximity should
reveal the presence of subroutines in the driver. By studying the different
versions you should be able to work them out. For example consider the
following section of trace from my UMAX Astra 600P
0x378 > 55 @ 0297:01ec
0x37a > 05 @ 0297:01f5
0x379 < 8f @ 0297:01fa
0x37a > 04 @ 0297:0211
0x378 > aa @ 0297:01ec
0x37a > 05 @ 0297:01f5
0x379 < 8f @ 0297:01fa
0x37a > 04 @ 0297:0211
0x378 > 00 @ 0297:01ec
0x37a > 05 @ 0297:01f5
0x379 < 8f @ 0297:01fa
0x37a > 04 @ 0297:0211
0x378 > 00 @ 0297:01ec
0x37a > 05 @ 0297:01f5
0x379 < 8f @ 0297:01fa
0x37a > 04 @ 0297:0211
0x378 > 00 @ 0297:01ec
0x37a > 05 @ 0297:01f5
0x379 < 8f @ 0297:01fa
0x37a > 04 @ 0297:0211
0x378 > 00 @ 0297:01ec
0x37a > 05 @ 0297:01f5
0x379 < 8f @ 0297:01fa
0x37a > 04 @ 0297:0211
As you can see their is a repeating structure starting at address 0297:01ec
that consists of four io access on the parallel port. Looking at it the first
io access writes a changing byte to the data port the second always writes the
byte 0x05 to the control port, then a value which always seems to 0x8f is read
from the status port at which point a byte 0x04 is written to the control port.
By studying this and other sections of the trace we can write a C routine that
emulates this, shown below with some macros to make reading/writing on the
parallel port easier to read.
#define r_dtr(x) inb(x)
#define r_str(x) inb(x+1)
#define r_ctr(x) inb(x+2)
#define w_dtr(x,y) outb(y, x)
#define w_str(x,y) outb(y, x+1)
#define w_ctr(x,y) outb(y, x+2)
/*
* Seems to be sending a command byte to the scanner
*
*/
int udpp_put(int udpp_base, unsigned char command)
{
int loop,value;
w_dtr(udpp_base, command);
w_ctr(udpp_base, 0x05);
for (loop=0;loop<10;loop++)
if (((value=r_str(udpp_base)) & 0x80)!=0x00) {
w_ctr(udpp_base, 0x04);
return value & 0xf8;
}
return (value & 0xf8) | 0x01;
}
For the UMAX Astra 600P only seven such routines exist (well 14 really, seven
for SPP and seven for EPP). Whether you choose to disassemble the driver at
this point to verify the routines is your own choice. If you do, the address
from the trace should help in locating them in the disassembly.
You will probably then find it useful to write a script/perl/C program to
analyse the logfile and decode them futher as this can reveal higher level
grouping of the low level routines. For example from the logs from my UMAX
Astra 600P when decoded futher reveal (this is a small snippet)
start:
put: 55 8f
put: aa 8f
put: 00 8f
put: 00 8f
put: 00 8f
put: c2 8f
wait: ff
get: af,87
wait: ff
get: af,87
end: cc
start:
put: 55 8f
put: aa 8f
put: 00 8f
put: 03 8f
put: 05 8f
put: 84 8f
wait: ff
From this it is easy to see that put routine is often grouped together in five
successive calls sending information to the scanner. Once these are understood
it should be possible to process the logs further to show the higher level
routines in an easy to see format. Once the highest level format that you
can derive from this process is understood, you then need to produce a
series of scans varying only one parameter between them, so you can
discover how to set the various parameters for the scanner.
Jonathan Buzzard
<jab@hex.prestel.co.uk>
--------------------------------------------------------------------
The following is the shrink.c program.
EOF
cat > shrink.c <<EOF
#include <stdio.h>
#include <string.h>
void
main (void)
{
char buff[256], lastline[256];
int count;
count = 0;
lastline[0] = 0;
while (!feof (stdin))
{
fgets (buff, sizeof (buff), stdin);
if (strcmp (buff, lastline) == 0)
{
count++;
}
else
{
if (count > 1)
fprintf (stdout, "# Last line repeated %i times #\n", count);
fprintf (stdout, "%s", buff);
strcpy (lastline, buff);
count = 1;
}
}
}
EOF

123
documentation/keyboard
View File

@ -1,123 +0,0 @@
Wine now needs to know about your keyboard layout. This requirement comes from
a need from many apps to have the correct scancodes available, since they read
these directly, instead of just taking the characters returned by the X server.
This means that Wine now needs to have a mapping from X keys to the scancodes
these applications expect.
On startup, Wine will try to recognize the active X layout by seeing if it
matches any of the defined tables. If it does, everything is allright. If not,
you need to define it.
To do this, open the file windows/x11drv/keyboard.c and take a look at the
existing tables. Make a backup copy of it, especially if you don't use CVS.
What you really would need to do, is to find out which scancode each key needs
to generate, find it in the main_key_scan table, which looks like this
static const int main_key_scan[MAIN_LEN] =
{
/* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D,
0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,
0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B,
0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
0x56 /* the 102nd key (actually to the right of l-shift) */
};
and then assign each scancode the characters imprinted on the keycaps. This
was done (sort of) for the US 101-key keyboard, which you can find near the
top in keyboard.c. It also shows that if there is no 102nd key, you can skip
that.
However, for most international 102-key keyboards, we have done it easy for you.
The scancode layout for these already pretty much matches the physical layout
in the main_key_scan, so all you need to do is to go through all the keys that
generate characters on your main keyboard (except spacebar), and stuff those
into an appropriate table. The only exception is that the 102nd key, which is
usually to the left of the first key of the last line (usually Z), must be
placed on a separate line after the last line.
For example, my Norwegian keyboard looks like this
§ ! " # ¤ % & / ( ) = ? ` Back-
| 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
Tab Q W E R T Y U I O P Å ^
¨~
Enter
Caps A S D F G H J K L Ø Æ *
Lock '
Sh- > Z X C V B N M ; : _ Shift
ift < , . -
Ctrl Alt Spacebar AltGr Ctrl
Note the 102nd key, which is the "<>" key, to the left of Z. The character
to the right of the main character is the character generated by AltGr.
This keyboard is defined as follows:
static const char main_key_NO[MAIN_LEN][4] =
{
"|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
"qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~",
"aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*",
"zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
"<>"
};
Except that " and \ needs to be quoted with a backslash, and that the 102nd
key is on a separate line, it's pretty straightforward.
After you have written such a table, you need to add it to the main_key_tab[]
layout index table. This will look like this:
static struct {
WORD lang, ansi_codepage, oem_codepage;
const char (*key)[MAIN_LEN][4];
} main_key_tab[]={
...
...
{MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
...
After you have added your table, recompile Wine and test that it works.
If it fails to detect your table, try running
wine -debugmsg +key,+keyboard >& key.log
and look in the resulting key.log file to find the error messages it
gives for your layout.
Note that the LANG_* and SUBLANG_* definitions are in include/winnls.h,
which you might need to know to find out which numbers your language
is assigned, and find it in the debugmsg output. The numbers will
be SUBLANG * 0x400 + LANG, so, for example the combination
LANG_NORWEGIAN (0x14) and SUBLANG_DEFAULT (0x1) will be (in hex)
14 + 1*400 = 414, so since I'm Norwegian, I could look for 0414 in
the debugmsg output to find out why my keyboard won't detect.
Once it works, submit it to the Wine project. If you use CVS, you
will just have to do
cvs -z3 diff -u windows/x11drv/keyboard.c > layout.diff
from your main Wine directory, then submit layout.diff to
wine-patches@winehq.com along with a brief note of what it is.
If you don't use CVS, you need to do
diff -u the_backup_file_you_made windows/x11drv/keyboard.c > layout.diff
and submit it as explained above.
If you did it right, it will be included in the next Wine release, and all
the troublesome applications (especially remote-control applications) and
games that use scancodes will be happily using your keyboard layout, and you
won't get those annoying fixme messages either.
Good luck.
-Ove Kåven <ovek@arcticnet.no>

82
documentation/languages
View File

@ -1,82 +0,0 @@
ADDING LANGUAGES TO WINE
This file documents the necessary procedure for adding a new language
to the list of languages that Wine can display system menus and forms
in. Currently at least the following languages are still missing:
Bulgarian, Chinese, Greek, Icelandic, Japanese, Romanian,
Croatian, Slovak, Turkish, and Slovanian.
To add a new language you need to be able to translate the relatively
few texts, of course. You will need very little knowledge of
programming, so you have almost no excuses for not adding your language,
right? We should easily be able to support 20 languages within a few
months, get going! Apart from re-compilation it'll take you about an
hour or two.
To add a new language to the list of languages that Wine can handle
you must...
0. Find the language ID in include/winnls.h .
1. Look in ole/ole2nls.c if your language is already incorporated in
the "static const struct NLS_langlocale". If not: find the
appropriate entries in include/winnls.h and add them to the list.
2. Edit the parameters defined in ole/nls/*.nls to fit your local
habits and language.
3. Edit documentation/wine.man.in (search for -language) to show the new
language abbreviation.
4. Edit misc/main.c variable "Languages" to contain the new language
abbreviation and language ID. Also edit struct "option_table" in
misc/options.c to show the new abbreviation.
5. Edit include/options.h enum "WINE_LANGUAGE" to have a member called
LANG_XX where XX is the new abbreviation.
6. Create a new file dlls/commdlg/cdlg_XX.rc (where XX is your language
abbreviation) containing all menus.
Your best bet is to copy cdlg_En.rc and start translating.
There is no real need to know how the internal structure of the file,
as you only need to translate the text within quotes.
In menus, the character "&" means that the next character will
be highlighted and that pressing that letter will select the item.
You should place these "&"s suitably for your language, not just
copy the positions from (say) English. In particular, items within
one menu should have different highlighted letters.
7. Edit dlls/commdlg/rsrc.rc to contain an include statement for your
cdlg_XX.rc file.
8. Repeat steps 6 and 7 again for:
- dlls/shell32/shell32_XX.rc and shres.rc
- resources/sysres_XX.rc and user32.rc
9. Re-configure, re-make dependencies, and re-make Wine.
10. Check your new menus and forms; when they're not ok,
go back to 6) and adapt the sizes, etc.
11. Several of the winelib based programs in the subdirectory programs
also have internationalisation support. See the appropriate files
there for reference.
12. Edit /documentation/internationalisation to show the new status.
13. Submit patches for inclusion in the next Wine release,
see file ./ANNOUNCE for details about where to submit.
January 1996
Morten Welinder
[I hope I got all the places where changes are needed. If you see any
place missing from the above list, submit a patch to this file please.
Also note that re-organization of the source code might change the list
of places.]
Therefore revised Februari 1999 by Klaas van Gend
Revised again May 23, 1999, Klaas van Gend
Updated May 26, 2000, Zoran Dzelajlija

137
documentation/linux-fat-permissions
View File

@ -1,137 +0,0 @@
This document describes how FAT and VFAT file system permissions work
in Linux with a focus on configuring them for Wine.
Introduction
------------
Linux is able to access DOS and Windows file systems using either the
FAT (older 8.3 DOS filesystems) or VFAT (newer Windows 95 or later
long filename filesystems) modules. Mounted FAT or VFAT filesystems
provide the primary means for which existing applications and their
data are accessed through Wine for dual boot (Linux + Windows)
systems.
Wine maps mounted FAT filesystems, such as "/c", to driver letters,
such as "c:", as indicated by the wine.conf file. The following
excerpt from a wine.conf file does this:
[Drive C]
Path=/c
Type=hd
Although VFAT filesystems are preferable to FAT filesystems for their
long filename support the term "FAT" will be used throughout the
remainder of this document to refer to FAT filesystems and their
derivatives. Also, "/c" will be used as the FAT mount point in
examples throughout this document.
Most modern Linux distributions either detect or allow existing FAT
file systems to be configured so that can be mounted, in a location
such as /c, 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:
~>cd /c
/c>ls -l
-rwxr-xr-x 1 root root 91 Oct 10 17:58 autoexec.bat
-rwxr-xr-x 1 root root 245 Oct 10 17:58 config.sys
drwxr-xr-x 41 root root 16384 Dec 30 1998 windows
where all the files are owned by "root", are in the "root" group and
are only writable by "root" (755 permissions). This is restrictive in
that it requires that Wine be run as root in order for applications to
be able to write to any part of the filesystem.
There three major approaches to overcoming the restrictive permissions
mentioned in the previous paragraph:
1) Run Wine as root
2) Mount the FAT filesystem with less restrictive permissions
3) Shadow the FAT filesystem by completely or partially copying it
Each approach will be discusses in the following "Running Wine as
root", "Mounting FAT filesystems" and "Shadowing FAT filesystems"
sections.
Running Wine as root
--------------------
Running Wine as root is the easiest and most thorough way of giving
applications that Wine runs unrestricted access to FAT files systems.
Running wine as root also allows applications to do things unrelated
to FAT filesystems, such as listening to ports that are less than
1024. Running Wine as root is dangerous since there is no limit to
what the application can do to the system.
Mounting FAT filesystems
------------------------
The FAT filesystem can be mounted with permissions less restrictive
than the default. This can be done by either changing the user that
mounts the FAT filesystem or by explicitly changing the permissions
that the FAT filesystem is mounted with. The permissions are
inherited from the process that mounts the FAT filesystem. Since the
process that mounts the FAT filesystem is usually a startup script
running as root the FAT filesystem inherits root's permissions. This
results in the files on the FAT filesystem having permissions similar
to files created by root. For example:
~>whoami
root
~>touch root_file
~>ls -l root_file
-rw-r--r-- 1 root root 0 Dec 10 00:20 root_file
which matches the owner, group and permissions of files seen on the
FAT filesystem except for the missing 'x's. The permissions on the
FAT filesystem can be changed by changing root's umask (unset
permissions bits). For example:
~>umount /c
~>umask
022
~>umask 073
~>mount /c
~>cd /c
/c>ls -l
-rwx---r-- 1 root root 91 Oct 10 17:58 autoexec.bat
-rwx---r-- 1 root root 245 Oct 10 17:58 config.sys
drwx---r-- 41 root root 16384 Dec 30 1998 windows
Mounting the FAT filesystem with a umask of 000 gives all users
complete control over the it.
Explicitly specifying the permissions of the FAT filesystem when it is
mounted provides additional control. There are three mount options
that are relevant to FAT permissions: "uid", "gid" and "umask". They
can each be specified when the filesystem is manually mounted. For
example:
~>umount /c
~>mount -o uid=500 -o gid=500 -o umask=002 /c
~>cd /c
/c>ls -l
-rwxrwxr-x 1 sle sle 91 Oct 10 17:58 autoexec.bat
-rwxrwxr-x 1 sle sle 245 Oct 10 17:58 config.sys
drwxrwxr-x 41 sle sle 16384 Dec 30 1998 windows
which gives "sle" complete control over /c. The options listed above
can be made permanent by adding them to the /etc/fstab file:
~>grep /c /etc/fstab
/dev/hda1 /c vfat uid=500,gid=500,umask=002,exec,dev,suid,rw 1 1
Note that the umask of 002 is common in the user private group file
permission scheme. On FAT file systems this umask assures that all
files are fully accessible by all users in the specified group (gid).
Shadowing FAT filesystems
-------------------------
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 parts. This is done with symbolic links.
For example, consider a system where an application named "AnApp" must
be able to read and write to the c:\windows and c:\AnApp directories
as well as have read access to the entire FAT filesystem. On this
system the FAT filesystem has default permissions which should not be
changed for security reasons or can not be changed due to lack of root
access. On this system a shadow directory might be set up in the
following manner:
~>cd /
/>mkdir c_shadow
/>cd c_shadow
/c_shadow>ln -s /c_/* .
/c_shadow>rm windows AnApp
/c_shadow>cp -R /c_/{windows,AnApp} .
/c_shadow>chmod -R 777 windows AnApp
/c_shadow>perl -p -i -e 's|/c$|/c_shadow|g' /usr/local/etc/wine.conf
The above gives everyone complete read and write access to the
"windows" and "AnApp" directories while only root has write access to
all other directories.
---
Steven Elliott (elliotsl@mindspring.com)

68
documentation/no-windows
View File

@ -1,68 +0,0 @@
Wine without Windows
====================
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 provided with Windows.
Therefore, once Wine is finished, you will not need to have windows
installed to use Wine.
Wine has already made enough progress that it may be possible to run
your target applications without Windows installed. If you want to try
it, follow these steps:
1. Create empty C:\windows, C:\windows\system, C:\windows\Start Menu,
and C:\windows\Start Menu\Programs directories.
Do not point Wine to a Windows directory full of old installations
and a messy registry. (Wine creates a special registry in your home
directory, in $HOME/.wine/*.reg. Perhaps you have to remove these
files).
2. Point [Drive C] in wine.conf or .winerc to where you want C: to be.
Refer to the Wine man page for more information. Remember to use
filesystem=win95 !
3. Use tools/wineinstall to compile Wine and install the default
registry. Or if you prefer to do it yourself, compile programs/regapi,
and run: programs/regapi/regapi setValue < winedefault.reg
4. Run and/or install your applications.
Because Wine is not yet complete, some programs will work better
with native Windows DLL's 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 C:\windows
directory in the configuration file does not point to a native Windows
installation but is in a separate Unix file system. (For instance,
"C:\windows" is really subdirectory "windows" located in
"/home/ego/wine/drives/c").
- Run the application with --debugmsg +module,+file to find out
which files are needed. Copy the required DLL's one by one to the
C:\windows\system directory. Do not copy KERNEL/KERNEL32, GDI/GDI32,
or USER/USER32. These implement the core functionality of the
Windows API, and the Wine internal versions must be used.
- Edit the [DllOverrides] section of wine.conf or .winerc to specify
'native' before 'builtin' for the Windows DLL's you want to use.
For more information about this, see the Wine manpage.
- Note that some network DLL's are not needed even though Wine is
looking for them. The Windows MPR.DLL currently does not work; you
must use the internal implementation.
- Copy SHELL/SHELL32 and COMDLG/COMDLG32 COMMCTRL/COMCTL32
only as pairs to your Wine directory (these DLL's are
"clean" to use). Make sure you have these specified in the
[DllPairs] section of wine.conf or .winerc.
- Be consistent: Use only DLL's from the same Windows version
together.
- Put regedit.exe in the C:\windows directory (office95 imports
a *.reg file when it runs with a empty registry, don't know
about office97).
- Also add winhelp.exe and winhlp32.exe if you want to be able to browse
through your programs' help function.

270
documentation/opengl
View File

@ -1,270 +0,0 @@
I What is needed to have OpenGL support in Wine
===============================================
Basically, if you have a Linux OpenGL ABI compliant libGL
(http://oss.sgi.com/projects/ogl-sample/ABI/) installed on your
computer, you should everything that is needed.
To be more clear, I will detail one step after another what the
configure script checks.
If, after Wine compiles, OpenGL support is not compiled in, you can
always check 'config.log' to see which of the following points failed.
I.1 Header files
----------------
The needed header files to build OpenGL support in Wine are :
- gl.h : the definition of all OpenGL core functions, types and
enumerants
- glx.h : how OpenGL integrates in the X Window environment
- glext.h : the list of all registered OpenGL extensions
The latter file (glext.h) is, as of now, not necessary to build
Wine. But as this file can be easily obtained from SGI
(http://oss.sgi.com/projects/ogl-sample/ABI/glext.h), and that all
OpenGL should provide one, I decided to keep it here.
I.2 OpenGL library thread-safety
--------------------------------
After that, the script checks if the OpenGL library relies or not on
the pthread library to provide thread safety (most 'modern' OpenGL
libraries do).
If the OpenGL library explicitely links in libpthread (you can check
it with a 'ldd libGL.so'), you need to force OpenGL support by
starting configure with the '--enable-opengl' flag.
The reason to this is that Wine contains some hacks done by Ove to
cohabit with pthread that are known to work well in most of the cases
(glibc 2.1.x). On the other hand, we never got Wine to work with glibc
2.0.6. Thus, I deemed preferable to play it safe : by default, I
suppose that the hack won't work and that it's the user's
responsability to enable it.
Anyway, it should be pretty safe to build with '--enable-opengl'.
I.3 OpenGL library itself
-------------------------
To check for the presence of 'libGL' on the system, the script checks
if it defines the 'glXCreateContext' function. There should be no
problem here.
I.4 glXGetProcAddressARB function
---------------------------------
The core of Wine's OpenGL implementation (at least for all extensions)
is the glXGetProcAddressARB function. Your OpenGL library needs to
have this function defined for Wine to be able to support OpenGL.
If your library does not provide it, you are out of luck.
(Note: this is not completely true as one could rewrite a
glXGetProcAddressARB replacement using 'dlopen' and friends,
but well, telling people to upgrade is easier :-) ).
II How to configure
===================
Configuration is quite easy : once OpenGL support has been built in
Wine, this internal OpenGL driver will be used each time an
application tries to load 'opengl32.dll'.
Due to restrictions (that do not exist in Windows) on OpenGL contexts,
if you want to prevent the screen to flicker when using OpenGL
applications (all games are using double-buffered contexts), you need
to set the following option in your .winerc / wine.ini in the [x11drv]
section :
DesktopDoubleBuffered = Y
and to run Wine with the '--desktop' option.
III How it all works
====================
The core OpenGL function calls are the same between Windows and
Linux. So what is the difficulty to support it in Wine ? Well, there
is two different problems :
- the interface to the windowing system is different for each
OS. It's called 'GLX' for Linux (well, for X Window) and 'wgl' for
Windows. Thus, one need first to emulate one (wgl) with the other
(GLX).
- the calling convention between Windows (the 'Pascal' convention or
'stdcall') is different from the one used on Linux (the 'C'
convention or 'cdecl'). This means that each call to an OpenGL
function must be 'translated' and cannot be used directly by the
Windows program.
Add to this some braindead programs (using GL calls without setting-up
a context or deleting three time the same context) and you have still
some work to do :-)
III.1 The Windowing system integration
--------------------------------------
This integration is done at two levels :
- at GDI level for all pixel format selection routines (ie choosing
if one wants a depth / alpha buffer, the size of these buffers,
...) and to do the 'page flipping' in double buffer mode. This is
implemented in 'graphics/x11drv/opengl.c' (all these functions are
part of Wine's graphic driver function pointer table and thus could
be reimplented if ever Wine works on another Windowing system than
X).
- in the OpenGL32.DLL itself for all other functionalities (context
creation / deletion, querying of extension functions, ...). This is
done in 'dlls/opengl32/wgl.c'.
III.2 The thunks
----------------
The thunks are the Wine code that does the calling convention
translation and they are auto-generated by a Perl script. In Wine's
CVS tree, these thunks are already generated for you. Now, if you want
to do it yourself, there is how it all works....
The script is located in dlls/opengl32 and is called 'make_opengl'. It
requires Perl5 to work and takes two arguments :
- the first is the path to the OpenGL registry. Now, you will all ask
'but what is the OpenGL registry ?' :-) Well, it's part of the
OpenGL sample implementation source tree from SGI (more
informations at this URL : http://oss.sgi.com/projects/ogl-sample/).
To summarize, these files contains human-readable but easily parsed
informations on ALL OpenGL core functions and ALL registered
extensions (for example the prototype, the OpenGL version, ...).
- the second is the OpenGL version to 'simulate'. This fixes the list
of functions that the Windows application can link directly to
without having to query them from the OpenGL driver. Windows is
based, for now, on OpenGL 1.1, but the thunks that are in the CVS
tree are generated for OpenGL 1.2.
This option can have three values '1.0', '1.1' and '1.2'.
This script generates three files :
- opengl32.spec gives Wine's linker the signature of all function in
the OpenGL32.DLL library so that the application can link
them. Only 'core' functions are listed here.
- opengl_norm.c contains all the thunks for the 'core'
functions. Your OpenGL library must provide ALL the function used
in this file as these are not queried at run time.
- opengl_ext.c contains all the functions that are not part of the
'core' functions. Contrary to the thunks in opengl_norm.c, these
functions do not depend at all on what your libGL provides.
In fact, before using one of these thunks, the Windows program
first needs to 'query' the function pointer. At this point, the
corresponding thunk is useless. But as we first query the same
function in libGL and store the returned function pointer in the
thunk, the latter becomes functional.
IV Known problems - shortcomings
=================================
IV.1 Missing GLU32.DLL
----------------------
GLU is a library that is layered upon OpenGL. There is a 100 %
corespondance between the libGLU.so that is used on Linux and
GLU32.DLL.
As for the moment, I did not create a set of thunks to support this
library natively in Wine (it would easy to do, but I am waiting for a
better solution than adding another autogenerated thunk file), you can
always download anywhere on the net (it's free) a GLU32.DLL file (by
browsing, for example, http://ftpsearch.lycos.com/).
IV.2 OpenGL not detected at configure time
------------------------------------------
See section (I) for a detailed explanation of the configure
requirements.
IV.3 When running an OpenGL application, the screen flickers
------------------------------------------------------------
See section (II) for how to create the context double-buffered and
thus preventing this flicker effect.
IV.4 Wine gives me the following error message :
------------------------------------------------
Extension defined in the OpenGL library but NOT in opengl_ext.c... Please report
(lionel.ulmer@free.fr) !
This means that the extension requested by the application is found in
the libGL used by Linux (ie the call to glXGetProcAddressARB returns a
non NULL pointer) but that this string was NOT found in Wine's
extension registry.
This can come from two causes :
- the opengl_ext.c file is too old and need to be generated again.
- use of obsolete extensions that are not supported anymore by SGI or
of 'private' extensions that are not registered. An example of the
former are 'glMTexCoord2fSGIS' and 'glSelectTextureSGIS' as used by
Quake 2 (and apparently also by old versions of Half Life). If
documentation can be found on these functions, they can be added to
Wine's extension set.
If you have this, run with --debugmsg +opengl and send me
(lionel.ulmer@free.fr) the TRACE.
IV.5 libopengl32.so is built but it is still not working
--------------------------------------------------------
This may be caused by some missing functions required by opengl_norm.c
but that your Linux OpenGL library does not provide.
To check for this, do the following steps :
- create a dummy .c file :
int main(void) {
return 0;
}
- try to compile it by linking both libwine and libopengl32 (this
command line supposes that you installed the Wine libraries in
/usr/local/lib, YMMV) :
gcc dummy.c -L/usr/local/lib -lwine -lopengl32
- if it works, the problem is somewhere else (and you can send me an
email). If not, you could re-generate the thunk files for OpenGL
1.1 for example (and send me your OpenGL version so that this
problem can be detected at configure time).
Lionel Ulmer (lionel.ulmer@free.fr)
last modification : 2000/06/13

458
documentation/opengl.sgml Normal file
View File

@ -0,0 +1,458 @@
<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>
(Extracted from <filename>wine/documentation/opengl</filename>)
</para>
<sect1 id="opengl-required">
<title>I What is needed to have OpenGL support in Wine</title>
<para>
Basically, if you have a Linux OpenGL ABI compliant libGL
(<ulink url="http://oss.sgi.com/projects/ogl-sample/ABI/">
http://oss.sgi.com/projects/ogl-sample/ABI/</ulink>)
installed on your computer, you should everything that is
needed.
</para>
<para>
To be more clear, I will detail one step after another what
the <command>configure</command> script checks.
</para>
<para>
If, after Wine compiles, OpenGL support is not compiled in,
you can always check <filename>config.log</filename> to see
which of the following points failed.
</para>
<sect2>
<title>I.1 Header files</title>
<para>
The needed header files to build OpenGL support in Wine are :
</para>
<variablelist>
<varlistentry>
<term><filename>gl.h:</filename></term>
<listitem>
<para>the definition of all OpenGL core functions, types and enumerants</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>glx.h:</filename></term>
<listitem>
<para>how OpenGL integrates in the X Window environment</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>glext.h:</filename></term>
<listitem>
<para>the list of all registered OpenGL extensions</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The latter file (<filename>glext.h</filename>) is, as of
now, not necessary to build Wine. But as this file can be
easily obtained from SGI
(<ulink url="http://oss.sgi.com/projects/ogl-sample/ABI/glext.h">
http://oss.sgi.com/projects/ogl-sample/ABI/glext.h</ulink>),
and that all OpenGL should provide one, I decided to keep it here.
</para>
</sect2>
<sect2>
<title>I.2 OpenGL library thread-safety</title>
<para>
After that, the script checks if the OpenGL library relies
or not on the pthread library to provide thread safety (most
'modern' OpenGL libraries do).
</para>
<para>
If the OpenGL library explicitely links in libpthread (you
can check it with a <command>ldd libGL.so</command>), you
need to force OpenGL support by starting
<command>configure</command> with the
<parameter>--enable-opengl</parameter> flag.
</para>
<para>
The reason to this is that Wine contains some hacks done by
Ove to cohabit with pthread that are known to work well in
most of the cases (glibc 2.1.x). On the other hand, we never
got Wine to work with glibc 2.0.6. Thus, I deemed preferable
to play it safe : by default, I suppose that the hack won't
work and that it's the user's responsability to enable it.
</para>
<para>
Anyway, it should be pretty safe to build with
<parameter>--enable-opengl</parameter>.
</para>
</sect2>
<sect2>
<title>I.3 OpenGL library itself</title>
<para>
To check for the presence of 'libGL' on the system, the
script checks if it defines the
<function>glXCreateContext</function> function. There should
be no problem here.
</para>
</sect2>
<sect2>
<title>I.4 glXGetProcAddressARB function</title>
<para>
The core of Wine's OpenGL implementation (at least for all
extensions) is the <function>glXGetProcAddressARB</function>
function. Your OpenGL library needs to have this function
defined for Wine to be able to support OpenGL.
</para>
<para>
If your library does not provide it, you are out of luck.
</para>
<note>
<para>
this is not completely true as one could rewrite a
<function>glXGetProcAddressARB</function> replacement
using <function>dlopen</function> and friends, but well,
telling people to upgrade is easier :-).
</para>
</note>
</sect2>
</sect1>
<sect1 id="opengl-configure">
<title>II How to configure</title>
<para>
Configuration is quite easy : once OpenGL support has been
built in Wine, this internal OpenGL driver will be used each
time an application tries to load
<filename>opengl32.dll</filename>.
</para>
<para>
Due to restrictions (that do not exist in Windows) on OpenGL
contexts, if you want to prevent the screen to flicker when
using OpenGL applications (all games are using double-buffered
contexts), you need to set the following option in your
<filename>.winerc</filename> / <filename>wine.ini</filename>
in the [x11drv] section :
</para>
<programlisting>
DesktopDoubleBuffered = Y
</programlisting>
<para>
and to run Wine with the <parameter>--desktop</parameter>
option.
</para>
</sect1>
<sect1 id="opengl-works">
<title>III How it all works</title>
<para>
The core OpenGL function calls are the same between Windows
and Linux. So what is the difficulty to support it in Wine ?
Well, there are two different problems :
</para>
<orderedlist>
<listitem>
<para>
the interface to the windowing system is different for
each OS. It's called 'GLX' for Linux (well, for X Window)
and 'wgl' for Windows. Thus, one need first to emulate one
(wgl) with the other (GLX).
</para>
</listitem>
<listitem>
<para>
the calling convention between Windows (the 'Pascal'
convention or 'stdcall') is different from the one used on
Linux (the 'C' convention or 'cdecl'). This means that
each call to an OpenGL function must be 'translated' and
cannot be used directly by the Windows program.
</para>
</listitem>
</orderedlist>
<para>
Add to this some braindead programs (using GL calls without
setting-up a context or deleting three time the same context)
and you have still some work to do :-)
</para>
<sect2>
<title>III.1 The Windowing system integration</title>
<para>
This integration is done at two levels :
</para>
<orderedlist>
<listitem>
<para>
At GDI level for all pixel format selection routines (ie
choosing if one wants a depth / alpha buffer, the size
of these buffers, ...) and to do the 'page flipping' in
double buffer mode. This is implemented in
<filename>graphics/x11drv/opengl.c</filename> (all these
functions are part of Wine's graphic driver function
pointer table and thus could be reimplented if ever Wine
works on another Windowing system than X).
</para>
</listitem>
<listitem>
<para>
In the <filename>OpenGL32.DLL</filename> itself for all
other functionalities (context creation / deletion,
querying of extension functions, ...). This is done in
<filename>dlls/opengl32/wgl.c</filename>.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>III.2 The thunks</title>
<para>
The thunks are the Wine code that does the calling
convention translation and they are auto-generated by a Perl
script. In Wine's CVS tree, these thunks are already
generated for you. Now, if you want to do it yourself, there
is how it all works....
</para>
<para>
The script is located in <filename>dlls/opengl32</filename>
and is called <command>make_opengl</command>. It requires
Perl5 to work and takes two arguments :
</para>
<orderedlist>
<listitem>
<para>
The first is the path to the OpenGL registry. Now, you
will all ask 'but what is the OpenGL registry ?' :-)
Well, it's part of the OpenGL sample implementation
source tree from SGI (more informations at this URL :
<ulink url="http://oss.sgi.com/projects/ogl-sample/">
http://oss.sgi.com/projects/ogl-sample/</ulink>.
</para>
<para>
To summarize, these files contain human-readable but
easily parsed information on ALL OpenGL core functions
and ALL registered extensions (for example the
prototype, the OpenGL version, ...).
</para>
</listitem>
<listitem>
<para>
the second is the OpenGL version to 'simulate'. This
fixes the list of functions that the Windows application
can link directly to without having to query them from
the OpenGL driver. Windows is based, for now, on OpenGL
1.1, but the thunks that are in the CVS tree are
generated for OpenGL 1.2.
</para>
<para>
This option can have three values:
<literal>1.0</literal>, <literal>1.1</literal> and
<literal>1.2</literal>.
</para>
</listitem>
</orderedlist>
<para>
This script generates three files :
</para>
<orderedlist>
<listitem>
<para>
<filename>opengl32.spec</filename> gives Wine's linker
the signature of all function in the
<filename>OpenGL32.DLL</filename> library so that the
application can link them. Only 'core' functions are
listed here.
</para>
</listitem>
<listitem>
<para>
<filename>opengl_norm.c</filename> contains all the
thunks for the 'core' functions. Your OpenGL library
must provide ALL the function used in this file as these
are not queried at run time.
</para>
</listitem>
<listitem>
<para>
<filename>opengl_ext.c</filename> contains all the
functions that are not part of the 'core' functions.
Contrary to the thunks in
<filename>opengl_norm.c</filename>, these functions do
not depend at all on what your libGL provides.
</para>
<para>
In fact, before using one of these thunks, the Windows
program first needs to 'query' the function pointer. At
this point, the corresponding thunk is useless. But as
we first query the same function in libGL and store the
returned function pointer in the thunk, the latter
becomes functional.
</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
<sect1 id="opengl-problems">
<title>IV Known problems - shortcomings</title>
<sect2>
<title>IV.1 Missing GLU32.DLL</title>
<para>
GLU is a library that is layered upon OpenGL. There is a
100% correspondence between the
<filename>libGLU.so</filename> that is used on Linux and
<filename>GLU32.DLL</filename>.
</para>
<para>
As for the moment, I did not create a set of thunks to support this
library natively in Wine (it would easy to do, but I am waiting for
a better solution than adding another autogenerated thunk file), you
can always download anywhere on the net (it's free) a
<filename>GLU32.DLL</filename> file (by browsing, for example,
<ulink url="http://ftpsearch.lycos.com/">
http://ftpsearch.lycos.com/</ulink>).
</para>
</sect2>
<sect2>
<title>IV.2 OpenGL not detected at configure time</title>
<para>
See section (I) for a detailed explanation of the
<filename>configure</filename> requirements.
</para>
</sect2>
<sect2>
<title>IV.3 When running an OpenGL application, the screen flickers</title>
<para>
See section (II) for how to create the context
double-buffered and thus preventing this flicker effect.
</para>
</sect2>
<sect2>
<title>IV.4 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) !
</screen>
<para>
This means that the extension requested by the application
is found in the libGL used by Linux (ie the call to
<function>glXGetProcAddressARB</function> returns a
non-<constant>NULL</constant> pointer) but that this string
was NOT found in Wine's extension registry.
</para>
<para>
This can come from two causes :
</para>
<orderedlist>
<listitem>
<para>
The <filename>opengl_ext.c</filename> file is too old
and needs to be generated again.
</para>
</listitem>
<listitem>
<para>
Use of obsolete extensions that are not supported
anymore by SGI or of 'private' extensions that are not
registered. An example of the former are
<function>glMTexCoord2fSGIS</function> and
<function>glSelectTextureSGIS</function> as used by
Quake 2 (and apparently also by old versions of Half
Life). If documentation can be found on these functions,
they can be added to Wine's extension set.
</para>
</listitem>
</orderedlist>
<para>
If you have this, run with <parameter>--debugmsg
+opengl</parameter> and send me
<email>lionel.ulmer@free.fr</email> the TRACE.
</para>
</sect2>
<sect2>
<title>IV.5 <filename>libopengl32.so</filename> is built but it is still not working</title>
<para>
This may be caused by some missing functions required by
<filename>opengl_norm.c</filename> but that your Linux
OpenGL library does not provide.
</para>
<para>
To check for this, do the following steps :
</para>
<orderedlist>
<listitem>
<para>
create a dummy <filename>.c</filename> file :
</para>
<programlisting>
int main(void) {
return 0;
}
</programlisting>
</listitem>
<listitem>
<para>
try to compile it by linking both libwine and
libopengl32 (this command line supposes that you
installed the Wine libraries in
<filename>/usr/local/lib</filename>, YMMV) :
</para>
<programlisting>
gcc dummy.c -L/usr/local/lib -lwine -lopengl32
</programlisting>
</listitem>
<listitem>
<para>
if it works, the problem is somewhere else (and you can
send me an email). If not, you could re-generate the
thunk files for OpenGL 1.1 for example (and send me your
OpenGL version so that this problem can be detected at
configure time).
</para>
</listitem>
</orderedlist>
</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" "")
End:
-->

760
documentation/packaging.sgml Normal file
View File

@ -0,0 +1,760 @@
<chapter id="packaging">
<title>Packaging Wine</title>
<sect1 id="distributing">
<title>A Small WINE Distribution Guide</title>
<para>
written by Marcus Meissner &lt;Marcus.Meissner@caldera.de>
</para>
<para>
(Extracted from <filename>wine/documentation/distributors</filename>)
</para>
<para>
While packaging WINE for one of the Linux distributions I came
across several points which have not been clarified yet.
Particularly a how-to for WINE packaging distributors is
missing. This document tries to give a brief overview over the
rationales I thought up and how I tried to implement it.
(While the examples use <command>rpm</command> most of this
stuff can be applied to other packagers too.)
</para>
<note>
<para>
YOU SHOULD RECHECK THIS FILE EVERY TWO MONTHS OR SO
(<command>diff -uN</command> comes to my mind here...).
We'll be adding stuff constantly here in order to improve
the Wine environment !
</para>
</note>
<orderedlist>
<listitem>
<para>Rationales</para>
<para>
A WINE install should:
</para>
<itemizedlist>
<listitem>
<para>Not have a world writeable directory (-tree).</para>
</listitem>
<listitem>
<para>
Require only as much user input as needed. It would be
very good if it would not require any at all. Just let
the system administrator do <command>rpm -i
wine.rpm</command> and let any user be able to run
<command>wine sol.exe</command> instantly.
</para>
</listitem>
<listitem>
<para>
Give the user as much flexibility as possible to
install his own applications, do his own configuring
etc.
</para>
</listitem>
<listitem>
<para>
Come as preconfigured as possible, so the user does
not need to change any configuration files.
</para>
</listitem>
<listitem>
<para>Use only as much diskspace as needed per user.</para>
</listitem>
</itemizedlist>
<para>
A WINE install needs:
</para>
<itemizedlist>
<listitem>
<para>
A writeable <filename>C:\</filename> directory
structure on a per user basis. Applications do dump
<filename>.ini</filename> files into
<filename>c:\windows</filename>, installers dump
<filename>.exe</filename>, <filename>.dll</filename>
and more into <filename>c:\windows\</filename> and
subdirectories or into <filename>C:\Program
Files\</filename>.
</para>
</listitem>
<listitem>
<para>
The <filename>.exe</filename> and
<filename>.dll</filename> from a global read-only
Windows installation to be found by applications.
</para>
</listitem>
<listitem>
<para>
Some special <filename>.dll</filename> and
<filename>.exe</filename> files in the
<filename>windows\system</filename> directory, since
applications directly check for their presence.
</para>
</listitem>
<listitem>
<para>Some special program environment.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Implementation</para>
<orderedlist inheritnum="inherit">
<listitem>
<para>Building the package</para>
<para>
WINE is configured the usual way (depending on your
build environment). The "prefix" is chosen using your
application placement policy
(<filename>/usr/</filename>,
<filename>/usr/X11R6/</filename>,
<filename>/opt/wine/</filename> or similar). The
configuration files (<filename>wine.conf</filename>,
<filename>wine.userreg</filename>,
<filename>wine.systemreg</filename>) are targeted for
<filename>/etc/wine/</filename> (rationale: FHS 2.0,
multiple readonly configuration files of a package).
</para>
<para>
Example (split this into <literal>%build</literal> and
<literal>%install</literal> section for
<command>rpm</command>):
</para>
<screen>
CFLAGS=$RPM_OPT_FLAGS \
./configure --prefix=/usr/X11R6 --sysconfdir=/etc/wine/ --enable-dll
make
BR=$RPM_BUILD_ROOT
make install prefix=$BR/usr/X11R6/ sysconfdir=$BR/etc/wine/
install -d $BR/etc/wine/
install -m 644 wine.ini $BR/etc/wine/wine.conf
# Put all our dlls in a seperate directory. (this works only if
# you have a buildroot)
install -d $BR/usr/X11R6/lib/wine
mv $BR/usr/X11R6/lib/lib* $BR/usr/X11R6/lib/wine/
# the clipboard server is started on demand.
install -m 755 windows/x11drv/wineclipsrv $BR/usr/X11R6/bin/
# The WINE server is needed.
install -m 755 server/wineserver $BR/usr/X11R6/bin/
</screen>
<para>
Here we unfortunately do need to create
<filename>wineuser.reg</filename> and
<filename>winesystem.reg</filename> from the WINE
distributed <filename>winedefault.reg</filename>. This
can be done using <command>./regapi</command> once for
one example user and then reusing his
<filename>.wine/user.reg</filename> and
<filename>.wine/system.reg</filename> files.
<note>
<title>FIXME</title>
<para>this needs to be done better</para>
</note>
</para>
<screen>
install -m 644 wine.sytemreg $BR/etc/wine/
install -m 644 wine.userreg $BR/etc/wine/
</screen>
<para>
There are now a lot of libraries generated by the
build process, so a seperate library directory should
be used.
</para>
<screen>
install -d 755 $BR/usr/X11R6/lib/
mv $BR/
</screen>
<para>
You will need to package the files:
</para>
<screen>
$prefix/bin/wine, $prefix/bin/dosmod, $prefix/lib/wine/*
$prefix/man/man1/wine.1, $prefix/include/wine/*,
$prefix/bin/wineserver, $prefix/bin/wineclipsrv
%config /etc/wine/*
%doc ... choose from the toplevel directory and documentation/
</screen>
<para>
The post-install script:
</para>
<screen>
if ! grep -q /usr/X11R6/lib/wine /etc/ld.so.conf; then
echo "/usr/X11R6/lib/wine" &gt;&gt; /etc/ld.so.conf
fi
/sbin/ldconfig
</screen>
<para>
The post-uninstall script:
</para>
<screen>
if [ "$1" = 0 ]; then
perl -ni -e 'print unless m:/usr/X11R6/lib/wine:;' /etc/ld.so.conf
fi
/sbin/ldconfig
</screen>
</listitem>
<listitem>
<para>Creating a good default configuration file</para>
<para>
For the rationales of needing as less input from the
user as possible arises the need for a very good
configuration file. The one supplied with WINE is
currently lacking. We need:
</para>
<itemizedlist>
<listitem>
<para>
[Drive X]:
</para>
<itemizedlist>
<listitem>
<para>
A for the floppy. Specify your distributions
default floppy mountpoint here.
</para>
<programlisting>
Path=/auto/floppy
</programlisting>
</listitem>
<listitem>
<para>
C for the <filename>C:\</filename> directory.
Here we use the users homedirectory, for most
applications do see <filename>C:\</filename>
as root-writeable directory of every windows
installation and this basically is it in the
UNIX-user context.
</para>
<programlisting>
Path=${HOME}
</programlisting>
</listitem>
<listitem>
<para>
R for the CD-Rom drive. Specify your
distributions default CD-ROM drives mountpoint
here.
</para>
<programlisting>
Path=/auto/cdrom
</programlisting>
</listitem>
<listitem>
<para>
T for temporary storage. We do use
<filename>/tmp/</filename> (rationale: between
process temporary data belongs to
<filename>/tmp/</filename>, FHS 2.0)
</para>
</listitem>
<listitem>
<para>
W for the original Windows installation. This
drive points to the
<filename>windows\</filename> subdirectory of
the original windows installation. This avoids
problems with renamed
<filename>windows</filename> directories (as
for instance <filename>lose95</filename>,
<filename>win</filename> or
<filename>sys\win95</filename>). During
compile/package/install we leave this to be
<filename>/</filename>, it has to be
configured after the package install.
</para>
</listitem>
<listitem>
<para>
Z for the UNIX Root directory. This avoids any
problems with "could not find drive for
current directory" users occasionaly complain
about in the newsgroup and the ircchannel. It
also makes the whole directory structure
browseable. The type of Z should be network,
so applications expect it to be readonly.
</para>
<programlisting>
Path=/
</programlisting>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
[wine]:
</para>
<screen>
Windows=c:\windows\ (the windows/ subdirectory in the users
homedirectory)
System=c:\windows\system\ (the windows/system subdirectory in the users
homedirectory)
Path=c:\windows;c:\windows\system;c:\windows\system32;w:\;w:\system;w:\system32;
; Using this trick we have in fact two windows installations in one, we
; get the stuff from the readonly installation and can write to our own.
Temp=t:\ (the TEMP directory)
</screen>
</listitem>
<listitem>
<para>[Tweak.Layout]</para>
<screen>
WineLook=win95 (just the coolest look ;)
</screen>
</listitem>
<listitem>
<para>
Possibly modify the [spooler], [serialports] and
[parallelports] sections.
</para>
<note>
<title>FIXME</title>
<para>possibly more, including printer stuff.</para>
</note>
</listitem>
</itemizedlist>
<para>Add this prepared configuration file to the package.</para>
</listitem>
<listitem>
<para>Installing WINE for the system administrator</para>
<para>
Install the package using the usual packager
<command>rpm -i wine.rpm</command>. You may edit
<filename>/etc/wine/wine.conf</filename>, [Drive W],
to point to a possible windows installation right
after the install. That's it.
</para>
<para>
Note that on Linux you should somehow try to add the
<option>unhide</option> mount option (see <command>man
mount</command>) to the CD-ROM entry in
<filename>/etc/fstab</filename> during package
install, as several stupid Windows programs mark some
setup (!) files as hidden (ISO9660) on CD-ROMs, which
will greatly confuse users as they won't find their
setup files on the CD-ROMs as they were used on
Windows systems when <option>unhide</option> is not
set ;-\ And of course the setup program will complain
that <filename>setup.ins</filename> or some other mess
is missing... If you choose to do so, then please make
this change verbose to the admin.
</para>
</listitem>
<listitem>
<para>Installing WINE for the user</para>
<para>
The user will need to run a setup script before the
first invocation of WINE. This script should:
</para>
<itemizedlist>
<listitem>
<para>
Copy <filename>/etc/wine/wine.conf</filename> for
user modification.
</para>
</listitem>
<listitem>
<para>
Allow specification of the original windows
installation to use (which modifies the copied
<filename>wine.conf</filename> file).
</para>
</listitem>
<listitem>
<para>
Create the windows directory structure
(<filename>c:\windows</filename>,
<filename>c:\windows\system</filename>,
<filename>c:\windows\Start Menu\Programs</filename>,
<filename>c:\Program Files</filename>,
<filename>c:\Desktop</filename>, etc.)
</para>
</listitem>
<listitem>
<para>
Symlink all <filename>.dll</filename> and
<filename>.exe</filename> files from the original
windows installation to the
<filename>windows</filename> directory. Why? Some
programs reference "%windowsdir%/file.dll" or
"%systemdir%/file.dll" directly and fail if they
are not present.
</para>
<para>
This will give a huge number of symlinks, yes.
However, if an installer later overwrites on of
those files, it will overwrite the symlink (so
that the file now lies in the
<filename>windows/</filename> subdirectory).
</para>
<note>
<title>FIXME</title>
<para>Not sure this is needed for all files.</para>
</note>
</listitem>
<listitem>
<para>
On later invocation the script might want to
compare regular files in the users windows
directories and in the global windows directories
and replace same files by symlinks (to avoid
diskspace problems).
</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
<para>Done.</para>
<para>
This procedure requires:
</para>
<itemizedlist>
<listitem>
<para>Much thought and work from the packager (1x)</para>
</listitem>
<listitem>
<para>
No work for the sysadmin. Well except one <command>rpm
-i</command> and possible one edit of the configuration
file.
</para>
</listitem>
<listitem>
<para>
Some or no work from the user, except running the per-user
setup script once.
</para>
</listitem>
<listitem>
<para>It scales well and suffices most of the rationales.</para>
</listitem>
</itemizedlist>
<bridgehead>Sample <filename>wine.ini</filename> for OpenLinux 2.x:</bridgehead>
<programlisting>
;;
;; MS-DOS drives configuration
;;
;; Each section has the following format:
;; [Drive X]
;; Path=xxx (Unix path for drive root)
;; Type=xxx (supported types are 'floppy', 'hd', 'cdrom' and 'network')
;; Label=xxx (drive label, at most 11 characters)
;; Serial=xxx (serial number, 8 characters hexadecimal number)
;; Filesystem=xxx (supported types are 'msdos'/'dos'/'fat', 'win95'/'vfat', 'unix')
;; This is the FS Wine is supposed to emulate on a certain
;; directory structure.
;; Recommended:
;; - "win95" for ext2fs, VFAT and FAT32
;; - "msdos" for FAT16 (ugly, upgrading to VFAT driver strongly recommended)
;; DON'T use "unix" unless you intend to port programs using Winelib !
;; Device=/dev/xx (only if you want to allow raw device access)
;;
;
;
; Floppy 'A' and 'B'
;
; OpenLinux uses an automounter under /auto/, so we use that too.
;
[Drive A]
Path=/auto/floppy/
Type=floppy
Label=Floppy
Serial=87654321
Device=/dev/fd0
Filesystem=win95
;
; Comment in ONLY if you have a second floppy or the automounter hangs
; for 5 minutes.
;
;[Drive B]
;Path=/auto/floppy2/
;Type=floppy
;Label=Floppy
;Serial=87654321
;Device=/dev/fd1
;Filesystem=win95
;
; Drive 'C' links to the users homedirectory.
;
; This must point to a writeable directory structure (not your readonly
; mounted DOS partitions!) since programs want to dump stuff into
; "Program Files/" "Programme/", "windows/", "windows/system/" etc.
;
; The basic structure is set up using the config script.
;
[Drive C]
Path=${HOME}
Type=hd
Label=MS-DOS
Filesystem=win95
;
; /tmp/ directory
;
; The temp drive (and directory) points to /tmp/. Windows programs fill it
; with junk, so it is approbiate.
;
[Drive T]
Path=/tmp
Type=hd
Label=Tmp Drive
Filesystem=win95
;
; 'U'ser homedirectory
;
; Just in case you want C:\ elsewhere.
;
[Drive U]
Path=${HOME}
Type=hd
Label=Home
Filesystem=win95
;
; CD-'R'OM drive (automounted)
;
; The default cdrom drive.
;
; If an application (or game) wants a specific CD-ROM you might have to
; temporary change the Label to the one of the CD itself.
;
; How to read them is described in /usr/doc/wine-cvs-xxxxx/cdrom-labels.
;
[Drive R]
Path=/auto/cdrom
Type=cdrom
Label=CD-Rom
Filesystem=win95
;
; The drive where the old windows installation resides (it points to the
; windows/ subdirectory).
;
; The Path is modified by the winesetup script.
;
[Drive W]
Path=/
Type=network
Label=Windows
Filesystem=win95
;
; The UNIX Root directory, so all other programs and directories are reachable.
;
; type network is used to tell programs to not write here.
;
[Drive Z]
Path=/
Type=network
Label=ROOT
Filesystem=win95
;
; Standard Windows path entries. WINE will not work if they are incorrect.
;
[wine]
;
; The windows/ directory. It must be writeable, for programs write into it.
;
Windows=c:\windows
;
; The windows/system/ directory. It must be writeable, for especially setup
; programs install dlls in there.
;
System=c:\windows\system
;
; The temp directory. Should be cleaned regulary, since install programs leave
; junk without end in there.
;
Temp=t:\
;
; The dll search path. It should contain at least:
; - the windows and the windows/system directory of the user.
; - the global windows and windows/system directory (from a possible readonly
; windows installation either on msdos filesystems or somewhere in the UNIX
; directory tree)
; - any other windows style directories you want to add.
;
Path=c:\windows;c:\windows\system;c:\windows\system32;t:\;w:\;w:\system;w:\system32
;
; Outdated and no longer used. (but needs to be present).
;
SymbolTableFile=./wine.sym
# &lt;wineconf&gt;
;
; Dll loadorder defaults. No need to modify.
;
[DllDefaults]
EXTRA_LD_LIBRARY_PATH=${HOME}/wine/cvs/lib
DefaultLoadOrder = native, elfdll, so, builtin
;
; What 32/16 dlls belong to each other (context wise). No need to modify.
;
[DllPairs]
kernel = kernel32
gdi = gdi32
user = user32
commdlg = comdlg32
commctrl= comctl32
ver = version
shell = shell32
lzexpand= lz32
mmsystem= winmm
msvideo = msvfw32
winsock = wsock32
;
; What type of dll to use in their respective loadorder.
;
[DllOverrides]
kernel32, gdi32, user32 = builtin
kernel, gdi, user = builtin
toolhelp = builtin
comdlg32, commdlg = elfdll, builtin, native
version, ver = elfdll, builtin, native
shell32, shell = builtin, native
lz32, lzexpand = builtin, native
commctrl, comctl32 = builtin, native
wsock32, winsock = builtin
advapi32, crtdll, ntdll = builtin, native
mpr, winspool = builtin, native
ddraw, dinput, dsound = builtin, native
winmm, mmsystem = builtin
msvideo, msvfw32 = builtin, native
mcicda.drv, mciseq.drv = builtin, native
mciwave.drv = builtin, native
mciavi.drv, mcianim.drv = native, builtin
w32skrnl = builtin
wnaspi32, wow32 = builtin
system, display, wprocs = builtin
wineps = builtin
;
; Options section. Does not need to be edited.
;
[options]
; allocate how much system colors on startup. No need to modify.
AllocSystemColors=100
;;
; Font specification. You usually do not need to edit this section.
;
; Read documentation/fonts before adding aliases
;
[fonts]
; The resolution defines what fonts to use (usually either 75 or 100 dpi fonts,
; or nearest match).
Resolution = 96
; Default font
Default = -adobe-times-
;
; serial ports used by "COM1" "COM2" "COM3" "COM4". Useful for applications
; that try to access serial ports.
;
[serialports]
Com1=/dev/ttyS0
Com2=/dev/ttyS1
Com3=/dev/modem,38400
Com4=/dev/modem
;
; parallel port(s) used by "LPT1" etc. Useful for applications that try to
; access these ports.
;
[parallelports]
Lpt1=/dev/lp0
;
; What spooling program to use on printing.
; Use "|program" or "filename", where the output will be dumped into.
;
[spooler]
LPT1:=|lpr
LPT2:=|gs -sDEVICE=bj200 -sOutputFile=/tmp/fred -q -
LPT3:=/dev/lp3
;
; Allow port access to WINE started by the root user. Useful for some
; supported devices, but it can make the system unstable.
; Read /usr/doc/wine-cvs-xxxxx/ioport-trace-hints.
;
[ports]
;read=0x779,0x379,0x280-0x2a0
;write=0x779,0x379,0x280-0x2a0
; debugging, not need to be modified.
[spy]
Exclude=WM_SIZE;WM_TIMER;
;
; What names for the registry datafiles, no need to modify.
;
[Registry]
; Paths must be given in /dir/dir/file.reg format.
; Wine will not understand dos file names here...
;UserFileName=xxx ; alternate registry file name (user.reg)
;LocalMachineFileName=xxx ; (system.reg)
;
; Layout/Look modifications. Here you can switch with a single line between
; windows 3.1 and windows 95 style.
; This does not change WINE behaviour or reported versions, just the look!
;
[Tweak.Layout]
;; WineLook=xxx (supported styles are 'Win31'(default), 'Win95', 'Win98')
WineLook=Win95
;
; What programs to start on WINE startup. (you should probably leave it empty)
;
[programs]
Default=
Startup=
; defunct section.
[Console]
;XtermProg=nxterm
;InitialRows=25
;InitialColumns=80
;TerminalType=nxterm
# &lt;/wineconf&gt;
</programlisting>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
End:
-->

11
documentation/patches.sgml Normal file
View File

@ -0,0 +1,11 @@
<chapter id="patches">
<title>Submitting Patches</title>
<para>How to create patches, and where to send them...</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
End:
-->

395
documentation/porting.sgml Normal file
View File

@ -0,0 +1,395 @@
<chapter id="porting">
<title>Porting Wine to new Platforms</title>
<para>Porting Wine to different (UNIX-based) operating systems...</para>
<sect1 id="wine-porting">
<title>Porting</title>
<para>
written by ???
</para>
<para>
(Extracted from <filename>wine/documentation/how-to-port</filename>)
</para>
<sect2>
<title>What is this?</title>
<para>
This note is a short description of:
</para>
<itemizedlist>
<listitem>
<para>How to port Wine to your favourite operating system</para>
</listitem>
<listitem>
<para>Why you probably shouldn't use <symbol>#ifdef MyOS</symbol></para>
</listitem>
<listitem>
<para>What to do instead.</para>
</listitem>
</itemizedlist>
<para>
This document does not say a thing about how to port Wine to
non-386 operating systems, though. You would need a CPU
emulator. Let's get Wine into a better shape on 386 first,
OK?
</para>
</sect2>
<sect2>
<title>Why <symbol>#ifdef MyOS</symbol> is probably a mistake.</title>
<para>
Operating systems change. Maybe yours doesn't have the
<filename>foo.h</filename> header, but maybe a future
version will have it. If you want to <symbol>#include
&lt;foo.h&gt;</symbol>, it doesn't matter what operating
system you are using; it only matters whether
<filename>foo.h</filename> is there.
</para>
<para>
Furthermore, operating systems change names or "fork" into
several ones. An <symbol>#ifdef MyOs</symbol> will break
over time.
</para>
<para>
If you use the feature of <command>autoconf</command> -- the
Gnu auto-configuration utility -- wisely, you will help
future porters automatically because your changes will test
for <emphasis>features</emphasis>, not names of operating
systems. A feature can be many things:
</para>
<itemizedlist>
<listitem>
<para>existance of a header file</para>
</listitem>
<listitem>
<para>existance of a library function</para>
</listitem>
<listitem>
<para>existance of libraries</para>
</listitem>
<listitem>
<para>bugs in header files, library functions, the compiler, ...</para>
</listitem>
<listitem>
<para>(you name it)</para>
</listitem>
</itemizedlist>
<para>
You will need Gnu Autoconf, which you can get from your
friendly Gnu mirror. This program takes Wine's
<filename>configure.in</filename> file and produces a
<filename>configure</filename> shell script that users use
to configure Wine to their system.
</para>
<para>
There <emphasis>are</emphasis> exceptions to the "avoid
<symbol>#ifdef MyOS</symbol>" rule. Wine, for example, needs
the internals of the signal stack -- that cannot easily be
described in terms of features.
</para>
<para>
Let's now turn to specific porting problems and how to solve
them.
</para>
</sect2>
<sect2>
<title>MyOS doesn't have the <filename>foo.h</filename> header!</title>
<para>
This first step is to make <command>autoconf</command> check
for this header. In <filename>configure.in</filename> you
add a segment like this in the section that checks for
header files (search for "header files"):
</para>
<programlisting>
AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
</programlisting>
<para>
If your operating system supports a header file with the
same contents but a different name, say
<filename>bar.h</filename>, add a check for that also.
</para>
<para>
Now you can change
</para>
<programlisting>
#include &lt;foo.h&gt;
</programlisting>
<para>
to
</para>
<programlisting>
#ifdef HAVE_FOO_H
#include &lt;foo.h&gt;
#elif defined (HAVE_BAR_H)
#include &lt;bar.h&gt;
#endif
</programlisting>
<para>
If your system doesn't have a corresponding header file even
though it has the library functions being used, you might
have to add an <symbol>#else</symbol> section to the
conditional. Avoid this if you can.
</para>
<para>
You will also need to add <symbol>#undef HAVE_FOO_H</symbol>
(etc.) to <filename>include/config.h.in</filename>
</para>
<para>
Finish up with <command>make configure</command> and
<command>./configure</command>.
</para>
</sect2>
<sect2>
<title>MyOS doesn't have the <function>bar</function> function!</title>
<para>
A typical example of this is the
<function>memmove</function> function. To solve this
problem you would add <function>memmove</function> to the
list of functions that <command>autoconf</command> checks
for. In <filename>configure.in</filename> you search for
<function>AC_CHECK_FUNCS</function> and add
<function>memmove</function>. (You will notice that someone
already did this for this particular function.)
</para>
<para>
Secondly, you will also need to add <symbol>#undef
HAVE_BAR</symbol> to
<filename>include/config.h.in</filename>
</para>
<para>
The next step depends on the nature of the missing function.
</para>
<variablelist>
<varlistentry>
<term>Case 1:</term>
<listitem>
<para>
It's easy to write a complete implementation of the
function. (<function>memmove</function> belongs to
this case.)
</para>
<para>
You add your implementation in
<filename>misc/port.c</filename> surrounded by
<symbol>#ifndef HAVE_MEMMOVE</symbol> and
<symbol>#endif</symbol>.
</para>
<para>
You might have to add a prototype for your function.
If so, <filename>include/miscemu.h</filename> might be the place. Don't
forget to protect that definition by <symbol>#ifndef
HAVE_MEMMOVE</symbol> and <symbol>#endif</symbol> also!
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Case 2:</term>
<listitem>
<para>
A general implementation is hard, but Wine is only
using a special case.
</para>
<para>
An example is the various <function>wait</function>
calls used in <function>SIGNAL_child</function> from
<filename>loader/signal.c</filename>. Here we have a
multi-branch case on features:
</para>
<programlisting>
#ifdef HAVE_THIS
...
#elif defined (HAVE_THAT)
...
#elif defined (HAVE_SOMETHING_ELSE)
...
#endif
</programlisting>
<para>
Note that this is very different from testing on
operating systems. If a new version of your operating
systems comes out and adds a new function, this code
will magically start using it.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Finish up with <command>make configure</command> and
<command>./configure</command>.
</para>
</sect2>
</sect1>
<sect1 id="os2-wine">
<title>Running & Compiling WINE in OS/2</title>
<para>
written by Robert Pouliot &lt;krynos@clic.net&gt;, January 9, 1997
</para>
<para>
(Extracted from <filename>wine/documentation/wine_os2</filename>)
</para>
<para>
If you want to help the port of WINE to OS/2, send me a
message at <email>krynos@clic.net</email> I currently don't
want beta testers. It must work before we can test it.
</para>
<para>
Here is what you need to (try to) compile Wine for OS/2:
</para>
<itemizedlist>
<listitem>
<para>EMX 0.9c (fix 2)</para>
</listitem>
<listitem>
<para>XFree86 3.2 OS/2 (with development libraries)</para>
</listitem>
<listitem>
<para>
<command>bash</command>, gnu <command>make</command>,
<command>grep</command>, <command>tar</command>,
<command>bison</command>, <command>flex</command>
</para>
</listitem>
<listitem>
<para><command>sed</command> (a working copy of)</para>
</listitem>
<listitem>
<para>xpm</para>
</listitem>
<listitem>
<para><command>diff</command> and <command>patch</command>
are recommended</para>
</listitem>
<listitem>
<para>Lots of disk space (about 40-50 megs after EMX and XFree installed)</para>
</listitem>
</itemizedlist>
<para>
To compile:
</para>
<screen>
<prompt>$ </prompt><userinput>sh</userinput>
<prompt>$ </prompt><userinput>tools/make_os2.sh</userinput>
<prompt>$ </prompt><userinput>make depend</userinput>
<prompt>$ </prompt><userinput>make</userinput>
<prompt>$ </prompt><userinput>emxbind wine</userinput>
</screen>
<para>
Currently:
</para>
<itemizedlist>
<listitem>
<para><command>configure</command> and <command>make depend</command> work...</para>
</listitem>
<listitem>
<para><command>make</command> compiles (with a modified
Linux <filename>mman.h</filename>), but doesn't
link.</para>
</listitem>
<listitem>
<para>signal handling is horrible... (if any)</para>
</listitem>
<listitem>
<para>EMX doesn't support <function>mmap</function> (and
related), SysV IPC and <function>stafs()</function></para>
</listitem>
<listitem>
<para>
XFree86/OS2 3.2 doesn't support
<function>XShmQueryExtension()</function> and
<function>XShmPixmapFormat()</function> due to the same
lack in EMX...
</para>
</listitem>
</itemizedlist>
<para>
What needs to be redone:
</para>
<itemizedlist>
<listitem>
<para>LDT (using <function>DosAllocSeg</function> in
<filename>memory/ldt.c</filename>) *</para>
</listitem>
<listitem>
<para>Implement <function>mmap()</function> and SysV IPC in EMX *</para>
</listitem>
<listitem>
<para>File functions, </para>
</listitem>
<listitem>
<para>I/O access (do it!),</para>
</listitem>
<listitem>
<para>Communication (modem),</para>
</listitem>
<listitem>
<para>Interrupt (if int unknown, call current RealMode one...), </para>
</listitem>
<listitem>
<para>
Verify that everything is thread safe (how does Win95/NT handle multi-thread?),
</para>
</listitem>
<listitem>
<para>
Move X functions in some files (and make a wrapper, to use PM instead latter),
</para>
</listitem>
<listitem>
<para>Return right CPU type, </para>
</listitem>
<listitem>
<para>Make winsock work</para>
</listitem>
</itemizedlist>
<para>
The good things:
</para>
<itemizedlist>
<listitem>
<para>OS/2 have DOS interrupts</para>
</listitem>
<listitem>
<para>OS/2 have I/O port access</para>
</listitem>
<listitem>
<para>OS/2 have multi-thread</para>
</listitem>
<listitem>
<para>Merlin have Open32 (to be used later...)</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
End:
-->

57
documentation/printing
View File

@ -1,57 +0,0 @@
Printing in Wine
================
Printing in Wine can be done in one of two ways. Both of which are very alpha.
1. Use a windows 3.1 printer driver.
2. Use the builtin Wine Postscript driver (+ ghostscript to produce output for
non-postscript printers).
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.
1. External printer drivers
---------------------------
At present only 16 bit drivers will work (note that these include win9x
drivers).
Add
printer=on
to the [wine] section of wine.conf (or ~/.winerc). This lets CreateDC proceed
if its driver argument is a 16 bit driver.
You will probably also need to add
TTEnable=0
TTOnly=0
to the [TrueType] section of win.ini .
The code for the driver interface is in graphics/win16drv .
2. Builtin Wine PostScript driver
---------------------------------
Enables printing of PostScript files via a driver built into Wine. See
documentation/psdriver for installation instructions. The code for the
PostScript driver is in graphics/psdrv .
Spooling
========
Spooling is rather primitive. The [spooler] section of wine.conf maps a port
(e.g. LPT1:) to a file or a command via a pipe. For example the following lines
LPT1:=foo.ps
LPT2:=|lpr
map LPT1: to file foo.ps and LPT2: to the lpr command. If a job is sent to an
unlisted port then a file is created with that port's name e.g. for LPT3: a
file called LPT3: would be created.

265
documentation/printing.sgml Normal file
View File

@ -0,0 +1,265 @@
<chapter id="printing">
<title>Printing in Wine</title>
<para>How to print documents in Wine...</para>
<sect1 id="wine-printing">
<title>Printing</title>
<para>
written by (???)
</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.
</para>
<orderedlist>
<listitem>
<para>Use an external windows 3.1 printer driver.</para>
</listitem>
<listitem>
<para>
Use the builtin Wine Postscript driver (+ ghostscript to produce
output for non-postscript printers).
</para>
</listitem>
</orderedlist>
<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.
</para>
<sect2>
<title>External printer drivers</title>
<para>
At present only 16 bit drivers will work (note that these include win9x
drivers). To use them, add
</para>
<screen>
printer=on
</screen>
<para>
to the [wine] section of <filename>wine.conf</filename> (or
<filename>~/.winerc</filename>). This lets
<function>CreateDC</function> proceed if its driver argument is a 16
bit driver. You will probably also need to add
</para>
<screen>
TTEnable=0 TTOnly=0
</screen>
<para>
to the [TrueType] section of <filename>win.ini</filename>. The code for
the driver interface is in <filename>graphics/win16drv</filename>.
</para>
</sect2>
<sect2>
<title>Builtin Wine PostScript driver</title>
<para>
Enables printing of PostScript files via a driver built into Wine. See
<filename>documentation/psdriver</filename> for installation
instructions. The code for the PostScript driver is in
<filename>graphics/psdrv</filename>.
</para>
</sect2>
<sect2>
<title>Spooling</title>
<para>
Spooling is rather primitive. The [spooler] section of
<filename>wine.conf</filename> maps a port (e.g.
<systemitem>LPT1:</systemitem>) to a file or a command via a pipe. For
example the following lines
</para>
<screen>
LPT1:=foo.ps LPT2:=|lpr
</screen>
<para>
map <systemitem>LPT1:</systemitem> to file <filename>foo.ps</filename>
and <systemitem>LPT2:</systemitem> to the <command>lpr</command>
command. If a job is sent to an unlisted port then a file is created
with that port's name e.g. for <systemitem>LPT3:</systemitem> a file
called <systemitem>LPT3:</systemitem> would be created.
</para>
</sect2>
</sect1>
<sect1 id="psdriver">
<title>The Wine PostScript Driver</title>
<para>
written by Huw Davies <email>h.davies1@physics.ox.ac.uk</email>
</para>
<para>
(Extracted from <filename>wine/documentation/psdriver</filename>)
</para>
<para>
When complete this will allow Wine to generate PostScript files without
needing an external printer driver. It should be possible to print to a
non PostScript printer by filtering the output through ghostscript.
</para>
<sect2>
<title>Installation</title>
<para>
The driver behaves as if it were a DRV file called
<filename>wineps.drv</filename> which at the moment is built into Wine.
Although it mimics a 16 bit driver it will work with both 16 and 32 bit
apps, just as win9x drivers do.
</para>
<para>
To install it add
</para>
<screen>
Wine PostScript Driver=WINEPS,LPT1:
</screen>
<para>
to the [devices] section of <filename>win.ini</filename> and to set it
as the default printer also add
</para>
<screen>
device=Wine PostScript Driver,WINEPS,LPT1:
</screen>
<para>
to the [windows] section of <filename>win.ini</filename> and ???
<emphasis>[sic]</emphasis>
</para>
<para>
To run 32 bit apps (and 16 bit apps using the
<literal>builtin</literal> commdlg) you also need to add certain
entries to the registry. The easiest way to do that at the moment is
to use the winelib program <command>programs/regapi/regapi</command>
with the file <filename>documentation/psdrv.reg</filename>. To do this
<command>cd</command> to <filename>programs/regapi/regapi</filename>
and type <userinput>make</userinput> to actually make the program, then
type <userinput>./regapi setValue
&lt;../../documentation/psdrv.reg</userinput>. You can obviously
edit <filename>psdrv.reg</filename> to suit your requirements.
</para>
<para>
You will need Adobe Font Metric (AFM) files for the (type 1 PostScript)
fonts that you wish to use. You can get these from
<ulink url="ftp://ftp.adobe.com/pub/adobe/type/win/all/afmfiles">
ftp://ftp.adobe.com/pub/adobe/type/win/all/afmfiles </ulink>. The
directories <filename>base17</filename> or <filename>base35</filename>
are good places to start. Note that these are only the font metrics and
not the fonts themselves. At the moment the driver does not download
additional fonts, so you can only use fonts that are already present on
the printer.
</para>
<para>
Then create a [afmfiles] section in your
<filename>wine.conf</filename> (or
<filename>~/.winerc</filename>) and add a line of the form
</para>
<screen>
file&lt;n&gt;=/unix/path/name/filename.afm
</screen>
<para>
for each AFM file that you wish to use. [This might change in the future]
</para>
<para>
You also require a PPD file for your printer. This describes certain
characteristics of the printer such as which fonts are installed, how
to select manual feed etc. Adobe also has many of these on its website,
have a look in <ulink url="ftp://ftp.adobe.com/pub/adobe/printerdrivers/win/all/">
ftp://ftp.adobe.com/pub/adobe/printerdrivers/win/all/</ulink>. Create
a [psdrv] section in your <filename>wine.conf</filename> (or
<filename>~/.winerc</filename>) and add the following entry:
</para>
<screen>
ppdfile=/somewhere/file.ppd
</screen>
<para>
By default, the driver will look for a file named
<filename>default.ppd</filename> in the directory from which
you started wine.
</para>
<para>
To enable colour printing you need to have the
<literal>*ColorDevice</literal> entry in the PPD set to
<literal>true</literal>, otherwise the driver will generate
greyscale.
</para>
<para>
Note that you need not set <literal>printer=on</literal> in
the [wine] section of <filename>wine.conf</filename>, this
enables printing via external printer drivers and does not
affect wineps.
</para>
<para>
If you're lucky you should now be able to produce PS files
from Wine!
</para>
<para>
I've tested it with win3.1 notepad/write, Winword6 and
Origin4.0 and 32 bit apps such as win98 wordpad, Winword97,
Powerpoint2000 with some degree of success - you should be
able to get something out, it may not be in the right place.
</para>
</sect2>
<sect2>
<title>TODO / Bugs</title>
<itemizedlist>
<listitem>
<para>
Driver does read PPD files, but ignores all constraints
and doesn't let you specify whether you have optional
extras such as envelope feeders. You will therefore find
a larger than normal selection of input bins in the
print setup dialog box. I've only really tested ppd
parsing on the <filename>hp4m6_v1.ppd</filename> file.
</para>
</listitem>
<listitem>
<para>No TrueType download.</para>
</listitem>
<listitem>
<para>StretchDIBits uses level 2 PostScript.</para>
</listitem>
<listitem>
<para>AdvancedSetup dialog box.</para>
</listitem>
<listitem>
<para>Many partially implemented functions.</para>
</listitem>
<listitem>
<para>ps.c is becoming messy.</para>
</listitem>
<listitem>
<para>
Notepad often starts text too far to the left depending
on the margin settings. However the win3.1
<filename>pscript.drv</filename> (under wine) also does
this.
</para>
</listitem>
<listitem>
<para>Probably many more...</para>
</listitem>
</itemizedlist>
<para>
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>
</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" "")
End:
-->

134
documentation/psdriver
View File

@ -1,134 +0,0 @@
Wine PostScript Driver
======================
When complete this will allow Wine to generate PostScript files without needing
an external printer driver. It should be possible to print to a non PostScript
printer by filtering the output through ghostscript.
Installation
------------
The driver behaves as if it were a DRV file called WINEPS.DRV which at the
moment is built into Wine. Although it mimics a 16 bit driver it will work
with both 16 and 32 bit apps, just as win9x drivers do.
To install it add
Wine PostScript Driver=WINEPS,LPT1:
to the [devices] section of win.ini and to set it as the default printer also
add
device=Wine PostScript Driver,WINEPS,LPT1:
to the [windows] section of win.ini and
To run 32 bit apps (and 16 bit apps using the builtin commdlg) you also need to
add certain entries to the registry. The easiest way to do that at the moment
is to use the winelib program programs/regapi/regapi with the file
documentation/psdrv.reg . To do this cd to programs/regapi/regapi and type
`make' to actually make the program, then type
`./regapi setValue <../../documentation/psdrv.reg' . You can obviously edit
psdrv.reg to suit your requirements.
You will need Adobe Font Metric (AFM) files for the (type 1 PostScript) fonts
that you wish to use. You can get these from
ftp://ftp.adobe.com/pub/adobe/type/win/all/afmfiles . The directories base17
or base35 are good places to start. Note that these are only the font metrics
and not the fonts themselves. At the moment the driver does not download
additional fonts, so you can only use fonts that are already present on the
printer.
Then create a [afmfiles] section in your wine.conf (or ~/.winerc) and add a
line of the form
file<n>=/unix/path/name/filename.afm
for each AFM file that you wish to use. [This might change in the future]
You also require a PPD file for your printer. This describes certain
characteristics of the printer such as which fonts are installed, how to select
manual feed etc. Adobe also has many of these on its website, have a look in
ftp://ftp.adobe.com/pub/adobe/printerdrivers/win/all/
Create a [psdrv] section in your wine.conf (or ~/.winerc) and add the
following entry:
ppdfile=/somewhere/file.ppd
By default, the driver will look for a file named default.ppd in the directory
from which you started wine.
To enable colour printing you need to have the *ColorDevice entry in the PPD
set to true, otherwise the driver will generate greyscale.
Note that you need not set printer=on in the [wine] section of wine.conf, this
enables printing via external printer drivers and does not affect wineps.
If you're lucky you should now be able to produce PS files from Wine!
I've tested it with win3.1 notepad/write, Winword6 and Origin4.0 and 32 bit
apps such as win98 wordpad, Winword97, Powerpoint2000 with some degree of
success - you should be able to get something out, it may not be in the right
place.
If you don't have a PostScript printer here is a short additional description
how to get the Wine PostScript Driver running with ghostscript. I had some
success with ghostscript 5.10 from the SuSE 6.2 distribution. My ghostscript
package contains some AFM files in the directory /usr/share/ghostscript/fonts.
I have used these for the [afmfiles] section in my wine.conf (or ~/.winerc)
file.
There are also two PPD file in my ghostscript package. They are located in the
directory /usr/share/ghostscript/5.10. I have used the file cbjc600.ppd because
of the supported papersize. Because my PPD file needed some changes i have
copyed it to /usr/local/etc/gs.ppd and enterd it into the [psdrv] section in
my wine.conf (or ~/.winerc) file.
When i started wine after this settings i got an error when wine tried to pars
the PPD file. There was the ':' missing in the line:
*CloseUI: *PrintColors
After this fix the PPD file was successfull parsed, but printing was still not
possible. The reason is that the PPD file contains no font information. To
create the font information I run wine with -debugmsg +font and redirected the
output into a file. Than I filterd the file for lines containing 'FontName'
using the grep command and extracted the names of the fonts with the cut
command into a new file.
grep FontName LOGFILE | cut -f 2 -d\' | sort -u > add.ppd
Now '*Font ' needs to be inserted at the beginning of each line of the new
file. The end of each line needs to become ': Standard'. The last step is to
add these line to the PPD file. After this I was able to print some text using
wines buildin PostScript driver and ghostscript.
TODO / Bugs
-----------
Driver does read PPD files, but ignores all constraints and doesn't let you
specify whether you have optional extras such as envelope feeders. You will
therefore find a larger than normal selection of input bins in the print setup
dialog box. I've only really tested ppd parsing on the hp4m6_v1.ppd file.
No TrueType download.
StretchDIBits uses level 2 PostScript.
AdvancedSetup dialog box.
Many partially implemented functions.
ps.c is becoming messy.
Notepad often starts text too far to the left depending on the margin
settings. However the win3.1 pscript.drv (under wine) also does this.
Probably many more...
Please contact me if you want to help so that we can avoid duplication.
Huw Davies <h.davies1@physics.ox.ac.uk>

178
documentation/registry
View File

@ -1,178 +0,0 @@
The Registry
------------
After Win3.x, the registry became a fundamental part of Windows. It is
the place where both Windows itself, and all
Win95/98/NT/2000/whatever-compliant applications, store configuration
and state data. While most sane system administrators (and Wine
developers) curse badly at the twisted nature of the Windows registry,
it is still necessary for Wine to support it somehow.
Registry structure
The Windows registry is an elaborate tree structure, and not even most
Windows programmers are fully aware of how the registry is laid out,
with its different "hives" and numerous links between them; a full
coverage is out of the scope of this document. But here are the basic
registry keys you might need to know about for now.
HKEY_LOCAL_MACHINE
This fundamental root key (in win9x, stored in the hidden file
system.dat) contains everything pertaining to the current
Windows installation.
HKEY_USERS
This fundamental root key (in win9x, stored in the hidden file
user.dat) contains configuration data for every user of the
installation.
HKEY_CLASSES_ROOT
This is a link to HKEY_LOCAL_MACHINE\Software\Classes. It
contains data describing things like file associations, OLE
document handlers, and COM classes.
HKEY_CURRENT_USER
This is a link to HKEY_USERS\your_username, i.e., your personal
configuration.
Using a Windows registry
If you point Wine at an existing MS Windows installation (by setting
the appropriate directories in wine.conf/.winerc), then Wine is able
to load registry data from it. However, Wine will not save anything to
the real Windows registry, but rather to its own registry files (see
below). Of course, if a particular registry value exists in both the
Windows registry and in the Wine registry, then Wine will use the
latter.
Occasionally, Wine may have trouble loading the Windows registry.
Usually, this is because the registry is inconsistent or damaged in
some way. If that becomes a problem, you may want to download the
regclean.exe from the MS website and use it to clean up the registry.
Alternatively, you can always use regedit.exe to export the registry
data you want into a text file, and then import it in Wine.
Wine registry data files
In the user's home directory, there is a subdirectory named .wine,
where Wine will try to save its registry by default. It saves into
four files, which are:
system.reg
This file contains HKEY_LOCAL_MACHINE.
user.reg
This file contains HKEY_CURRENT_USER.
userdef.reg
This file contains HKEY_USERS\.Default (i.e. the default user
settings).
wine.userreg
Wine saves HKEY_USERS to this file (both current and default
user), but does not load from it, unless userdef.reg is
missing.
All of these files are human-readable text files, so unlike Windows,
you can actually use an ordinary text editor on them if you must.
In addition to these files, Wine can also optionally load from global
registry files residing in the same directory as the global wine.conf
(i.e. /usr/local/etc if you compiled from source). These are:
wine.systemreg
Contains HKEY_LOCAL_MACHINE.
wine.userreg
Contains HKEY_USERS.
System administration
With the above file structure, it is possible for a system
administrator to configure the system so that a system Wine
installation (and applications) can be shared by all the users, and
still let the users all have their own personalized configuration. An
administrator can, after having installed Wine and any Windows
application software he wants the users to have access to, copy the
resulting system.reg and wine.userreg over to the global registry
files (which we assume will reside in /usr/local/etc here), with:
cd ~/.wine
cp system.reg /usr/local/etc/wine.systemreg
cp wine.userreg /usr/local/etc/wine.userreg
and perhaps even symlink these back to the administrator's account, to
make it easier to install apps system-wide later:
ln -sf /usr/local/etc/wine.systemreg system.reg
ln -sf /usr/local/etc/wine.userreg wine.userreg
Note that the tools/wineinstall script already does all of this for
you, if you install Wine as root. If you then install Windows
applications while logged in as root, all your users will
automatically be able to use them. While the application setup will be
taken from the global registry, the users' personalized configurations
will be saved in their own home directories.
But be careful with what you do with the administrator account - if
you do copy or link the administrator's registry to the global
registry, any user might be able to read the administrator's
preferences, which might not be good if sensitive information
(passwords, personal information, etc) is stored there. Only use the
administrator account to install software, not for daily work; use an
ordinary user account for that.
The default registry
A Windows registry contains many keys by default, and some of them are
necessary for even installers to operate correctly. The keys that the
Wine developers have found necessary to install applications are
distributed in a file called "winedefault.reg". It is automatically
installed for you if you use the tools/wineinstall script, but if you
want to install it manually, you can do so by using the regapi tool.
You can find more information about this in the
documentation/no-windows document in the Wine distribution.
The [registry] section
With the above information fresh in mind, let's look at the
wine.conf/.winerc options for handling the registry.
LoadGlobalRegistryFiles
Controls whether to try to load the global registry files, if
they exist.
LoadHomeRegistryFiles
Controls whether to try to load the user's registry files (in
the .wine subdirectory of the user's home directory).
LoadWindowsRegistryFiles
Controls whether Wine will attempt to load registry data from a
real Windows registry in an existing MS Windows installation.
WritetoHomeRegistryFiles
Controls whether registry data will be written to the user's
registry files. (Currently, there is no alternative, so if you
turn this off, Wine cannot save the registry on disk at all;
after you exit Wine, your changes will be lost.)
UseNewFormat
This option is obsolete. Wine now always use the new format;
support for the old format was removed a while ago.
PeriodicSave
If this option is set to a nonzero value, it specifies that you
want the registry to be saved to disk at the given interval. If
it is not set, the registry will only be saved to disk when the
wineserver terminates.
SaveOnlyUpdatedKeys
Controls whether the entire registry is saved to the user's
registry files, or only subkeys the user have actually changed.
Considering that the user's registry will override any global
registry files and Windows registry files, it usually makes
sense to only save user-modified subkeys; that way, changes to
the rest of the global or Windows registries will still affect
the user.
- Ove Kåven

344
documentation/registry.sgml Normal file
View File

@ -0,0 +1,344 @@
<sect1 id="registry">
<title>The Registry</title>
<para>
written by Ove Kåven
</para>
<para>
(Extracted from <filename>wine/documentation/registry</filename>)
</para>
<para>
After Win3.x, the registry became a fundamental part of Windows.
It is the place where both Windows itself, and all
Win95/98/NT/2000/whatever-compliant applications, store
configuration and state data. While most sane system
administrators (and Wine developers) curse badly at the twisted
nature of the Windows registry, it is still necessary for Wine
to support it somehow.
</para>
<sect2>
<title>Registry structure</title>
<para>
The Windows registry is an elaborate tree structure, and not
even most Windows programmers are fully aware of how the
registry is laid out, with its different "hives" and numerous
links between them; a full coverage is out of the scope of
this document. But here are the basic registry keys you might
need to know about for now.
</para>
<variablelist>
<varlistentry>
<term>HKEY_LOCAL_MACHINE</term>
<listitem>
<para>
This fundamental root key (in win9x, stored in the
hidden file <filename>system.dat</filename>) contains
everything pertaining to the current Windows
installation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HKEY_USERS</term>
<listitem>
<para>
This fundamental root key (in win9x, stored in the
hidden file <filename>user.dat</filename>) contains
configuration data for every user of the installation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HKEY_CLASSES_ROOT</term>
<listitem>
<para>
This is a link to HKEY_LOCAL_MACHINE\Software\Classes.
It contains data describing things like file
associations, OLE document handlers, and COM classes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HKEY_CURRENT_USER</term>
<listitem>
<para>
This is a link to HKEY_USERS\your_username, i.e., your
personal configuration.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>Using a Windows registry</title>
<para>
If you point Wine at an existing MS Windows installation (by
setting the appropriate directories in
<filename>wine.conf</filename> or
<filename>.winerc</filename>), then Wine is able to load
registry data from it. However, Wine will not save anything to
the real Windows registry, but rather to its own registry
files (see below). Of course, if a particular registry value
exists in both the Windows registry and in the Wine registry,
then Wine will use the latter.
</para>
<para>
Occasionally, Wine may have trouble loading the Windows
registry. Usually, this is because the registry is
inconsistent or damaged in some way. If that becomes a
problem, you may want to download the
<filename>regclean.exe</filename> from the MS website and use
it to clean up the registry. Alternatively, you can always use
<filename>regedit.exe</filename> to export the registry data
you want into a text file, and then import it in Wine.
</para>
</sect2>
<sect2>
<title>Wine registry data filesr</title>
<para>
In the user's home directory, there is a subdirectory named
<filename>.wine</filename>, where Wine will try to save its
registry by default. It saves into four files, which are:
</para>
<variablelist>
<varlistentry>
<term><filename>system.reg</filename></term>
<listitem>
<para>
This file contains HKEY_LOCAL_MACHINE.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>user.reg</filename></term>
<listitem>
<para>
This file contains HKEY_CURRENT_USER.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>userdef.reg</filename></term>
<listitem>
<para>
This file contains HKEY_USERS\.Default (i.e. the default
user settings).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>wine.userreg</filename></term>
<listitem>
<para>
Wine saves HKEY_USERS to this file (both current and
default user), but does not load from it, unless
<filename>userdef.reg</filename> is missing.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
All of these files are human-readable text files, so unlike
Windows, you can actually use an ordinary text editor on them
if you must.
</para>
<para>
In addition to these files, Wine can also optionally load from
global registry files residing in the same directory as the
global <filename>wine.conf</filename> (i.e.
<filename>/usr/local/etc</filename> if you compiled from
source). These are:
</para>
<variablelist>
<varlistentry>
<term><filename>wine.systemreg</filename></term>
<listitem>
<para>Contains HKEY_LOCAL_MACHINE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>wine.userreg</filename></term>
<listitem>
<para>Contains HKEY_USERS.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>System administration</title>
<para>
With the above file structure, it is possible for a system
administrator to configure the system so that a system Wine
installation (and applications) can be shared by all the
users, and still let the users all have their own personalized
configuration. An administrator can, after having installed
Wine and any Windows application software he wants the users
to have access to, copy the resulting
<filename>system.reg</filename> and
<filename>wine.userreg</filename> over to the global registry
files (which we assume will reside in
<filename>/usr/local/etc</filename> here), with:
</para>
<screen>
cd ~/.wine
cp system.reg /usr/local/etc/wine.systemreg
cp wine.userreg /usr/local/etc/wine.userreg
</screen>
<para>
and perhaps even symlink these back to the administrator's
account, to make it easier to install apps system-wide later:
</para>
<screen>
ln -sf /usr/local/etc/wine.systemreg system.reg
ln -sf /usr/local/etc/wine.userreg wine.userreg
</screen>
<para>
Note that the <filename>tools/wineinstall</filename> script
already does all of this for you, if you install Wine as root.
If you then install Windows applications while logged in as
root, all your users will automatically be able to use them.
While the application setup will be taken from the global
registry, the users' personalized configurations will be saved
in their own home directories.
</para>
<para>
But be careful with what you do with the administrator account
- if you do copy or link the administrator's registry to the
global registry, any user might be able to read the
administrator's preferences, which might not be good if
sensitive information (passwords, personal information, etc)
is stored there. Only use the administrator account to install
software, not for daily work; use an ordinary user account for
that.
</para>
</sect2>
<sect2>
<title>The default registry</title>
<para>
A Windows registry contains many keys by default, and some of
them are necessary for even installers to operate correctly.
The keys that the Wine developers have found necessary to
install applications are distributed in a file called
<filename>winedefault.reg</filename>. It is automatically
installed for you if you use the
<filename>tools/wineinstall</filename> script, but if you want
to install it manually, you can do so by using the
<command>regapi</command> tool. You can find more information
about this in the
<filename>documentation/no-windows</filename> document in the
Wine distribution.
</para>
</sect2>
<sect2>
<title>The [registry] section</title>
<para>
With the above information fresh in mind, let's look at the
<filename>wine.conf</filename>/<filename>.winerc</filename>
options for handling the registry.
</para>
<variablelist>
<varlistentry>
<term>LoadGlobalRegistryFiles</term>
<listitem>
<para>
Controls whether to try to load the global registry
files, if they exist.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LoadHomeRegistryFiles</term>
<listitem>
<para>
Controls whether to try to load the user's registry
files (in the <filename>.wine</filename> subdirectory of
the user's home directory).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LoadWindowsRegistryFiles</term>
<listitem>
<para>
Controls whether Wine will attempt to load registry data
from a real Windows registry in an existing MS Windows
installation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WritetoHomeRegistryFiles</term>
<listitem>
<para>
Controls whether registry data will be written to the
user's registry files. (Currently, there is no
alternative, so if you turn this off, Wine cannot save
the registry on disk at all; after you exit Wine, your
changes will be lost.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>UseNewFormat</term>
<listitem>
<para>
This option is obsolete. Wine now always use the new
format; support for the old format was removed a while
ago.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PeriodicSave</term>
<listitem>
<para>
If this option is set to a nonzero value, it specifies
that you want the registry to be saved to disk at the
given interval. If it is not set, the registry will only
be saved to disk when the wineserver terminates.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SaveOnlyUpdatedKeys</term>
<listitem>
<para>
Controls whether the entire registry is saved to the
user's registry files, or only subkeys the user have
actually changed. Considering that the user's registry
will override any global registry files and Windows
registry files, it usually makes sense to only save
user-modified subkeys; that way, changes to the rest of
the global or Windows registries will still affect the
user.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("configuring.sgml" "chapter" "sect1" "")
End:
-->

45
documentation/resources
View File

@ -1,45 +0,0 @@
This document desribes tools for handling resources within wine
### bin2res ###
This tool allows the editing of embedded binary resources within
*.rc files. These resources are stored as hex dump so they can be
stored within the cvs. This makes the editing of the embedded
bitmaps and icons harder.
### Create binary files from.rc ###
the resources in the .rc file have to be marked by a header:
/* BINRES idb_std_small.bmp */
IDB_STD_SMALL BITMAP LOADONCALL DISCARDABLE
{
'42 4D 20 07 00 00 00 00 00 00 76 00 00 00 28 00'
BINRES is the keyword followed by a filename.
"bin2res -d bin rsrc.rc" generates binary files from all marked
resources. If the binary file is newer it gets not overwritten.
To force overwriting use the -f switch.
### Create a .rc file from binaries ###
Put a header followed by empty brackets in the.rc file.
/* BINRES idb_std_small.bmp */
{}
Then run "bin2res rsrc.rc". It will merge the resources into the
.rc file if the binary resources are newer than the.rc file.
To force the resources into the.rc file use the -f switch.
If there is already a resource with the same filename in the.rc
file it gets overwritten.
### output of bin2res ###
bash-2.03# ../../tools/bin2res -d bin shres.rc
[000.ico:c][003.ico:c][008.ico:s][015.ico:s][034.ico:s]
s means skiped, c means changed
---
juergen.schmied@debitel.net (11/99)

18
documentation/running.sgml Normal file
View File

@ -0,0 +1,18 @@
<chapter id="running">
<title>Running Wine</title>
<para>Explain the command-line options you can use to run Wine</para>
<sect1 id="running-wine">
<title>How to run Wine</title>
<para>
The first thing you need to do is...
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
End:
-->

94
documentation/tools.sgml Normal file
View File

@ -0,0 +1,94 @@
<chapter id="tools">
<title>Tools</title>
<sect1 id="bin2res">
<title>bin2res</title>
<para>
written by juergen.schmied@debitel.net (11/99)
</para>
<para>
(Extracted from <filename>wine/documentation/resources</filename>)
</para>
<para>
This document desribes tools for handling resources within wine
</para>
<sect2>
<title>bin2res</title>
<para>
This tool allows the editing of embedded binary resources
within <filename>*.rc</filename> files. These resources are
stored as hex dump so they can be stored within the cvs
tree. This makes the editing of the embedded bitmaps and
icons harder.
</para>
</sect2>
<sect2>
<title>Create binary files from an <filename>.rc</filename> file</title>
<para>
The resources in the <filename>.rc</filename> file have to
be marked by a header:
</para>
<programlisting>
/* BINRES idb_std_small.bmp */
IDB_STD_SMALL BITMAP LOADONCALL DISCARDABLE
{
'42 4D 20 07 00 00 00 00 00 00 76 00 00 00 28 00'
</programlisting>
<para>
<constant>BINRES</constant> is the keyword followed by a
filename. <command>bin2res -d bin rsrc.rc</command>
generates binary files from all marked resources. If the
binary file is newer it gets not overwritten. To force
overwriting use the <parameter>-f</parameter> switch.
</para>
</sect2>
<sect2>
<title>Create a <filename>.rc</filename> file from binaries</title>
<para>
Put a header followed by empty brackets in the
<filename>.rc</filename> file.
</para>
<programlisting>
/* BINRES idb_std_small.bmp */
{}
</programlisting>
<para>
Then run <command>bin2res rsrc.rc</command>. It will merge
the resources into the <filename>.rc</filename> file if the
binary resources are newer than the.rc file. To force the
resources into the <filename>.rc</filename> file use the
<parameter>-f</parameter> switch. If there is already a
resource with the same filename in the
<filename>.rc</filename> file it gets overwritten.
</para>
</sect2>
<sect2>
<title>output of <command>bin2res</command></title>
<programlisting>
bash-2.03# ../../tools/bin2res -d bin shres.rc
[000.ico:c][003.ico:c][008.ico:s][015.ico:s][034.ico:s]
</programlisting>
<para>
<literal>s</literal> means skipped, <literal>c</literal>
means changed.
</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" "")
End:
-->

50
documentation/ttfserver
View File

@ -1,50 +0,0 @@
1. Get freetype-1.0.full.tar.gz
2. Read docus, unpack, configure and install
3. Test the library, e.g. "ftview 20 /dosc/win95/fonts/times "
4. Get xfsft-beta1e.linux-i586
5. Install it and start it when booting, e.g. in an rc-script.
The manpage for xfs applies.
6. Follow the hints given by williamc@dai.ed.ac.uk
==========
I got xfsft from http://www.dcs.ed.ac.uk/home/jec/progindex.html.
I have it running all the time. Here is /usr/X11R6/lib/X11/fs/config:
clone-self = on
use-syslog = off
catalogue = /c/windows/fonts
error-file = /usr/X11R6/lib/X11/fs/fs-errors
default-point-size = 120
default-resolutions = 75,75,100,100
Obviously /c/windows/fonts is where my Windows fonts on my
Win95 C: drive live; could be e.g. /mnt/dosC/windows/system
for Win31.
In /c/windows/fonts/fonts.scale I have
14
arial.ttf -monotype-arial-medium-r-normal--0-0-0-0-p-0-iso8859-1
arialbd.ttf -monotype-arial-bold-r-normal--0-0-0-0-p-0-iso8859-1
arialbi.ttf -monotype-arial-bold-o-normal--0-0-0-0-p-0-iso8859-1
ariali.ttf -monotype-arial-medium-o-normal--0-0-0-0-p-0-iso8859-1
cour.ttf -monotype-courier-medium-r-normal--0-0-0-0-p-0-iso8859-1
courbd.ttf -monotype-courier-bold-r-normal--0-0-0-0-p-0-iso8859-1
courbi.ttf -monotype-courier-bold-o-normal--0-0-0-0-p-0-iso8859-1
couri.ttf -monotype-courier-medium-o-normal--0-0-0-0-p-0-iso8859-1
times.ttf -monotype-times-medium-r-normal--0-0-0-0-p-0-iso8859-1
timesbd.ttf -monotype-times-bold-r-normal--0-0-0-0-p-0-iso8859-1
timesbi.ttf -monotype-times-bold-i-normal--0-0-0-0-p-0-iso8859-1
timesi.ttf -monotype-times-medium-i-normal--0-0-0-0-p-0-iso8859-1
symbol.ttf -monotype-symbol-medium-r-normal--0-0-0-0-p-0-microsoft-symbol
wingding.ttf -microsoft-wingdings-medium-r-normal--0-0-0-0-p-0-microsoft-symbol
In /c/windows/fonts/fonts.dir I have exactly the same.
In /usr/X11R6/lib/X11/XF86Config I have
FontPath "tcp/localhost:7100"
in front of the other FontPath lines.
That's it! As an interesting by-product of course, all those web
pages which specify Arial come up in Arial in Netscape ...
=======
7. Shut down X and restart ( and debug errors you did while setting
up everything.
8. Test with e.g "xlsfont |grep arial"
Hope this helps

24
documentation/win95look
View File

@ -1,24 +0,0 @@
Win95/Win98 interface code is being introduced.
Instead of compiling Wine for Win3.1 vs. Win95 using #define switches,
the code now looks in a special [Tweak.Layout] section of wine.conf
for a "WineLook=Win95" or "WineLook=Win98" entry.
A few new sections and a number of entries have been added to the
wine.conf file -- these are for debugging the Win95 tweaks only and may
be removed in a future release! These entries/sections are:
[Tweak.Fonts]
System.Height=<point size> # Sets the height of the system typeface
System.Bold=[true|false] # Whether the system font should be boldfaced
System.Italic=[true|false] # Whether the system font should be italicized
System.Underline=[true|false] # Whether the system font should be underlined
System.StrikeOut=[true|false] # Whether the system font should be struck out
OEMFixed.xxx # Same parameters for the OEM fixed typeface
AnsiFixed.xxx # Same parameters for the Ansi fixed typeface
AnsiVar.xxx # Same parameters for the Ansi variable typeface
SystemFixed.xxx # Same parameters for the System fixed typeface
[Tweak.Layout]
WineLook=[Win31|Win95|Win98] # Changes Wine's look and feel

94
documentation/wine-doc.sgml Normal file
View File

@ -0,0 +1,94 @@
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity running SYSTEM "running.sgml">
<!entity installing SYSTEM "installing.sgml">
<!entity configuring SYSTEM "configuring.sgml">
<!entity registry SYSTEM "registry.sgml">
<!entity bugs SYSTEM "bugs.sgml">
<!entity fonts SYSTEM "fonts.sgml">
<!entity printing SYSTEM "printing.sgml">
<!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 debugger SYSTEM "debugger.sgml">
<!entity consoles SYSTEM "consoles.sgml">
<!entity implementation SYSTEM "implementation.sgml">
<!entity opengl SYSTEM "opengl.sgml">
<!entity build SYSTEM "build.sgml">
<!entity tools SYSTEM "tools.sgml">
<!entity dlls SYSTEM "dlls.sgml">
<!entity status SYSTEM "status.sgml">
]>
<book id="index">
<bookinfo>
<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>
<part id="part-one">
<title>Using Wine</title>
&running;
&installing;
&configuring;
&bugs;
&fonts;
&printing;
</part>
<part id="part-two">
<title>Developing Wine</title>
&compiling;
&debugging;
&documentation;
&patches;
&i18n;
&porting;
</part>
<part id="part-three">
<title>Distributing Wine</title>
&packaging;
</part>
<part id="part-four">
<title>Wine Architecture</title>
&architecture;
&debugger;
&consoles;
&implementation;
&opengl;
&build;
&tools;
&dlls;
</part>
</book>

52
documentation/wine_os2
View File

@ -1,52 +0,0 @@
Running & Compiling WINE in OS/2
If you want to help for the port of WINE to OS/2,
send me a message at krynos@clic.net
I currently don't want beta testers. It must work before we can test it.
Here is what you need to (try to) compile Wine for OS/2:
EMX 0.9c (fix 2)
XFree86 3.2 OS/2 (with development libraries)
bash, gnu make, grep, tar, bison, flex
sed (a working copy of)
xpm
diff and patch are recommended
Lots of disk space (about 40-50 megs after EMX and XFree installed)
To compile:
sh
tools/make_os2.sh
make depend
make
emxbind wine
Currently:
- configure and make depend work...
- make compiles (with a modified Linux mman.h), but doesn't link.
- signal handling is horrible... (if any)
- EMX doesn't support mmap (and related), SysV IPC and stafs()
- XFree86/OS2 3.2 doesn't support XShmQueryExtension() and XShmPixmapFormat()
due to the same lack in EMX...
What needs to be redone:
- LDT (using DosAllocSeg in memory/ldt.c) *
- implement mmap() and SysV IPC in EMX *
- File functions,
- I/O access (do it!),
- Communication (modem),
- Interrupt (if int unknown, call current RealMode one...),
- verify that everything is thread safe (how does Win95/NT handle multi-thread?),
- move X functions in some files (and make a wrapper, to use PM instead latter),
- return right CPU type,
- make winsock work
* Top priority
The good things:
- OS/2 have DOS interrupts
- OS/2 have I/O port access
- OS/2 have multi-thread
- Merlin have Open32 (to be used later...)
Robert Pouliot <krynos@clic.net>
January 9, 1997


476
documentation/winedbg
View File

@ -1,476 +0,0 @@
I Introduction
==============
I.1 Processes and threads: in underlying OS and in Windows
----------------------------------------------------------
Before going into the depths of debugging in Wine, here's a small
overview of process and thread handling in Wine. It has to be clear
that there are two different beasts: processes/threads from the Unix
point of view and processes/threads from a Windows point of view.
Each Windows' thread is implemented as a Unix process (under Linux
using the clone syscall), meaning that all threads of a same Windows'
process share the same (unix) address space.
In the following:
+ W-process means a process in Windows' terminology
+ U-process means a process in Unix' terminology
+ W-thread means a thread in Windows' terminology
A W-process is made of one or several W-threads.
Each W-thread is mapped to one and only one U-process. All U-processes
of a same W-process share the same address space.
Each Unix process can be identified by two values:
- the Unix process id (upid in the following)
- the Windows's thread id (tid)
Each Windows' process has also a Windows' process (wpid in the
following). It must be clear that upid and wpid are different and
shall not be used instead of the other.
Wpid and tid are defined (Windows) system wide. They must not be
confused with process or thread handles which, as any handle, is an
indirection to a system object (in this case process or thread). A
same process can have several different handles on the same kernel
object. The handles can be defined as local (the values is only valid
in a process), or system wide (the same handle can be used by any
W-process).
I.2 Wine, debugging and WineDbg
-------------------------------
When talking of debugging in Wine, there are at least two levels to
think of:
+ the Windows' debugging API.
+ the Wine integrated debugger, dubbed WineDbg.
Wine implements most the the Windows' debugging API (the part in
KERNEL32, not the one in IMAGEHLP.DLL), and allows any program
(emulated or WineLib) using that API to debug a W-process.
WineDbg is a WineLib application making use of this API to allow
debugging both any Wine or WineLib applications as well as Wine itself
(kernel and all DLLs).
II WineDbg's modes of invocation
================================
II.1 Starting a process
-----------------------
Any application (either a Windows' native executable, or a WineLib
application) can be run through WineDbg. Command line options and
tricks are the same than for wine:
winedbg telnet.exe
winedbg "hl.exe -windowed"
II.2 Attaching
--------------
WineDbg can also launched without any command line argument:
- WineDbg is started without any attached process. You can get a list
of running W-processes (and their wpid:s) using 'walk process'
command, and then, with the attach command, pick up the wpid of the
W-process you want to debug.
This is (for now) a neat feature for the following reasons:
* debug an already started application
II.3 On exception
-----------------
When something goes wrong, Windows track this as an
exception. Exceptions exist for segmentation violation, stack
overflow, division by zero...
When an exception occurs, Wine checks if the W-process is debugged. If
so, the exception event is sent to the debugger, which takes care of
it: end of the story. This mechanism is part of the standard Windows'
debugging API.
If the W-process is not debugged, Wine tries to launch a
debugger. This debugger (normally WineDbg, see III Configuration for
more details), at startup, attaches to the W-process which generated
the exception event. In this case, you are able to look at the causes
of the exception, and either fix the causes (and continue further the
execution) or dig deeper to understand what went wrong.
If WineDbg is the standard debugger, the 'pass' and 'cont' commands
are the two ways to let the process go further for the handling of the
exception event.
To be more precise on the way Wine (and Windows) generates exception
events, when a fault occurs (segmentation violation, stack
overflow...), the event is first sent to the debugger (this is know as
a first chance exception). The debugger can give two answers:
- continue: the debugger had the ability to correct what's generated
the exception, and is now able to continue process execution.
- pass: the debugger couldn't correct the cause of the (first chance
exception). Wine will now try to walk the list of exception handlers
to see if one of them can handle the exception. If no exception
handler is found, the exception is sent once again to the debugger to
indicate the failure of the exception handling.
Note: since some of Wine's code uses exceptions and try/catch blocks
to provide some functionality, WineDbg can be entered in such cases
with segv exceptions. This happens, for example, with IsBadReadPtr
function. In that case, the pass command shall be used, to let the
handling of the exception to be done by the catch block in
IsBadReadPtr.
II.4 Quitting
-------------
Unfortunately, Windows' don't provide a detach kind of API, meaning
that once you started debugging a process, you must do so until the
process dies. Killing (or stopping/aborting) the debugger will also
kill the debugged process.
This will be true for any Windows' debugging API compliant debugger,
starting with WineDbg.
III Configuration
=================
III.1 Registry configuration
----------------------------
The Windows' debugging API uses a registry entry to know with debugger
to invoke when an unhandled exception occurs (see II.3 for some
details).
Two values in key
"MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
determine the behavior:
+ Debugger: this is the command line used to launch the debugger (it
uses two printf formats (%ld) to pass context dependent information to
the debugger). You should put here a complete path to your debugger
(WineDbg can of course be used, but any other Windows' debugging API
aware debugger will do).
+ Auto: if this value is zero, a message box will ask the user if
he/she wishes to launch the debugger when an unhandled exception
occurs. Otherwise, the debugger is automatically started.
A regular Wine registry looks like:
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
"Auto"=dword:00000001
"Debugger"="/usr/local/bin/winedbg %ld %ld"
Note 1: creating this key is mandatory. Not doing so will not fire the
debugger when an exception occurs.
Note 2: wineinstall sets up this correctly. However, due to some
limitation of the registry installed, if a previous Wine installation
exists, it's safer to remove the whole
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
key before running again wineinstall to regenerate this key.
III.2 WineDbg configuration
---------------------------
WineDbg can be configured thru a number of options. Those options are
stored in the registry, on a per user basis. The key is (in *my*
registry) [eric\\Software\\Wine\\WineDbg]
Those options can be read/written while inside WineDbg, as part of the
debugger expressions. To refer to one of this option, its name must be
prefixed by a $ sign.
For example,
set $BreakAllThreadsStartup = 1
sets the option 'BreakAllThreadsStartup' to TRUE.
All the options are read from the registry when WineDbg starts (if no
corresponding value is found, a default value is used), and are
written back to the registry when WineDbg exits (hence, all
modifications to those options are automatically saved when WineDbg
terminates).
Here's the list of all options:
III.2.1 Controling when the debugger is entered
BreakAllThreadsStartup set to TRUE if at all threads start-up the
debugger stops
set to FALSE if only at the first thread
startup of a given process the debugger stops.
FALSE by default.
BreakOnCritSectTimeOut set to TRUE if the debugger stops when a
critical section times out (5 minutes);
TRUE by default.
BreakOnAttach, set to TRUE if when WineDbg attaches to an
existing process after an unhandled exception,
WineDbg shall be entered on the first attach
event.
Since the attach event is meaningless in the
context of an exception event (the next event
which is the exception event is of course
relevant), that option is likely to be FALSE.
BreakOnDllLoad When set to TRUE, allows the debugger to be
entered when a new DLL is loaded into the system.
FALSE by default.
BreakOnFirstChance an exception can generate two debug events.
The first one is passed to the debugger (known
as a first chance) just after the
exception. The debugger can then decides
either to resume execution (see winedbg's cont
command) or pass the exception up to the
exception handler chain in the program (if it
exists) (winedbg implements this thru the pass
command). If none of the exception handlers
takes care of the exception, the exception
event is sent again to the debugger (known as
last chance exception). You cannot pass on a
last exception. When the BreakOnFirstChance
exception is TRUE, then winedbg is entered for
both first and last chance execptions (to
FALSE, it's only entered for last chance exceptions).
III.2.1 Output handling
ConChannelMask mask of active debugger output channels on
console
StdChannelMask mask of active debugger output channels on
stderr
UseXTerm set to TRUE if the debugger uses its own xterm
window for console input/output
set to FALSE is the debugger uses the current
Unix console for input/output
Those last 3 variables are jointly used in two generic ways:
1/ default
ConChannelMask = DBG_CHN_MESG (1)
StdChannelMask = 0
UseXTerm = 1
In this case, all input/output goes into a specific xterm window (but
all debug messages TRACE/WARN... still goes to tty where wine is run
from).
2/ to have all input/output go into the tty where Wine was started
from (to be used in a X11-free environment)
ConChannelMask = 0
StdChannelMask = DBG_CHN_MESG (1)
UseXTerm = 1
Those variables also allow, for example for debugging purposes, to
use:
ConChannelMask = 0xfff
StdChannelMask = 0xfff
UseXTerm = 1
This allows to redirect all WineDbg output to both tty Wine was
started from, and xterm debugging window. If Wine (or WineDbg) was
started with a redirection of stdout and/or stderr to a file (with for
example >& shell redirect command), you'll get in that file both
outputs. It may be interesting to look in the relay trace for specific
values which the process segv:ed on.
III.2.3 Context information
ThreadId ID of the W-thread currently examined by the
debugger
ProcessId ID of the W-thread currently examined by the
debugger
<registers> All CPU registers are also available
The ThreadId and ProcessId variables can be handy to set conditional
breakpoints on a given thread or process.
IV WineDbg commands
===================
IV.1 Misc
---------
abort aborts the debugger
quit exits the debugger
attach N attach to a W-process (N is its ID). IDs can be
obtained thru walk process command
help prints some help on the commands
help info prints some help on info commands
mode 16 switch to 16 bit mode
mode 32 switch to 32 bit mode
IV.2 Flow control
-----------------
cont continue execution until next breakpoint or exception.
pass pass the exception event up to the filter chain.
step continue execution until next C line of code (enters
function call)
next continue execution until next C line of code (doesn't
enter function call)
stepi execute next assembly instruction (enters function
call)
nexti execute next assembly instruction (doesn't enter
function call)
finish do nexti commands until current function is exited
cont, step, next, stepi, nexti can be postfixed by a number (N),
meaning that the command must be executed N times.
IV.3 Breakpoints, watch points
------------------------------
enable N enables (break|watch)point #N
disable N disables (break|watch)point #N
delete N deletes (break|watch)point #N
cond N removes any a existing condition to (break|watch)point N
cond N <expr> adds condition <expr> to (break|watch)point N. <expr>
will be evaluated each time the breakpoint is hit. If
the result is a zero value, the breakpoint isn't
triggered
break * N adds a breakpoint at address N
break <id> adds a breakpoint at the address of symbol <id>
break <id> N adds a breakpoint at the address of symbol <id> (N ?)
break N adds a breakpoint at line N of current source file
break adds a breakpoint at current $pc address
watch * N adds a watch command (on write) at address N (on 4 bytes)
watch <id> adds a watch command (on write) at the address of
symbol <id>
info break lists all (break|watch)points (with state)
IV.4 Stack manipulation
-----------------------
bt print calling stack of current thread
up goes up one frame in current thread's stack
up N goes up N frames in current thread's stack
dn goes down one frame in current thread's stack
dn N goes down N frames in current thread's stack
frame N set N as the current frame
info local prints information on local variables for current
function
IV.5 Directory & source file manipulation
-----------------------------------------
show dir
dir <pathname>
dir
symbolfile <pathname>
list lists 10 source lines from current position
list - lists 10 source lines before current position
list N lists 10 source lines from line N in current file
list <path>:N lists 10 source lines from line N in file <path>
list <id> lists 10 source lines of function <id>
list * N lists 10 source lines from address N
You can specify the end target (to change the 10 lines value) using
the ','. For example:
list 123, 234 lists source lines from line 123 up to line 234 in
current file
list foo.c:1,56 lists source lines from line 1 up to 56 in file foo.c
IV.6 Displaying
---------------
a display is an expression that's evaluated and printed after the
execution of any WineDbg command
display lists the active displays
info display (same as above command)
display <expr> adds a display for expression <expr>
display /fmt <expr> adds a display for expression <expr>. Printing
evaluated <expr> is done using the given format (see
print command for more on formats)
del display N deletes display #N
undisplay N (same as del display)
IV.7 Disassembly
----------------
disas disassemble from current position
disas <expr> disassemble from address <expr>
disas <expr>,<expr>disassembles code between addresses specified by
the two <expr>
IV.8 Information on Wine's internals
------------------------------------
info class <id> prints information on Windows's class <id>
walk class lists all Windows' class registered in Wine
info share lists all the dynamic libraries loaded the debugged
program (including .so files, NE and PE DLLs)
info module N prints information on module of handle N
walk module lists all modules loaded by debugged program
info queue N prints information on Wine's queue N
walk queue lists all queues allocated in Wine
info regs prints the value of CPU register
info segment N prints information on segment N
info segment lists all allocated segments
info stack prints the values on top of the stack
info map lists all virtual mappings used by the debugged
program
info wnd N prints information of Window of handle N
walk wnd lists all the window hierarchy starting from the
desktop window
walk wnd N lists all the window hierarchy starting from the
window of handle N
walk process lists all w-processes in Wine session
walk thread lists all w-threads in Wine session
walk modref (no longer avail)
IV.9 Memory (reading, writing, typing)
x <expr> examines memory at <expr> address
x /fmt <expr> examines memory at <expr> address using format /fmt
print <expr> prints the value of <expr> (possibly using its type)
print /fmt <expr> prints the value of <expr> (possibly using its
type)
set <lval>=<expr> writes the value of <expr> in <lval>
whatis <expr> prints the C type of expression <expr>
/fmt is either /<letter> or /<count><letter>
letter can be
s => an ASCII string
u => an Unicode UTF16 string
i => instructions (disassemble)
x => 32 bit unsigned hexadecimal integer
d => 32 bit signed decimal integer
w => 16 bit unsigned hexadecimal integer
c => character (only printable 0x20-0x7f are actually
printed)
b => 8 bit unsigned hexadecimal integer
V Other debuggers
=================
V.1 Using other Unix debuggers
------------------------------
You can also use other debuggers (like gdb), but you must be aware of
a few items:
- you need to attach the unix debugger to the correct unix process
(representing the correct windows thread) (you can "guess" it from a
'ps fax' for example: When running the emulator, usually the first
two upids are for the Windows' application running the desktop, the
first thread of the application is generally the third upid; when
running a WineLib program, the first thread of the application is
generally the first upid)
Note: even if latest gdb implements the notion of threads, it won't
work with Wine because the thread abstraction used for implementing
Windows' thread is not 100% mapped onto the linux posix threads
implementation. It means that you'll have to spawn a different gdb
session for each Windows' thread you wish to debug.
V.2 Using other Windows debuggers
---------------------------------
You can use any Windows' debugging API compliant debugger with
Wine. Some reports have been made of success with VisualStudio
debugger (in remote mode, only the hub runs in Wine).
GoVest fully runs in Wine.
V.3 Main differences between winedbg and regular Unix debuggers
---------------------------------------------------------------
+----------------------------------+---------------------------------+
| WineDbg | gdb |
+----------------------------------+---------------------------------+
|WineDbg debugs a Windows' process:|gdb debugs a Windows' thread: |
|+ the various threads will be |+ a separate gdb session is |
| handled by the same WineDbg | needed for each thread of |
| session | Windows' process |
|+ a breakpoint will be triggered |+ a breakpoint will be triggered |
| for any thread of the w-process | only for the w-thread debugged |
+----------------------------------+---------------------------------+
|WineDbg supports debug information|gdb supports debug information |
|from: |from: |
|+ stabs (standard Unix format) |+ stabs (standard Unix format) |
|+ Microsoft's C, CodeView, .DBG | |
+----------------------------------+---------------------------------+
VI Limitations
==============
+ 16 bit processes are not supported (but calls to 16 bit code in 32
bit applications is).
+ there are reports of debugger's freeze when loading large PDB files
Last updated: 6/14/2000 by ericP

129
documentation/x11drv
View File

@ -1,129 +0,0 @@
The X11 driver
--------------
Most Wine users run Wine under the windowing system known as X11.
During most of Wine's history, this was the only display driver
available, but in recent years, parts of Wine has been reorganized to
allow for other display drivers (although the only alternative
currently available is Patrik Stridvall's ncurses-based ttydrv, which
he claims works for displaying calc.exe). The display driver is chosen
with the "GraphicsDriver" option in the [wine] section of
wine.conf/.winerc, but I will only cover the x11drv in this document.
x11drv modes of operation
The x11drv consists of two conceptually distinct pieces, the graphics
driver (GDI part), and the windowing driver (USER part). Both of these
are linked into the libx11drv.so module, though (which you load with
the "GraphicsDriver" option). In Wine, running on X11, the graphics
driver must draw on drawables (window interiors) provided by the
windowing driver. This differs a bit from the Windows model, where the
windowing system creates and configures device contexts controlled by
the graphics driver, and applications are allowed to hook into this
relationship anywhere they like. Thus, to provide any reasonable
tradeoff between compatibility and usability, the x11drv has three
different modes of operation.
Unmanaged/Normal
The default. Window-manager-independent (any running window
manager is ignored completely). Window decorations (title bars,
borders, etc) are drawn by Wine to look and feel like the real
Windows. This is compatible with applications that depend on
being able to compute the exact sizes of any such decorations,
or that want to draw their own.
Managed
Specified by using the --managed command-line option or the
Managed wine.conf option (see below). Ordinary top-level frame
windows with thick borders, title bars, and system menus will
be managed by your window manager. This lets these applications
integrate better with the rest of your desktop, but may not
always work perfectly. (A rewrite of this mode of operation, to
make it more robust and less patchy, is highly desirable,
though, and is planned to be done before the Wine 1.0 release.)
Desktop-in-a-Box
Specified by using the --desktop command-line option (with a
geometry, e.g. --desktop 800x600 for a such-sized desktop, or
even --desktop 800x600+0+0 to automatically position the
desktop at the upper-left corner of the display). This is the
mode most compatible with the Windows model. All application
windows will just be Wine-drawn windows inside the
Wine-provided desktop window (which will itself be managed by
your window manager), and Windows applications can roam freely
within this virtual workspace and think they own it all,
without disturbing your other X apps.
The [x11drv] section
AllocSystemColors
Applies only if you have a palette-based display, i.e. if your
X server is set to a depth of 8bpp, and if you haven't
requested a private color map. It specifies the maximum number
of shared colormap cells (palette entries) Wine should occupy.
The higher this value, the less colors will be available to
other applications.
PrivateColorMap
Applies only if you have a palette-based display, i.e. if your
X server is set to a depth of 8bpp. It specifies that you don't
want to use the shared color map, but a private color map,
where all 256 colors are available. The disadvantage is that
Wine's private color map is only seen while the mouse pointer
is inside a Wine window, so psychedelic flashing and funky
colors will become routine if you use the mouse a lot.
PerfectGraphics
This option only determines whether fast X11 routines or exact
Wine routines will be used for certain ROP codes in blit
operations. Most users won't notice any difference.
ScreenDepth
Applies only to multi-depth displays. It specifies which of the
available depths Wine should use (and tell Windows apps about).
Display
This specifies which X11 display to use, and if specified, will
override both the DISPLAY environment variable and the
--display command-line option.
Managed
Wine can let frame windows be managed by your window manager.
This option specifies whether you want that by default.
UseDGA
This specifies whether you want DirectDraw to use XFree86's
Direct Graphics Architecture (DGA), which is able to take over
the entire display and run the game full-screen at maximum
speed. (With DGA1 (XFree86 3.x), you still have to configure
the X server to the game's requested bpp first, but with DGA2
(XFree86 4.x), runtime depth-switching may be possible,
depending on your driver's capabilities.) But be aware that if
Wine crashes while in DGA mode, it may not be possible to
regain control over your computer without rebooting. DGA
normally requires either root privileges or read/write access
to /dev/mem.
UseXShm
If you don't want DirectX to use DGA, you can at least use X
Shared Memory extensions (XShm). It is much slower than DGA,
since the app doesn't have direct access to the physical frame
buffer, but using shared memory to draw the frame is at least
faster than sending the data through the standard X11 socket,
even though Wine's XShm support is still known to crash
sometimes.
DXGrab
If you don't use DGA, you may want an alternative means to
convince the mouse cursor to stay within the game window. This
option does that. Of course, as with DGA, if Wine crashes,
you're in trouble (although not as badly as in the DGA case,
since you can still use the keyboard to get out of X).
DesktopDoubleBuffered
Applies only if you use the --desktop command-line option to
run in a desktop window. Specifies whether to create the
desktop window with a double-buffered visual, something most
OpenGL games need to run correctly.
- Ove Kåven