X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/919ccb4c4446a94c7d6c44d4ee279704ecd4474d..fe1a36a70c2f5ed8a6f9ea0b82005ebb987e5860:/utils/ifacecheck/src/ifacecheck.cpp

diff --git a/utils/ifacecheck/src/ifacecheck.cpp b/utils/ifacecheck/src/ifacecheck.cpp
index b7b8474e41..a8ce9b2bc6 100644
--- a/utils/ifacecheck/src/ifacecheck.cpp
+++ b/utils/ifacecheck/src/ifacecheck.cpp
@@ -22,6 +22,7 @@
 
 #include "wx/cmdline.h"
 #include "wx/textfile.h"
+#include "wx/filename.h"
 #include "wx/stopwatch.h"       // for wxGetLocalTime
 #include "xmlparser.h"
 
@@ -34,20 +35,29 @@ bool g_verbose = false;
 // 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",
@@ -66,6 +76,8 @@ public:
     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);
@@ -73,12 +85,23 @@ public:
     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)
@@ -87,41 +110,78 @@ int IfaceCheckApp::OnRun()
 {
     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;
@@ -135,7 +195,7 @@ void IfaceCheckApp::ShowProgress()
 
 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;
@@ -143,8 +203,30 @@ bool IfaceCheckApp::Compare()
     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();
@@ -153,9 +235,9 @@ bool IfaceCheckApp::Compare()
         // 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) {
@@ -166,15 +248,15 @@ bool IfaceCheckApp::Compare()
         } else {
 
             LogMessage("%s: couldn't find the real interface for the '%s' class",
-                       interface[i].GetHeader(), cname);
+                       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;
 }
@@ -192,27 +274,32 @@ int IfaceCheckApp::CompareClasses(const wxClass* iface, const wxClassPtrArray& a
         searchedclasses += "/" + api[j]->GetName();
     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);
-        const wxString& tofind = m.GetAsString();
         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++)
         {
             real = api[j]->FindMethod(m);
-            if (real) {
-
-                // there is a matching prototype! It's ok!
-                //LogMessage("the doxygen method '%s' has a match in the real interface of '%s'!",
-                //           tofind, api[j]->GetName());
-                matches++;
-            }
+            if (real)
+                matches++;                // there is a real matching prototype! It's ok!
         }
 
         if (matches == 0)
@@ -229,32 +316,61 @@ int IfaceCheckApp::CompareClasses(const wxClass* iface, const wxClassPtrArray& a
                 WX_APPEND_ARRAY(overloads, results);
             }
 
-            if (overloads.GetCount()>1)
-            {
-                // TODO: decide which of these overloads is the most "similar" to m
-                //       and eventually modify it
-                LogWarning("%s: there are %d overloads of method '%s' in the classes '%s' "
-                           "all with different signatures; manual fix is required",
-                           header, overloads.GetCount(), tofind, searchedclasses);
-            }
-            else if (overloads.GetCount() == 1)
+            if (overloads.GetCount()==0)
             {
-                wxString tmp;
-                if (m_modify) tmp = "; fixing it...";
-
-                LogWarning("%s: the method '%s' of classes '%s' has a different signature%s",
-                           header, tofind, searchedclasses, tmp);
-
-                // try to modify it!
-                if (m_modify)
-                    FixMethod(iface->GetHeader(), &m, overloads[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
             }
             else
             {
-                LogMessage("%s: real '%s' class has no method '%s'",
-                           header, searchedclasses, tofind);
-                count++;        // count this type of warnings
+                // first, output a warning
+                wxString warning = header;
+                if (overloads.GetCount()>1)
+                    warning += wxString::Format(": in the real headers there are %d overloads of '%s' for "
+                                                "'%s' all with different signatures:\n",
+                                                overloads.GetCount(), m.GetName(), searchedclasses);
+                else
+                    warning += wxString::Format(": in the real headers there is a method '%s' for '%s'"
+                                                " but has different signature:\n",
+                                                m.GetName(), searchedclasses);
+
+                warning += "\tdoxy header: " + m.GetAsString();
+                for (unsigned int j=0; j<overloads.GetCount(); j++)
+                    warning += "\n\treal header: " + overloads[j]->GetAsString();
+
+                wxPrint(warning + "\n");
+                count++;
+
+                if (overloads.GetCount()>1)
+                {
+                    // TODO: decide which of these overloads is the most "similar" to m
+                    //       and eventually modify it
+                    if (m_modify)
+                        wxPrint("\tmanual fix is required\n");
+                }
+                else
+                {
+                    wxASSERT(overloads.GetCount() == 1);
+
+                    if (m_modify)
+                    {
+                        wxPrint("\tfixing it...\n");
+
+                        // try to modify it!
+                        FixMethod(iface->GetHeader(), &m, overloads[0]);
+                    }
+                }
             }
+
+            count++;
         }
     }
 
@@ -267,63 +383,192 @@ void IfaceCheckApp::FixMethod(const wxString& header, const wxMethod* iface, con
 
     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(";")) {
+        LogWarning("\tinvalid location info for method '%s': %d.",
                    iface->GetAsString(), iface->GetLocation());
         return;
     }
 
     // find the start point of this prototype declaration:
-    int start = end;
+    int start = end-1;
+    bool founddecl = false;
     while (start > 0 &&
            !file.GetLine(start).Contains(";") &&
-            !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;
     }
 
+    // start-th line contains either the declaration of another prototype
+    // or the closing tag */ of a doxygen comment; start one line below
+    start++;
+
     // remove the old prototype
     for (int i=start; i<=end; i++)
         file.RemoveLine(start);     // remove (end-start)-nth times the start-th line
 
 #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);
+
+    // discard API argument names and replace them with those parsed from doxygen XML:
+    const wxArgumentTypeArray& doxygenargs = iface->GetArgumentTypes();
+    const wxArgumentTypeArray& realargs = api->GetArgumentTypes();
+    if (realargs.GetCount() == doxygenargs.GetCount())
+    {
+        for (unsigned int j=0; j<doxygenargs.GetCount(); j++)
+            if (doxygenargs[j]==realargs[j])
+                realargs[j].SetArgumentName(doxygenargs[j].GetArgumentName());
+
+        tmp.SetArgumentTypes(realargs);
+    }
+
+#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 one
-    file.InsertLine(INDENTATION_STR + api->GetAsString() + ";", start);
+    // 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);
 }