wine/documentation/winedev-coding.sgml
2005-01-19 20:54:03 +00:00

514 lines
16 KiB
Text

<chapter id="codingpractice">
<title>Coding Practice</title>
<para>
This chapter describes the relevant coding practices in Wine,
that you should be aware of before doing any serious development
in Wine.
</para>
<sect1 id="patch-format">
<title>Patch Format</title>
<para>
Patches are submitted via email to the Wine patches mailing
list, <email>wine-patches@winehq.org</email>. Your patch
should include:
</para>
<itemizedlist>
<listitem>
<para>
A meaningful subject (very short description of patch)
</para>
</listitem>
<listitem>
<para>
A long (paragraph) description of what was wrong and what
is now better. (recommended)
</para>
</listitem>
<listitem>
<para>
A change log entry (short description of what was
changed).
</para>
</listitem>
<listitem>
<para>
The patch in <command>diff -u</command> format
</para>
</listitem>
</itemizedlist>
<para></para>
<para>
<command>cvs diff -u</command> works great for the common case
where a file is edited. However, if you add or remove a file
<command>cvs diff</command> will not report that correctly so
make sure you explicitly take care of this rare case.
</para>
<para>
For additions simply include them by appending the
<command>diff -u /dev/null /my/new/file</command> output of
them to any <command>cvs diff -u</command> output you may
have. Alternatively, use <command>diff -Nu olddir/
newdir/</command> in case of multiple new files to add.
</para>
<para>
For removals, clearly list the files in the description of the
patch.
</para>
<para>
Since wine is constantly changing due to development it is
strongly recommended that you use cvs for patches, if you
cannot use cvs for some reason, you can submit patches against
the latest tarball. To do this make a copy of the files that
you will be modifying and <command>diff -u</command> against
the old file. I.E.
</para>
<screen>
diff -u file.old file.c > file.txt
</screen>
</sect1>
<sect1 id="Style-notes">
<title>Some notes about style</title>
<para>
There are a few conventions about coding style that have
been adopted over the years of development. The rational for
these <quote>rules</quote> is explained for each one.
</para>
<itemizedlist>
<listitem>
<para>
No HTML mail, since patches should be in-lined and HTML
turns the patch into garbage. Also it is considered bad
etiquette as it uglifies the message, and is not viewable
by many of the subscribers.
</para>
</listitem>
<listitem>
<para>
Only one change set per patch. Patches should address only
one bug/problem at a time. If a lot of changes need to be
made then it is preferred to break it into a series of
patches. This makes it easier to find regressions.
</para>
</listitem>
<listitem>
<para>
Tabs are not forbidden but discouraged. A tab is defined
as 8 characters and the usual amount of indentation is 4
characters.
</para>
</listitem>
<listitem>
<para>
C++ style comments are discouraged since some compilers
choke on them.
</para>
</listitem>
<listitem>
<para>
Commenting out a block of code is usually done by
enclosing it in <command>#if 0 ... #endif</command>
Statements. For example.
</para>
<screen>
/* note about reason for commenting block */
#if 0
code
code /* comments */
code
#endif
</screen>
<para>
The reason for using this method is that it does not
require that you edit comments that may be inside the
block of code.
</para>
</listitem>
<listitem>
<para>
Patches should be in-lined (if you can configure your
email client to not wrap lines), or attached as plain text
attachments so they can be read inline. This may mean some
more work for you. However it allows others to review your
patch easily and decreases the chances of it being
overlooked or forgotten.
</para>
</listitem>
<listitem>
<para>
Code is usually limited to 80 columns. This helps prevent
mailers mangling patches by line wrap. Also it generally
makes code easier to read.
</para>
</listitem>
<listitem>
<para>
If the patch fixes a bug in Bugzilla please provide a link
to the bug in the comments of the patch. This will make it
easier for the maintainers of Bugzilla.
</para>
</listitem>
</itemizedlist>
<sect2 id="Inline-Attachments-with-OE">
<title>Inline attachments with Outlook Express</title>
<para>
Outlook Express is notorious for mangling
attachments. Giving the patch a <filename>.txt</filename>
extension and attaching will solve the problem for most
mailers including Outlook. Also, there is a way to enable
Outlook Express to send <filename>.diff</filename>
attachments.
</para>
<para>
You need the following two things to make it work.
</para>
<orderedlist>
<listitem>
<para>
Make sure that <filename>.diff</filename> files have
\r\n line ends, because if OE detects that there is no
\r\n line endings it switches to quoted-printable format
attachments.
</para>
</listitem>
<listitem>
<para>
Using regedit add key "Content Type"
with value "text/plain" to the
<filename>.diff</filename> extension under
HKEY_CLASSES_ROOT (same as for <filename>.txt</filename>
extension). This tells OE to use
Content-Type:&nbsp;text/plain instead of
application/octet-stream.
</para>
</listitem>
</orderedlist>
<para>
Item #1 is important. After you hit the "Send" button, go to
"Outbox" and using "Properties" verify the message source to
make sure that the mail has the correct format. You might want
to send several test emails to yourself too.
</para>
</sect2>
<sect2 id="Alexandre-Bottom-Line">
<title>Alexandre's Bottom Line</title>
<para>
<quote>The basic rules are: no attachments, no MIME crap, no
line wrapping, a single patch per mail. Basically if I can't
do <command>"cat raw_mail | patch -p0"</command> it's in the
wrong format.</quote>
</para>
</sect2>
</sect1>
<sect1 id="patch-quality">
<title>Quality Assurance</title>
<para>
(Or, "How do I get Alexandre to apply my patch quickly so I
can build on it and it will not go stale?")
</para>
<para>
Make sure your patch applies to the current CVS head
revisions. If a bunch of patches are committed to CVS that may
affect whether your patch will apply cleanly then verify that
your patch does apply! <command>cvs update</command> is your
friend!
</para>
<para>
Save yourself some embarrassment and run your patched code
against more than just your current test example. Experience
will tell you how much effort to apply here. If there are
any conformance tests for the code you're working on, run them
and make sure they still pass after your patch is applied. Running
tests can be done by running <command>make test</command>. You may
need to run <command>make testclean</command> to undo the results
of a previous test run. See the <quote>testing</quote> guide for
more details on Wine's conformance tests.
</para>
</sect1>
<sect1 id="porting">
<title>Porting Wine to new Platforms</title>
<para>
This document provides a few tips on porting Wine to your
favorite (UNIX-based) operating system.
</para>
<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>
existence of a header file
</para>
</listitem>
<listitem>
<para>
existence of a library function
</para>
</listitem>
<listitem>
<para>
existence of libraries
</para>
</listitem>
<listitem>
<para>
bugs in header files, library functions, the compiler, ...
</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.ac</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. Moreover, you can not use
<filename>autoconf</filename>'s <symbol>HAVE_*</symbol>
symbols in Wine's headers, as these may be used by Winelib
users who may not be using a <filename>configure</filename>
script.
</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="adding-languages">
<title>Adding New Languages</title>
<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. Adding new translations is not hard as it
requires no programming knowledge or special skills.
</para>
<para>
Language dependent resources reside in files
named <filename>somefile_Xx.rc</filename> or
<filename>Xx.rc</filename>, where <literal>Xx</literal>
is your language abbreviation (look for it in
<filename>include/winnls.h</filename>). These are included
in a master file named <filename>somefile.rc</filename> or
<filename>rsrc.rc</filename>, located in the same
directory as the language files.
</para>
<para>
To add a new language to one of these resources you
need to make a copy of the English resource (located
in the <filename>somefile_En.rc</filename> file) over to
your <filename>somefile_Xx.rc</filename> file, include this
file in the master <filename>somefile.rc</filename> file,
and edit the new file to translate the English text.
You may also need to rearrange some of the controls
to better fit the newly translated strings. Test your changes
to make sure they properly layout on the screen.
</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 English. In particular,
items within one menu should have different highlighted
letters.
</para>
<para>
To get a list of the files that need translating,
run the following command in the root of your Wine tree:
<command>find -name "*En.rc"</command>.
</para>
<para>
When adding a new language, also make sure the parameters
defined in <filename>./dlls/kernel/nls/*.nls</filename>
fit your local habits and language.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
End:
-->