From 564283334562ba4baa17f8f9283f2d23f900de6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 4 Jan 2016 16:27:32 +0100 Subject: [PATCH 01/10] Fix doxygen warnings about deprecated tags Doxygen 1.8.10 warns that those tags are obsolete. Since we're not generating XML anyway, it seems harmless to remove them even for earlier versions. --- doxygen/mbedtls.doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 57bc5182b..5aa970b80 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -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 From 9c81d0101d2ed18b557ac9aaac0cd75a13970a96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 4 Jan 2016 16:49:09 +0100 Subject: [PATCH 02/10] Add test script for doxygen warnings --- tests/scripts/all.sh | 6 ++++++ tests/scripts/doxygen.sh | 25 +++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100755 tests/scripts/doxygen.sh diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 53c5e37a2..7ee3cc838 100755 --- a/tests/scripts/all.sh +++ b/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 + ################################################################ diff --git a/tests/scripts/doxygen.sh b/tests/scripts/doxygen.sh new file mode 100755 index 000000000..5a00c90b7 --- /dev/null +++ b/tests/scripts/doxygen.sh @@ -0,0 +1,25 @@ +#!/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 make apidoc > doc.out 2>doc.err; then :; else + cat doc.err + echo "FAIL" >&2 + exit 1; +fi + +if grep warning doc.out doc.err; then + echo "FAIL" >&2 + exit 1; +fi + +make apidoc_clean +rm -f doc.out doc.err From dec65c27eed645eb6a1ff1983d78df403009c94b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 4 Jan 2016 17:08:31 +0100 Subject: [PATCH 03/10] Add new doxygen test to travis --- .travis.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.travis.yml b/.travis.yml index 91a36c92d..3a12b56b4 100644 --- a/.travis.yml +++ b/.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" From 43e015a4cf6a4fd83771a50c7734a1b802d5aeaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 8 Jan 2016 16:47:33 +0100 Subject: [PATCH 04/10] Exclude some warnings from the doxygen test Apparently travis has an old version of doxygen that doesn't know all tags in our config. That's not something we care about, we only want to know about warnings in our doxygen content --- tests/scripts/doxygen.sh | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tests/scripts/doxygen.sh b/tests/scripts/doxygen.sh index 5a00c90b7..1013cbd16 100755 --- a/tests/scripts/doxygen.sh +++ b/tests/scripts/doxygen.sh @@ -16,10 +16,14 @@ if make apidoc > doc.out 2>doc.err; then :; else exit 1; fi -if grep warning doc.out doc.err; then +cat doc.out doc.err | \ + grep -v "warning: ignoring unsupported tag" \ + > doc.filtered + +if grep "warning" doc.filtered; then echo "FAIL" >&2 exit 1; fi make apidoc_clean -rm -f doc.out doc.err +rm -f doc.out doc.err doc.filtered From b8a78d91128788b1684f385908a55252ccb3903e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 8 Jan 2016 16:48:51 +0100 Subject: [PATCH 05/10] Exclude more things from doxygen inputs --- doxygen/mbedtls.doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 5aa970b80..d8ee6c3d4 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -664,7 +664,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = . +INPUT = include # 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 @@ -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 From 71d5c58a1f22e1952ac9fdecccfb56efd7f0424f Mon Sep 17 00:00:00 2001 From: Simon Butcher Date: Tue, 12 Jan 2016 00:59:15 +0000 Subject: [PATCH 06/10] Reverted the INPUT in doxygen to . Previous change to include excluded the content in doxygen/input --- doxygen/mbedtls.doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index d8ee6c3d4..7a8be1b6c 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -664,7 +664,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = include +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 From 85c379d6d15b40212ebebf38a767b70bb102559c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 12 Jan 2016 13:59:39 +0000 Subject: [PATCH 07/10] Revert changes done to 'make apidoc' target This partially reverts 1989caf71c1d4 (only the changes to Makefile and CMakeLists, the addition to scripts/config.pl is kept). Modifying config.h in the apidoc target creates a race condition with make -j4 all apidoc where some parts of the library, tests or programs could be built with the wrong config.h, resulting in all kinds of (semi-random) errors. Recent versions of CMake mitigate this by adding a .NOTPARALLEL target to the generated Makefile, but people would still get errors with older CMake versions that are still in use (eg in RHEL 5), and with plain make. An additional issue is that, by failing to use cp -p, the apidoc target was updating the timestamp on config.h, which seems to cause further build issues. Let's get back to the previous, safe, situation. The improved apidoc building will be resurrected in a script in the next commit. fixes #390 fixes #391 --- CMakeLists.txt | 17 +++-------------- ChangeLog | 2 ++ Makefile | 3 --- 3 files changed, 5 insertions(+), 17 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index f032ad40c..d3213575d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -130,20 +130,9 @@ if(ENABLE_PROGRAMS) add_subdirectory(programs) endif() -# targets for doxygen only work on Unix -if(UNIX) - ADD_CUSTOM_TARGET(apidoc - 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) +ADD_CUSTOM_TARGET(apidoc + COMMAND doxygen doxygen/mbedtls.doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) if(ENABLE_TESTING) enable_testing() diff --git a/ChangeLog b/ChangeLog index ef01bcfee..61a063133 100644 --- a/ChangeLog +++ b/ChangeLog @@ -24,6 +24,8 @@ 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 = mbed TLS 2.1.14 branch released 2018-07-25 diff --git a/Makefile b/Makefile index 0eece74ab..dd76b40e2 100644 --- a/Makefile +++ b/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 From b82d09b6a2f3b6e5ca2ab3666972f5cce1e90c8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 12 Jan 2016 14:17:52 +0000 Subject: [PATCH 08/10] Add scripts/apidoc_full.sh This re-introduces the apidoc with full config.h, but hopefully with the race conditions and other issues that the previous implementation had. Adapt doxygen test script to use that new script, and also check for errors in addition to warnings while at it. --- scripts/apidoc_full.sh | 25 +++++++++++++++++++++++++ tests/scripts/doxygen.sh | 4 ++-- 2 files changed, 27 insertions(+), 2 deletions(-) create mode 100755 scripts/apidoc_full.sh diff --git a/scripts/apidoc_full.sh b/scripts/apidoc_full.sh new file mode 100755 index 000000000..bebab103e --- /dev/null +++ b/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 diff --git a/tests/scripts/doxygen.sh b/tests/scripts/doxygen.sh index 1013cbd16..e7758c9e8 100755 --- a/tests/scripts/doxygen.sh +++ b/tests/scripts/doxygen.sh @@ -10,7 +10,7 @@ if [ -d library -a -d include -a -d tests ]; then :; else exit 1 fi -if make apidoc > doc.out 2>doc.err; then :; else +if scripts/apidoc_full.sh > doc.out 2>doc.err; then :; else cat doc.err echo "FAIL" >&2 exit 1; @@ -20,7 +20,7 @@ cat doc.out doc.err | \ grep -v "warning: ignoring unsupported tag" \ > doc.filtered -if grep "warning" doc.filtered; then +if egrep "(warning|error):" doc.filtered; then echo "FAIL" >&2 exit 1; fi From 3ccce199a209cf66dfef357fb3773ba845085d9a Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 10 Sep 2018 12:21:04 +0200 Subject: [PATCH 09/10] Document the behavior change of make apidoc --- ChangeLog | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/ChangeLog b/ChangeLog index 61a063133..5d2bb4770 100644 --- a/ChangeLog +++ b/ChangeLog @@ -27,6 +27,11 @@ Bugfix * 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 Security From a2710dc0944e219834e0337315dc3ec2013d5a34 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 2 Oct 2018 10:45:22 +0200 Subject: [PATCH 10/10] Look for documentation only in specific directories Generate the documentation from include and doxygen/input only. Don't get snared by files containing Doxygen comments that lie in other directories such as tests, yotta, crypto/include, ... The only difference this makes in a fresh checkout is that the documentation no longer lists target_config.h. This file is from yotta, does not contain any Doxygen comment, and its inclusion in the rendered documentation was clearly an oversight. --- doxygen/mbedtls.doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 7a8be1b6c..bf64fc3d2 100644 --- a/doxygen/mbedtls.doxyfile +++ b/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