This page is being reorganized. The 2009 version of this page is here.
Slides prepared for UCLA's CS130 are online: Winter 2009, Winter 2007, magicpoint source, Winter 2006, html/ Winter 2006, magicpoint source.
Many companies and governments are currently planning to start using Linux on the desktop, but use several legacy Windows applications that are not yet available for Linux. The Wine project could be an important part of these organizations' transition plans. For instance, Munich is converting about 14000 computers from Windows to Linux by 2008, and will use VMWare, Terminal Servers, or Wine when Linux versions of applications are unavailable.
By contributing improvements to Wine, students will help reduce software costs for millions of people around the world.
Don't use an old versions of Linux (e.g. Red Hat 9, Fedora Core 1); it's best to use a fairly recent mainstream, e.g. Ubuntu 6.06 or Ubuntu 6.10. Also, use the 32 bit version of the OS; Wine does not yet play well with 64 bit software. The Linux system should have the full suite of GNU developer tools (gcc, binutils, etc.) as well as git installed. The wiki page RecommendedPackages describes how to add the needed packages to the Linux system. The easiest way to do this is to run my canned script, e.g. if you're using Ubuntu 6.06, download dapper.sh and run it like this:
wget http://kegel.com/wine/dapper.sh sudo sh dapper.shOr if you're using Ubuntu 6.10, do:
wget http://kegel.com/wine/edgy.sh sudo sh edgy.sh(Thanks to Lei for updating edgy.sh.)
The Windows system should have either Cygwin's C compiler (freely downloadable from cygwin.com) or the Microsoft C compiler and Platform SDK installed. The latter are freely downloadable from microsoft.com: first grab Visual C++ Express, then install Platform SDK.
If the school does not provide a lab set up with such computers, the instructor may have to provide the students with Linux CD-ROMs and have them spend the first project setting up their own computers. This should be coordinated with the school's Linux User Group, which may be able to host an Installfest to assist the students.
The students will also need reasonably fast Internet connections. This document will assume everyone has cable modem, DSL, or T1 access. (Students without fast access can also participate, though the procedures will be a bit different, and will not be covered here.)
To download Wine from git, do:
git clone git://source.winehq.org/git/wine.git wine-gitThis takes a couple minutes if you have a fast connection. (It even works on Windows under Cygwin.)
To build Wine, just use configure and make. (You can give the command 'git pull' before making to be sure you have the very latest wine sources.)
cd ~/wine-git git pull ./configure make depend makeNote: If you're using ubuntu 6.10, you may need to disable a C compiler option when building wine:
If you have a ~/.wine directory left over from an older version of Wine, you should delete or rename it (since Wine is still changing rapidly, it often breaks backwards compatibility with old ~/.wine contents):
cd ~ mv .wine .wine.old(If you aren't running X already, e.g. if you're running Wine under VMWare and/or your copy of linux isn't set to use graphics on bootup, start X now with the command startx.)
Once that's done, try running some of the programs that come with Wine, e.g.
cd ~/wine-git ./wine programs/notepad/notepad.exe.so
If notepad works, try running winefile, e.g.
programs/winefile/winefileThat should give you an idea of how Wine maps drive letters.
Then try installing and running a real Windows program using Wine. One good program to try is WinZip. Download the latest version, save the file in your home directory, then install it with Wine like this:
cd ~ wine-git/wine winzip100.exeand then run it, e.g.
wine-git/wine 'c:\Program Files\WinZip\WINZIP32.EXE'to make sure it works as you'd expect.
ps augxw | grep wineTo kill it (and all other wine processes), try
killall wine-preloaderor, if you actually installed Wine (not recommended while developing it),
Once your patch works, add a changelog entry at the top, giving your name and the license (LGPL), and saying very briefly what it does. Then have a friend review the patch for errors, and clean up anything they found confusing or wrong.
If you're a student working in a structured project, send it to your project leader for review, and clean up any issues they find.
Finally, post it to the wine-patches mailing list, and watch for replies on the wine-devel mailing list.
If the patch isn't accepted right away, don't worry, just address any feedback you're given, and resubmit it once a week or so. Ask on wine-devel if you're unsure what's happening. Continue resubmitting until it makes it in. (Sometimes the Wine maintainer's mailbox overflows, so don't expect approval to be quick or easy.)
Note: do not include any third-party code (e.g. from Microsoft) in your tests! You have to write everything from scratch yourself (or get the author's permission to contribute his/her code to Wine under the LGPL), otherwise the Wine project won't be able to accept your code!
If the DLL has many functions, that's ok, just test the most important or most commonly used ones. Later, you or others can add tests for more of its functions.
If you need a data file, create it during the run, as the test must be fully self-contained. Make sure the test runs properly on at least Windows XP, and preferably also on Windows 98, before running it under Wine.
I find it easiest to compile the test standalone on Wine using Microsoft's C++ toolkit using commands like (assuming I'm trying to build the 'file.c' conformance test for msvcrt):
cd dlls/msvcrt/tests cl -DSTANDALONE -D_X86_ -I../../../include file.cThis lets me compile the test once, and run it on both Wine and Windows.
Once it runs properly on both Windows and Wine, copy it into the tests subdirectory of the DLL in question, add the neccessary changes to configure.ac and Makefile.in (see the lzexpand test patch for an example), run autoconf to regenerate configure from configure.ac, and make sure your test builds properly.
If the DLL you're testing is nontrivial, you probably want to plan on submitting an initial version that only tests a subset of the DLL. While you're waiting for that to be accepted, continue adding coverage to your tests. Getting a partial test into the Wine source tree can sometimes make it easier and quicker to get the full test in later.
For UCLA cs130 Winter 2007 term, see Lei Zhang's great web page at linux.ucla.edu/~leiz/software/wine/cs130_w07.php for the specific DLL we plan to work on.
cd ~/wine-git make -k test > log 2>&1(The -k makes it continue past failing tests; the "2>&1 log" redirects both stdout and stderr to a file named "log".) This should take about five minutes. If a test crashes, you may need to click 'cancel' to make the crash dialog box go away.
To see a list of failures, just look for lines with "Test failed" in them, e.g.
grep "Test failed" log | moreYou can get a count of failures with wc:
grep "Test failed" log | wc
or a breakdown by test source file with sed, uniq, and sort (I admit, I love the Unix shell!):
grep "Test failed" log | sed 's/:.*//' | uniq -c | sortOn my machine, I got the following breakdown of errors in 2004:
2 typelib.c 4 capture.c 4 wave.c 7 vartype.cIf you see more errors than this, something's probably wrong, and you need to troubleshoot a bit before going on.
metafile.c:91: Test failed: pass 0: dx (1079638356) didn't match 6it probably means you don't have any TrueType fonts installed, and Wine didn't install any for you by default. To fix this, install a TrueType font, e.g. download and run http://prdownloads.sourceforge.net/corefonts/courie32.exe.
This year, everybody was asked to implement a windows message currently unimplemented by riched20, starting with the conformance tests. The unofficial TA forged ahead and wrote an initial test suite for riched20 that the students could add to; he then went and implemented a couple features himself. It took much persistance and many rewrites, but his patches made it into winehq.org's CVS in time: