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