documentation/winelib-intro.sgml

   1   <chapter id="winelib-introduction">
   2     <title id="introduction.title">Winelib Introduction</title>
   3
   4     <sect1 id="winelib-whatis">
   5       <title>What is Winelib?</title>
   6
   7       <para>
   8         Winelib is a development toolkit which allows you to compile your
   9         Windows applications on Unix.
  10       </para>
  11       <para>
  12         Most of Winelib's code consists of the Win32 API implementation.
  13         Fortunately this part is 100 percent shared with Wine. The remainder
  14         consists of Windows compatible headers and tools like the resource
  15         compiler (and even these are used when compiling Wine).
  16       </para>
  17       <para>
  18         Thanks to the above, Winelib supports most C and C++ 32bit source code,
  19         resource and message files, and can generate graphical or console
  20         applications as well as dynamic libraries.
  21       </para>
  22       <para>
  23         What is not supported is 16bit source code as the types it depends on
  24         (especially segmented pointers) are not supported by Unix compilers.
  25         Also missing are some of the more exotic features of Microsoft's
  26         compiler like native COM support and structured exception handling.
  27         So you may need to perform some modifications in your code when
  28         recompiling your application with Winelib. This guide is here to help
  29         you in this task.
  30       </para>
  31       <para>
  32         What you gain by recompiling your application with Winelib is the
  33         ability to make calls to Unix APIs, directly from your
  34         Windows source code. This allows for a better integration with the
  35         Unix environment than is allowed by running an unmodified Windows
  36         application running in Wine. Another benefit is that a Winelib
  37         application can relatively easily be recompiled on a non-Intel
  38         architecture and run there without the need for a slow software
  39         emulation of the processor.
  40       </para>
  41     </sect1>
  42
  43     <sect1 id="winelib-requirements">
  44       <title id="requirements.title">System requirements</title>
  45       <para>
  46         The requirements for Winelib are similar to those for Wine.
  47       </para>
  48       <para>
  49         Basically if you can run Wine on your computer then you can run
  50         Winelib. But the converse is not true. You can also build Winelib
  51         and Winelib applications on platforms not supported by Wine,
  52         typically platforms with a non i386 processor. But this is still
  53         pretty much uncharted territory. It would be more reasonable to
  54         target one of the more mundane i386-based platforms first.
  55       </para>
  56       <para>
  57         The main difference is that the compiler becomes much more important.
  58         It is highly recommended that you use gcc, g++, and the GNU binutils.
  59         The more recent your gcc compiler the better.
  60         For any serious amount of code you should not consider anything older
  61         than gcc 2.95.2. The latest gcc snapshots contain some useful bug
  62         fixes and much better support for anonymous structs and unions. This
  63         can help reduce the number of changes you have to do in your code but
  64         these are not stable releases of the compiler so you may not want to
  65         use them in production.
  66       </para>
  67     </sect1>
  68
  69     <sect1 id="winelib-getting-started">
  70       <title id="getting-started.title">Getting Started</title>
  71
  72       <sect2 id="winemaker-introduction">
  73         <title id="winemaker-introduction.title">Winemaker introduction</title>
  74         <para>
  75           So what is needed to compile a Windows application with Winelib?
  76           Well, it really depends on the complexity of your application but
  77           here are some issues that are shared by all applications:
  78         </para>
  79         <itemizedlist>
  80           <listitem>
  81             <para>
  82               the case of your files may be bad. For example they could be
  83               in all caps: <filename>HELLO.C</filename>. It's not very nice to
  84               work with and probably not what you intended.
  85             </para>
  86           </listitem>
  87           <listitem>
  88             <para>
  89               then the case of the filenames in your include statements may be
  90               wrong: maybe they include <filename>Windows.h</filename> instead
  91               of <filename>windows.h</filename>.
  92             </para>
  93           </listitem>
  94           <listitem>
  95             <para>
  96               your include statements may use '\' instead of '/'. '\' is not
  97               recognized by Unix compilers while '/' is recognized in both
  98               environments.
  99             </para>
 100           </listitem>
 101           <listitem>
 102             <para>
 103               you will need to perform the usual Dos to Unix text file conversion
 104               otherwise you'll get in trouble when the compiler considers that
 105               your '\' is not at the end of the line since it is followed by a
 106               pesky carriage return.
 107             </para>
 108           </listitem>
 109           <listitem>
 110             <para>
 111               you will have to write new makefiles.
 112             </para>
 113           </listitem>
 114         </itemizedlist>
 115
 116         <para>
 117           The best way to take care of all these issues is to use winemaker.
 118         </para>
 119         <para>
 120           Winemaker is a perl script which is designed to help you bootstrap
 121           the conversion of your Windows projects to Winelib. In order to do
 122           this it will go analyze your code, fixing the issues listed above
 123           and generate straight Makefiles.
 124         </para>
 125         <para>
 126           Let's suppose that you are already in the top directory of your
 127           sources. Then converting your project to Winelib may be as simple
 128           as just running the three commands below (note the dot indicating
 129           current directory at the end of the first command):
 130         </para>
 131         <programlisting>
 132           $ winemaker --lower-uppercase .
 133           $ make
 134         </programlisting>
 135
 136         <para>
 137           But of course things are not always that simple which is why we have
 138           this guide at all.
 139         </para>
 140       </sect2>
 141
 142       <sect2 id="winemaker-test">
 143         <title id="winemaker-test.title">Test Drive</title>
 144
 145         <para>
 146           Before starting to work on a big project you may want to try to port a
 147           small application. The notepad application from the Wine source tree
 148           suits well for testing purposes. It can be found in the programs
 149           subdirectory. notepad is a simple application, but has a few C,
 150           header and resource files.
 151         </para>
 152         <para>
 153           Run <command>make clean</command> in the
 154           notepad source directory if it contains results of previous builds.
 155           Create a separate directory with name notepad2, so it won't conflict
 156           with the Wine copy of the application. Copy the sources of notepad
 157           (files *.c, *.h, *.rc) to this directory. Now run the commands,
 158           mentioned above from the notepad2 directory:
 159         </para>
 160         <programlisting>
 161           $ winemaker --lower-uppercase .
 162           $ make
 163         </programlisting>
 164
 165         <para>
 166           Notice how the build fails in a resource file
 167           (<filename>Da.rc</filename> at the time this was written).
 168           This is because for the time being, the Wine resource compiler
 169           (<command>windres</command>) can't cope with more than one
 170           resource file ending up in a given executable. To get around
 171           that limitation, the Wine developers have chosen to only have
 172           one master resource file per application, and include the
 173           other ones via <literal>#include</literal> statements in the
 174           master one. The included files do not
 175           <literal>#include</literal> the necessary files to be
 176           compilable on their own. You will need to do the same thing
 177           for now in your own Winelib port projects.
 178         </para>
 179         <para>
 180           To fix that problem, you will need to edit the list of
 181           resource files winemaker thought notepad used, and only keep
 182           the master resource file. To do so, open
 183           <filename>notepad2/Makefile</filename> in a text editor and
 184           search for an assignment to a variable with
 185           <literal>RC_SRCS</literal> as part of its name. It will likely
 186           be named <literal>notepad2_exe_RC_SRCS</literal>. There will
 187           be a list of resource files starting on the same line. Remove
 188           them all except <filename>rsrc.rc</filename> (this is the
 189           master one for notepad). Save your work.
 190         </para>
 191         <para>
 192           Now you're ready to continue at the same point the first
 193           <command>make</command> failed. Return to the notepad2
 194           directory and type:
 195         </para>
 196         <programlisting>
 197           $ make
 198         </programlisting>
 199
 200         <para>
 201           You are done! Now you can start the application as
 202           <command>./notepad2</command>.
 203         </para>
 204         <para>
 205           If you come across problems preparing and building this application
 206           this probably means that winemaker utility is broken by some changes
 207           in Wine. Try asking for help on <email>wine-devel@winehq.org</email>
 208         </para>
 209       </sect2>
 210
 211       <sect2 id="winemaker-guide">
 212         <title id="winemaker-guide.title">Step by step guide</title>
 213
 214         <para>
 215           Let's retrace the steps above in more details.
 216         </para>
 217         <variablelist>
 218           <varlistentry>
 219             <term><option>Getting the source</option></term>
 220             <listitem>
 221               <para>
 222                 First if you can try to get the sources together with the
 223                 executables/libraries that they build. In the current state of
 224                 winemaker having these around can help it guess what it is that
 225                 your project is trying to build. Later, when it is able to
 226                 understand Visual C++ projects, and if you use them, this will
 227                 no longer be necessary. Usually the executables and libraries
 228                 are in a <filename class="Directory">Release</filename> or
 229                 <filename class="Directory">Debug</filename> subdirectory of the
 230                 directory where the sources are. So it's best if you can
 231                 transfer the source files and either of these directories to
 232                 Linux. Note that you don't need to transfer the
 233                 <filename>.obj</filename>, <filename>.pch</filename>,
 234                 <filename>.sbr</filename> and other files that also reside in
 235                 these directories; especially as they tend to be quite big.
 236               </para>
 237             </listitem>
 238           </varlistentry>
 239           <varlistentry>
 240             <term><option>cd &lt;root_dir&gt;</option></term>
 241             <listitem>
 242               <para>
 243                 Then go to the root directory where are your source files.
 244                 Winemaker can deal with a whole directory hierarchy at once so
 245                 you don't need to go into a leaf directory, quite the contrary.
 246                 Winemaker will automatically generate makefiles in each
 247                 directory where one is required, and will generate a global
 248                 makefile so that you can rebuild all your executables and
 249                 libraries with a single <command>make</command> command.
 250               </para>
 251             </listitem>
 252           </varlistentry>
 253           <varlistentry>
 254             <term><option>Making the source writable</option></term>
 255             <listitem>
 256               <para>
 257                 Then make sure you have write access to your sources. It may
 258                 sound obvious, but if you copied your source files from a
 259                 CD-ROM or if they are in Source Safe on Windows, chances are
 260                 that they will be read-only.
 261                 But Winemaker needs write access so that it can fix them. You
 262                 can arrange that by running <command>chmod -R u+w .</command>.
 263                 Also you will want to make sure that you have a backup copy of
 264                 your sources in case something went horribly wrong, or more
 265                 likely, just for reference at a later point. If you use a
 266                 version control system you're already covered.
 267               </para>
 268               <para>
 269                 If you have already modified your source files and you want
 270                 to make sure that winemaker will not make further changes to
 271                 them then you can use the --nosource-fix option to protect
 272                 them.
 273               </para>
 274             </listitem>
 275           </varlistentry>
 276           <varlistentry>
 277             <term><option>Running winemaker</option></term>
 278             <listitem>
 279               <para>
 280                 Then you'll run winemaker. Here are the options you will most
 281                 likely want to use. For complete list of options see
 282                 the winemaker man page.
 283               </para>
 284               <variablelist>
 285                 <varlistentry>
 286                   <term><option>--lower-uppercase</option></term>
 287                   <term><option>--lower-all</option></term>
 288                   <listitem>
 289                     <para>
 290                       These options specify how to deal with files, and
 291                       directories, that have an 'incorrect' case.
 292                       <option>--lower-uppercase</option> specifies they should
 293                       only be renamed if their name is all uppercase. So files
 294                       that have a mixed case, like 'Hello.c' would not be
 295                       renamed. <option>--lower-all</option> will rename any
 296                       file. If neither is specified then no file or directory
 297                       will be renamed, almost. As you will see
 298                       <link linkend="renaming">later</link> winemaker may
 299                       still have to rename some files.
 300                     </para>
 301                   </listitem>
 302                 </varlistentry>
 303                 <varlistentry>
 304                   <term><option>--nobackup</option></term>
 305                   <listitem>
 306                     <para>
 307                       Winemaker normally makes a backup of all the files in which
 308                       it does more than the standard Dos to Unix conversion.
 309                       But if you already have (handy) copies of these files
 310                       elsewhere you may not need these so you should use this
 311                       option.
 312                     </para>
 313                   </listitem>
 314                 </varlistentry>
 315                 <varlistentry>
 316                   <term><option>--dll</option></term>
 317                   <term><option>--console</option></term>
 318                   <listitem>
 319                     <para>
 320                       These option lets winemaker know what kind of target you are
 321                       building. If you have the windows library in your source
 322                       hierarchy then you should not need to specify
 323                       <option>--dll</option>. But if you have console executables
 324                       then you will need to use the corresponding option.
 325                     </para>
 326                   </listitem>
 327                 </varlistentry>
 328                 <varlistentry>
 329                   <term><option>--mfc</option></term>
 330                   <listitem>
 331                     <para>
 332                       This option tells winemaker that you are building an MFC
 333                       application/library.
 334                     </para>
 335                   </listitem>
 336                 </varlistentry>
 337                 <varlistentry>
 338                   <term><option>-Dmacro[=defn]</option></term>
 339                   <term><option>-Idir</option></term>
 340                   <term><option>-Ldir</option></term>
 341                   <term><option>-idll</option></term>
 342                   <term><option>-llibrary</option></term>
 343                   <listitem>
 344                     <para>
 345                       The <option>-i</option> specifies a Winelib library to
 346                       import via the <link linkend="spec-file">spec file</>
 347                       mechanism. Contrast this with the <option>-l</option>
 348                       which specifies a Unix library to link with. The other
 349                       options work the same way they would with a C
 350                       compiler. All are applied to all the targets found.
 351                       When specifying a directory with either
 352                       <option>-I</option> or <option>-L</option>, winemaker
 353                       will prefix a relative path with
 354                       <literal>$(TOPDIRECTORY)/</literal> so that it is valid
 355                       from any of the source directories. You can also use a
 356                       variable in the path yourself if you wish (but don't
 357                       forget to escape the '$'). For instance you could specify
 358                       <literal>-I\$(WINELIB_INCLUDE_ROOT)/msvcrt</literal>.
 359                     </para>
 360                   </listitem>
 361                 </varlistentry>
 362               </variablelist>
 363               <para>
 364                 So your command may finally look like:
 365                 <literal>winemaker --lower-uppercase -Imylib/include .</literal>
 366               </para>
 367             </listitem>
 368           </varlistentry>
 369           <varlistentry>
 370             <term id="renaming"><option>File renaming</option></term>
 371             <listitem>
 372               <para>
 373                 When you execute winemaker it will first rename files to bring
 374                 their character case in line with your expectations and so that they can
 375                 be processed by the makefiles. This later category implies that
 376                 files with a non lowercase extension will be renamed so that the
 377                 extension is in lowercase. So, for instance,
 378                 <filename>HELLO.C</filename> will be renamed to
 379                 <filename>HELLO.c</filename>. Also if a file or directory name
 380                 contains a space or a dollar, then this
 381                 character will be replaced with an underscore. This is because
 382                 these characters cause problems with current versions of autoconf
 383                 (2.13) and make (3.79).
 384               </para>
 385             </listitem>
 386           </varlistentry>
 387           <varlistentry>
 388             <term><option>Source modifications and makefile generation</option></term>
 389             <listitem>
 390               <para>
 391                 winemaker will then proceed to modify the source files so that
 392                 they will compile more readily with Winelib. As it does so it
 393                 may print warnings when it has to make a guess or identifies a
 394                 construct that it cannot correct. Finally it will generate the
 395                 autoconf-based makefiles. Once all this is done you can review
 396                 the changes that winemaker did to your files by using
 397                 <command>diff -uw</command>. For instance:
 398                 <command>diff -uw hello.c.bak hello.c</command>
 399               </para>
 400             </listitem>
 401           </varlistentry>
 402           <varlistentry>
 403             <term><option>Running the configure script</option></term>
 404             <listitem>
 405               <para>
 406                 Before you run <command>make</command> you must run the
 407                 autoconf <command>configure</command> script. The goal of this
 408                 step is to analyze your system and generate customized
 409                 makefiles from the <filename>Makefile.in</filename> files. This
 410                 is also when you have to tell where Winelib resides on your
 411                 system. If wine is installed in a single directory or you have
 412                 the Wine sources compiled somewhere then you can just run
 413                 <command>./configure --with-wine=/usr/local/bin</command>
 414                 or <command>./configure --with-wine=~/wine</command>
 415                 respectively.
 416               </para>
 417             </listitem>
 418           </varlistentry>
 419           <varlistentry>
 420             <term><option>Running make</option></term>
 421             <listitem>
 422               <para>
 423                 This is a pretty simple step: just type <command>make</command>
 424                 and voila, you should have all your executables and libraries.
 425                 If this did not work out, then it means that you will have to
 426                 read this guide further to:
 427                 <itemizedlist>
 428                   <listitem>
 429                     <para>
 430                       review the <filename>Makefile.in</filename> files to
 431                       adjust the default compilation and link options set by
 432                       winemaker. See the <xref linkend="source-analysis"
 433                       endterm="source-analysis.title"> section for some hints.
 434                     </para>
 435                   </listitem>
 436                   <listitem>
 437                     <para>
 438                       fix the portability issues in your sources. See
 439                       <xref linkend="portability-issues"
 440                             endterm="portability-issues.title"> for more details.
 441                     </para>
 442                   </listitem>
 443                 </itemizedlist>
 444               </para>
 445               <para>
 446                 If you find yourself modifying the Makefile.in to specify the
 447                 location of the Wine header or library files then go back to
 448                 the previous step (the configure script) and use the various
 449                 --with-wine-* options to specify where they are.
 450               </para>
 451             </listitem>
 452           </varlistentry>
 453         </variablelist>
 454       </sect2>
 455     </sect1>
 456   </chapter>
 457
 458 <!-- Keep this comment at the end of the file
 459 Local variables:
 460 mode: sgml
 461 sgml-parent-document:("winelib-user.sgml" "book" "chapter" "")
 462 End:
 463 -->