Want to be a Wine Coder?

From Wine-Wiki

1 Learning to contribute code - starting from scratch
2 Links

[edit] Learning to contribute code - starting from scratch

A user wrote in Mar 08 on wine dev some questions which lead to a discussion about how to start from not knowing anything about programming, to being a contributor to Wine. This page contains some of their quotes and comments, but to get a more complete picture you can always read the original posts:http://thread.gmane.org/gmane.comp.emulators.wine.user/21566/focus=21668

He Asked: I want to learn just enough to be useful for the Wine project. can you give me an ordered to-do-list in becoming a Code Monkey for WineHQ?

Like do I have to know both C and C++ to code for Wine.
What books with easy exercises is best for total newbies learning to programming in the WineHQ language?
Do I have to go through every resource link to be able to code for Wine?
What sort of stuff in C or C++ should I play with in order to learn the relevant stuff for Wine coding at the basic programmer level?
Is there any HowTo books in Coding for Wine, that would sort of help?
Give me a list of that nature so I can focus on learning the relevant stuff just for some easy Monkey Coding.

[edit] The book to get

D. Kegel: [You need to know] just C. Go through "The C Programming Language" by Kernighan and Ritchie, and do all the exercizes.[...] Amazon has them used for $20 including shipping. That's what I would have paid, $97 is too much.

http://www.amazon.co.uk/C-Programming-Language-2nd/dp/customer-reviews/0131103628/ref=dp_top_cm_cr_acr_txt?ie=UTF8&showViewpoints=1&customer-reviews.start=1&qid=1205449841&sr=8-1#customerReviews

Dan Kegel also has a list of resources: http://kegel.com/academy/tutorials.html

J. McKenzie: If you can make it through the book, you are very good and will work well for the Wine project.

The user asked: Can you recommend a good C programming video CD/DVD? but was told: No. The user then commented Learning by watching goes a little faster than reading for me personally. Books are good for referencing but not good for getting into the game. But D. Kegel pointed out this book is an exceptional book: K&R is different. Read it and do the examples. You'll see.

J. McKenzie: This book is "THE GUIDE" to programming in c. These two gentlemen created [the language called C]. So, what you have to do is find a copy of "The 'c' Puzzle Book' and work through the puzzles. Then you will be ready for programming in 'c'.

[edit] The API

D. Timoshkov: Wine programming requires Windows API programming skills as well, one needs an experience of using at least APIs for the component(s) of Wine he/she is going to write the code for, and a good knowledge how it's supposed to work/operate internally. One should be prepared to write lots of tests to investigate/clarify behaviour described/missing in MSDN.

J. McKenzie: However, for the basics, K&R will do. They teach how to write excellent code rather than passable code. Also, knowledge on programming best practices is good to have as well.

