Skip to content

Commit

Permalink
Bug #27627136 DOXYERROR.LOG DOESN'T CONTAIN ERRORS FROM PLANTUML AND DIA
Browse files Browse the repository at this point in the history
Problem: Doxygen runs with QUIET=NO and
WARN_LOGFILE=@CMAKE_CURRENT_BINARY_DIR@/doxyerror.log. This writes all
Doxygen errors and warnings to doxyerror.log instead of to
stderr. However, errors from external tools called by Doxygen, such as
PlantUML and dia, are not included. These are only writen to stderr, and
lost in a long list of Doxygen stdout messages.

Solution: Use the output to stderr instead of WARN_LOGFILE in order to
pick up errors from third party tools. Build all error filtering that
used to be done with sed and grep into the CMake script, so that
everything is done by one call to make doxygen.

The result is the following files:

doxyoutput.log:
  stdout from Doxygen.

doxyerror.log:
  stderr from Doxygen.

tofix-all.log:
  Same as doxyerror.log, but without dia status messages, and with paths
  relative to the source directory.

tofix-regressions.log:
  Same as tofix-all.log, but without known warnings and errors (filters
  defined in Doxyfile-ignored).

The tofix-regressions.log messages are also printed to stdout during
make doxygen, and the target will finish by reporting if any regressions
were found.

Change-Id: I0e45745976bedbcb83f8ed952e52f927de99eb21
  • Loading branch information
nryeng committed Apr 6, 2018
1 parent e1f99e4 commit 64fb797
Show file tree
Hide file tree
Showing 4 changed files with 132 additions and 31 deletions.
14 changes: 12 additions & 2 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1033,8 +1033,18 @@ FIND_PACKAGE(Doxygen)
IF(DOXYGEN_FOUND)
CONFIGURE_FILE(Doxyfile.in Doxyfile @ONLY)
ADD_CUSTOM_TARGET(
doxygen ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
doxygen
COMMAND ${CMAKE_COMMAND}
-DDOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}
-DDOXYFILE=${CMAKE_BINARY_DIR}/Doxyfile
-DERROR_FILE=${CMAKE_BINARY_DIR}/doxyerror.log
-DOUTPUT_FILE=${CMAKE_BINARY_DIR}/doxyoutput.log
-DSOURCE_DIR=${CMAKE_SOURCE_DIR}
-DTOFIX_FILE=${CMAKE_BINARY_DIR}/tofix-all.log
-DREGRESSION_FILE=${CMAKE_BINARY_DIR}/tofix-regressions.log
-DIGNORE_FILE=${CMAKE_SOURCE_DIR}/Doxyfile-ignored
-P ${CMAKE_SOURCE_DIR}/run_doxygen.cmake
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
COMMENT "Generating Doxygen documentation" VERBATIM
)
SET_PROPERTY(TARGET doxygen PROPERTY EXCLUDE_FROM_ALL TRUE)
Expand Down
11 changes: 5 additions & 6 deletions Doxyfile-ignored
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License, version 2.0,
Expand All @@ -21,6 +21,10 @@
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
#===========================================================================

# All non-empty non-comment lines are regex patterns using CMake regex
# syntax. Matching lines will be removed from the error log when writing
# tofix-all.log. See run_doxygen.cmake for details.

#===========================================================================
# MAINTAINER:
# File a bug for each doxygen failure seen during the build:
Expand All @@ -43,8 +47,3 @@
# DATE / BUG REPORT AUTHOR
# include/m_ctype.h:*
#===========================================================================

