1 /////////////////////////////////////////////////////////////////////////////
2 // Name: ifacecheck.cpp
3 // Purpose: Interface headers <=> real headers coherence checker
4 // Author: Francesco Montorsi
7 // Copyright: (c) 2008 Francesco Montorsi
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
11 // For compilers that support precompilation, includes "wx/wx.h".
12 #include "wx/wxprec.h"
18 // for all others, include the necessary headers
23 #include "wx/cmdline.h"
24 #include "wx/textfile.h"
25 #include "wx/filename.h"
26 #include "wx/stopwatch.h" // for wxGetLocalTime
27 #include "xmlparser.h"
29 // global verbosity flag
30 bool g_verbose
= false;
34 // ----------------------------------------------------------------------------
36 // ----------------------------------------------------------------------------
38 #define API_DUMP_FILE "dump.api.txt"
39 #define INTERFACE_DUMP_FILE "dump.interface.txt"
41 #define PROCESS_ONLY_OPTION "p"
42 #define USE_PREPROCESSOR_OPTION "u"
44 #define MODIFY_SWITCH "m"
45 #define DUMP_SWITCH "d"
46 #define HELP_SWITCH "h"
47 #define VERBOSE_SWITCH "v"
49 static const wxCmdLineEntryDesc g_cmdLineDesc
[] =
51 { wxCMD_LINE_OPTION
, USE_PREPROCESSOR_OPTION
, "use-preproc",
52 "uses the preprocessor output to increase the checker accuracy",
53 wxCMD_LINE_VAL_STRING
, wxCMD_LINE_NEEDS_SEPARATOR
},
54 { wxCMD_LINE_OPTION
, PROCESS_ONLY_OPTION
, "process-only",
55 "processes only header files matching the given wildcard",
56 wxCMD_LINE_VAL_STRING
, wxCMD_LINE_NEEDS_SEPARATOR
},
57 { wxCMD_LINE_SWITCH
, MODIFY_SWITCH
, "modify",
58 "modify the interface headers to match the real ones" },
59 { wxCMD_LINE_SWITCH
, DUMP_SWITCH
, "dump",
60 "dump both interface and API to plain text dump.*.txt files" },
61 { wxCMD_LINE_SWITCH
, HELP_SWITCH
, "help",
62 "show help message", wxCMD_LINE_VAL_NONE
, wxCMD_LINE_OPTION_HELP
},
63 { wxCMD_LINE_SWITCH
, VERBOSE_SWITCH
, "verbose",
65 { wxCMD_LINE_PARAM
, NULL
, NULL
,
66 "gccXML", wxCMD_LINE_VAL_STRING
, wxCMD_LINE_OPTION_MANDATORY
},
67 { wxCMD_LINE_PARAM
, NULL
, NULL
,
68 "doxygenXML", wxCMD_LINE_VAL_STRING
, wxCMD_LINE_OPTION_MANDATORY
},
72 class IfaceCheckApp
: public wxAppConsole
75 // don't use builtin cmd line parsing:
76 virtual bool OnInit() { m_modify
=false; return true; }
79 bool ParsePreprocessorOutput(const wxString
& filename
);
82 int CompareClasses(const wxClass
* iface
, const wxClassPtrArray
& api
);
83 bool FixMethod(const wxString
& header
, const wxMethod
* iface
, const wxMethod
* api
);
86 void PrintStatistics(long secs
);
88 bool IsToProcess(const wxString
& headername
) const
90 if (m_strToMatch
.IsEmpty())
92 return wxMatchWild(m_strToMatch
, headername
, false);
96 wxXmlGccInterface m_gccInterface
; // "real" headers API
97 wxXmlDoxygenInterface m_doxyInterface
; // doxygen-commented headers API
99 // was the MODIFY_SWITCH passed?
102 // if non-empty, then PROCESS_ONLY_OPTION was passed and this is the
103 // wildcard expression to match
104 wxString m_strToMatch
;
107 IMPLEMENT_APP_CONSOLE(IfaceCheckApp
)
109 int IfaceCheckApp::OnRun()
111 long startTime
= wxGetLocalTime(); // for timing purpose
113 wxCmdLineParser
parser(g_cmdLineDesc
, argc
, argv
);
115 wxString::Format("wxWidgets Interface checker utility (built %s against %s)",
116 __DATE__
, wxVERSION_STRING
));
118 // parse the command line...
120 wxString preprocFile
;
121 switch (parser
.Parse())
124 if (parser
.Found(VERBOSE_SWITCH
))
127 // IMPORTANT: parsing #define values must be done _before_ actually
128 // parsing the GCC/doxygen XML files
129 if (parser
.Found(USE_PREPROCESSOR_OPTION
, &preprocFile
))
131 if (!ParsePreprocessorOutput(preprocFile
))
135 // in any case set basic std preprocessor #defines:
136 m_doxyInterface
.AddPreprocessorValue("NULL", "0");
138 g_bLogEnabled
= false;
140 // parse the two XML files which contain the real and the doxygen interfaces
141 // for wxWidgets API:
142 if (!m_gccInterface
.Parse(parser
.GetParam(0)) ||
143 !m_doxyInterface
.Parse(parser
.GetParam(1)))
146 g_bLogEnabled
= true;
148 if (parser
.Found(DUMP_SWITCH
))
150 LogMessage("Dumping real API to '%s'...", API_DUMP_FILE
);
151 m_gccInterface
.Dump(API_DUMP_FILE
);
153 LogMessage("Dumping interface API to '%s'...", INTERFACE_DUMP_FILE
);
154 m_doxyInterface
.Dump(INTERFACE_DUMP_FILE
);
158 if (parser
.Found(MODIFY_SWITCH
))
161 if (parser
.Found(PROCESS_ONLY_OPTION
, &m_strToMatch
))
163 size_t len
= m_strToMatch
.Len();
164 if (m_strToMatch
.StartsWith("\"") &&
165 m_strToMatch
.EndsWith("\"") &&
167 m_strToMatch
= m_strToMatch
.Mid(1, len
-2);
174 PrintStatistics(wxGetLocalTime() - startTime
);
178 wxPrintf("\nThis utility checks that the interface XML files created by Doxygen are in\n");
179 wxPrintf("synch with the real headers (whose contents are extracted by the gcc XML file).\n\n");
180 wxPrintf("The 'gccXML' parameter should be the wxapi.xml file created by the 'rungccxml.sh'\n");
181 wxPrintf("script which resides in 'utils/ifacecheck'.\n");
182 wxPrintf("The 'doxygenXML' parameter should be the index.xml file created by Doxygen\n");
183 wxPrintf("for the wxWidgets 'interface' folder.\n\n");
184 wxPrintf("Since the gcc XML file does not contain info about #defines, if you use\n");
185 wxPrintf("the -%s option, you'll get a smaller number of false warnings.\n",
186 USE_PREPROCESSOR_OPTION
);
188 // HELP_SWITCH was passed or a syntax error occurred
195 void IfaceCheckApp::ShowProgress()
201 bool IfaceCheckApp::Compare()
203 const wxClassArray
& interface
= m_doxyInterface
.GetClasses();
206 int mcount
= 0, ccount
= 0;
208 LogMessage("Comparing the interface API to the real API (%d classes to compare)...",
209 interface
.GetCount());
211 if (!m_strToMatch
.IsEmpty())
212 LogMessage("Processing only header files matching '%s' expression.", m_strToMatch
);
214 for (unsigned int i
=0; i
<interface
.GetCount(); i
++)
216 // only compare the methods which are available for the port
217 // for which the gcc XML was produced
218 if (interface
[i
].GetAvailability() != wxPORT_UNKNOWN
&&
219 (interface
[i
].GetAvailability() & m_gccInterface
.GetInterfacePort()) == 0) {
222 LogMessage("skipping class '%s' since it's not available for the %s port.",
223 interface
[i
].GetName(), m_gccInterface
.GetInterfacePortName());
225 continue; // skip this method
228 // shorten the name of the header so the log file is more readable
229 // and also for calling IsToProcess() against it
230 wxString header
= wxFileName(interface
[i
].GetHeader()).GetFullName();
232 if (!IsToProcess(header
))
233 continue; // skip this one
235 wxString cname
= interface
[i
].GetName();
239 // search in the real headers for i-th interface class; we search for
240 // both class cname and cnameBase since in wxWidgets world tipically
241 // class cname is platform-specific while the real public interface of
242 // that class is part of the cnameBase class.
243 c
= m_gccInterface
.FindClass(cname
);
245 c
= m_gccInterface
.FindClass(cname
+ "Base");
248 // sometimes the platform-specific class is named "wxGeneric" + cname
250 c
= m_gccInterface
.FindClass("wxGeneric" + cname
.Mid(2));
252 c
= m_gccInterface
.FindClass("wxGtk" + cname
.Mid(2));
255 if (api
.GetCount()>0) {
257 // there is a class with exactly the same name!
258 mcount
+= CompareClasses(&interface
[i
], api
);
262 LogMessage("%s: couldn't find the real interface for the '%s' class",
268 LogMessage("%d methods (%.1f%%) of the interface headers do not exist in the real headers",
269 mcount
, (float)(100.0 * mcount
/m_doxyInterface
.GetMethodCount()));
270 LogMessage("%d classes (%.1f%%) of the interface headers do not exist in the real headers",
271 ccount
, (float)(100.0 * ccount
/m_doxyInterface
.GetClassesCount()));
276 int IfaceCheckApp::CompareClasses(const wxClass
* iface
, const wxClassPtrArray
& api
)
278 wxString searchedclasses
;
279 const wxMethod
*real
;
282 wxASSERT(iface
&& api
.GetCount()>0);
284 // build a string with the names of the API classes compared to iface
285 for (unsigned int j
=0; j
<api
.GetCount(); j
++)
286 searchedclasses
+= "/" + api
[j
]->GetName();
287 searchedclasses
.Remove(0, 1);
289 // shorten the name of the header so the log file is more readable
290 wxString header
= wxFileName(iface
->GetHeader()).GetFullName();
292 for (unsigned int i
=0; i
<iface
->GetMethodCount(); i
++)
294 const wxMethod
& m
= iface
->GetMethod(i
);
297 // only compare the methods which are available for the port
298 // for which the gcc XML was produced
299 if (m
.GetAvailability() != wxPORT_UNKNOWN
&&
300 (m
.GetAvailability() & m_gccInterface
.GetInterfacePort()) == 0) {
303 LogMessage("skipping method '%s' since it's not available for the %s port.",
304 m
.GetAsString(), m_gccInterface
.GetInterfacePortName());
306 continue; // skip this method
309 // search in the methods of the api classes provided
310 for (unsigned int j
=0; j
<api
.GetCount(); j
++)
312 real
= api
[j
]->FindMethod(m
);
314 matches
++; // there is a real matching prototype! It's ok!
320 wxMethodPtrArray overloads
;
322 // try searching for methods with the same name but with
323 // different return type / arguments / qualifiers
324 for (unsigned int j
=0; j
<api
.GetCount(); j
++)
326 wxMethodPtrArray results
= api
[j
]->FindMethodsNamed(m
.GetName());
328 // append "results" array to "overloads"
329 WX_APPEND_ARRAY(overloads
, results
);
332 #define HACK_TO_AUTO_CORRECT_ONLY_VIRTUAL_AND_CONST_ATTRIBUTES 1
333 #if HACK_TO_AUTO_CORRECT_ONLY_VIRTUAL_AND_CONST_ATTRIBUTES
334 for (unsigned int k
=0; k
<results
.GetCount(); k
++)
335 if (results
[k
]->MatchesExceptForAttributes(m
) &&
336 results
[k
]->IsPureVirtual() == m
.IsPureVirtual())
338 // fix default values of results[k]:
339 wxMethod
tmp(*results
[k
]);
340 tmp
.SetArgumentTypes(m
.GetArgumentTypes());
342 // modify interface header
343 if (FixMethod(iface
->GetHeader(), &m
, &tmp
))
344 LogMessage("Adjusted attributes of '%s' method", m
.GetAsString());
355 #if HACK_TO_AUTO_CORRECT_ONLY_VIRTUAL_AND_CONST_ATTRIBUTES
360 if (overloads
.GetCount()==0)
363 TODO: sometimes the interface headers re-document a method
364 inherited from a base class even if the real header does
365 not actually re-implement it.
366 To avoid false positives, we'd need to search in the base classes
367 of api[] classes and search for a matching method.
369 LogMessage("%s: real '%s' class has no method '%s'",
370 header
, searchedclasses
, m
.GetAsString());
371 // we've found no overloads
375 // first, output a warning
376 wxString warning
= header
;
377 if (overloads
.GetCount()>1)
378 warning
+= wxString::Format(": in the real headers there are %d overloads of '%s' for "
379 "'%s' all with different signatures:\n",
380 overloads
.GetCount(), m
.GetName(), searchedclasses
);
382 warning
+= wxString::Format(": in the real headers there is a method '%s' for '%s'"
383 " but has different signature:\n",
384 m
.GetName(), searchedclasses
);
386 // get a list of the prototypes with _all_ possible attributes:
387 warning
+= "\tdoxy header: " + m
.GetAsString(true, true, true);
388 for (unsigned int j
=0; j
<overloads
.GetCount(); j
++)
389 warning
+= "\n\treal header: " + overloads
[j
]->GetAsString(true, true, true);
391 wxPrint(warning
+ "\n");
394 if (overloads
.GetCount()>1)
396 // TODO: decide which of these overloads is the most "similar" to m
397 // and eventually modify it
399 wxPrint("\tmanual fix is required\n");
403 wxASSERT(overloads
.GetCount() == 1);
407 wxPrint("\tfixing it...\n");
410 FixMethod(iface
->GetHeader(), &m
, overloads
[0]);
417 #if HACK_TO_AUTO_CORRECT_ONLY_VIRTUAL_AND_CONST_ATTRIBUTES
426 bool IfaceCheckApp::FixMethod(const wxString
& header
, const wxMethod
* iface
, const wxMethod
* api
)
428 wxASSERT(iface
&& api
);
431 if (!file
.Open(header
)) {
432 LogError("\tcan't open the '%s' header file.", header
);
436 // GetLocation() returns the line where the last part of the prototype is placed:
437 int end
= iface
->GetLocation()-1;
438 if (end
<= 0 || end
>= (int)file
.GetLineCount()) {
439 LogWarning("\tinvalid location info for method '%s': %d.",
440 iface
->GetAsString(), iface
->GetLocation());
444 if (!file
.GetLine(end
).Contains(";")) {
445 LogWarning("\tinvalid location info for method '%s': %d.",
446 iface
->GetAsString(), iface
->GetLocation());
450 // is this a one-line prototype declaration?
451 bool founddecl
= false;
453 if (file
.GetLine(end
).Contains(iface
->GetName()))
455 // yes, this prototype is all on this line:
463 // find the start point of this prototype declaration:
465 !file
.GetLine(start
).Contains(";") &&
466 !file
.GetLine(start
).Contains("*/"))
470 founddecl
|= file
.GetLine(start
).Contains(iface
->GetName());
473 // start-th line contains either the declaration of another prototype
474 // or the closing tag */ of a doxygen comment; start one line below
478 if (start
<= 0 || !founddecl
)
480 LogError("\tcan't find the beginning of the declaration of '%s' method in '%s' header looking backwards from line %d",
481 iface
->GetAsString(), header
, end
);
485 // remove the old prototype
486 for (int i
=start
; i
<=end
; i
++)
487 file
.RemoveLine(start
); // remove (end-start)-nth times the start-th line
489 #define INDENTATION_STR wxString(" ")
491 // if possible, add also the @deprecated tag in the doxygen comment if it's missing
492 int deprecationOffset
= 0;
493 if (file
.GetLine(start
-1).Contains("*/") &&
494 (api
->IsDeprecated() && !iface
->IsDeprecated()))
496 file
.RemoveLine(start
-1);
497 file
.InsertLine(INDENTATION_STR
+ INDENTATION_STR
+
498 "@deprecated @todo provide deprecation description", start
-1);
499 file
.InsertLine(INDENTATION_STR
+ "*/", start
++);
501 // we have added a new line in the final balance
507 // discard API argument names and replace them with those parsed from doxygen XML:
508 const wxArgumentTypeArray
& doxygenargs
= iface
->GetArgumentTypes();
509 const wxArgumentTypeArray
& realargs
= api
->GetArgumentTypes();
510 if (realargs
.GetCount() == doxygenargs
.GetCount())
512 for (unsigned int j
=0; j
<doxygenargs
.GetCount(); j
++)
513 if (doxygenargs
[j
]==realargs
[j
])
514 realargs
[j
].SetArgumentName(doxygenargs
[j
].GetArgumentName());
516 tmp
.SetArgumentTypes(realargs
);
519 #define WRAP_COLUMN 80
521 wxArrayString toinsert
;
522 toinsert
.Add(INDENTATION_STR
+ tmp
.GetAsString() + ";");
524 int nStartColumn
= toinsert
[0].Find('(');
525 wxASSERT(nStartColumn
!= wxNOT_FOUND
);
527 // wrap lines too long at comma boundaries
528 for (unsigned int i
=0; i
<toinsert
.GetCount(); i
++)
530 size_t len
= toinsert
[i
].Len();
531 if (len
> WRAP_COLUMN
)
533 wxASSERT(i
== toinsert
.GetCount()-1);
536 wxString tmpleft
= toinsert
[i
].Left(WRAP_COLUMN
);
537 int comma
= tmpleft
.Find(',', true /* from end */);
538 if (comma
== wxNOT_FOUND
)
539 break; // break out of the for cycle...
541 toinsert
.Add(wxString(' ', nStartColumn
+1) +
542 toinsert
[i
].Right(len
-comma
-2)); // exclude the comma and the space after it
543 toinsert
[i
] = tmpleft
.Left(comma
+1); // include the comma
547 // insert the new lines
548 for (unsigned int i
=0; i
<toinsert
.GetCount(); i
++)
549 file
.InsertLine(toinsert
[i
], start
+i
);
551 // now save the modification
553 LogError("\tcan't save the '%s' header file.", header
);
557 // how many lines did we add/remove in total?
558 int nOffset
= toinsert
.GetCount() + deprecationOffset
- (end
-start
+1);
563 LogMessage("\tthe final row offset for following methods is %d lines.", nOffset
);
565 // update the other method's locations for those methods which belong to the modified header
566 // and are placed _below_ the modified method
567 wxClassPtrArray cToUpdate
= m_doxyInterface
.FindClassesDefinedIn(header
);
568 for (unsigned int i
=0; i
< cToUpdate
.GetCount(); i
++)
570 for (unsigned int j
=0; j
< cToUpdate
[i
]->GetMethodCount(); j
++)
572 wxMethod
& m
= cToUpdate
[i
]->GetMethod(j
);
573 if (m
.GetLocation() > iface
->GetLocation())
575 // update the location of this method
576 m
.SetLocation(m
.GetLocation()+nOffset
);
584 bool IfaceCheckApp::ParsePreprocessorOutput(const wxString
& filename
)
587 if (!tf
.Open(filename
)) {
588 LogError("can't open the '%s' preprocessor output file.", filename
);
593 for (unsigned int i
=0; i
< tf
.GetLineCount(); i
++)
595 const wxString
& line
= tf
.GetLine(i
);
596 wxString defnameval
= line
.Mid(8); // what follows the "#define " string
598 // the format of this line should be:
599 // #define DEFNAME DEFVALUE
600 if (!line
.StartsWith("#define ")) {
601 LogError("unexpected content in '%s' at line %d.", filename
, i
+1);
605 if (defnameval
.Contains(" "))
608 wxString defname
= defnameval
.BeforeFirst(' ');
609 if (defname
.Contains("("))
610 continue; // this is a macro, skip it!
613 wxString defval
= defnameval
.AfterFirst(' ').Strip(wxString::both
);
614 if (defval
.StartsWith("(") && defval
.EndsWith(")"))
615 defval
= defval
.Mid(1, defval
.Len()-2);
617 // store this pair in the doxygen interface, where it can be useful
618 m_doxyInterface
.AddPreprocessorValue(defname
, defval
);
623 // it looks like the format of this line is:
625 // we are not interested to symbols #defined to nothing,
626 // so we just ignore this line.
630 LogMessage("Parsed %d preprocessor #defines from '%s' which will be used later...",
636 void IfaceCheckApp::PrintStatistics(long secs
)
638 LogMessage("wx real headers contains declaration of %d classes (%d methods)",
639 m_gccInterface
.GetClassesCount(), m_gccInterface
.GetMethodCount());
640 LogMessage("wx interface headers contains declaration of %d classes (%d methods)",
641 m_doxyInterface
.GetClassesCount(), m_doxyInterface
.GetMethodCount());
642 LogMessage("total processing took %d seconds.", secs
);