- Wine-Devel - list.winehq.org

Re: Documentation fixes
by Alexandre Julliard July 13, 2001

July 13, 2001

Patrik Stridvall <ps(a)leissner.se> writes: > Well, there is the issue of maintaining redundant information. > Sure winapi_check can (and indeed was the original reason for it) > find missmatchs. But given the number of errors I have seen people > make that winapi_check detected, we really should avoid having > redundant information if we can. If there is an easy way to avoid it, sure. But if it requires a Perl script as complex as winapi_check, especially the maintaining of the *.api files, I'm not sure it's a win. And it seems to me you are finding a lot more errors in the comments than in the spec files ;-) > In addition it will be much easier for the developers (especially > newbies). If you change the prototype in the .c files or the > ordinal in the comment above it, it will be enough. Stub files > will be something normal developers needn't concern himself with. If normal developers need to change the spec file for an existing function, something is seriously wrong. The spec entry is dictated by the dll interface, and there is no reason to change it (except maybe to change a 'ptr' into an 'str', but this is a cosmetic issue). -- Alexandre Julliard julliard(a)winehq.com

1 0

RE: Documentation fixes
by Patrik Stridvall July 13, 2001

July 13, 2001

> Patrik Stridvall <ps(a)leissner.se> writes: > > > For normal entry point, however, I respectfully disagree. > > One of the major reasons of having automatically > > generated .spec files is to avoid having to > > store redundant information. The needed information > > is already in the C function declaration and storing > > in a comment as well brings us back to the current > > situation. Sure it makes that generator less > > complicatated but it really isn't that important > > as long as it is reliable and not ambigeous. > > IMO, this is true if we can make the generator work purely on the > source code, so that you can give it the unmodified source of a > Windows dll and it spits out the spec file. If you need to add > comments before each and every exported function, then I don't see > much advantage to parsing the source. You might as well put all the > information in the comment (or leave it in the current spec file for > that matter). Well, the ordinal of each function and for that that matter which functions that should be exported must be specified somewhere. Currently winapi_extract takes this information from the comment lines looking like this in the nearest preceding comment: * Foo (BAR.@) All non-static functions with such preceding comment line(s) is considered exported using the name specified in the comment as the external name. Of course, I can take this information from anywhere, but for obvious reason I can't guess it. If the unmodified source contains Microsoft Visual C++ __declspec(dllexport) directives or the project has a Microsoft Export file (a .def file) I can generate a spec file. This is not supported yet, but is no particular problem supporting in itself. A little worse problem is that I currently doesn't extract the function "kinds" (long ptr double str wstr) from the source but use the tools/winapi_check/win{16,32}/*.api files to determine the "kinds". This is not a teoretical problem, however it might take some time to fix all the same. But after that winapi_extract will be able to take unmodified source if __declspec(dllexport) directives or a .def file exists. However I think we concentrate primarily on the Wine source. I think as far the it is concerned it will suffice to use comment lines like * Foo (BAR.@) to extract the normal entries for the spec files. The stubs and forwards need to have special handling but then so must it in the case of __declspec(dllexport) directives or a .def file as well. There is no problem for winapi_extract to support all the above either (except implementation time of course). > Basically, if the source parsing allows doing more than we do now > (like build spec files for new dlls) it's worthwhile; if all it does > is generate the existing spec files some other way I don't think > there's much point. After all, we have the spec files already, and > they are not going to change much. Well, there is the issue of maintaining redundant information. Sure winapi_check can (and indeed was the original reason for it) find missmatchs. But given the number of errors I have seen people make that winapi_check detected, we really should avoid having redundant information if we can. In addition it will be much easier for the developers (especially newbies). If you change the prototype in the .c files or the ordinal in the comment above it, it will be enough. Stub files will be something normal developers needn't concern himself with. > Another use of the source parser could be to generate more detailed > debugging information for +relay; but in this case I'd say it should > go to a completely different file, used by some external relay dumping > program. I don't want all the extra debug information to clutter up > the spec files. That is another thing that I have planned to do with winapi_extract. I don't have any good idea how this should look like yet. You (or somebody else) are welcome to write a specification on exactly what you want so I can fix the how when I have time.

1 0

Re: Documentation fixes
by Alexandre Julliard July 13, 2001

July 13, 2001

Patrik Stridvall <ps(a)leissner.se> writes: > For normal entry point, however, I respectfully disagree. > One of the major reasons of having automatically > generated .spec files is to avoid having to > store redundant information. The needed information > is already in the C function declaration and storing > in a comment as well brings us back to the current > situation. Sure it makes that generator less > complicatated but it really isn't that important > as long as it is reliable and not ambigeous. IMO, this is true if we can make the generator work purely on the source code, so that you can give it the unmodified source of a Windows dll and it spits out the spec file. If you need to add comments before each and every exported function, then I don't see much advantage to parsing the source. You might as well put all the information in the comment (or leave it in the current spec file for that matter). Basically, if the source parsing allows doing more than we do now (like build spec files for new dlls) it's worthwhile; if all it does is generate the existing spec files some other way I don't think there's much point. After all, we have the spec files already, and they are not going to change much. Another use of the source parser could be to generate more detailed debugging information for +relay; but in this case I'd say it should go to a completely different file, used by some external relay dumping program. I don't want all the extra debug information to clutter up the spec files. -- Alexandre Julliard julliard(a)winehq.com

1 0

Re: GetCommState16 ....
by lawson_whitney＠juno.com July 13, 2001

July 13, 2001

Good day! If you get this, neither this patch nor any of the recently committed patches that muck with 16 bit comms bother my 16 bit comms app. Mike, did you not get juno.tar.gz or do you just not want to be bothered filling in the junk to make a new account? Regards, Lawson ---cut--- ________________________________________________________________ GET INTERNET ACCESS FROM JUNO! Juno offers FREE or PREMIUM Internet access for less! Join Juno today! For your FREE software, visit: http://dl.www.juno.com/get/tagj.

1 0

hello all
by Brandon Kilgore July 13, 2001

July 13, 2001

Hi everyone, Just letting you all know that there's a new listener out here, eager to pick up on what you're discussing. I'm only 17, so I'll be pretty much staying out of the way, but I love programming so hopefully you won't mind if I stick my hand up to ask a question or respond to someone every once in a while. Just so you can know a bit about me...I used to be a purely QBasic programmer in my "early" days, but a few years ago I began broadening my horizons, mostly with HTML and Visual Basic. For a long time I had wanted to learn C but never really got around to it, but a little over a year ago I finally sat down and started learning, and now its one of the only languages I ever use. Some other languages I currently program in (or would come back to me if need be :-) : C/C++/Visual C++ (Q)Basic/Visual Basic HTML Perl BF (there's an interesting language...) Java/JavaScript WISE InstallMaster scripting ;-) Anyways, I'll let you all get back to the important development discussions. I'll be talking to you... - Brandon

2 2

RE: Documentation fixes
by Patrik Stridvall July 13, 2001

July 13, 2001

> Patrik Stridvall <ps(a)leissner.se> writes: > > > Like: > > > > > /************************************************************* > ********** > > * strcpy (MSVCRT.@) > > */ > > #if 0 /* Suppress warnings */ > > extern char *strcpy(char *dest, const char *src); > > #endif > > > > Perhaps we could do the same with atom functions and lstrcmpi? > > The #if 0 #endif isn't even needed for them I believe. > > That's quite ugly IMO. The #if 0 #endif or having to have a documentation comment at all? Anyway the #if 0 is not needed I thought it might be needed in some cases but it is not. I mistakingly believed it might be type conflicts but it can't be since any exported function must of course use the C library types otherwise you can't export them directly. If you are refering to the documentation comment, I can't really see why. All other functions have it and adding additional documentation might be a good idea in some cases as well. Furthermore the extern declaration makes it possible for the C compiler to check that the prototype is the same as the prototype in the included files. I spotted several error when doing the patch because of this. As hinted above, I have implemented a working solution that does what I have described above. See separate mail. > As long as we require comments, we might as > well put everything explicitly in the comment, something like: > > /* ##spec## msvcrt "@ cdecl strcpy(ptr str) strcpy" */ > > (we can probably come up with a better syntax, but you get the idea). > Then we can simply grep for '##spec##' and extract everything into the > spec file. We can do the same for forwards etc. (and in fact we could > do it for normal entry points as well). For forwards, stubs and other special cases, perhaps. I don't like it very much but it is acceptable. But we need not decide that now. I will think more about it and come back later with some kind of proposal that might or might not match yours. I'm not sure, we will see. For normal entry point, however, I respectfully disagree. One of the major reasons of having automatically generated .spec files is to avoid having to store redundant information. The needed information is already in the C function declaration and storing in a comment as well brings us back to the current situation. Sure it makes that generator less complicatated but it really isn't that important as long as it is reliable and not ambigeous. PS. For the record: I consider winapi_extract a prototype not something that nessary will finally use in "production". We might of course use it, but I would rather rewrite it so it becomes simpler and more reliable. Perhaps it shouldn't be in Perl but in C instead? Oh, well, that is a minor issue compared to how the information should be stored.

