Changed default paper size to letter.

[wine] / documentation / winelib-intro.sgml

  <chapter id="winelib-introduction">
    <title id="introduction.title">Winelib Introduction</title>

    <sect1>
      <title>What is Winelib?</title>

      <para>
        Winelib is a development toolkit which allows you to compile your 
        Windows applications on Unix.
      </para>
      <para>
        Most of Winelib's code consists of the Win32 API implementation. 
        Fortunately this part is 100 percent shared with Wine. The remainder 
        consists of Windows compatible headers and tools like the resource 
        compiler (and even these are used when compiling Wine).
      </para>
      <para>
        Thanks to the above, Winelib supports most C and C++ 32bit source code, 
        resource and message files, and can generate graphical or console 
        applications as well as dynamic libraries.
      </para>
      <para>
        What is not supported is 16bit source code as the types it depends on 
        (especially segmented pointers) are not supported by Unix compilers. 
        Also missing are some of the more exotic features of Microsoft's 
        compiler like native COM support and structured exception handling. 
        So you may need to perform some modifications in your code when 
        recompiling your application with Winelib. This guide is here to help 
        you in this task.
      </para>
      <para>
        What you gain by recompiling your application with Winelib is the 
        ability to make calls to Unix APIs, directly from your 
        Windows source code. This allows for a better integration with the 
        Unix environment than is allowed by runnning an unmodified Windows 
        application running in Wine. Another benefit is that a Winelib 
        application can relatively easily be recompiled on a non-Intel 
        architecture and run there without the need for a slow software 
        emulation of the processor.
      </para>
    </sect1>

    <sect1 id="winelib-requirements">
      <title id="requirements.title">System requirements</title>
      <para>
        The requirements for Winelib are similar to those for Wine.
      </para>
      <para>
        Basically if you can run Wine on your computer then you can run 
        Winelib. But the converse is not true. You can also build Winelib 
        and Winelib applications on platforms not supported by Wine, 
        typically platforms with a non i386 processor. But this is still 
        pretty much an uncharted territory. It would be more reasonable to 
        first target one of the more mundane i386-based platforms first.
      </para>
      <para>
        The main difference is that the compiler becomes much more important. 
        It is highly recommended that you use gcc, g++, 
        and the GNU binutils. The more recent your gcc compiler the better. 
        For any serious amount of code you should not consider anything older 
        than gcc 2.95.2. The latest gcc snapshots contain some useful bug 
        fixes and much better support for anonymous structs and unions. This 
        can help reduce the number of changes you have to do in your code but 
        these are not stable releases of the compiler so you may not want to 
        use them in production.
      </para>
    </sect1>

    <sect1 id="winelib-getting-started">
      <title id="getting-started.title">Getting Started</title>

      <sect2 id="winemaker-introduction">
        <title id="winemaker-introduction.title">Winemaker introduction</title>
        <para>
          So what is needed to compile a Windows application with Winelib?
          Well, it really depends on the complexity of your application but 
          here are some issues that are shared by all applications:
        </para>
        <itemizedlist>
          <listitem>
            <para>
              the case of your files may be bad. For example they could be 
              in all caps: <filename>HELLO.C</filename>. It's not very nice to 
              work with and probably not what you intended.
            </para>
          </listitem>
          <listitem>
            <para>
              then the case of the filenames in your include statements may be 
              wrong: maybe they include 'Windows.h' instead of 'windows.h'.
            </para>
          </listitem>
          <listitem>
            <para>
              your include statements may use '\' instead of '/'. '\' is not 
              recognized by Unix compilers while '/' is recognized in both 
              environments.
            </para>
          </listitem>
          <listitem>
            <para>
              you will need to perform the usual Dos to Unix text file conversion
              otherwise you'll get in trouble when the compiler considers that 
              your '\' is not at the end of the line since it is followed by a 
              pesky carriage return.
            </para>
          </listitem>
          <listitem>
            <para>
              you will have to write new makefiles.
            </para>
          </listitem>
        </itemizedlist>

        <para>
          The best way to take care of all these issues is to use winemaker.
        </para>
        <para>
          Winemaker is a perl script which is designed to help you bootstrap 
          the conversion of your Windows projects to Winelib. In order to do 
          this it will go analyze your code, fixing the issues listed above  
          and generate autoconf-based Makefiles.
        </para>
        <para>
          Let's suppose that Wine/Winelib has been installed in the 
          <filename class="Directory">/usr/local/wine</filename>
          directory, and that you are already in the top directory of your 
          sources. Then converting your project to Winelib may be as simple 
          as just running the three commands below:
        </para>
        <programlisting>
          $ winemaker --lower-uppercase .
          $ ./configure --with-wine=/usr/local/wine
          $ make
        </programlisting>

        <para>
          But of course things are not always that simple which is why we have 
          this guide at all.
        </para>
      </sect2>

      <sect2 id="winemaker-guide">
        <title id="winemaker-guide.title">Step by step guide</title>

        <para>
          Let's retrace the steps above in more details.
        </para>
        <variablelist>
          <varlistentry>
            <term><option>Getting the source</option></term>
            <listitem>
              <para>
                First if you can try to get the sources together with the 
                executables/libraries that they build. In the current state of 
                winemaker having these around can help it guess what it is that 
                your project is trying to build. Later, when it is able to 
                understand Visual C++ projects, and if you use them, this will 
                no longer be necessary. Usually the executables and libraries 
                are in a <filename class="Directory">Release</filename> or 
                <filename class="Directory">Debug</filename> subdirectory of the 
                directory where the sources are. So it's best if you can 
                transfer the source files and either of these directories to 
                Linux. Note that you don't need to transfer the 
                <filename>.obj</filename>, <filename>.pch</filename>, 
                <filename>.sbr</filename> and other files that also reside in 
                these directories; especially as they tend to be quite big.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><option>cd &lt;root_dir&gt;</option></term>
            <listitem>
              <para>
                Then go to the root directory where are your source files. 
                Winemaker can deal with a whole directory hierarchy at once so 
                you don't need to go into a leaf directory, quite the contrary. 
                Winemaker will automatically generate makefiles in each 
                directory where one is required, and will generate a global 
                makefile so that you can rebuild all your executables and 
                libraries with a single <command>make</command> command.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><option>Making the source writable</option></term>
            <listitem>
              <para>
                Then make sure you have write access to your sources. It may 
                sound obvious, but if you copied your source files from a 
                CD-ROM or if they are in Source Safe on Windows, chances are 
                that they will be read-only. 
                But Winemaker needs write access so that it can fix them. You 
                can arrange that by running <command>chmod -R u+w .</command>. 
                Also you will want to make sure that you have a backup copy of 
                your sources in case something went horribly wrong, or more 
                likely, just for reference at a later point. If you use a 
                version control system you're already covered.
              </para>
              <para>
                If you have already modified your source files and you want
                to make sure that winemaker will not make further changes to
                them then you can use the --nosource-fix option to protect 
                them.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><option>Running winemaker</option></term>
            <listitem>
              <para>
                Then you'll run winemaker. Here are the options you will most 
                likely want to use.
              </para>
              <variablelist>
                <varlistentry>
                  <term><option>--lower-uppercase</option></term>
                  <term><option>--lower-all</option></term>
                  <listitem>
                    <para>
                      These options specify how to deal with files, and 
                      directories, that have an 'incorrect' case. 
                      <option>--lower-uppercase</option> specifies they should 
                      only be renamed if their name is all uppercase. So files 
                      that have a mixed case, like 'Hello.c' would not be 
                      renamed. <option>--lower-all</option> will rename any 
                      file. If neither is specified then no file or directory 
                      will be renamed, almost. As you will see 
                      <link linkend="renaming">later</link> winemaker may 
                      still have to rename some files.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term><option>--nobackup</option></term>
                  <listitem>
                    <para>
                      Winemaker normally makes a backup of all the files in which 
                      it does more than the standard Dos to Unix conversion. 
                      But if you already have (handy) copies of these files 
                      elsewhere you may not need these so you should use this 
                      option.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term><option>--dll</option></term>
                  <term><option>--console</option></term>
                  <listitem>
                    <para>
                      These option lets winemaker know what kind of target you are 
                      building. If you have the windows library in your source 
                      hierarchy then you should not need to specify 
                      <option>--dll</option>. But if you have console executables 
                      then you will need to use the corresponding option.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term><option>--mfc</option></term>
                  <listitem>
                    <para>
                      This option tells winemaker that you are building an MFC 
                      application/library.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term><option>-Dmacro[=defn]</option></term>
                  <term><option>-Idir</option></term>
                  <term><option>-Ldir</option></term>
                  <term><option>-idll</option></term>
                  <term><option>-llibrary</option></term>
                  <listitem>
                    <para>
                      The <option>-i</option> specifies a Winelib library to 
                      import via the <link linkend="spec-file">spec file</> 
                      mechanism. Contrast this with the <option>-l</option> 
                      which specifies a Unix library to link with. The other 
                      options work the same way they would with a C 
                      compiler. All are applied to all the targets found. 
                      When specifying a directory with either 
                      <option>-I</option> or <option>-L</option>, winemaker 
                      will prefix a relative path with 
                      <literal>$(TOPDIRECTORY)/</literal> so that it is valid 
                      from any of the source directories. You can also use a 
                      variable in the path yourself if you wish (but don't 
                      forget to escape the '$'). For instance you could specify 
                      <literal>-I\$(WINELIB_INCLUDE_ROOT)/msvcrt</literal>.
                    </para>
                  </listitem>
                </varlistentry>
              </variablelist>
              <para>
                So your command may finally look like:
                <literal>winemaker --lower-uppercase -Imylib/include .</literal>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term id="renaming"><option>File renaming</option></term>
            <listitem>
              <para>
                When you execute winemaker it will first rename files to bring 
                their character case in line with your expectations and so that they can 
                be processed by the makefiles. This later category implies that 
                files with a non lowercase extension will be renamed so that the 
                extension is in lowercase. So, for instance, 
                <filename>HELLO.C</filename> will be renamed to 
                <filename>HELLO.c</filename>. Also if a file or directory name 
                contains a space or a dollar, then this 
                character will be replaced with an underscore. This is because 
                these characters cause problems with current versions of autoconf 
                (2.13) and make (3.79).
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><option>Source modifications and makefile generation</option></term>
            <listitem>
              <para>
                winemaker will then proceed to modify the source files so that 
                they will compile more readily with Winelib. As it does so it 
                may print warnings when it has to make a guess or identifies a 
                construct that it cannot correct. Finally it will generate the 
                autoconf-based makefiles. Once all this is done you can review 
                the changes that winemaker did to your files by using 
                <command>diff -uw</command>. For instance: 
                <command>diff -uw hello.c.bak hello.c</command>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><option>Running the configure script</option></term>
            <listitem>
              <para>
                Before you run <command>make</command> you must run the 
                autoconf <command>configure</command> script. The goal of this 
                step is to analyze your system and generate customized 
                makefiles from the <filename>Makefile.in</filename> files. This 
                is also when you have to tell where Winelib resides on your 
                system. If wine is installed in a single directory or you have 
                the Wine sources compiled somewhere then you can just run 
                <command>./configure --with-wine=/usr/local/bin</command> 
                or <command>./configure --with-wine=~/wine</command> 
                respectively.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><option>Running make</option></term>
            <listitem>
              <para>
                This is a pretty simple step: just type <command>make</command> 
                and voila, you should have all your executables and libraries. 
                If this did not work out, then it means that you will have to 
                read this guide further to:
                <itemizedlist>
                  <listitem>
                    <para>
                      review the <filename>Makefile.in</filename> files to 
                      adjust the default compilation and link options set by 
                      winemaker. See the <xref linkend="source-analysis" 
                                               endterm="source-analysis.title"> section for some hints.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      fix the portability issues in your sources. See 
                      <xref linkend="portability-issues" 
                            endterm="portability-issues.title"> for more details.
                    </para>
                  </listitem>
                </itemizedlist>
              </para>
              <para>
                If you find yourself modifying the Makefile.in to specify the
                location of the Wine header or library files then go back to
                the previous step (the configure script) and use the various
                --with-wine-* options to specify where they are.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>
    </sect1>
  </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
End:
-->