documentation/porting.sgml

   1   <chapter id="porting">
   2     <title>Porting Wine to new Platforms</title>
   3     <para>
   4         This document provides a few tips on porting Wine to your
   5         favorite (UNIX-based) operating system.
   6     </para>
   7
   8     <sect1 id="wine-porting">
   9       <title>Porting Wine to new Platforms</title>
  10       <sect2>
  11         <title>Why <symbol>#ifdef MyOS</symbol> is probably a mistake.</title>
  12
  13         <para>
  14           Operating systems change.  Maybe yours doesn't have the
  15           <filename>foo.h</filename> header, but maybe a future
  16           version will have it.  If you want to <symbol>#include
  17             &lt;foo.h&gt;</symbol>, it doesn't matter what operating
  18           system you are using; it only matters whether
  19           <filename>foo.h</filename> is there.
  20         </para>
  21         <para>
  22           Furthermore, operating systems change names or "fork" into
  23           several ones.  An <symbol>#ifdef MyOs</symbol> will break
  24           over time.
  25         </para>
  26         <para>
  27           If you use the feature of <command>autoconf</command> -- the
  28           Gnu auto-configuration utility -- wisely, you will help
  29           future porters automatically because your changes will test
  30           for <emphasis>features</emphasis>, not names of operating
  31           systems.  A feature can be many things:
  32         </para>
  33
  34         <itemizedlist>
  35           <listitem>
  36             <para>
  37               existence of a header file
  38             </para>
  39           </listitem>
  40           <listitem>
  41             <para>
  42               existence of a library function
  43             </para>
  44           </listitem>
  45           <listitem>
  46             <para>
  47               existence of libraries
  48             </para>
  49           </listitem>
  50           <listitem>
  51             <para>
  52               bugs in header files, library functions, the compiler, ...
  53             </para>
  54           </listitem>
  55         </itemizedlist>
  56         <para>
  57           You will need Gnu Autoconf, which you can get from your
  58           friendly Gnu mirror.  This program takes Wine's
  59           <filename>configure.ac</filename> file and produces a
  60           <filename>configure</filename> shell script that users use
  61           to configure Wine to their system.
  62         </para>
  63         <para>
  64           There <emphasis>are</emphasis> exceptions to the "avoid
  65           <symbol>#ifdef MyOS</symbol>" rule. Wine, for example, needs
  66           the internals of the signal stack -- that cannot easily be
  67           described in terms of features. Moreover, you can not use
  68           <filename>autoconf</filename>'s <symbol>HAVE_*</symbol>
  69           symbols in Wine's headers, as these may be used by Winelib
  70           users who may not be using a <filename>configure</filename>
  71           script.
  72         </para>
  73         <para>
  74           Let's now turn to specific porting problems and how to solve
  75           them.
  76         </para>
  77       </sect2>
  78
  79       <sect2>
  80         <title>MyOS doesn't have the <filename>foo.h</filename> header!</title>
  81
  82         <para>
  83           This first step is to make <command>autoconf</command> check
  84           for this header. In <filename>configure.in</filename> you
  85           add a segment like this in the section that checks for
  86           header files (search for "header files"):
  87         </para>
  88         <programlisting>
  89 AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
  90         </programlisting>
  91         <para>
  92           If your operating system supports a header file with the
  93           same contents but a different name, say
  94           <filename>bar.h</filename>, add a check for that also.
  95         </para>
  96         <para>
  97           Now you can change
  98         </para>
  99         <programlisting>
 100 #include &lt;foo.h&gt;
 101         </programlisting>
 102         <para>
 103           to
 104         </para>
 105         <programlisting>
 106 #ifdef HAVE_FOO_H
 107 #include &lt;foo.h&gt;
 108 #elif defined (HAVE_BAR_H)
 109 #include &lt;bar.h&gt;
 110 #endif
 111         </programlisting>
 112         <para>
 113           If your system doesn't have a corresponding header file even
 114           though it has the library functions being used, you might
 115           have to add an <symbol>#else</symbol> section to the
 116           conditional.  Avoid this if you can.
 117         </para>
 118         <para>
 119           You will also need to add <symbol>#undef HAVE_FOO_H</symbol>
 120           (etc.) to <filename>include/config.h.in</filename>
 121         </para>
 122         <para>
 123           Finish up with <command>make configure</command> and
 124           <command>./configure</command>.
 125         </para>
 126       </sect2>
 127
 128       <sect2>
 129         <title>MyOS doesn't have the <function>bar</function> function!</title>
 130
 131         <para>
 132           A typical example of this is the
 133           <function>memmove</function> function.  To solve this
 134           problem you would add <function>memmove</function> to the
 135           list of functions that <command>autoconf</command> checks
 136           for.  In <filename>configure.in</filename> you search for
 137           <function>AC_CHECK_FUNCS</function> and add
 138           <function>memmove</function>.  (You will notice that someone
 139           already did this for this particular function.)
 140         </para>
 141         <para>
 142           Secondly, you will also need to add <symbol>#undef
 143             HAVE_BAR</symbol> to
 144           <filename>include/config.h.in</filename>
 145         </para>
 146         <para>
 147           The next step depends on the nature of the missing function.
 148         </para>
 149
 150         <variablelist>
 151           <varlistentry>
 152             <term>Case 1:</term>
 153             <listitem>
 154               <para>
 155                 It's easy to write a complete implementation of the
 156                 function.  (<function>memmove</function> belongs to
 157                 this case.)
 158               </para>
 159               <para>
 160                 You add your implementation in
 161                 <filename>misc/port.c</filename> surrounded by
 162                 <symbol>#ifndef HAVE_MEMMOVE</symbol> and
 163                 <symbol>#endif</symbol>.
 164               </para>
 165               <para>
 166                 You might have to add a prototype for your function.
 167                 If so, <filename>include/miscemu.h</filename> might be the place.  Don't
 168                 forget to protect that definition by <symbol>#ifndef
 169                   HAVE_MEMMOVE</symbol> and <symbol>#endif</symbol> also!
 170               </para>
 171             </listitem>
 172           </varlistentry>
 173           <varlistentry>
 174             <term>Case 2:</term>
 175             <listitem>
 176               <para>
 177                 A general implementation is hard, but Wine is only
 178                 using a special case.
 179               </para>
 180               <para>
 181                 An example is the various <function>wait</function>
 182                 calls used in <function>SIGNAL_child</function> from
 183                 <filename>loader/signal.c</filename>.  Here we have a
 184                 multi-branch case on features:
 185               </para>
 186               <programlisting>
 187 #ifdef HAVE_THIS
 188 ...
 189 #elif defined (HAVE_THAT)
 190 ...
 191 #elif defined (HAVE_SOMETHING_ELSE)
 192 ...
 193 #endif
 194               </programlisting>
 195               <para>
 196                 Note that this is very different from testing on
 197                 operating systems.  If a new version of your operating
 198                 systems comes out and adds a new function, this code
 199                 will magically start using it.
 200               </para>
 201             </listitem>
 202           </varlistentry>
 203         </variablelist>
 204         <para>
 205           Finish up with <command>make configure</command> and
 206           <command>./configure</command>.
 207         </para>
 208
 209       </sect2>
 210     </sect1>
 211
 212     </chapter>
 213
 214 <!-- Keep this comment at the end of the file
 215 Local variables:
 216 mode: sgml
 217 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
 218 End:
 219 -->