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" 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 8c82d08d1..7d08150f8 100644 --- a/ChangeLog +++ b/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 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 diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 89a10c2f9..381ff3a8c 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 @@ -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 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/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..e7758c9e8 --- /dev/null +++ b/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