# Bug 25542956 - INNODB_MEMCACHED DOXYGEN DOCUMENTATION
# 2017-02-13 Marc Alff
plugin/innodb_memcached/*

29 changes: 6 additions & 23 deletions Doxyfile.in
Original file line number Diff line number Diff line change
Expand Up @@ -41,28 +41,11 @@
#
# cmake --build . --config <Debug|RelWithDebInfo> --target doxygen
#
# See the logs in ./doxyerror.log
# See the doc in ./doxygen/html/index.html
#
# To parse the error log generated:
# ---------------------------------
#
# sort -u doxyerror.log |
# grep "^"`pwd` |
# sed -e "s|"`pwd`"/||g" > tofix-all.log
#
# See the errors to fix in tofix-all.log
#
# To filter known issues from the error log:
# ------------------------------------------
#
# grep -v "#" Doxyfile-ignored |
# grep -v "^[[:space:]]*$" > Doxyfile-ignored.tmp
#
# grep -v -E --file=Doxyfile-ignored.tmp tofix-all.log > tofix-regressions.log
#
# See the list of filtering rules in Doxyfile-ignored.tmp
# See the list of regression errors in tofix-regressions.log
# The documentation can be found in ./doxygen/html/index.html
# Doxygen stdout is written to ./doxyoutput.log
# Doxygen stderr is written to ./doxyerror.log
# All errors and warnings are written to ./tofix-all.log
# Regressions are written to ./tofix-regressions.log
#
# To edit the list of known errors:
# ---------------------------------
Expand Down Expand Up @@ -844,7 +827,7 @@ WARN_FORMAT = "$file:$line: $text"
# messages should be written. If left blank the output is written to standard
# error (stderr).

WARN_LOGFILE = @CMAKE_CURRENT_BINARY_DIR@/doxyerror.log
WARN_LOGFILE =

#---------------------------------------------------------------------------
# Configuration options related to the input files
Expand Down
109 changes: 109 additions & 0 deletions run_doxygen.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License, version 2.0,
# as published by the Free Software Foundation.
#
# This program is also distributed with certain software (including
# but not limited to OpenSSL) that is licensed under separate terms,
# as designated in a particular file or component or in included license
# documentation. The authors of MySQL hereby grant you an additional
# permission to link the program and your derivative works with the
# separately licensed software that they have included with MySQL.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License, version 2.0, for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

CMAKE_POLICY(SET CMP0007 NEW)

MESSAGE(STATUS "Writing stdout to ${OUTPUT_FILE}")
MESSAGE(STATUS "Writing stderr to ${ERROR_FILE}")

EXECUTE_PROCESS(
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE}
ERROR_FILE ${ERROR_FILE}
OUTPUT_FILE ${OUTPUT_FILE}
)

MESSAGE("Filtering out ignored warnings/errors")
MESSAGE(STATUS "Writing warnings/errors to ${TOFIX_FILE}")

# Read IGNORE_FILE and create a list of patterns that we should ignore in
# ERROR_FILE.
FILE(READ ${IGNORE_FILE} IGNORE_FILE_CONTENTS)
STRING(REPLACE ";" "\\\\;" IGNORE_FILE_CONTENTS ${IGNORE_FILE_CONTENTS})
STRING(REPLACE "\n" ";" IGNORE_FILE_LINES ${IGNORE_FILE_CONTENTS})
FOREACH(LINE ${IGNORE_FILE_LINES})
STRING(REGEX MATCH "^[\r\n\t ]*#" MATCH_COMMENT ${LINE})
STRING(REGEX MATCH "^[\r\n\t ]*$" MATCH_EMPTY ${LINE})
IF(NOT (MATCH_COMMENT OR MATCH_EMPTY))
MESSAGE(STATUS "Ignoring pattern ${LINE}")
SET(IGNORE_LIST "${IGNORE_LIST};${LINE}")
ENDIF()
ENDFOREACH()

# Convert ERROR_FILE contents to a list of lines, and sort it
FILE(READ ${ERROR_FILE} ERROR_FILE_CONTENTS)
STRING(REPLACE ";" "\\\\;" ERROR_FILE_CONTENTS ${ERROR_FILE_CONTENTS})
STRING(REPLACE "\n" ";" ERROR_FILE_LINES ${ERROR_FILE_CONTENTS})
LIST(SORT ERROR_FILE_LINES)
LIST(REMOVE_DUPLICATES ERROR_FILE_LINES)

FILE(REMOVE ${TOFIX_FILE})
FILE(REMOVE ${REGRESSION_FILE})
UNSET(FOUND_WARNINGS)
# See if we have any warnings/errors.
FOREACH(LINE ${ERROR_FILE_LINES})
# Filter out information messages from dia.
STRING(REGEX MATCH "^.*\\.dia --> dia_.*\\.png\$" DIA_STATUS ${LINE})
STRING(LENGTH "${DIA_STATUS}" LEN_DIA_STATUS)
IF (${LEN_DIA_STATUS} GREATER 0)
CONTINUE()
ENDIF()

STRING(REGEX MATCH "^(${SOURCE_DIR}/)(.*)" XXX ${LINE})
IF(CMAKE_MATCH_1)
SET(LINE ${CMAKE_MATCH_2})
ELSE()
GET_FILENAME_COMPONENT(SOURCE_DIR_REALPATH ${SOURCE_DIR} REALPATH)
STRING(REGEX MATCH "^(${SOURCE_DIR_REALPATH}/)(.*)" XXX ${LINE})
IF(CMAKE_MATCH_1)
SET(LINE ${CMAKE_MATCH_2})
ENDIF()
ENDIF()

# Check for known patterns. Known patterns are not reported as regressions.
SET(IS_REGRESSION 1)
FOREACH(IGNORE_PATTERN ${IGNORE_LIST})
STRING(REGEX MATCH "${IGNORE_PATTERN}" IGNORED ${LINE})
STRING(LENGTH "${IGNORED}" LEN_IGNORED)
IF (${LEN_IGNORED} GREATER 0)
# The line matches a pattern in IGNORE_FILE, so this is a known error.
UNSET(IS_REGRESSION)
BREAK()
ENDIF()
ENDFOREACH()

# All errors go to TOFIX_FILE.
FILE(APPEND ${TOFIX_FILE} "${LINE}\n")

# Only regressions go to REGRESSION_FILE.
IF (${IS_REGRESSION})
MESSAGE(${LINE})
FILE(APPEND ${REGRESSION_FILE} "${LINE}\n")
SET(FOUND_WARNINGS 1)
ENDIF()
ENDFOREACH()

# Only report regressions.
IF(FOUND_WARNINGS)
MESSAGE("\n\nFound warnings/errors, see ${REGRESSION_FILE}")
ELSE()
MESSAGE("No warnings/errors found")
ENDIF()

0 comments on commit 64fb797

Please sign in to comment.