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         written by ???
  10       </para>
  11       <para>
  12         (Extracted from <filename>wine/documentation/how-to-port</filename>)
  13       </para>
  14
  15       <sect2>
  16         <title>What is this?</title>
  17
  18         <para>
  19           This note is a short description of:
  20         </para>
  21
  22         <itemizedlist>
  23           <listitem>
  24             <para>How to port Wine to your favourite operating system</para>
  25           </listitem>
  26           <listitem>
  27             <para>Why you probably shouldn't use <symbol>#ifdef MyOS</symbol></para>
  28           </listitem>
  29           <listitem>
  30             <para>What to do instead.</para>
  31           </listitem>
  32         </itemizedlist>
  33
  34         <para>
  35           This document does not say a thing about how to port Wine to
  36           non-386 operating systems, though.  You would need a CPU
  37           emulator.  Let's get Wine into a better shape on 386 first,
  38           OK?
  39         </para>
  40       </sect2>
  41
  42       <sect2>
  43         <title>Why <symbol>#ifdef MyOS</symbol> is probably a mistake.</title>
  44
  45         <para>
  46           Operating systems change.  Maybe yours doesn't have the
  47           <filename>foo.h</filename> header, but maybe a future
  48           version will have it.  If you want to <symbol>#include
  49             &lt;foo.h&gt;</symbol>, it doesn't matter what operating
  50           system you are using; it only matters whether
  51           <filename>foo.h</filename> is there.
  52         </para>
  53         <para>
  54           Furthermore, operating systems change names or "fork" into
  55           several ones.  An <symbol>#ifdef MyOs</symbol> will break
  56           over time.
  57         </para>
  58         <para>
  59           If you use the feature of <command>autoconf</command> -- the
  60           Gnu auto-configuration utility -- wisely, you will help
  61           future porters automatically because your changes will test
  62           for <emphasis>features</emphasis>, not names of operating
  63           systems.  A feature can be many things:
  64         </para>
  65
  66         <itemizedlist>
  67           <listitem>
  68             <para>existance of a header file</para>
  69           </listitem>
  70           <listitem>
  71             <para>existance of a library function</para>
  72           </listitem>
  73           <listitem>
  74             <para>existance of libraries</para>
  75           </listitem>
  76           <listitem>
  77             <para>bugs in header files, library functions, the compiler, ...</para>
  78           </listitem>
  79           <listitem>
  80             <para>(you name it)</para>
  81           </listitem>
  82         </itemizedlist>
  83         <para>
  84           You will need Gnu Autoconf, which you can get from your
  85           friendly Gnu mirror.  This program takes Wine's
  86           <filename>configure.in</filename> file and produces a
  87           <filename>configure</filename> shell script that users use
  88           to configure Wine to their system.
  89         </para>
  90         <para>
  91           There <emphasis>are</emphasis> exceptions to the "avoid
  92           <symbol>#ifdef MyOS</symbol>" rule. Wine, for example, needs
  93           the internals of the signal stack -- that cannot easily be
  94           described in terms of features.
  95         </para>
  96         <para>
  97           Let's now turn to specific porting problems and how to solve
  98           them.
  99         </para>
 100       </sect2>
 101
 102       <sect2>
 103         <title>MyOS doesn't have the <filename>foo.h</filename> header!</title>
 104
 105         <para>
 106           This first step is to make <command>autoconf</command> check
 107           for this header. In <filename>configure.in</filename> you
 108           add a segment like this in the section that checks for
 109           header files (search for "header files"):
 110         </para>
 111         <programlisting>
 112 AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
 113         </programlisting>
 114         <para>
 115           If your operating system supports a header file with the
 116           same contents but a different name, say
 117           <filename>bar.h</filename>, add a check for that also.
 118         </para>
 119         <para>
 120           Now you can change
 121         </para>
 122         <programlisting>
 123 #include &lt;foo.h&gt;
 124         </programlisting>
 125         <para>
 126           to
 127         </para>
 128         <programlisting>
 129 #ifdef HAVE_FOO_H
 130 #include &lt;foo.h&gt;
 131 #elif defined (HAVE_BAR_H)
 132 #include &lt;bar.h&gt;
 133 #endif
 134         </programlisting>
 135         <para>
 136           If your system doesn't have a corresponding header file even
 137           though it has the library functions being used, you might
 138           have to add an <symbol>#else</symbol> section to the
 139           conditional.  Avoid this if you can.
 140         </para>
 141         <para>
 142           You will also need to add <symbol>#undef HAVE_FOO_H</symbol>
 143           (etc.) to <filename>include/config.h.in</filename>
 144         </para>
 145         <para>
 146           Finish up with <command>make configure</command> and
 147           <command>./configure</command>.
 148         </para>
 149       </sect2>
 150
 151       <sect2>
 152         <title>MyOS doesn't have the <function>bar</function> function!</title>
 153
 154         <para>
 155           A typical example of this is the
 156           <function>memmove</function> function.  To solve this
 157           problem you would add <function>memmove</function> to the
 158           list of functions that <command>autoconf</command> checks
 159           for.  In <filename>configure.in</filename> you search for
 160           <function>AC_CHECK_FUNCS</function> and add
 161           <function>memmove</function>.  (You will notice that someone
 162           already did this for this particular function.)
 163         </para>
 164         <para>
 165           Secondly, you will also need to add <symbol>#undef
 166             HAVE_BAR</symbol> to
 167           <filename>include/config.h.in</filename>
 168         </para>
 169         <para>
 170           The next step depends on the nature of the missing function.
 171         </para>
 172
 173         <variablelist>
 174           <varlistentry>
 175             <term>Case 1:</term>
 176             <listitem>
 177               <para>
 178                 It's easy to write a complete implementation of the
 179                 function.  (<function>memmove</function> belongs to
 180                 this case.)
 181               </para>
 182               <para>
 183                 You add your implementation in
 184                 <filename>misc/port.c</filename> surrounded by
 185                 <symbol>#ifndef HAVE_MEMMOVE</symbol> and
 186                 <symbol>#endif</symbol>.
 187               </para>
 188               <para>
 189                 You might have to add a prototype for your function.
 190                 If so, <filename>include/miscemu.h</filename> might be the place.  Don't
 191                 forget to protect that definition by <symbol>#ifndef
 192                   HAVE_MEMMOVE</symbol> and <symbol>#endif</symbol> also!
 193               </para>
 194             </listitem>
 195           </varlistentry>
 196           <varlistentry>
 197             <term>Case 2:</term>
 198             <listitem>
 199               <para>
 200                 A general implementation is hard, but Wine is only
 201                 using a special case.
 202               </para>
 203               <para>
 204                 An example is the various <function>wait</function>
 205                 calls used in <function>SIGNAL_child</function> from
 206                 <filename>loader/signal.c</filename>.  Here we have a
 207                 multi-branch case on features:
 208               </para>
 209               <programlisting>
 210 #ifdef HAVE_THIS
 211 ...
 212 #elif defined (HAVE_THAT)
 213 ...
 214 #elif defined (HAVE_SOMETHING_ELSE)
 215 ...
 216 #endif
 217               </programlisting>
 218               <para>
 219                 Note that this is very different from testing on
 220                 operating systems.  If a new version of your operating
 221                 systems comes out and adds a new function, this code
 222                 will magically start using it.
 223               </para>
 224             </listitem>
 225           </varlistentry>
 226         </variablelist>
 227         <para>
 228           Finish up with <command>make configure</command> and
 229           <command>./configure</command>.
 230         </para>
 231
 232       </sect2>
 233     </sect1>
 234
 235     <sect1 id="os2-wine">
 236       <title>Running & Compiling WINE in OS/2</title>
 237
 238       <para>
 239         Written by &name-robert-pouliot; <email>&email-robert-pouliot;</email>,
 240         January 9, 1997
 241       </para>
 242       <para>
 243         (Extracted from <filename>wine/documentation/wine_os2</filename>)
 244       </para>
 245
 246       <para>
 247         If you want to help the port of WINE to OS/2, send me a
 248         message at <email>krynos@clic.net</email> I currently don't
 249         want beta testers. It must work before we can test it.
 250       </para>
 251       <para>
 252         Here is what you need to (try to) compile Wine for OS/2:
 253       </para>
 254
 255       <itemizedlist>
 256         <listitem>
 257           <para>EMX 0.9c (fix 2)</para>
 258         </listitem>
 259         <listitem>
 260           <para>XFree86 3.2 OS/2 (with development libraries)</para>
 261         </listitem>
 262         <listitem>
 263           <para>
 264             <command>bash</command>, gnu <command>make</command>,
 265             <command>grep</command>, <command>tar</command>,
 266             <command>bison</command>, <command>flex</command>
 267           </para>
 268         </listitem>
 269         <listitem>
 270           <para><command>sed</command> (a working copy of)</para>
 271         </listitem>
 272         <listitem>
 273           <para><command>diff</command> and <command>patch</command>
 274             are recommended</para>
 275         </listitem>
 276         <listitem>
 277           <para>Lots of disk space (about 40-50 megs after EMX and XFree installed)</para>
 278         </listitem>
 279       </itemizedlist>
 280
 281       <para>
 282         To compile:
 283       </para>
 284
 285       <screen>
 286 <prompt>$ </prompt><userinput>sh</userinput>
 287 <prompt>$ </prompt><userinput>tools/make_os2.sh</userinput>
 288 <prompt>$ </prompt><userinput>make depend</userinput>
 289 <prompt>$ </prompt><userinput>make</userinput>
 290 <prompt>$ </prompt><userinput>emxbind wine</userinput>
 291       </screen>
 292
 293       <para>
 294         Currently:
 295       </para>
 296
 297       <itemizedlist>
 298         <listitem>
 299           <para><command>configure</command> and <command>make depend</command> work...</para>
 300         </listitem>
 301         <listitem>
 302           <para><command>make</command> compiles (with a modified
 303             Linux <filename>mman.h</filename>), but doesn't
 304             link.</para>
 305         </listitem>
 306         <listitem>
 307           <para>signal handling is horrible... (if any)</para>
 308         </listitem>
 309         <listitem>
 310           <para>EMX doesn't support <function>mmap</function> (and
 311             related), SysV IPC and <function>stafs()</function></para>
 312         </listitem>
 313         <listitem>
 314           <para>
 315             XFree86/OS2 3.2 doesn't support
 316             <function>XShmQueryExtension()</function> and
 317             <function>XShmPixmapFormat()</function> due to the same
 318             lack in EMX...
 319           </para>
 320         </listitem>
 321       </itemizedlist>
 322
 323       <para>
 324         What needs to be redone:
 325       </para>
 326
 327       <itemizedlist>
 328         <listitem>
 329           <para>LDT (using <function>DosAllocSeg</function> in
 330             <filename>memory/ldt.c</filename>) *</para>
 331         </listitem>
 332         <listitem>
 333           <para>Implement <function>mmap()</function> and SysV IPC in EMX *</para>
 334         </listitem>
 335         <listitem>
 336           <para>File functions, </para>
 337         </listitem>
 338         <listitem>
 339           <para>I/O access (do it!),</para>
 340         </listitem>
 341         <listitem>
 342           <para>Communication (modem),</para>
 343         </listitem>
 344         <listitem>
 345           <para>Interrupt (if int unknown, call current RealMode one...), </para>
 346         </listitem>
 347         <listitem>
 348           <para>
 349             Verify that everything is thread safe (how does Win95/NT handle multi-thread?),
 350           </para>
 351         </listitem>
 352         <listitem>
 353           <para>
 354             Move X functions in some files (and make a wrapper, to use PM instead latter),
 355           </para>
 356         </listitem>
 357         <listitem>
 358           <para>Return right CPU type, </para>
 359         </listitem>
 360         <listitem>
 361           <para>Make winsock work</para>
 362         </listitem>
 363       </itemizedlist>
 364
 365       <para>
 366         The good things:
 367       </para>
 368
 369       <itemizedlist>
 370         <listitem>
 371           <para>OS/2 have DOS interrupts</para>
 372         </listitem>
 373         <listitem>
 374           <para>OS/2 have I/O port access</para>
 375         </listitem>
 376         <listitem>
 377           <para>OS/2 have multi-thread</para>
 378         </listitem>
 379         <listitem>
 380           <para>Merlin have Open32 (to be used later...)</para>
 381         </listitem>
 382       </itemizedlist>
 383     </sect1>
 384
 385     </chapter>
 386
 387 <!-- Keep this comment at the end of the file
 388 Local variables:
 389 mode: sgml
 390 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
 391 End:
 392 -->