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 IfaceCheckApp
: public wxAppConsole
76 // don't use builtin cmd line parsing:
77 virtual bool OnInit() { m_modify
=false; return true; }
80 bool ParsePreprocessorOutput(const wxString
& filename
);
83 int CompareClasses(const wxClass
* iface
, const wxClass
* api
);
84 bool FixMethod(const wxString
& header
, const wxMethod
* iface
, const wxMethod
* api
);
87 void PrintStatistics(long secs
);
89 bool IsToProcess(const wxString
& headername
) const
91 if (m_strToMatch
.IsEmpty())
93 return wxMatchWild(m_strToMatch
, headername
, false);
97 wxXmlGccInterface m_gccInterface
; // "real" headers API
98 wxXmlDoxygenInterface m_doxyInterface
; // doxygen-commented headers API
100 // was the MODIFY_SWITCH passed?
103 // if non-empty, then PROCESS_ONLY_OPTION was passed and this is the
104 // wildcard expression to match
105 wxString m_strToMatch
;
108 IMPLEMENT_APP_CONSOLE(IfaceCheckApp
)
110 int IfaceCheckApp::OnRun()
112 long startTime
= wxGetLocalTime(); // for timing purpose
114 wxCmdLineParser
parser(g_cmdLineDesc
, argc
, argv
);
116 wxString::Format("wxWidgets Interface checker utility (built %s against %s)",
117 __DATE__
, wxVERSION_STRING
));
119 // parse the command line...
121 wxString preprocFile
;
122 switch (parser
.Parse())
125 if (parser
.Found(VERBOSE_SWITCH
))
128 // IMPORTANT: parsing #define values must be done _before_ actually
129 // parsing the GCC/doxygen XML files
130 if (parser
.Found(USE_PREPROCESSOR_OPTION
, &preprocFile
))
132 if (!ParsePreprocessorOutput(preprocFile
))
136 // in any case set basic std preprocessor #defines:
137 m_doxyInterface
.AddPreprocessorValue("NULL", "0");
139 //g_bLogEnabled = false;
141 // parse the two XML files which contain the real and the doxygen interfaces
142 // for wxWidgets API:
143 if (!m_gccInterface
.Parse(parser
.GetParam(0)) ||
144 !m_doxyInterface
.Parse(parser
.GetParam(1)))
147 g_bLogEnabled
= true;
149 if (parser
.Found(DUMP_SWITCH
))
151 LogMessage("Dumping real API to '%s'...", API_DUMP_FILE
);
152 m_gccInterface
.Dump(API_DUMP_FILE
);
154 LogMessage("Dumping interface API to '%s'...", INTERFACE_DUMP_FILE
);
155 m_doxyInterface
.Dump(INTERFACE_DUMP_FILE
);
159 if (parser
.Found(MODIFY_SWITCH
))
162 if (parser
.Found(PROCESS_ONLY_OPTION
, &m_strToMatch
))
164 size_t len
= m_strToMatch
.Len();
165 if (m_strToMatch
.StartsWith("\"") &&
166 m_strToMatch
.EndsWith("\"") &&
168 m_strToMatch
= m_strToMatch
.Mid(1, len
-2);
175 PrintStatistics(wxGetLocalTime() - startTime
);
179 wxPrintf("\nThis utility checks that the interface XML files created by Doxygen are in\n");
180 wxPrintf("synch with the real headers (whose contents are extracted by the gcc XML file).\n\n");
181 wxPrintf("The 'gccXML' parameter should be the wxapi.xml file created by the 'rungccxml.sh'\n");
182 wxPrintf("script which resides in 'utils/ifacecheck'.\n");
183 wxPrintf("The 'doxygenXML' parameter should be the index.xml file created by Doxygen\n");
184 wxPrintf("for the wxWidgets 'interface' folder.\n\n");
185 wxPrintf("Since the gcc XML file does not contain info about #defines, if you use\n");
186 wxPrintf("the -%s option, you'll get a smaller number of false warnings.\n",
187 USE_PREPROCESSOR_OPTION
);
189 // HELP_SWITCH was passed or a syntax error occurred
194 void IfaceCheckApp::ShowProgress()
200 bool IfaceCheckApp::Compare()
202 const wxClassArray
& interfaces
= m_doxyInterface
.GetClasses();
204 int mcount
= 0, ccount
= 0;
206 LogMessage("Comparing the interface API to the real API (%d classes to compare)...",
207 interfaces
.GetCount());
209 if (!m_strToMatch
.IsEmpty())
210 LogMessage("Processing only header files matching '%s' expression.", m_strToMatch
);
212 for (unsigned int i
=0; i
<interfaces
.GetCount(); i
++)
214 // only compare the methods which are available for the port
215 // for which the gcc XML was produced
216 if (interfaces
[i
].GetAvailability() != wxPORT_UNKNOWN
&&
217 (interfaces
[i
].GetAvailability() & m_gccInterface
.GetInterfacePort()) == 0) {
220 LogMessage("skipping class '%s' since it's not available for the %s port.",
221 interfaces
[i
].GetName(), m_gccInterface
.GetInterfacePortName());
223 continue; // skip this method
226 // shorten the name of the header so the log file is more readable
227 // and also for calling IsToProcess() against it
228 wxString header
= wxFileName(interfaces
[i
].GetHeader()).GetFullName();
230 if (!IsToProcess(header
))
231 continue; // skip this one
233 wxString cname
= interfaces
[i
].GetName();
235 // search in the real headers for i-th interface class; we search for
236 // both class cname and cnameBase since in wxWidgets world tipically
237 // class cname is platform-specific while the real public interface of
238 // that class is part of the cnameBase class.
239 /*c = m_gccInterface.FindClass(cname + "Base");
242 c
= m_gccInterface
.FindClass(cname
);
245 // sometimes the platform-specific class is named "wxGeneric" + cname
247 c
= m_gccInterface
.FindClass("wxGeneric" + cname
.Mid(2));
250 c
= m_gccInterface
.FindClass("wxGtk" + cname
.Mid(2));
256 // there is a class with the same (logic) name!
257 mcount
+= CompareClasses(&interfaces
[i
], c
);
261 LogMessage("%s: couldn't find the real interface for the '%s' class",
267 LogMessage("%d methods (%.1f%%) of the interface headers do not exist in the real headers",
268 mcount
, (float)(100.0 * mcount
/m_doxyInterface
.GetMethodCount()));
269 LogMessage("%d classes (%.1f%%) of the interface headers do not exist in the real headers",
270 ccount
, (float)(100.0 * ccount
/m_doxyInterface
.GetClassesCount()));
275 int IfaceCheckApp::CompareClasses(const wxClass
* iface
, const wxClass
* api
)
277 const wxMethod
*real
;
280 wxASSERT(iface
&& api
);
282 // shorten the name of the header so the log file is more readable
283 wxString header
= wxFileName(iface
->GetHeader()).GetFullName();
285 for (unsigned int i
=0; i
<iface
->GetMethodCount(); i
++)
287 const wxMethod
& m
= iface
->GetMethod(i
);
289 // only compare the methods which are available for the port
290 // for which the gcc XML was produced
291 if (m
.GetAvailability() != wxPORT_UNKNOWN
&&
292 (m
.GetAvailability() & m_gccInterface
.GetInterfacePort()) == 0) {
295 LogMessage("skipping method '%s' since it's not available for the %s port.",
296 m
.GetAsString(), m_gccInterface
.GetInterfacePortName());
298 continue; // skip this method
301 // search in the methods of the api classes provided
302 real
= api
->RecursiveUpwardFindMethod(m
, &m_gccInterface
);
306 wxMethodPtrArray overloads
=
307 api
->RecursiveUpwardFindMethodsNamed(m
.GetName(), &m_gccInterface
);
309 #define HACK_TO_AUTO_CORRECT_ONLY_METHOD_ATTRIBUTES 0
310 #if HACK_TO_AUTO_CORRECT_ONLY_METHOD_ATTRIBUTES
312 for (unsigned int k
=0; k
<overloads
.GetCount(); k
++)
313 if (overloads
[k
]->MatchesExceptForAttributes(m
) &&
314 overloads
[k
]->IsPureVirtual() == m
.IsPureVirtual())
316 // fix default values of results[k]:
317 wxMethod
tmp(*overloads
[k
]);
318 tmp
.SetArgumentTypes(m
.GetArgumentTypes());
320 // modify interface header
321 if (FixMethod(iface
->GetHeader(), &m
, &tmp
))
322 LogMessage("Adjusted attributes of '%s' method", m
.GetAsString());
330 #endif // HACK_TO_AUTO_CORRECT_ONLY_METHOD_ATTRIBUTES
332 if (overloads
.GetCount()==0)
334 LogMessage("%s: real '%s' class and their parents have no method '%s'",
335 header
, api
->GetName(), m
.GetAsString());
336 // we've found no overloads
340 // first, output a warning
341 wxString warning
= header
;
342 if (overloads
.GetCount()>1)
343 warning
+= wxString::Format(": in the real headers there are %d overloads of '%s' for "
344 "'%s' all with different signatures:\n",
345 overloads
.GetCount(), m
.GetName(), api
->GetName());
347 warning
+= wxString::Format(": in the real headers there is a method '%s' for '%s'"
348 " but has different signature:\n",
349 m
.GetName(), api
->GetName());
352 // get a list of the prototypes with _all_ possible attributes:
353 warning
+= "\tdoxy header: " + m
.GetAsString(true, true, true, true);
354 for (unsigned int j
=0; j
<overloads
.GetCount(); j
++)
355 warning
+= "\n\treal header: " + overloads
[j
]->GetAsString(true, true, true, true);
357 wxPrint(warning
+ "\n");
360 if (overloads
.GetCount()>1)
362 // TODO: decide which of these overloads is the most "similar" to m
363 // and eventually modify it
365 wxPrint("\tmanual fix is required\n");
369 wxASSERT(overloads
.GetCount() == 1);
373 wxPrint("\tfixing it...\n");
376 FixMethod(iface
->GetHeader(), &m
, overloads
[0]);
383 #if HACK_TO_AUTO_CORRECT_ONLY_METHOD_ATTRIBUTES
392 bool IfaceCheckApp::FixMethod(const wxString
& header
, const wxMethod
* iface
, const wxMethod
* api
)
394 wxASSERT(iface
&& api
);
397 if (!file
.Open(header
)) {
398 LogError("\tcan't open the '%s' header file.", header
);
402 // GetLocation() returns the line where the last part of the prototype is placed:
403 int end
= iface
->GetLocation()-1;
404 if (end
<= 0 || end
>= (int)file
.GetLineCount()) {
405 LogWarning("\tinvalid location info for method '%s': %d.",
406 iface
->GetAsString(), iface
->GetLocation());
410 if (!file
.GetLine(end
).Contains(";")) {
411 LogWarning("\tinvalid location info for method '%s': %d.",
412 iface
->GetAsString(), iface
->GetLocation());
416 // is this a one-line prototype declaration?
417 bool founddecl
= false;
419 if (file
.GetLine(end
).Contains(iface
->GetName()))
421 // yes, this prototype is all on this line:
429 // find the start point of this prototype declaration:
431 !file
.GetLine(start
).Contains(";") &&
432 !file
.GetLine(start
).Contains("*/"))
436 founddecl
|= file
.GetLine(start
).Contains(iface
->GetName());
439 // start-th line contains either the declaration of another prototype
440 // or the closing tag */ of a doxygen comment; start one line below
444 if (start
<= 0 || !founddecl
)
446 LogError("\tcan't find the beginning of the declaration of '%s' method in '%s' header looking backwards from line %d",
447 iface
->GetAsString(), header
, end
);
451 // remove the old prototype
452 for (int i
=start
; i
<=end
; i
++)
453 file
.RemoveLine(start
); // remove (end-start)-nth times the start-th line
455 #define INDENTATION_STR wxString(" ")
457 // if possible, add also the @deprecated tag in the doxygen comment if it's missing
458 int deprecationOffset
= 0;
459 if (file
.GetLine(start
-1).Contains("*/") &&
460 (api
->IsDeprecated() && !iface
->IsDeprecated()))
462 file
.RemoveLine(start
-1);
463 file
.InsertLine(INDENTATION_STR
+ INDENTATION_STR
+
464 "@deprecated @todo provide deprecation description", start
-1);
465 file
.InsertLine(INDENTATION_STR
+ "*/", start
++);
467 // we have added a new line in the final balance
473 // discard API argument names and replace them with those parsed from doxygen XML:
474 const wxArgumentTypeArray
& doxygenargs
= iface
->GetArgumentTypes();
475 const wxArgumentTypeArray
& realargs
= api
->GetArgumentTypes();
476 if (realargs
.GetCount() == doxygenargs
.GetCount())
478 for (unsigned int j
=0; j
<doxygenargs
.GetCount(); j
++)
479 if (doxygenargs
[j
]==realargs
[j
])
480 realargs
[j
].SetArgumentName(doxygenargs
[j
].GetArgumentName());
482 tmp
.SetArgumentTypes(realargs
);
485 #define WRAP_COLUMN 80
487 wxArrayString toinsert
;
488 toinsert
.Add(INDENTATION_STR
+ tmp
.GetAsString() + ";");
490 int nStartColumn
= toinsert
[0].Find('(');
491 wxASSERT(nStartColumn
!= wxNOT_FOUND
);
493 // wrap lines too long at comma boundaries
494 for (unsigned int i
=0; i
<toinsert
.GetCount(); i
++)
496 size_t len
= toinsert
[i
].Len();
497 if (len
> WRAP_COLUMN
)
499 wxASSERT(i
== toinsert
.GetCount()-1);
502 wxString tmpleft
= toinsert
[i
].Left(WRAP_COLUMN
);
503 int comma
= tmpleft
.Find(',', true /* from end */);
504 if (comma
== wxNOT_FOUND
)
505 break; // break out of the for cycle...
507 toinsert
.Add(wxString(' ', nStartColumn
+1) +
508 toinsert
[i
].Right(len
-comma
-2)); // exclude the comma and the space after it
509 toinsert
[i
] = tmpleft
.Left(comma
+1); // include the comma
513 // insert the new lines
514 for (unsigned int i
=0; i
<toinsert
.GetCount(); i
++)
515 file
.InsertLine(toinsert
[i
], start
+i
);
517 // now save the modification
519 LogError("\tcan't save the '%s' header file.", header
);
523 // how many lines did we add/remove in total?
524 int nOffset
= toinsert
.GetCount() + deprecationOffset
- (end
-start
+1);
529 LogMessage("\tthe final row offset for following methods is %d lines.", nOffset
);
531 // update the other method's locations for those methods which belong to the modified header
532 // and are placed _below_ the modified method
533 wxClassPtrArray cToUpdate
= m_doxyInterface
.FindClassesDefinedIn(header
);
534 for (unsigned int i
=0; i
< cToUpdate
.GetCount(); i
++)
536 for (unsigned int j
=0; j
< cToUpdate
[i
]->GetMethodCount(); j
++)
538 wxMethod
& m
= cToUpdate
[i
]->GetMethod(j
);
539 if (m
.GetLocation() > iface
->GetLocation())
541 // update the location of this method
542 m
.SetLocation(m
.GetLocation()+nOffset
);
550 bool IfaceCheckApp::ParsePreprocessorOutput(const wxString
& filename
)
553 if (!tf
.Open(filename
)) {
554 LogError("can't open the '%s' preprocessor output file.", filename
);
559 for (unsigned int i
=0; i
< tf
.GetLineCount(); i
++)
561 const wxString
& line
= tf
.GetLine(i
);
562 wxString defnameval
= line
.Mid(8); // what follows the "#define " string
564 // the format of this line should be:
565 // #define DEFNAME DEFVALUE
566 if (!line
.StartsWith("#define ")) {
567 LogError("unexpected content in '%s' at line %d.", filename
, i
+1);
571 if (defnameval
.Contains(" "))
574 wxString defname
= defnameval
.BeforeFirst(' ');
575 if (defname
.Contains("("))
576 continue; // this is a macro, skip it!
579 wxString defval
= defnameval
.AfterFirst(' ').Strip(wxString::both
);
580 if (defval
.StartsWith("(") && defval
.EndsWith(")"))
581 defval
= defval
.Mid(1, defval
.Len()-2);
583 // store this pair in the doxygen interface, where it can be useful
584 m_doxyInterface
.AddPreprocessorValue(defname
, defval
);
589 // it looks like the format of this line is:
591 // we are not interested to symbols #defined to nothing,
592 // so we just ignore this line.
596 LogMessage("Parsed %d preprocessor #defines from '%s' which will be used later...",
602 void IfaceCheckApp::PrintStatistics(long secs
)
604 LogMessage("wx real headers contains declaration of %d classes (%d methods)",
605 m_gccInterface
.GetClassesCount(), m_gccInterface
.GetMethodCount());
606 LogMessage("wx interface headers contains declaration of %d classes (%d methods)",
607 m_doxyInterface
.GetClassesCount(), m_doxyInterface
.GetMethodCount());
608 LogMessage("total processing took %d seconds.", secs
);