1 0

To strip or not to strip
by Jeremy White July 13, 2001

July 13, 2001

We've always built the CodeWeavers Wine RPM unstripped, in the theory that it made supporting Wine newbies easier. However, AFAICT from watching cemw, we never get into a situation where a newbie goes into winedbg; more often, they shift first to the CVS tip, and from there maybe to winedbg. So, it seems like shipping debug symbols may just be a waste of bandwidth. (Note, we build with all full logging enabled, and we'll never change that). However, before we go ahead and yank the debug info out of our RPM, I thought I'd post a note, and let someone tell me if I'm wrong. Thanks, Jer

1 0

Re: Documentation fixes
by Alexandre Julliard July 12, 2001

July 12, 2001

Patrik Stridvall <ps(a)leissner.se> writes: > Like: > > /*********************************************************************** > * strcpy (MSVCRT.@) > */ > #if 0 /* Suppress warnings */ > extern char *strcpy(char *dest, const char *src); > #endif > > Perhaps we could do the same with atom functions and lstrcmpi? > The #if 0 #endif isn't even needed for them I believe. That's quite ugly IMO. As long as we require comments, we might as well put everything explicitly in the comment, something like: /* ##spec## msvcrt "@ cdecl strcpy(ptr str) strcpy" */ (we can probably come up with a better syntax, but you get the idea). Then we can simply grep for '##spec##' and extract everything into the spec file. We can do the same for forwards etc. (and in fact we could do it for normal entry points as well). -- Alexandre Julliard julliard(a)winehq.com

