<qandadiv id="porting">
<title>&title-porting;</title>

<!-- QA template -->
<!--
<qandaentry>
<question>
<para></para>
</question>
<answer>
<para></para>
</answer>
</qandaentry>
-->


<qandaentry>
<question id="q-ported-software-list">
<para>Is there a list of software that has been ported to &project;?</para>
</question>

<answer>
<para>
Look in Cygwin's setup program for packages in the X11 category.
</para>
</answer>
</qandaentry>


<qandaentry>
<question id="q-how-to-port">
<para>How do I start porting software to &project;?</para>
</question>

<answer>
<para>&project; provides a software interface that is very similar to
the software interface provided by &linux; and other &unix; systems.
Most software packages will compile on &project; without any changes
at all.  To begin with, try to compile a given software package
following that package's compilation instructions for &linux;.</para>
</answer>
</qandaentry>


<qandaentry>
<question id="q-common-porting-problems">
<para>Are there common problems encountered when porting software to
&project;?</para>
</question>

<answer>
<para>One common problem encountered when porting software to
&project; is due to &cygwin;'s inability to distinguish between files
with the same name but different capitalization (e.g. XvMC.h and
xvmc.h), which is due to a &windows;' limitation.</para>

<example id="example-include-problems">
<title>Include Problems</title>

<para>This example is based off an error that actually occurred in the
source code tree in
<filename>xc/programs/Xserver/Xext/xvmc.c</filename>.
<filename>xvmc.c</filename> included <filename>XvMC.h</filename>, as
shown below:</para>

<programlisting>
#include "XvMC.h"
</programlisting>

<para>The intention was to include the file
<filename>xc/include/extensions/XvMC.h</filename>.  Unfortunately,
there was a file named
<filename>xc/programs/Xserver/Xext/xvmc.h</filename> that ended up
getting included instead of the desired file, because the precompiler
searched the local directory, <filename
class="directory">xc/programs/Xserver/Xext/</filename>, before
searching the rest of the include path.  &cygwin; can't distinguish
between <filename>XvMC.h</filename> and <filename>xvmc.h</filename>,
so <filename>xvmc.h</filename> ended up being included in
<filename>xvmc.c</filename>.  The build process on &cygwin; broke
because the contents of <filename>XvMC.h</filename> were entirely
different than the contents of <filename>xvmc.h</filename>.</para>

<para>The solution was to change the include to specifically reference
the desired header:</para>

<programlisting>
#include "../../../include/extensions/XvMC.h"
</programlisting>

</example>
</answer>
</qandaentry>

<qandaentry>
<question id="q-opengl-link-problems">
<para>Problems linking OpenGL applications? Undefined reference to _gl<emphasis>something</emphasis>?</para>
</question>

<answer>
<para>
Cygwin has two OpenGL implementations:
</para>

<orderedlist>

<listitem>
<para>
headers in /usr/include/w32api/GL, libraries (-lglut32 -lglu32 -lopengl32) from the opengl and w32api packages
which are for displaying
OpenGL graphics directly through the native Windows interface (Win32) without any X server
</para>
</listitem>

<listitem>
<para>
headers in /usr/include/GL, libraries (-lglut -lglu -lgl) from the Mesa libGL packages
(libGL-devel, libGL1, libGLU-devel, libGLU1, libglut-devel, libglut3, freeglut)
which are for displaying OpenGL graphics through an X server.
</para>
</listitem>

</orderedlist>

<para>
These are incompatible, even the headers (as the native OpenGL API has the stdcall calling convention on x86),
so you must exercise care if you have both sets of devel packages installed.  An application must be built using only one of these.
</para>

<itemizedlist spacing="compact">
<listitem><para>X applications using GLX must be built using option 2.</para></listitem>
<listitem><para>Applications using GLUT have a choice.</para></listitem>
<listitem><para>Applications using the WGL API must be built using option 1.</para></listitem>
</itemizedlist>

<para>
(Words adapted from an email by André Bleau)
</para>

</answer>
</qandaentry>

</qandadiv>
 
