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
24 #include "wx/cmdline.h"
25 #include "wx/textfile.h"
26 #include "wx/filename.h"
27 #include "wx/stopwatch.h" // for wxGetLocalTime
28 #include "xmlparser.h"
30 // global verbosity flag
31 bool g_verbose
= false;
35 // ----------------------------------------------------------------------------
37 // ----------------------------------------------------------------------------
39 #define API_DUMP_FILE "dump.api.txt"
40 #define INTERFACE_DUMP_FILE "dump.interface.txt"
42 #define PROCESS_ONLY_OPTION "p"
43 #define USE_PREPROCESSOR_OPTION "u"
45 #define MODIFY_SWITCH "m"
46 #define DUMP_SWITCH "d"
47 #define HELP_SWITCH "h"
48 #define VERBOSE_SWITCH "v"
50 static const wxCmdLineEntryDesc g_cmdLineDesc
[] =
52 { wxCMD_LINE_OPTION
, USE_PREPROCESSOR_OPTION
, "use-preproc",
53 "uses the preprocessor output to increase the checker accuracy",
54 wxCMD_LINE_VAL_STRING
, wxCMD_LINE_NEEDS_SEPARATOR
},
55 { wxCMD_LINE_OPTION
, PROCESS_ONLY_OPTION
, "process-only",
56 "processes only header files matching the given wildcard",
57 wxCMD_LINE_VAL_STRING
, wxCMD_LINE_NEEDS_SEPARATOR
},
58 { wxCMD_LINE_SWITCH
, MODIFY_SWITCH
, "modify",
59 "modify the interface headers to match the real ones" },
60 { wxCMD_LINE_SWITCH
, DUMP_SWITCH
, "dump",
61 "dump both interface and API to plain text dump.*.txt files" },
62 { wxCMD_LINE_SWITCH
, HELP_SWITCH
, "help",
63 "show help message", wxCMD_LINE_VAL_NONE
, wxCMD_LINE_OPTION_HELP
},
64 { wxCMD_LINE_SWITCH
, VERBOSE_SWITCH
, "verbose",
66 { wxCMD_LINE_PARAM
, NULL
, NULL
,
67 "gccXML", wxCMD_LINE_VAL_STRING
, wxCMD_LINE_OPTION_MANDATORY
},
68 { wxCMD_LINE_PARAM
, NULL
, NULL
,
69 "doxygenXML", wxCMD_LINE_VAL_STRING
, wxCMD_LINE_OPTION_MANDATORY
},
73 class IfaceCheckLog
: public wxLog
78 void DoLog(wxLogLevel
, const wxString
& msg
, time_t)
80 // send all messages to stdout (normal behaviour is to sent them to stderr)
86 wxSUPPRESS_DOLOG_HIDE_WARNING()
89 class IfaceCheckApp
: public wxAppConsole
92 // don't use builtin cmd line parsing:
93 virtual bool OnInit() { m_modify
=false; return true; }
96 bool ParsePreprocessorOutput(const wxString
& filename
);
99 int CompareClasses(const wxClass
* iface
, const wxClass
* api
);
100 bool FixMethod(const wxString
& header
, const wxMethod
* iface
, const wxMethod
* api
);
101 bool StringContainsMethodName(const wxString
& str
, const wxMethod
* m
);
103 void PrintStatistics(long secs
);
105 bool IsToProcess(const wxString
& headername
) const
107 if (m_strToMatch
.IsEmpty())
109 return wxMatchWild(m_strToMatch
, headername
, false);
113 wxXmlGccInterface m_gccInterface
; // "real" headers API
114 wxXmlDoxygenInterface m_doxyInterface
; // doxygen-commented headers API
116 // was the MODIFY_SWITCH passed?
119 // if non-empty, then PROCESS_ONLY_OPTION was passed and this is the
120 // wildcard expression to match
121 wxString m_strToMatch
;
124 IMPLEMENT_APP_CONSOLE(IfaceCheckApp
)
126 int IfaceCheckApp::OnRun()
128 long startTime
= wxGetLocalTime(); // for timing purpose
130 wxCmdLineParser
parser(g_cmdLineDesc
, argc
, argv
);
132 wxString::Format("wxWidgets Interface checker utility (built %s against %s)",
133 __DATE__
, wxVERSION_STRING
));
135 // make the output more readable:
136 wxLog::SetActiveTarget(new IfaceCheckLog
);
137 wxLog::DisableTimestamp();
139 // parse the command line...
141 wxString preprocFile
;
142 switch (parser
.Parse())
145 if (parser
.Found(VERBOSE_SWITCH
))
148 // IMPORTANT: parsing #define values must be done _before_ actually
149 // parsing the GCC/doxygen XML files
150 if (parser
.Found(USE_PREPROCESSOR_OPTION
, &preprocFile
))
152 if (!ParsePreprocessorOutput(preprocFile
))
156 // in any case set basic std preprocessor #defines:
157 m_doxyInterface
.AddPreprocessorValue("NULL", "0");
159 //g_bLogEnabled = false;
161 // parse the two XML files which contain the real and the doxygen interfaces
162 // for wxWidgets API:
163 if (!m_gccInterface
.Parse(parser
.GetParam(0)) ||
164 !m_doxyInterface
.Parse(parser
.GetParam(1)))
167 // g_bLogEnabled = true;
169 if (parser
.Found(DUMP_SWITCH
))
171 wxLogMessage("Dumping real API to '%s'...", API_DUMP_FILE
);
172 m_gccInterface
.Dump(API_DUMP_FILE
);
174 wxLogMessage("Dumping interface API to '%s'...", INTERFACE_DUMP_FILE
);
175 m_doxyInterface
.Dump(INTERFACE_DUMP_FILE
);
179 if (parser
.Found(MODIFY_SWITCH
))
182 if (parser
.Found(PROCESS_ONLY_OPTION
, &m_strToMatch
))
184 size_t len
= m_strToMatch
.Len();
185 if (m_strToMatch
.StartsWith("\"") &&
186 m_strToMatch
.EndsWith("\"") &&
188 m_strToMatch
= m_strToMatch
.Mid(1, len
-2);
195 PrintStatistics(wxGetLocalTime() - startTime
);
199 wxPrintf("\nThis utility checks that the interface XML files created by Doxygen are in\n");
200 wxPrintf("synch with the real headers (whose contents are extracted by the gcc XML file).\n\n");
201 wxPrintf("The 'gccXML' parameter should be the wxapi.xml file created by the 'rungccxml.sh'\n");
202 wxPrintf("script which resides in 'utils/ifacecheck'.\n");
203 wxPrintf("The 'doxygenXML' parameter should be the index.xml file created by Doxygen\n");
204 wxPrintf("for the wxWidgets 'interface' folder.\n\n");
205 wxPrintf("Since the gcc XML file does not contain info about #defines, if you use\n");
206 wxPrintf("the -%s option, you'll get a smaller number of false warnings.\n",
207 USE_PREPROCESSOR_OPTION
);
209 // HELP_SWITCH was passed or a syntax error occurred
214 bool IfaceCheckApp::Compare()
216 const wxClassArray
& interfaces
= m_doxyInterface
.GetClasses();
218 int mcount
= 0, ccount
= 0;
220 wxLogMessage("Comparing the interface API to the real API (%d classes to compare)...",
221 interfaces
.GetCount());
223 if (!m_strToMatch
.IsEmpty())
224 wxLogMessage("Processing only header files matching '%s' expression.", m_strToMatch
);
226 for (unsigned int i
=0; i
<interfaces
.GetCount(); i
++)
228 // only compare the methods which are available for the port
229 // for which the gcc XML was produced
230 if (interfaces
[i
].GetAvailability() != wxPORT_UNKNOWN
&&
231 (interfaces
[i
].GetAvailability() & m_gccInterface
.GetInterfacePort()) == 0) {
234 wxLogMessage("skipping class '%s' since it's not available for the %s port.",
235 interfaces
[i
].GetName(), m_gccInterface
.GetInterfacePortName());
237 continue; // skip this method
240 // shorten the name of the header so the log file is more readable
241 // and also for calling IsToProcess() against it
242 wxString header
= wxFileName(interfaces
[i
].GetHeader()).GetFullName();
244 if (!IsToProcess(header
))
245 continue; // skip this one
247 wxString cname
= interfaces
[i
].GetName();
249 // search in the real headers for i-th interface class; we search for
250 // both class cname and cnameBase since in wxWidgets world tipically
251 // class cname is platform-specific while the real public interface of
252 // that class is part of the cnameBase class.
253 /*c = m_gccInterface.FindClass(cname + "Base");
256 c
= m_gccInterface
.FindClass(cname
);
259 // sometimes the platform-specific class is named "wxGeneric" + cname
261 c
= m_gccInterface
.FindClass("wxGeneric" + cname
.Mid(2));
264 c
= m_gccInterface
.FindClass("wxGtk" + cname
.Mid(2));
270 // there is a class with the same (logic) name!
271 mcount
+= CompareClasses(&interfaces
[i
], c
);
275 wxLogMessage("%s: couldn't find the real interface for the '%s' class",
281 wxLogMessage("%d on a total of %d methods (%.1f%%) of the interface headers do not exist in the real headers",
282 mcount
, m_doxyInterface
.GetMethodCount(), (float)(100.0 * mcount
/m_doxyInterface
.GetMethodCount()));
283 wxLogMessage("%d on a total of %d classes (%.1f%%) of the interface headers do not exist in the real headers",
284 ccount
, m_doxyInterface
.GetClassesCount(), (float)(100.0 * ccount
/m_doxyInterface
.GetClassesCount()));
289 int IfaceCheckApp::CompareClasses(const wxClass
* iface
, const wxClass
* api
)
291 const wxMethod
*real
;
294 wxASSERT(iface
&& api
);
296 // shorten the name of the header so the log file is more readable
297 wxString header
= wxFileName(iface
->GetHeader()).GetFullName();
299 for (unsigned int i
=0; i
<iface
->GetMethodCount(); i
++)
301 const wxMethod
& m
= iface
->GetMethod(i
);
303 // only compare the methods which are available for the port
304 // for which the gcc XML was produced
305 if (m
.GetAvailability() != wxPORT_UNKNOWN
&&
306 (m
.GetAvailability() & m_gccInterface
.GetInterfacePort()) == 0) {
309 wxLogMessage("skipping method '%s' since it's not available for the %s port.",
310 m
.GetAsString(), m_gccInterface
.GetInterfacePortName());
312 continue; // skip this method
315 // search in the methods of the api classes provided
316 real
= api
->RecursiveUpwardFindMethod(m
, &m_gccInterface
);
318 // avoid some false positives:
319 if (!real
&& m
.ActsAsDefaultCtor())
321 // build an artificial default ctor for this class:
323 temp
.GetArgumentTypes().Clear();
326 real
= api
->RecursiveUpwardFindMethod(temp
, &m_gccInterface
);
333 wxMethodPtrArray overloads
=
334 api
->RecursiveUpwardFindMethodsNamed(m
.GetName(), &m_gccInterface
);
336 // avoid false positives:
337 for (unsigned int k
=0; k
<overloads
.GetCount(); k
++)
338 if (overloads
[k
]->MatchesExceptForAttributes(m
) &&
339 m
.IsDeprecated() && !overloads
[k
]->IsDeprecated())
341 // maybe the iface method is marked as deprecated but the
342 // real method is not?
343 wxMethod
tmp(*overloads
[k
]);
344 tmp
.SetDeprecated(true);
348 // in this case, we can disregard this warning... the real
349 // method probably is included in WXWIN_COMPAT sections!
350 proceed
= false; // skip this method
354 #define HACK_TO_AUTO_CORRECT_ONLY_METHOD_ATTRIBUTES 0
355 #if HACK_TO_AUTO_CORRECT_ONLY_METHOD_ATTRIBUTES
356 for (unsigned int k
=0; k
<overloads
.GetCount(); k
++)
357 if (overloads
[k
]->MatchesExceptForAttributes(m
))
359 // fix default values of results[k]:
360 wxMethod
tmp(*overloads
[k
]);
361 tmp
.SetArgumentTypes(m
.GetArgumentTypes());
363 // modify interface header
364 if (FixMethod(iface
->GetHeader(), &m
, &tmp
))
365 wxLogMessage("Adjusted attributes of '%s' method", m
.GetAsString());
370 #endif // HACK_TO_AUTO_CORRECT_ONLY_METHOD_ATTRIBUTES
374 if (overloads
.GetCount()==0)
376 wxLogMessage("%s: real '%s' class and their parents have no method '%s'",
377 header
, api
->GetName(), m
.GetAsString());
378 // we've found no overloads
382 // first, output a warning
383 wxString warning
= header
;
384 if (overloads
.GetCount()>1)
385 warning
+= wxString::Format(": in the real headers there are %d overloads of '%s' for "
386 "'%s' all with different signatures:\n",
387 overloads
.GetCount(), m
.GetName(), api
->GetName());
389 warning
+= wxString::Format(": in the real headers there is a method '%s' for '%s'"
390 " but has different signature:\n",
391 m
.GetName(), api
->GetName());
394 // get a list of the prototypes with _all_ possible attributes:
395 warning
+= "\tdoxy header: " + m
.GetAsString(true, true, true, true);
396 for (unsigned int j
=0; j
<overloads
.GetCount(); j
++)
397 warning
+= "\n\treal header: " + overloads
[j
]->GetAsString(true, true, true, true);
399 wxLogWarning(warning
);
402 if (overloads
.GetCount()>1)
404 // TODO: decide which of these overloads is the most "similar" to m
405 // and eventually modify it
407 wxLogWarning("\tmanual fix is required");
411 wxASSERT(overloads
.GetCount() == 1);
413 if (m_modify
|| m
.IsCtor())
415 wxLogWarning("\tfixing it...");
418 FixMethod(iface
->GetHeader(), &m
, overloads
[0]);
431 bool IfaceCheckApp::StringContainsMethodName(const wxString
& str
, const wxMethod
* m
)
433 return str
.Contains(m
->GetName()) ||
434 (m
->IsOperator() && str
.Contains("operator"));
437 bool IfaceCheckApp::FixMethod(const wxString
& header
, const wxMethod
* iface
, const wxMethod
* api
)
440 wxASSERT(iface
&& api
);
443 if (!file
.Open(header
)) {
444 wxLogError("\tcan't open the '%s' header file.", header
);
448 // GetLocation() returns the line where the last part of the prototype is placed;
449 // i.e. the line containing the semicolon at the end of the declaration.
450 int end
= iface
->GetLocation()-1;
451 if (end
<= 0 || end
>= (int)file
.GetLineCount()) {
452 wxLogWarning("\tinvalid location info for method '%s': %d.",
453 iface
->GetAsString(), iface
->GetLocation());
457 if (!file
.GetLine(end
).Contains(";")) {
458 wxLogWarning("\tinvalid location info for method '%s': %d.",
459 iface
->GetAsString(), iface
->GetLocation());
463 // is this a one-line prototype declaration?
464 bool founddecl
= false;
466 if (StringContainsMethodName(file
.GetLine(end
), iface
))
468 // yes, this prototype is all on this line:
474 start
= end
; // will be decremented inside the while{} loop below
476 // find the start point of this prototype declaration; i.e. the line
477 // containing the function name, which is also the line following
478 // the marker '*/' for the closure of the doxygen comment
481 start
--; // go up one line
483 if (StringContainsMethodName(file
.GetLine(start
), iface
))
486 while (start
> 0 && !founddecl
&&
487 !file
.GetLine(start
).Contains(";") &&
488 !file
.GetLine(start
).Contains("*/"));
491 if (start
<= 0 || !founddecl
)
493 wxLogError("\tcan't find the beginning of the declaration of '%s' method in '%s' header looking backwards from line %d; I arrived at %d and gave up",
494 iface
->GetAsString(), header
, end
+1 /* zero-based => 1-based */, start
);
498 // remove the old prototype
499 for (int k
=start
; k
<=end
; k
++)
500 file
.RemoveLine(start
); // remove (end-start)-nth times the start-th line
502 #define INDENTATION_STR wxString(" ")
504 // if possible, add also the @deprecated tag in the doxygen comment if it's missing
505 int deprecationOffset
= 0;
506 if (file
.GetLine(start
-1).Contains("*/") &&
507 (api
->IsDeprecated() && !iface
->IsDeprecated()))
509 file
.RemoveLine(start
-1);
510 file
.InsertLine(INDENTATION_STR
+ INDENTATION_STR
+
511 "@deprecated @todo provide deprecation description", start
-1);
512 file
.InsertLine(INDENTATION_STR
+ "*/", start
++);
514 // we have added a new line in the final balance
520 // discard gcc XML argument names and replace them with those parsed from doxygen XML;
521 // in this way we should avoid introducing doxygen warnings about cases where the argument
522 // 'xx' of the prototype is called 'yy' in the function's docs.
523 const wxArgumentTypeArray
& doxygenargs
= iface
->GetArgumentTypes();
524 const wxArgumentTypeArray
& realargs
= api
->GetArgumentTypes();
525 if (realargs
.GetCount() == doxygenargs
.GetCount())
527 for (j
=0; j
<doxygenargs
.GetCount(); j
++)
528 if (doxygenargs
[j
]==realargs
[j
])
530 realargs
[j
].SetArgumentName(doxygenargs
[j
].GetArgumentName());
532 if (realargs
[j
].GetDefaultValue().IsNumber() &&
533 doxygenargs
[j
].GetDefaultValue().StartsWith("wx"))
534 realargs
[j
].SetDefaultValue(doxygenargs
[j
].GetDefaultValue());
537 tmp
.SetArgumentTypes(realargs
);
540 #define WRAP_COLUMN 80
542 wxArrayString toinsert
;
543 toinsert
.Add(INDENTATION_STR
+ tmp
.GetAsString() + ";");
545 int nStartColumn
= toinsert
[0].Find('(');
546 wxASSERT(nStartColumn
!= wxNOT_FOUND
);
548 // wrap lines too long at comma boundaries
549 for (i
=0; i
<toinsert
.GetCount(); i
++)
551 size_t len
= toinsert
[i
].Len();
552 if (len
> WRAP_COLUMN
)
554 wxASSERT(i
== toinsert
.GetCount()-1);
557 wxString tmpleft
= toinsert
[i
].Left(WRAP_COLUMN
);
558 int comma
= tmpleft
.Find(',', true /* from end */);
559 if (comma
== wxNOT_FOUND
)
560 break; // break out of the for cycle...
562 toinsert
.Add(wxString(' ', nStartColumn
+1) +
563 toinsert
[i
].Right(len
-comma
-2)); // exclude the comma and the space after it
564 toinsert
[i
] = tmpleft
.Left(comma
+1); // include the comma
568 // insert the new lines
569 for (i
=0; i
<toinsert
.GetCount(); i
++)
570 file
.InsertLine(toinsert
[i
], start
+i
);
572 // now save the modification
574 wxLogError("\tcan't save the '%s' header file.", header
);
578 // how many lines did we add/remove in total?
579 int nOffset
= toinsert
.GetCount() + deprecationOffset
- (end
-start
+1);
584 wxLogMessage("\tthe final row offset for following methods is %d lines.", nOffset
);
586 // update the other method's locations for those methods which belong to the modified header
587 // and are placed _below_ the modified method
588 wxClassPtrArray cToUpdate
= m_doxyInterface
.FindClassesDefinedIn(header
);
589 for (i
=0; i
< cToUpdate
.GetCount(); i
++)
591 for (j
=0; j
< cToUpdate
[i
]->GetMethodCount(); j
++)
593 wxMethod
& m
= cToUpdate
[i
]->GetMethod(j
);
594 if (m
.GetLocation() > iface
->GetLocation())
596 // update the location of this method
597 m
.SetLocation(m
.GetLocation()+nOffset
);
605 bool IfaceCheckApp::ParsePreprocessorOutput(const wxString
& filename
)
608 if (!tf
.Open(filename
)) {
609 wxLogError("can't open the '%s' preprocessor output file.", filename
);
614 for (unsigned int i
=0; i
< tf
.GetLineCount(); i
++)
616 const wxString
& line
= tf
.GetLine(i
);
617 wxString defnameval
= line
.Mid(8); // what follows the "#define " string
619 // the format of this line should be:
620 // #define DEFNAME DEFVALUE
621 if (!line
.StartsWith("#define ")) {
622 wxLogError("unexpected content in '%s' at line %d.", filename
, i
+1);
626 if (defnameval
.Contains(" "))
629 wxString defname
= defnameval
.BeforeFirst(' ');
630 if (defname
.Contains("("))
631 continue; // this is a macro, skip it!
634 wxString defval
= defnameval
.AfterFirst(' ').Strip(wxString::both
);
635 if (defval
.StartsWith("(") && defval
.EndsWith(")"))
636 defval
= defval
.Mid(1, defval
.Len()-2);
638 // store this pair in the doxygen interface, where it can be useful
639 m_doxyInterface
.AddPreprocessorValue(defname
, defval
);
644 // it looks like the format of this line is:
646 // we are not interested to symbols #defined to nothing,
647 // so we just ignore this line.
651 wxLogMessage("Parsed %d preprocessor #defines from '%s' which will be used later...",
657 void IfaceCheckApp::PrintStatistics(long secs
)
659 // these stats, for what regards the gcc XML, are all referred to the wxWidgets
662 wxLogMessage("wx real headers contains declaration of %d classes (%d methods)",
663 m_gccInterface
.GetClassesCount(), m_gccInterface
.GetMethodCount());
664 wxLogMessage("wx interface headers contains declaration of %d classes (%d methods)",
665 m_doxyInterface
.GetClassesCount(), m_doxyInterface
.GetMethodCount());
667 // build a list of the undocumented wx classes
670 const wxClassArray
& arr
= m_gccInterface
.GetClasses();
671 for (unsigned int i
=0; i
<arr
.GetCount(); i
++) {
672 if (m_doxyInterface
.FindClass(arr
[i
].GetName()) == NULL
) {
673 list
+= arr
[i
].GetName() + ", ";
681 wxLogMessage("the list of the %d undocumented wx classes is: %s", undoc
, list
);
682 wxLogMessage("total processing took %d seconds.", secs
);