1.3. Getting Started

1.3.1. Winemaker introduction

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:

The best way to take care of all these issues is to use winemaker.

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.

Let's suppose that Wine/Winelib has been installed in the /usr/local/wine 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 (note the dot indicating current directory at the end of the first command):

          $ winemaker --lower-uppercase .
          $ ./configure --with-wine=/usr/local/wine
          $ make
        

But of course things are not always that simple which is why we have this guide at all.

1.3.2. Test Drive

Before starting to work on a big project you may want to try to port a small application. The winemine application from the Wine source tree suits well for testing purposes. It can be found in the programs subdirectory. winemine is a simple application, but has a few C, header and resource files.

Run make clean in the winemine source directory if it contains results of previous builds. Create a separate directory with name winemine2, so it won't conflict with the Wine copy of the application. Copy the sources of winemine (files *.c, *.h, *.rc) to this directory. Now run the commands, mentioned above from the winemine2 directory:

          $ winemaker --lower-uppercase .
          $ ./configure --with-wine=/usr/local/wine
          $ make
        

You are done! Now you can start the application as ./winemine2.

If you come across problems preparing and building this application this probably means that winemaker utility is broken by some changes in Wine. Try asking for help on

1.3.3. Step by step guide

Let's retrace the steps above in more details.

Getting the source

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 Release or Debug 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 .obj, .pch, .sbr and other files that also reside in these directories; especially as they tend to be quite big.

cd <root_dir>

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 make command.

Making the source writable

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 chmod -R u+w .. 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.

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.

Running winemaker

Then you'll run winemaker. Here are the options you will most likely want to use. For complete list of options see the winemaker man page.

--lower-uppercase, --lower-all

These options specify how to deal with files, and directories, that have an 'incorrect' case. --lower-uppercase 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. --lower-all will rename any file. If neither is specified then no file or directory will be renamed, almost. As you will see later winemaker may still have to rename some files.

--nobackup

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.

--dll, --console

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 --dll. But if you have console executables then you will need to use the corresponding option.

--mfc

This option tells winemaker that you are building an MFC application/library.

-Dmacro[=defn], -Idir, -Ldir, -idll, -llibrary

The -i specifies a Winelib library to import via the spec file mechanism. Contrast this with the -l 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 -I or -L, winemaker will prefix a relative path with $(TOPDIRECTORY)/ 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 -I\$(WINELIB_INCLUDE_ROOT)/msvcrt.

So your command may finally look like: winemaker --lower-uppercase -Imylib/include .

File renaming

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, HELLO.C will be renamed to HELLO.c. 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).

Source modifications and makefile generation

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 diff -uw. For instance: diff -uw hello.c.bak hello.c

Running the configure script

Before you run make you must run the autoconf configure script. The goal of this step is to analyze your system and generate customized makefiles from the Makefile.in 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 ./configure --with-wine=/usr/local/bin or ./configure --with-wine=~/wine respectively.

Running make

This is a pretty simple step: just type make 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:

  • review the Makefile.in files to adjust the default compilation and link options set by winemaker. See the Winemaker's source analysis section for some hints.

  • fix the portability issues in your sources. See Portability issues for more details.

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.