From b86cc9d8a0fe2a1c75451b486b5b68c8a873f899 Mon Sep 17 00:00:00 2001 From: Juan Carrano Date: Fri, 8 Feb 2019 17:11:52 +0100 Subject: [PATCH 1/3] Makefile.include: move BUILD_DIR definition to makefiles/ The definition of BUILD_DIR is moved to makefiles/buildout.inc.mk so that ic can be reused by makefiles that do not include Makefile.include (such as the docs makefile). Additionally, a common logging directory is defined insude the build dir, and with an implicit rule to create directories. --- Makefile.include | 5 +++-- makefiles/buildout.inc.mk | 13 +++++++++++++ 2 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 makefiles/buildout.inc.mk diff --git a/Makefile.include b/Makefile.include index d0468a86124b..af399228a25a 100644 --- a/Makefile.include +++ b/Makefile.include @@ -23,7 +23,6 @@ RIOTTOOLS ?= $(RIOTBASE)/dist/tools RIOTPROJECT ?= $(shell git rev-parse --show-toplevel 2>/dev/null || pwd) GITCACHE ?= $(RIOTTOOLS)/git/git-cache GIT_CACHE_DIR ?= $(HOME)/.gitcache -BUILD_DIR ?= $(RIOTBASE)/build APPDIR ?= $(CURDIR) BINDIRBASE ?= $(APPDIR)/bin BINDIR ?= $(BINDIRBASE)/$(BOARD) @@ -31,6 +30,8 @@ PKGDIRBASE ?= $(BINDIRBASE)/pkg/$(BOARD) DLCACHE ?= $(RIOTTOOLS)/dlcache/dlcache.sh DLCACHE_DIR ?= $(RIOTBASE)/.dlcache +include $(RIOTMAKE)/buildout.inc.mk + __DIRECTORY_VARIABLES := \ RIOTBASE \ RIOTCPU \ @@ -41,6 +42,7 @@ __DIRECTORY_VARIABLES := \ RIOTPROJECT \ APPDIR \ BUILD_DIR \ + LOGS_DIR \ BINDIRBASE \ BINDIR \ CCACHE_BASEDIR \ @@ -60,7 +62,6 @@ override RIOTTOOLS := $(abspath $(RIOTTOOLS)) override RIOTPROJECT := $(abspath $(RIOTPROJECT)) override GITCACHE := $(abspath $(GITCACHE)) override APPDIR := $(abspath $(APPDIR)) -override BUILD_DIR := $(abspath $(BUILD_DIR)) override BINDIRBASE := $(abspath $(BINDIRBASE)) override BINDIR := $(abspath $(BINDIR)) override PKGDIRBASE := $(abspath $(PKGDIRBASE)) diff --git a/makefiles/buildout.inc.mk b/makefiles/buildout.inc.mk new file mode 100644 index 000000000000..8bd18a460f2a --- /dev/null +++ b/makefiles/buildout.inc.mk @@ -0,0 +1,13 @@ +# Include this file to use the common buildout directory. + +BUILD_DIR ?= $(RIOTBASE)/build +LOGS_DIR ?= $(BUILD_DIR)/logs + +override BUILD_DIR := $(abspath $(BUILD_DIR)) +override LOGS_DIR := $(abspath $(LOGS_DIR)) + +# This rule is OK if the buildout dir only contains directorties (which should +# be the case for tidyness) + +$(BUILD_DIR)/%: + $(Q)mkdir -p $@ From a58d1b10e9cc3310791e576f7f6f5c583a9184af Mon Sep 17 00:00:00 2001 From: Juan Carrano Date: Fri, 8 Feb 2019 17:14:47 +0100 Subject: [PATCH 2/3] doxygen/Makefile: summarize warnings, log full output to file. The latest versions of doxygen produce an unwieldy amount of warnings. Instead of ignoring them, this commit causes them to be saved to a log file in the common build directory and prints only a summary with a tally of the number of each type of warning found. --- doc/doxygen/Makefile | 20 ++++++++++++++------ doc/doxygen/warning_patterns.sed | 5 +++++ 2 files changed, 19 insertions(+), 6 deletions(-) create mode 100644 doc/doxygen/warning_patterns.sed diff --git a/doc/doxygen/Makefile b/doc/doxygen/Makefile index f9eb957b08f6..439ff8bde64d 100644 --- a/doc/doxygen/Makefile +++ b/doc/doxygen/Makefile @@ -1,4 +1,7 @@ RIOTBASE=$(shell git rev-parse --show-toplevel) + +include $(RIOTBASE)/makefiles/buildout.inc.mk + # Generate list of quoted absolute include paths. Evaluated in riot.doxyfile. export STRIP_FROM_INC_PATH_LIST=$(shell \ git ls-tree -dr --full-tree --name-only HEAD core drivers sys |\ @@ -9,17 +12,22 @@ export STRIP_FROM_INC_PATH_LIST=$(shell \ # It can also be installed in ubuntu with the `node-less` package LESSC ?= $(shell command -v lessc 2>/dev/null) +DOXYGEN ?= doxygen - + +DOXY_ERROR_PIPE = ($(DOXYGEN) 3>&2 2>&1 1>&3 3>&- | tee $(LOGS_DIR)/doxygen.log | \ + sed -nf warning_patterns.sed | sort | uniq -c) 3>&2 2>&1 1>&3 3>&- + .PHONY: doc doc: html # by marking html as phony we force make to re-run Doxygen even if the directory exists. .PHONY: html -html: src/css/riot.css src/changelog.md - ( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | doxygen - +html: src/css/riot.css src/changelog.md | $(LOGS_DIR) + ( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | $(DOXY_ERROR_PIPE) .PHONY: man -man: src/changelog.md - ( cat riot.doxyfile ; echo "GENERATE_MAN = yes" ) | doxygen - +man: src/changelog.md | $(LOGS_DIR) + ( cat riot.doxyfile ; echo "GENERATE_MAN = yes" ) | $(DOXY_ERROR_PIPE) ifneq (,$(LESSC)) src/css/riot.css: src/css/riot.less src/css/variables.less @@ -34,8 +42,8 @@ src/changelog.md: src/changelog.md.tmp ../../release-notes.txt @./generate-changelog.py $+ $@ .PHONY: -latex: src/changelog.md - ( cat riot.doxyfile ; echo "GENERATE_LATEX= yes" ) | doxygen - +latex: src/changelog.md | $(LOGS_DIR) + ( cat riot.doxyfile ; echo "GENERATE_LATEX= yes" ) | $(DOXY_ERROR_PIPE) clean: -@rm -rf latex man html doxygen_objdb_*.tmp doxygen_entrydb_*.tmp src/changelog.md diff --git a/doc/doxygen/warning_patterns.sed b/doc/doxygen/warning_patterns.sed new file mode 100644 index 000000000000..196170f0ddc6 --- /dev/null +++ b/doc/doxygen/warning_patterns.sed @@ -0,0 +1,5 @@ +/Member .* is not documented/ { c Undocumented member + n} +/multiple use of section label/ { c Repeated label + n} +/warning/ c Other warnings From 72d832147bb5401f745e00654e34f0c2e6d84dc9 Mon Sep 17 00:00:00 2001 From: Juan Carrano Date: Fri, 8 Feb 2019 17:53:30 +0100 Subject: [PATCH 3/3] doccheck: Display only a summary of warnings. The lates version of doxygen generates so much warnings that it is inconvenient to display. The docs makefile was update to output a summary. This patch makes doccheck expect that summary instead of the real output. --- dist/tools/doccheck/check.sh | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/dist/tools/doccheck/check.sh b/dist/tools/doccheck/check.sh index f5fa0e27ef8b..caee28d46963 100755 --- a/dist/tools/doccheck/check.sh +++ b/dist/tools/doccheck/check.sh @@ -20,18 +20,16 @@ else CRESET= fi -DOXY_OUTPUT=$(make -C "${RIOTBASE}" doc 2>&1) +DOXY_STDERR=$(make -sC "${RIOTBASE}" doc 3>&2 2>&1 1>&3 3>&-) DOXY_ERRCODE=$? if [ "${DOXY_ERRCODE}" -ne 0 ] ; then echo "'make doc' exited with non-zero code (${DOXY_ERRCODE})" - echo "${DOXY_OUTPUT}" exit 2 else - ERRORS=$(echo "${DOXY_OUTPUT}" | grep '.*warning' | sed "s#${PWD}/\([^:]*\)#\1#g") - if [ -n "${ERRORS}" ] ; then + if [ -n "${DOXY_STDERR}" ] ; then echo -e "${CERROR}ERROR: Doxygen generates the following warnings:${CRESET}" - echo "${ERRORS}" + echo "${DOXY_STDERR}" exit 2 fi fi