wine/documentation/winedev-coding.sgml

  <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:
-->