Merge remote-tracking branch 'public/pr/2011' into mbedtls-2.1

.travis.yml

@@ -10,6 +10,7 @@ script:
 - tests/scripts/check-doxy-blocks.pl
 - tests/scripts/check-names.sh
 - tests/scripts/check-files.py
+- tests/scripts/doxygen.sh
 - cmake -D CMAKE_BUILD_TYPE:String="Check" .
 - make
 - make test
@@ -24,6 +25,10 @@ env:
     secure: "barHldniAfXyoWOD/vcO+E6/Xm4fmcaUoC9BeKW+LwsHqlDMLvugaJnmLXkSpkbYhVL61Hzf3bo0KPJn88AFc5Rkf8oYHPjH4adMnVXkf3B9ghHCgznqHsAH3choo6tnPxaFgOwOYmLGb382nQxfE5lUdvnM/W/psQjWt66A1+k="
 
 addons:
+  apt:
+    packages:
+    - doxygen
+    - graphviz
   coverity_scan:
     project:
       name: "ARMmbed/mbedtls"

CMakeLists.txt

@@ -130,20 +130,9 @@ if(ENABLE_PROGRAMS)
     add_subdirectory(programs)
 endif()
 
-# targets for doxygen only work on Unix
+ADD_CUSTOM_TARGET(apidoc
-if(UNIX)
+    COMMAND doxygen doxygen/mbedtls.doxyfile
-    ADD_CUSTOM_TARGET(apidoc
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
-        COMMAND mkdir -p apidoc
-        COMMAND cp include/mbedtls/config.h include/mbedtls/config.h.bak
-        COMMAND scripts/config.pl realfull
-        COMMAND doxygen doxygen/mbedtls.doxyfile
-        COMMAND mv include/mbedtls/config.h.bak include/mbedtls/config.h
-        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
-
-    ADD_CUSTOM_TARGET(apidoc_clean
-        COMMAND rm -rf apidoc
-        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
-endif(UNIX)
 
 if(ENABLE_TESTING)
     enable_testing()

ChangeLog

@@ -45,6 +45,13 @@ Bugfix
      (found by Catena cyber using oss-fuzz)
    * Fix memory leak and free without initialization in pk_encrypt
      and pk_decrypt example programs. Reported by Brace Stout. Fixes #1128.
+   * Fix potential build failures related to the 'apidoc' target, introduced
+     in the previous patch release. Found by Robert Scheck. #390 #391
+
+Changes
+   * "make apidoc" now generates the documentation for the current
+     configuration. Run "scripts/apidoc_full.sh" to generate the full
+     documentation. This aligns the behavior with Mbed TLS 2.2+.
 
 = mbed TLS 2.1.14 branch released 2018-07-25
 

Makefile

@@ -87,10 +87,7 @@ lcov:
 
 apidoc:
 	mkdir -p apidoc
-	cp include/mbedtls/config.h include/mbedtls/config.h.bak
-	scripts/config.pl realfull
 	doxygen doxygen/mbedtls.doxyfile
-	mv include/mbedtls/config.h.bak include/mbedtls/config.h
 
 apidoc_clean:
 	rm -rf apidoc

doxygen/mbedtls.doxyfile

@@ -664,7 +664,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = .
+INPUT                  = include doxygen/input
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -696,7 +696,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = configs
+EXCLUDE                =
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -710,7 +710,7 @@ EXCLUDE_SYMLINKS       = YES
 # against the file with absolute path, so to exclude all test directories
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = *_internal.h *_wrap.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1485,13 +1485,13 @@ XML_OUTPUT             = xml
 # which can be used by a validating XML parser to check the
 # syntax of the XML files.
 
-XML_SCHEMA             =
+#XML_SCHEMA             =
 
 # The XML_DTD tag can be used to specify an XML DTD,
 # which can be used by a validating XML parser to check the
 # syntax of the XML files.
 
-XML_DTD                =
+#XML_DTD                =
 
 # If the XML_PROGRAMLISTING tag is set to YES Doxygen will
 # dump the program listings (including syntax highlighting

scripts/apidoc_full.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+
+# Generate doxygen documentation with a full config.h (this ensures that every
+# available flag is documented, and avoids warnings about documentation
+# without a corresponding #define).
+#
+# /!\ This must not be a Makefile target, as it would create a race condition
+# when multiple targets are invoked in the same parallel build.
+
+set -eu
+
+CONFIG_H='include/mbedtls/config.h'
+
+if [ -r $CONFIG_H ]; then :; else
+    echo "$CONFIG_H not found" >&2
+    exit 1
+fi
+
+CONFIG_BAK=${CONFIG_H}.bak
+cp -p $CONFIG_H $CONFIG_BAK
+
+scripts/config.pl realfull
+make apidoc
+
+mv $CONFIG_BAK $CONFIG_H

tests/scripts/all.sh

@@ -400,6 +400,12 @@ msg "test/build: declared and exported names" # < 3s
 cleanup
 tests/scripts/check-names.sh
 
+if which doxygen >/dev/null; then
+    msg "test: doxygen warnings" # ~ 3s
+    cleanup
+    tests/scripts/doxygen.sh
+fi
+
 
 
 ################################################################

tests/scripts/doxygen.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+
+# Make sure the doxygen documentation builds without warnings
+
+# Abort on errors (and uninitiliased variables)
+set -eu
+
+if [ -d library -a -d include -a -d tests ]; then :; else
+    echo "Must be run from mbed TLS root" >&2
+    exit 1
+fi
+
+if scripts/apidoc_full.sh > doc.out 2>doc.err; then :; else
+    cat doc.err
+    echo "FAIL" >&2
+    exit 1;
+fi
+
+cat doc.out doc.err | \
+    grep -v "warning: ignoring unsupported tag" \
+    > doc.filtered
+
+if egrep "(warning|error):" doc.filtered; then
+    echo "FAIL" >&2
+    exit 1;
+fi
+
+make apidoc_clean
+rm -f doc.out doc.err doc.filtered