Vitamin: KnR is probably the best choice since it's classic and not much really changed since then. [You dont have to go thru every ressource..as] That's the reference. You'll need one or the other when you start hacking Wine. However you need to know win32api if you want to get anywhere.. [..] Read wine-patches and the git history - to see what patches are being committed and which are not. Read wine-devel too see why. [There is a HowTo for coding in Wine] Wine Developer's Guide (http://winehq.org/site/docs/winedev-guide/index)

And start hacking already.

M. Knect: I am not a coder but I think the more or less consistent response to step two is look at the list of bugs or uncoded parts of Windows compatibility, pick one that you have an interest in, and then see if you can figure out what's up. The ToDo list is here: http://wiki.winehq.org/TodoList

E. Savage: Jeffz linked me to a very handy beginners windows programming site the other day http://winprog.org/tutorial/start.html which I would suggest would be your first step once you know how to write basic c applications. I've found it extremely helpful. After that it is simply a case of going to the bug list and finding nice little simple issues and spending time working out what is going wrong, how changing things effects the result, seeing if you can come up with work a rounds for the issue...And then using your built up knowledge

Just remember that while on the out side the wine develops seem harsh and uninterested in helping (I remember that being my thoughts when I first started looking at helping wine) if you are making a genuine effort I've found answers to questions to be easily at hand and every one to be very helpful.

Just have a go

A. Sornes: Personally I found the 'Introductory C Programming Class Notes (standalone)' as a very useful beginner's guide. Maybe we should add a 'begginer's section' to WineHQ? http://www.eskimo.com/~scs/cclass/cclass.html attempting to fix the bug.

[edit] Programming forums

The user asked: Can you also recommend some good C programming forums where you can hang out with ppl in the same situation as me? Learning together with newbies is usually easier than hanging with some elite C programmers at least at the very beginning.

M. Wysocki: if you really need help you could always check ##c on irc.freenode.net, or just write me an email (or contact me on freenode, nick: maci), i'm not some kind of elite coder but i think i will be pretty well be able to answer your questions.

E. Savage suggested not to rely on help too much: There is a very easy trap you can fall in to when learning c/cpp in that the simple tasks you are doing are easier for others to fix than for them to teach you why it is broken. This leads to you not really learning what is wrong or how to fix it. Believe it or not the five hours that you sit looking at some stupid simple issue will teach you more than the same amount of reading some book while you try and work through to find the solution.

[edit] The wine development plan

J. Hawkins: If you're expecting someone to hold your hand and tell you exactly what to code in this project, you're going to be very disappointed. Working on Wine is different than working on most other projects. There is a design plan, but we have no access to it. We're blind men feeling our way through a maze with our hands (the test suite). Even if a developer knew the solution to the problem, it would take much longer for him to guide you through implementing that solution than for him to just implement it himself. If you really want to work on this project, just start somewhere...do something. No one will tell you what to do, and reading books only goes so far.

J. Hawkins: Our development process is completely transparent. Discussions occur on wine-devel, patches are sent to wine-patches, and the committed patches show up in wine-cvs. Users are helped in wine-users. The way we work now, we sort of have unofficial maintainers of sub-projects. Each developer then becomes an expert in his subsystem and efficiently fixes bugs in his area of expertise. That isn't to say that we each have exactly one area of expertise. 'Outsiders' can't see the results, because they don't know what they're looking at.

The user asked: Do you guys recommend that a person with no previous C experience should first spend some time on smaller C related open-source projects elsewhere, as a first project before jumping on the Wine project?

D. Kegel: Just start programming. You can only learn by doing. J. McKenzie: It is definitely doable [ to have Wine project as a newbies first open-source project]. You can start with something small, or pick up a fix that was abandoned (like I did) and clean it up for inclusion into the project.

D. Gerard: The main thing is to stop asking where to start, and just start

[edit] Getting Started

D. Kegel: Feel free to get off the training track and just start fixing bugs whenever you feel ready. But please don't send in any patches that don't have conformance tests, or whose conformance tests don't pass in both wine and windows. [Ed] However, there is one important thing. Do Not Look at Microsoft code. A. English explained [Jan 09]: If you know C and haven't seen Microsoft source code [You can work on wine]. [Ed] Dont try disassembly of Microsoft code - that would prevent you contributing. too [The following is a compilation of above and extra posts by vitamin]

K & R book. Read "The C Programming Language" and do all the excercises.
The API Reference
Doing "home work" from that book is all well and good, but it's more fun to actually use it for something... like Wine. For that you'll need to know the API (what functions to call at least). However, the API is not something you just read like a book. You just need to have an API reference http://msdn.microsoft.com) handy. However you will need some basic concepts of how things work. That's where this one comes in: [Reading] the Win API tutorial. http://winprog.org/tutorial/start.html
How to compile wine and how to debug it
When you get all excited and want to actually do something with Wine you'll need to know at least where what files are, how to compile Wine and how to debug it. You can find that info here in 14 chapters: Wine Developer's Guide http://winehq.org/site/docs/winedev-guide/index Wine Developer's Guide. Get the software called git. When you are working on wine you need to get familiar with some of the basics of using git. This is important because
1. You can always work with latest version of the code.
2. It is easier to maintain your patches that aren't accepted (and find out when they are accepted).
3. You can properly test for bugs to see if they are fixed identify bad commits for regressions.
4. It uses the preferred format for patches sent to wine-patches.
Review some of the patches others sent to Wine. Eventually Send your Patches to Wine (along with conformance tests)
when you get to a point of sending patch, that's how you do it: Subscribe to <wine-patches <at> winehq.org> read it [and learn from it] Read wine-patches and the git history - to see what patches are being committed and which are not. Read wine-devel too see why. Only send in any patches that have conformance tests, or whose conformance tests pass in both wine and windows.
Simple Projects
There are probably many ways of identify where to start working on Wine. If you need some simple projects to start with you can find one list of them here. Most don't require too much of API knowledge. Some don't even need programming experience. Of course you do need to understand plain C.
- http://wiki.winehq.org/JanitorialProjects. (note a couple of these projects have become outdated. But they do give you experience)
- D.Kegel [May 2007 wine devel]: I would suggest starting by doing a couple weeks of bug triage. See http://kegel.com/wine/qa/ Then, while still doing bug triage, start writing conformance tests to expose some of the bugs you're seeing. Getting conformance tests committed to the WineHQ tree is a good rite of passage. Then, once you have the hang of that, pick one of the bugs you've written a good conformance test for, and try to fix it. [Another devloper suggested] given that Wine development is mostly centred around fixing bugs that affect programs, it might be a good idea to search for a nice easy bug report for an application. [If someone has done a really nice bug report and regularly update it], it may have already identified the component that likely is causing the bug, so this can be a starting point for what part of the code to work on. [Ed] Check the application Database how to install it and then Using the latest version of Wine obtained through Git go ahead and see if you can install it. Have a play and see what you can learn to get it working better in Wine. You dont need to fix everything, just make it work a better that it did before. Then hunt for another easy bug to squash...
- A.English[feb09] Another good thing to do is look in bugzilla for bugs with patches attached. Often times they work, but they're not complete, or need a testcase. [Ed As a new contributor, you may need to first work at getting the test cases into Wine to build A. Julliards trust in your code].
- Walk before Running. One started out with [feb09 wineuser]: what's the most important DLL that prevents a lot of applications not to work and I want to start to work on it? I had read that KERNEL32 is just a functions forwarder to NTDLL but it's not completed yet, is it the right choice to start with? A developer then suggested walking before running, building up experience on wine: Not really. You need to know lots of things to be able to hack those dlls. You should start at something simple and less destructive - for example comctl32.dll
- No reverse engineering. If you are not sure about how it should work, write a test case. You can politely ask on the wine-devel list, and someone will run a test for you. There are even some virtual machines available to developers. Winehq Bugzilla entry 19425 Using a relay trace of a native component to implement similar functionality in the corresponding Wine component is not allowed. That's considered reverse-engineering.

You don't have to do this one after the other. Most you can do in parallel. Or even backwards if you so desire. Just please don't ask people to teach you C. That's what the step #1 is for. And most people won't tell you exactly what each function does.

Just have a go

You do not need to be a seriously experienced coder to be able to help. Just recently (Jan 2008) one person helped merely with a few missing stubs and now another program has started to run under Wine. However keep in mind what A. Julliard wrote jan 08 winedevel: You are not allowed to look at what calls the native dll makes, that's an implementation detail. The only thing you can do with native is to write test cases to determine the externally visible behavior.

To build confidence that your code is correct, send in a test case and then after you have shown your understanding is correct, the developers can have more confidence in your work. The value of tests was highlighted in this code review [jan10 winedev]:

You [are] changing [..] too many things without a single test. Lots of those areas you touch will break oh so many apps.

For starters write some tests and verify what you doing is correct. You should be able to write tests for all injected messages (send_mouse_event). If you can't make an automated test, write a visual test for the rest and send to wine-devel. Especially pay attention to all messages sent, and order of calling hook, sending messages, modifying values returned from GetCursorPos().