wine/documentation/porting.sgml

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

    <sect1 id="wine-porting">
      <title>Porting Wine to new Platforms</title>
      <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>

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