documentation/porting.sgml

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