Software Engineering with Wine - 2011

Introduction
Project organization
Requirements
Tasks
Useful links
Generic Wine Development Documentation
Setting Up a Wine Development System
Running Wine's Test Suite
How To Submit Changes To Wine

Introduction

Linux and Mac users often are tempted to run Windows apps, but don't like having to buy a copy of Windows, or having to run it in a virtual machine on their computers. This is where Wine comes in. Wine is a clean-room, open source, and free reimplementation of the Win32 API on top of the Unix API.

When Windows games don't work properly, it's common to run dxdiag, a handy little app that comes with Microsoft DirectX; gamers use it to get information about their 3d graphics card and to test to make sure it's working ok.

The project here is to both get Microsoft's dxdiag working a little better on Wine, and to get Wine's dxdiag to be more feature complete.

To try the native (Microsoft) version of dxdiag, do

$ wget http://winetricks.org/winetricks-alpha
$ sh winetricks-alpha dxdiag
$ wine dxdiag

In 2009, cs130 also tried improving Wine's dxdiag. Their code is online at code.google.com/p/yadxdiag, but was never committed to Wine because they tried to send it too late in the term. Let's not make that mistake this time. On the very first week, let's try to submit the smallest possible patch to improve Wine's dxdiag, and keep trying until it gets in.

Requirements

The new dxdiag must:

compile and run properly on real windows using either cygwin or visual C++ (your choice)
be integrated into wine's build system by successive patches to programs/dxdiag
when running on wine, should provide the following extra information in its log file:
- the version of wine
- the values of WINE and WINEPREFIX
- the contents of the HKCU\Software\Wine\DllOverrides and HKCU\Software\Wine\Fonts registry trees
have the same menu items as Microsoft's dxdiag (to avoid user confusion)
generally use the same APIs (particularly dxdiagn.dll) to retrieve info as Microsoft's dxdiag
Commandline behavior:
- If no arguments, puts up its main window
- If an argument starting with / that is not recognized, puts up usage dialog and exits
- Recognized options are /x outfile and /t outfile to output log file and quit with no gui
- The /whql:on and /whql:off options should be accepted but ignored
- If an argument not starting with /, behaves as if /t were given
Tasks
Each of the following things needs doing, everybody should pick one of these to work on:
- commandline behavior (non-gui case)
- main window / menu
- system tab
- DirectX Files tab
- display tab
- display tab - 2d tests
- display tab - 3d tests
- sound tab
- input tab
- conformance test (a test script that puts the app through its paces and verifies all the menu items do something and the logs are plausible; the test script should work properly with either Microsoft's dxdiag or ours)
In general, the task for each of those is "make it work just like Microsoft's, without violating any copyright laws". i.e. don't copy and paste from Microsoft's visuals, and don't log the calls they make and duplicate them.
The wine maintainer's policy is that only the person who writes the code should submit it to wine-patches, so we can't reuse the old code in yadxdiag that Allen Hair wrote.
Project organization
First off, please install Linux (see below) on your laptop; you might find the UCLA LUG's Installfest on Saturday January 15th useful.
Then let's have a meeting where everyone brings their computer, we get a Wine development environment set up on it, and verify that you can build the existing dxdiag. (Perhaps this can be done during the UCLA LUG installfest.)
Then let's have one or two meetings where we bring our computers and get started with the development work in person.
The mailing list ucla-cs130-wine is set up for students currently enrolled in the class. Please use this to ask questions about the project or run ideas past the coordinator or other students.
You can commit to the existing code.google.com/p/yadxdiag repo while getting things together, but the real source code repository is the git repository at winehq.org. To commit, you have to submit patches as described at Sending Patches.
I've also set up a chat room for this project using IRC; it's at irc://irc.freenode.net/#ucla-cs130-wine
My favorite way to access IRC is with the Chatzilla plugin to Firefox (Tools / Addons / Get Addons, search for IRC). Then you can just click on the above link, and/or add it to your bookmarks.

Generic Wine Development Documentation
www.winehq.org has a fair amount of documentation. You should at least have a look at the following:
Setting Up a Wine Development System
1. If possible, get a fast system with an Nvidia graphics card, and devote a real partition to Linux. Developing in a virtual machine is possible, but slow, and doesn't support Direct3D well if at all. (You can also use a Mac to develop Wine, but that's difficult, only try it if you're very comfortable with building open source software on Mac OS X. )
2. Install a fairly recent mainstream linux distribution, e.g. Ubuntu 10.10. (Students with Windows already installed may wish to try the Wubi installer, which installs Ubuntu as if it were a Windows application.)
3. Install the packages needed to build wine, using the commands
```
wget http://winezeug.googlecode.com/svn/trunk/install-wine-deps.sh
sudo sh install-wine-deps.sh
```
  (see RecommendedPackages).
4. Get the Wine source tree as described at wiki.winehq.org/GitWine:
```
git clone git://source.winehq.org/git/wine.git wine-git
```
  This creates a Wine source tree in a new directory named wine-git.
5. Build Wine by doing "./configure; make" as usual in the Wine source tree.
6. Try running some of the programs that come with Wine, e.g.
```
cd ~/wine-git
./wine programs/cmd/cmd.exe.so
```
Running Wine's Test Suite
Once you have built Wine, you probably want to run the conformance test suite to make sure your system is ok. See the instructions at www.winehq.org/docs/winedev-guide/testing-wine. For example, if you're building inside the source tree:
```
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 hangs, you may need to kill the process or wineserver from another window.)
To see a list of failures, just look for lines with "Test failed" in them, e.g.
```
grep "Test failed" log | more
```
You can get a count of failures with wc:
```
grep "Test failed" log | wc
```
You shouldn't see more than ten or so errors in 32 bit Wine (assuming your have an nvidia graphics card).
How To Submit Changes To Wine
See http://wiki.winehq.org/SubmittingPatches.
Once you have made a change to Wine or its test suite that you're happy with, create a patch (see here and here for how), and make sure the patch applies cleanly to a fresh checkout of the Wine sources, and still builds and runs properly. If you used git to retrieve the sources, you should be able to use 'git diff > my.patch' to create a patch.
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.)

Contents