#include "wx/cmdline.h"
#include "wx/textfile.h"
+#include "wx/filename.h"
#include "wx/stopwatch.h" // for wxGetLocalTime
#include "xmlparser.h"
// IfaceCheckApp
// ----------------------------------------------------------------------------
-#define API_DUMP_FILE "dump.api.txt"
-#define INTERFACE_DUMP_FILE "dump.interface.txt"
+#define API_DUMP_FILE "dump.api.txt"
+#define INTERFACE_DUMP_FILE "dump.interface.txt"
-#define MODIFY_SWITCH "m"
-#define DUMP_SWITCH "dump"
-#define HELP_SWITCH "h"
-#define VERBOSE_SWITCH "v"
+#define PROCESS_ONLY_OPTION "p"
+#define USE_PREPROCESSOR_OPTION "u"
+
+#define MODIFY_SWITCH "m"
+#define DUMP_SWITCH "d"
+#define HELP_SWITCH "h"
+#define VERBOSE_SWITCH "v"
static const wxCmdLineEntryDesc g_cmdLineDesc[] =
{
+ { wxCMD_LINE_OPTION, USE_PREPROCESSOR_OPTION, "use-preproc",
+ "uses the preprocessor output to increase the checker accuracy",
+ wxCMD_LINE_VAL_STRING, wxCMD_LINE_NEEDS_SEPARATOR },
+ { wxCMD_LINE_OPTION, PROCESS_ONLY_OPTION, "process-only",
+ "processes only header files matching the given wildcard",
+ wxCMD_LINE_VAL_STRING, wxCMD_LINE_NEEDS_SEPARATOR },
{ wxCMD_LINE_SWITCH, MODIFY_SWITCH, "modify",
"modify the interface headers to match the real ones" },
- { wxCMD_LINE_SWITCH, "", DUMP_SWITCH,
- "dump both interface and API to plain text" },
+ { wxCMD_LINE_SWITCH, DUMP_SWITCH, "dump",
+ "dump both interface and API to plain text dump.*.txt files" },
{ wxCMD_LINE_SWITCH, HELP_SWITCH, "help",
"show help message", wxCMD_LINE_VAL_NONE, wxCMD_LINE_OPTION_HELP },
{ wxCMD_LINE_SWITCH, VERBOSE_SWITCH, "verbose",
virtual bool OnInit() { m_modify=false; return true; }
virtual int OnRun();
+ bool ParsePreprocessorOutput(const wxString& filename);
+
bool Compare();
int CompareClasses(const wxClass* iface, const wxClassPtrArray& api);
void FixMethod(const wxString& header, const wxMethod* iface, const wxMethod* api);
void ShowProgress();
void PrintStatistics(long secs);
+ bool IsToProcess(const wxString& headername) const
+ {
+ if (m_strToMatch.IsEmpty())
+ return true;
+ return wxMatchWild(m_strToMatch, headername, false);
+ }
+
protected:
- wxXmlGccInterface m_api; // "real" headers API
- wxXmlDoxygenInterface m_interface; // doxygen-commented headers API
+ wxXmlGccInterface m_gccInterface; // "real" headers API
+ wxXmlDoxygenInterface m_doxyInterface; // doxygen-commented headers API
// was the MODIFY_SWITCH passed?
bool m_modify;
+
+ // if non-empty, then PROCESS_ONLY_OPTION was passed and this is the
+ // wildcard expression to match
+ wxString m_strToMatch;
};
IMPLEMENT_APP_CONSOLE(IfaceCheckApp)
{
long startTime = wxGetLocalTime(); // for timing purpose
- // parse the command line...
wxCmdLineParser parser(g_cmdLineDesc, argc, argv);
+ parser.SetLogo(
+ wxString::Format("wxWidgets Interface checker utility (built %s against %s)",
+ __DATE__, wxVERSION_STRING));
+
+ // parse the command line...
bool ok = true;
+ wxString preprocFile;
switch (parser.Parse())
{
- case -1:
- // HELP_SWITCH was passed
- return 0;
-
case 0:
if (parser.Found(VERBOSE_SWITCH))
g_verbose = true;
- if (!m_api.Parse(parser.GetParam(0)) ||
- !m_interface.Parse(parser.GetParam(1)))
+ // IMPORTANT: parsing #define values must be done _before_ actually
+ // parsing the GCC/doxygen XML files
+ if (parser.Found(USE_PREPROCESSOR_OPTION, &preprocFile))
+ {
+ if (!ParsePreprocessorOutput(preprocFile))
+ return 1;
+ }
+
+ // in any case set basic std preprocessor #defines:
+ m_doxyInterface.AddPreprocessorValue("NULL", "0");
+
+ // parse the two XML files which contain the real and the doxygen interfaces
+ // for wxWidgets API:
+ if (!m_gccInterface.Parse(parser.GetParam(0)) ||
+ !m_doxyInterface.Parse(parser.GetParam(1)))
return 1;
if (parser.Found(DUMP_SWITCH))
{
LogMessage("Dumping real API to '%s'...", API_DUMP_FILE);
- m_api.Dump(API_DUMP_FILE);
+ m_gccInterface.Dump(API_DUMP_FILE);
LogMessage("Dumping interface API to '%s'...", INTERFACE_DUMP_FILE);
- m_interface.Dump(INTERFACE_DUMP_FILE);
+ m_doxyInterface.Dump(INTERFACE_DUMP_FILE);
}
else
{
if (parser.Found(MODIFY_SWITCH))
m_modify = true;
+ if (parser.Found(PROCESS_ONLY_OPTION, &m_strToMatch))
+ {
+ size_t len = m_strToMatch.Len();
+ if (m_strToMatch.StartsWith("\"") &&
+ m_strToMatch.EndsWith("\"") &&
+ len > 2)
+ m_strToMatch = m_strToMatch.Mid(1, len-2);
+ }
+
ok = Compare();
}
PrintStatistics(wxGetLocalTime() - startTime);
return ok ? 0 : 1;
+
+ default:
+ wxPrintf("\nThis utility checks that the interface XML files created by Doxygen are in\n");
+ wxPrintf("synch with the real headers (whose contents are extracted by the gcc XML file).\n\n");
+ wxPrintf("The 'gccXML' parameter should be the wxapi.xml file created by the 'rungccxml.sh'\n");
+ wxPrintf("script which resides in 'utils/ifacecheck'.\n");
+ wxPrintf("The 'doxygenXML' parameter should be the index.xml file created by Doxygen\n");
+ wxPrintf("for the wxWidgets 'interface' folder.\n\n");
+ wxPrintf("Since the gcc XML file does not contain info about #defines, if you use\n");
+ wxPrintf("the -%s option, you'll get a smaller number of false warnings.\n",
+ USE_PREPROCESSOR_OPTION);
+
+ // HELP_SWITCH was passed or a syntax error occurred
+ return 0;
}
return 1;
bool IfaceCheckApp::Compare()
{
- const wxClassArray& interface = m_interface.GetClasses();
+ const wxClassArray& interface = m_doxyInterface.GetClasses();
const wxClass* c;
wxClassPtrArray api;
int mcount = 0, ccount = 0;
LogMessage("Comparing the interface API to the real API (%d classes to compare)...",
interface.GetCount());
+ if (!m_strToMatch.IsEmpty())
+ LogMessage("Processing only header files matching '%s' expression.", m_strToMatch);
+
for (unsigned int i=0; i<interface.GetCount(); i++)
{
+ // only compare the methods which are available for the port
+ // for which the gcc XML was produced
+ if (interface[i].GetAvailability() != wxPORT_UNKNOWN &&
+ (interface[i].GetAvailability() & m_gccInterface.GetInterfacePort()) == 0) {
+
+ if (g_verbose)
+ LogMessage("skipping class '%s' since it's not available for the %s port.",
+ interface[i].GetName(), m_gccInterface.GetInterfacePortName());
+
+ continue; // skip this method
+ }
+
+ // shorten the name of the header so the log file is more readable
+ // and also for calling IsToProcess() against it
+ wxString header = wxFileName(interface[i].GetHeader()).GetFullName();
+
+ if (!IsToProcess(header))
+ continue; // skip this one
+
wxString cname = interface[i].GetName();
api.Empty();
// for both class cname and cnameBase as in wxWidgets world, most often
// class cname is platform-specific while the real public interface of
// that class is part of the cnameBase class.
- c = m_api.FindClass(cname);
+ c = m_gccInterface.FindClass(cname);
if (c) api.Add(c);
- c = m_api.FindClass(cname + "Base");
+ c = m_gccInterface.FindClass(cname + "Base");
if (c) api.Add(c);
if (api.GetCount()>0) {
} else {
- // shorten the name of the header so the log file is more readable
- wxString header = interface[i].GetHeader().AfterLast('/');
-
LogMessage("%s: couldn't find the real interface for the '%s' class",
header, cname);
ccount++;
}
LogMessage("%d methods (%.1f%%) of the interface headers do not exist in the real headers",
- mcount, (float)(100.0 * mcount/m_interface.GetMethodCount()));
+ mcount, (float)(100.0 * mcount/m_doxyInterface.GetMethodCount()));
LogMessage("%d classes (%.1f%%) of the interface headers do not exist in the real headers",
- ccount, (float)(100.0 * ccount/m_interface.GetClassesCount()));
+ ccount, (float)(100.0 * ccount/m_doxyInterface.GetClassesCount()));
return true;
}
searchedclasses.Remove(0, 1);
// shorten the name of the header so the log file is more readable
- wxString header = iface->GetHeader().AfterLast('/');
+ wxString header = wxFileName(iface->GetHeader()).GetFullName();
for (unsigned int i=0; i<iface->GetMethodCount(); i++)
{
const wxMethod& m = iface->GetMethod(i);
int matches = 0;
+ // only compare the methods which are available for the port
+ // for which the gcc XML was produced
+ if (m.GetAvailability() != wxPORT_UNKNOWN &&
+ (m.GetAvailability() & m_gccInterface.GetInterfacePort()) == 0) {
+
+ if (g_verbose)
+ LogMessage("skipping method '%s' since it's not available for the %s port.",
+ m.GetAsString(), m_gccInterface.GetInterfacePortName());
+
+ continue; // skip this method
+ }
+
// search in the methods of the api classes provided
for (unsigned int j=0; j<api.GetCount(); j++)
{
if (overloads.GetCount()==0)
{
+ /*
+ TODO: sometimes the interface headers re-document a method
+ inherited from a base class even if the real header does
+ not actually re-implement it.
+ To avoid false positives, we'd need to search in the base classes
+ of api[] classes and search for a matching method.
+ */
LogMessage("%s: real '%s' class has no method '%s'",
header, searchedclasses, m.GetAsString());
// we've found no overloads
wxTextFile file;
if (!file.Open(header)) {
- LogError("can't open the '%s' header file.", header);
+ LogError("\tcan't open the '%s' header file.", header);
return;
}
// GetLocation() returns the line where the last part of the prototype is placed:
int end = iface->GetLocation()-1;
if (end <= 0 || end >= (int)file.GetLineCount()) {
- LogWarning("invalid location info for method '%s': %d.",
+ LogWarning("\tinvalid location info for method '%s': %d.",
iface->GetAsString(), iface->GetLocation());
return;
}
- if (!file.GetLine(end).Contains(iface->GetName())) {
- LogWarning("invalid location info for method '%s': %d.",
+ if (!file.GetLine(end).Contains(";")) {
+ LogWarning("\tinvalid location info for method '%s': %d.",
iface->GetAsString(), iface->GetLocation());
return;
}
// find the start point of this prototype declaration:
int start = end-1;
+ bool founddecl = false;
while (start > 0 &&
!file.GetLine(start).Contains(";") &&
!file.GetLine(start).Contains("*/"))
+ {
start--;
- if (start <= 0)
+ founddecl |= file.GetLine(start).Contains(iface->GetName());
+ }
+
+ if (start <= 0 || !founddecl)
{
- LogError("can't find the beginning of the declaration of '%s' method in '%s' header",
+ LogError("\tcan't find the beginning of the declaration of '%s' method in '%s' header",
iface->GetAsString(), header);
return;
}
#define INDENTATION_STR wxString(" ")
- // if possible, add also the @deprecated tag in the doxygen comment
- if (file.GetLine(start-1).Contains("*/") && api->IsDeprecated())
+ // if possible, add also the @deprecated tag in the doxygen comment if it's missing
+ int deprecationOffset = 0;
+ if (file.GetLine(start-1).Contains("*/") &&
+ (api->IsDeprecated() && !iface->IsDeprecated()))
{
file.RemoveLine(start-1);
file.InsertLine(INDENTATION_STR + INDENTATION_STR +
"@deprecated @todo provide deprecation description", start-1);
file.InsertLine(INDENTATION_STR + "*/", start++);
+
+ // we have added a new line in the final balance
+ deprecationOffset=1;
}
wxMethod tmp(*api);
tmp.SetArgumentTypes(realargs);
}
- // insert the new one
- file.InsertLine(INDENTATION_STR + tmp.GetAsString() + ";", start);
+#define WRAP_COLUMN 80
+
+ wxArrayString toinsert;
+ toinsert.Add(INDENTATION_STR + tmp.GetAsString() + ";");
+
+ int nStartColumn = toinsert[0].Find('(');
+ wxASSERT(nStartColumn != wxNOT_FOUND);
+
+ // wrap lines too long at comma boundaries
+ for (unsigned int i=0; i<toinsert.GetCount(); i++)
+ {
+ size_t len = toinsert[i].Len();
+ if (len > WRAP_COLUMN)
+ {
+ wxASSERT(i == toinsert.GetCount()-1);
+
+ // break this line
+ wxString tmpleft = toinsert[i].Left(WRAP_COLUMN);
+ int comma = tmpleft.Find(',', true /* from end */);
+ if (comma == wxNOT_FOUND)
+ break; // break out of the for cycle...
+
+ toinsert.Add(wxString(' ', nStartColumn+1) +
+ toinsert[i].Right(len-comma-2)); // exclude the comma and the space after it
+ toinsert[i] = tmpleft.Left(comma+1); // include the comma
+ }
+ }
+
+ // insert the new lines
+ for (unsigned int i=0; i<toinsert.GetCount(); i++)
+ file.InsertLine(toinsert[i], start+i);
// now save the modification
if (!file.Write()) {
- LogError("can't save the '%s' header file.", header);
+ LogError("\tcan't save the '%s' header file.", header);
return;
}
+
+ // how many lines did we add/remove in total?
+ int nOffset = toinsert.GetCount() + deprecationOffset - (end-start+1);
+ if (nOffset == 0)
+ return;
+
+ if (g_verbose)
+ LogMessage("\tthe final row offset for following methods is %d lines.", nOffset);
+
+ // update the other method's locations for those methods which belong to the modified header
+ // and are placed _below_ the modified method
+ wxClassPtrArray cToUpdate = m_doxyInterface.FindClassesDefinedIn(header);
+ for (unsigned int i=0; i < cToUpdate.GetCount(); i++)
+ {
+ for (unsigned int j=0; j < cToUpdate[i]->GetMethodCount(); j++)
+ {
+ wxMethod& m = cToUpdate[i]->GetMethod(j);
+ if (m.GetLocation() > iface->GetLocation())
+ {
+ // update the location of this method
+ m.SetLocation(m.GetLocation()+nOffset);
+ }
+ }
+ }
+}
+
+bool IfaceCheckApp::ParsePreprocessorOutput(const wxString& filename)
+{
+ wxTextFile tf;
+ if (!tf.Open(filename)) {
+ LogError("can't open the '%s' preprocessor output file.", filename);
+ return false;
+ }
+
+ size_t useful = 0;
+ for (unsigned int i=0; i < tf.GetLineCount(); i++)
+ {
+ const wxString& line = tf.GetLine(i);
+ wxString defnameval = line.Mid(8); // what follows the "#define " string
+
+ // the format of this line should be:
+ // #define DEFNAME DEFVALUE
+ if (!line.StartsWith("#define ") || !defnameval.Contains(" ")) {
+ LogError("unexpected content in '%s' at line %d.", filename, i);
+ return false;
+ }
+
+ // get DEFNAME
+ wxString defname = defnameval.BeforeFirst(' ');
+ if (defname.Contains("("))
+ continue; // this is a macro, skip it!
+
+ // get DEFVAL
+ wxString defval = defnameval.AfterFirst(' ').Strip(wxString::both);
+ if (defval.StartsWith("(") && defval.EndsWith(")"))
+ defval = defval.Mid(1, defval.Len()-2);
+
+ // store this pair in the doxygen interface, where it can be useful
+ m_doxyInterface.AddPreprocessorValue(defname, defval);
+ useful++;
+ }
+
+ LogMessage("Parsed %d preprocessor #defines from '%s' which will be used later...",
+ useful, filename);
+
+ return true;
}
void IfaceCheckApp::PrintStatistics(long secs)
{
LogMessage("wx real headers contains declaration of %d classes (%d methods)",
- m_api.GetClassesCount(), m_api.GetMethodCount());
+ m_gccInterface.GetClassesCount(), m_gccInterface.GetMethodCount());
LogMessage("wx interface headers contains declaration of %d classes (%d methods)",
- m_interface.GetClassesCount(), m_interface.GetMethodCount());
+ m_doxyInterface.GetClassesCount(), m_doxyInterface.GetMethodCount());
LogMessage("total processing took %d seconds.", secs);
}
projects / wxWidgets.git / blobdiff