Table Of Contents
|1.||24�Jul�2001�-�26�Jul�2001||(4 posts)||Using Native DLL's|
|2.||18�Jul�2001�-�19�Jul�2001||(5 posts)||Adding 16-bit Headers|
|3.||20�Jul�2001�-�23�Jul�2001||(11 posts)||Shared Source a Danger?|
|4.||24�Jul�2001||(2 posts)||CallWindowProc Syntax|
|5.||30�Jul�2001�-�1�Aug�2001||(10 posts)||Documenting Functions|
This is the 101st release of the Wine's kernel cousin publication. It's main goal is to distribute widely what's going on around Wine (the Un*x windows emulator).
We saw Wine-20010731 escape this week. Alexandre noted the following changes:
Mailing List Stats For This Week
We looked at 173 posts in 530K.
There were 41 different contributors. 23 posted more than once. 18 posted last week too.
The top posters of the week were:
1. Using Native DLL's
24�Jul�2001�-�26�Jul�2001 (4 posts) Archive Link: "native dll's"
People: Jose Soriano Diaz,�Francois Gouget,�
Jose Soriano Diaz wondered how to go about using a native DLL:
Hi there, I'm working in a telerobotics project and I need to link a windows dll in order to use a Cybernet Joystick. First I tried to use the winAPI functions LoadLibrary,FreeLibrary and GetProccessAddress as I were working on Windows, and I recompiled my program with winelib:
but it didn't create any executable, what I obtained was a lib*.so, because winemaker thought I was trying to compile a dll, not to use one. After that I tried to compile my program without winemaker, and I obtained a HEAP_PTR error when executing what I copiled. And If I tried to link the lib*.so and load the main symbol I obtained the same error.
So my question is quite simple How can I link a native dll in a Unix project? I've read somewhere that I have to use a parser, Is there anybody who can give me some code?
Francois Gouget thought LoadLibrary / GetProcessAddress / FreeLibrary was the simplest approach if it worked. Then he explained:
To force winemaker to generate an executable simply use it as
"winemaker --cuiexe /my_path"to indicate a console executable
"winemaker --guiexe /my_path"to indicate a graphical executable
You can also use "winemaker -?" to get a list of options supported by winemaker.
2. Adding 16-bit Headers
18�Jul�2001�-�19�Jul�2001 (5 posts) Archive Link: "Re: more misc fixes"
People: Alexandre Julliard,�Patrik Stridvall,�,�Francois Gouget,�Patrik Stridval
Patrik Stridvall posted a patch to
that had a line:
#include "wine/windef16.h". Alexandre
This is wrong; Win32 header files must not include 16-bit ones.
Also please avoid adding more 16-bit headers in include/wine, there are already too many of them. These headers (when they are really necessary) belong in their respective dll directory. And BTW your new lzexpand16.h is an example of a header file that is *not* necessary.
Patrik wasn't sure exactly where to add it though. Alexandre said to add it to the DLL directories and if possible to the .c file where they're needed. Patrik thought, " However IMO all exported functions whether they are 16-bit or 32-bit and whether they are actually uses by other files or not should have declarations in some header file." . Because of Winelib this is necessary for 32-bit functions, however Patrik felt there were several advantages for 16-bit ones too.
Alexandre disagreed and explained, " All 16-bit API functions must be treated as if they were static. They cannot be because of the spec file reference, but ideally no code should ever call a 16-bit API, it should use the corresponding 32-bit API. Adding prototypes and a header file is only going to encourage using these functions which is not what we want."
Patrik wondered, " You want all 16-bit exported function prototypes moved from the .h files to the implementing .c file in all cases that is is possible (ie Wine compiles without errors or warnings)?" Alexandre said that was exactly what he wanted, " but note that in most cases the prototype is not even needed at all. I don't want all 16-bit C files to start with a bunch of prototypes either, this would just be unnecessary duplication; only the functions that are actually called from elsewhere in the file should be prototyped IMO."
Brandon Kilgore thought this last point didn't make much sense. Namely, when would there ever be a function that isn't called from anywhere? Francois Gouget explained that for 16-bit functions they might be called by Windows programs.
3. Shared Source a Danger?
20�Jul�2001�-�23�Jul�2001 (11 posts) Archive Link: "Microsoft source code releases - a danger to Wine?"
People: Ian Pilcher,�Gavriel State,�Patrik Stridvall,�,�Patrik Stridval,�TransGaming
Ian Pilcher wondered what the potential legal ramifications are with the "shared source" licenses being bandied about by Microsoft:
According to Slashdot, Microsoft has released the Windows CE source code under one of their "shared source" licenses. Needless to say, it would be an *extremely* bad idea for anyone associated with the Wine project to look at it.
This leads me to wonder if anyone's ever thought of taking steps to protect Wine from "contamination" by Microsoft IP (legally, not tech- nically :-). As the number of programmers who have been exposed to MS source code grows the chances of this happening will increase. I believe that the FSF uses some type of form/statement before they will accept code, and it seems like the nature of this project would make it particularly beneficial.
Gavriel State posted some thoughts on this that generated several replies:
While I agree that it is probably not a great idea to look at the CE code at this point, Microsoft's 'Shared Source' license is *very* interesting in a number of respects. First and foremost, the license is by far the most simple and straightforward software copyright license that I have ever seen. There is barely a hint of legalese about it.
As such, it appears to me that there may be some interesting ways in which the license can be exploited to benefit Wine. 8-)
Note that I'm not suggesting that anyone go out and do this without spending a fair bit of time (and money, unfortunately) with a lawyer. Certainly, no one at TransGaming is going to be downloading or looking at those sources.
So - on to some analysis of the license. Everything below is based only on my own personal understanding of the legal issues involved, nothing more.
Well, first off, copyright law generally governs copying, not use. Attempts to overreach the provisions of copyright law through additional clauses in shrink-wrap/click-wrap and other contracts have been turned aside in some court cases. In the US, federal copyright law trumps state contract law, from what I've read. Thus, the license starts off on shaky ground.
Again, the use issue rears its head. Another interesting question here is the one of derivatives. It is possible that knowledge gained by study of the source code, which is then applied to Wine, would not in and of itself cause Wine to become a 'derived' work, assuming that no actual source code was used. It is a somewhat grey area that I don't know very well, but it may be worth investigating.
Here again, we have the usage issue, as well as the platform-restrictive clause for commercial users. The platform restrictions may constitute anti-competitive 'copyright misuse', and thus be unenforceable. The language used here is also interesting - they say 'reference', rather than 'use'. I suspect that they are trying to explicitly restrict efforts like Wine from even studying their code - an apparent violation of 'fair use' provisions of copyright law.
The rest of the license is pretty straightforward with nothing that's too objectionable that I can see immediately. I won't bother going through it in detail.
That said, nothing I can see appears to restrict someone who has accepted their license from answering explicit questions we might have, so long as they are not doing so for hire (thus 'commercially'), and so long as they don't distribute source code. A fair bit of useful knowledge might be gained in that way, albeit slowly.
Anyhow, a useful link for anyone interested in more background on some of the legal issues is: http://www.richmond.edu/~jolt/v1i1/liberman.html (http://www.richmond.edu/~jolt/v1i1/liberman.html)
The discussion turned to what problems might be caused by someone coincidentally submitting code that was similar to Microsoft's. Even if no one had actually looked at their source code it might be difficult to prove that. Patrik Stridvall pointed out that:
In short, while IANAL, if Microsoft (or somebody) feels that some code in the CVS is copyrighted by them we should simple require that.
4. CallWindowProc Syntax
24�Jul�2001 (2 posts) Archive Link: "CallWindowProc syntax"
People: Marco Bizzarri,�Alexandre Julliard,�
Marco Bizzarri was digging through some documentation and had a question:
While looking at the source code of wine, I looked into the synopsys of the CallWindowProc function. According to winproc.c, the hWnd parameter should be the handle to the window which has to receive the message.
OTOH, if you look at MSDN, at
it looks like the hWnd is the windows procedure which should receive the message.
Can anyone help?
To which Alexandre Julliard replied, " hWnd is clearly a window handle, not a window procedure. As a rule, any resemblance between what MSDN says and what the code actually does is purely fortuitous."
5. Documenting Functions
30�Jul�2001�-�1�Aug�2001 (10 posts) Archive Link: "Documenting functions"
People: Bill Medland,�Andreas Mohr,�Francois Gouget,�Alexandre Julliard,�Uwe Bonnes,�Bill Medland wanted to know how to go about adding documentation to the Wine source:
Suppose I am looking at a low-level function that I believe is only 75%-complete (the most important 75% of course and no disrespect meant to those who have got it that far).
One of the problems with it is it is not totally clear EXACTLY what the function should do in some of its more esoteric modes.
To me the first task is to define what it should do and that should be part of the documentation of the function.
The particular function currently does not have any true documentation within the code; the best documentation of what it does is the code itself, and the best documentation of what it should do is the MSDN description of the function.
Andreas Mohr replied:
IMNSHO full documentation should *not* be included in the Wine tree. Instead, we should rely on MSDN documented stuff wherever possible and only explain quirks/undocumented behaviour/whatever isn't documented.
Having full docu inside the source tree simply bloats it too much IMHO.
Not to mention that none, zero, zilch of the planned undertakings in that direction have actually taken off so far. Docu in general is fine, but duplicated function docu in source tree ? Avoid as much as possible, I think.
If there's no additional "Wine" information about this function, then this is perfectly reasonable IMHO (see above).
I'd like to see at most: function header with comment above with short description of i/o, additional statements about undocumented/special behaviour.
Francois Gouget disagreed and posted a lengthy explanation:
Well, let me offer a different opinion.
Wine is an open-source reimplementation of the Win32 API. You can use it to run existing Windows applications and to recompile or develop Win32 applications using Winelib.
Now, for me an open-source project that implements an API for which there is no open-source documentation is not complete. Especially for Winelib where the API is part of what we provide to the user, i.e. to programmers using Winelib.
And currently the only documentation of the Win32 API is available from Microsoft as part of the MSDN. I see many problems with that:
So I think the functions implemented in Wine should be fully documented. And the only place to do that is in the code source because this is the only place where they have a remote chance of staying up to date (and also where it's most practical to have it).
Of course developpers are very well-known for hating to document stuff so it's going to be pretty hard to get proper documentation. But we should encourage all Wine developpers to write good documentation for the functions they implement/fix, not dissuade them to do so.
Also I agree with you that the strict minimum is to at least document all the undocumented/weird behaviors. Especially since without some sort of documentation the next developper may be tempted to remove what looks like unnecessarily convoluted/obviously wrong code.
Then come the open questions:
How do we get people motivated to write documentation?
Maybe people writing tests (as in using programs/winetest) should/could write documentation. After all to write proper tests you have to understand the API well enough to know what are the corner cases. So you might as well document the functions you test while you're at it. Then people doing the first non-stub implementation of an API would be in a good position to document it. After all if you implement an API aren't you supposed to know how it works?
I certainly don't think we should bar code (implementation or tests) that comes with no documentation from getting into CVS. But maybe we could gently ask as a reminder if the submitter could write some doc too.
Is the current format the most appropriate one?
Well, it's just that I'm a fan of JavaDoc-like formats and that I've always been a bit skeptical of the current system (c2man). Does it still work btw? Is http://www.winehq.com/WineAPI/ up to date?
Also it seems we should have documentation on what messages do, especially for things like LVM_XXX. Maybe these could be documented with ListView_XXX macros so that searching for either will return the right page.
Similarly there should be a policy wrt. documenting xxxA and/or xxxW. It seems like they should end up being documented on the same (man) page and that obviously we don't want to duplicate the documentation in the source. But there does not seem to be anything in place currently. It would probably be a good idea to also have a general way to group related functions together (e.g. all the MSVCRT execXXX variants).
Did I say yet that I think a testing framework with many tests would be a great boon for Wine? No! Well, I'm going to stop there anyway. Lucky you :-)
After several people had posted their thoughts Alexandre posted a few shorter replies that summed up several points:
Yes it would be nice to have a free Win API documentation, but it definitely doesn't belong inside the Wine source. First it would be a huge bloat in the source; and more importantly the Wine source doesn't define the Windows API, it is defined by Microsoft.
I'd much rather have developers spend their time writing code. Making them duplicate the whole MSDN documentation would be a huge waste of their time. Our resources are not infinite, and it's much more useful to have 100% API coverage with no docs at all than 50% coverage and tons of docs.
I think you misunderstand my position; I'm not opposed to having a comment at the start of the function explaining the general goal and the non-obvious things going on. But if you need more than a couple of paragraphs to do this, then either there are too many non-obvious things going on in your function, or you are wasting space explaining the obvious.
I do strongly think that the goal should be to write code that doesn't require documentation in order to be understood. Of course adding a small amount of comments is a good idea; but when you start having more lines of documentation than lines of code, something is very wrong IMO.
But this is mainly a matter of personal taste, and except in extreme cases I'm not going to reject code because it has too much (or not enough) documentation.
Almost everyone agreed though that it is important to document the obscurities of the Windows API where it differs from the MSDN documentation.
Uwe Bonnes went on to posted some related information, " while this doesn't answer many question, I think it is worth knowing: Javob Navia has achieved the explicit right to distribute the win32 help files with his lcc-win32. You can download lcc-win32 and win32help for free at http://www.cs.virginia.edu/~lcc-win32/ "
Sharon And Joy
Kernel Traffic is grateful to be developed on a computer donated by Professor Greg Benson and Professor Allan Cruse in the Department of Computer Science at the University of San Francisco. This is the same department that invented FlashMob Computing. Kernel Traffic is hosted by the generous folks at kernel.org. All pages on this site are copyright their original authors, and distributed under the terms of the GNU General Public License version 2.0.