2 1

RE: Documentation fixes
by Patrik Stridvall July 12, 2001

July 12, 2001

> > The problem is that if I say that the memory directory doesn't > > "belong" to dlls/user/user.spec winapi_{check,extract,fixup} will > > not find implementations for all functions, which will cause > > problems. > > > > For example how should winapi_extract know that I should > generate the line > > 471 pascal16 lstrcmpi(str str) lstrcmpiA > > when it generates the spec files? > > Well, it's a more general problem, namely that the spec files can > reference functions that are not implemented directly in the dll. > > You also have for instance: > > @ cdecl strcpy(ptr str) strcpy > > in MSVCRT, and strcpy is clearly not implemented there since it's in > the C library. So you cannot assume that only the functions contained > in the dll can be used in the spec files, it is legal for the spec > file to reference external functions. True. I didn't even thought of that particular problem. Functions like strcpy is currently suppressed by having it listed in tools/winapi_check/nativeapi.dat, but that is a little kludgy. [Thinking...] Well you could simply have an function documentation comment without a function implementation in some file that belongs to MSVCRT. Like: /*********************************************************************** * strcpy (MSVCRT.@) */ #if 0 /* Suppress warnings */ extern char *strcpy(char *dest, const char *src); #endif Perhaps we could do the same with atom functions and lstrcmpi? The #if 0 #endif isn't even needed for them I believe. > > I think that we need to move the solution of this problem one step > > up the "ladder" and discuss the more general problem: > > How should we store the information needed to generate > > the spec files in the source, especially concerning > > the forwards and stubs? > > You'll need a file somewhere that specifies all the entries that > cannot be determined automatically from the source. You simply cannot > build a 100% correct spec file based only on the function comments. Yes. I have some ideas, but no really good one. My currently best suggestion is having a .spec.in file that approximately looks like the .spec files but supports configure like substitutions. foo.spec.in: ---8<--- name foo type win32 init @init@ rsrc foo.res import baz.dll @debug_channels@ 101 forward Bar BAZ.Bar 102 stub BarFoo @fixed@ @ forward Foo BAZ.Foo @ stub FooBar @unfixed@ ---8<--- And simply let winapi_extract or whatever simple substitute @init@, @debug_channels@, @fixed@ and @unfixed@ with what can be extracted from the source. > And you definitely do not want to need to parse KERNEL source files > (like the ones in memory/) to build the USER spec file. Of course. The question was whether the memory directory belongs to USER or not. I have now accepted that it does not.

1 0

Re: Documentation fixes
by Alexandre Julliard July 12, 2001

July 12, 2001

Patrik Stridvall <ps(a)leissner.se> writes: > > No, USER does not use the memory directory. It links directly to > > libkernel32.so because it needs some internal functions in there, > > Like the atom functions that are implemented in memory/atom.c I guess > you mean. Actually no, the atom functions are similar to lstrcmpi, they are exported from kernel so we don't need to link to libkernel32.so to get them (and they shouldn't have USER comments either). The real problem is the internal kernel functions called by user, things like THUNK_Alloc or LOCAL_Alloc. > The problem is that if I say that the memory directory doesn't > "belong" to dlls/user/user.spec winapi_{check,extract,fixup} will > not find implementations for all functions, which will cause > problems. > > For example how should winapi_extract know that I should generate the line > 471 pascal16 lstrcmpi(str str) lstrcmpiA > when it generates the spec files? Well, it's a more general problem, namely that the spec files can reference functions that are not implemented directly in the dll. You also have for instance: @ cdecl strcpy(ptr str) strcpy in MSVCRT, and strcpy is clearly not implemented there since it's in the C library. So you cannot assume that only the functions contained in the dll can be used in the spec files, it is legal for the spec file to reference external functions. > I think that we need to move the solution of this problem one step > up the "ladder" and discuss the more general problem: > How should we store the information needed to generate > the spec files in the source, especially concerning > the forwards and stubs? You'll need a file somewhere that specifies all the entries that cannot be determined automatically from the source. You simply cannot build a 100% correct spec file based only on the function comments. And you definitely do not want to need to parse KERNEL source files (like the ones in memory/) to build the USER spec file. -- Alexandre Julliard julliard(a)winehq.com

1 0