# Doxygen configuration and our utility scripts
DOXY_DIR ?= $(WS_ROOT)/doxygen
-# Input directories and files
-DOXY_INPUT ?= \
- README.md \
+# Primary source directories
+DOXY_SRC_DIRECTORIES = \
vppinfra \
svm \
vlib \
vlib-api \
vnet \
vpp \
- vpp-api \
+ vpp-api
+
+# Input directories and files
+DOXY_INPUT ?= \
+ $(wildcard $(WS_ROOT)/*.md) \
+ $(wildcard $(DOXY_DIR)/*.md) \
+ $(DOXY_SRC_DIRECTORIES) \
plugins
+# Strip leading workspace path from input names
+DOXY_INPUT := $(subst $(WS_ROOT)/,,$(DOXY_INPUT))
+
+# Files to exclude, from pre-Doxygen steps, eg because they're
+# selectively compiled.
+# Examples would be to exclude non-DPDK related sources when
+# there's a DPDK equivalent that conflicts.
+# These must be left-anchored paths for the regexp below to work.
+DOXY_EXCLUDE ?= \
+ vlib/vlib/buffer.c \
+ vlib/example \
+ plugins/sample-plugin
+
+# Generate a regexp for filenames to exclude
+DOXY_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_EXCLUDE))' | sed -e 's/ /|/g')))
+
+# Include all the normal source directories in the include file path
+DOXY_INCLUDE_PATH = $(DOXY_SRC_DIRECTORIES)
+
+# Also include any plugin directories that exist
+DOXY_INCLUDE_PATH += \
+ $(shell find $(WS_ROOT)/plugins -maxdepth 1 -type d | sed -e 's@^$(WS_ROOT)/*@@')
+
+# Find API header directories and include them in the header path.
+# This is only useful if VPP and plugins are already built; nothing
+# here depends on those targets. We don't build documentation for these
+# header files, they're just added to the INCLUDE search path for Doxygen.
+_vpp_br = $(shell find "$(BR)" -maxdepth 1 -type d \
+ '(' -name build-vpp_debug-native -o -name build-vpp-native ')' -print \
+ | sed -e 's@^$(WS_ROOT)/*@@' -e 1q)
+ifneq ($(strip $(_vpp_br)),)
+DOXY_INCLUDE_PATH += \
+ $(_vpp_br)/vlib-api \
+ $(_vpp_br)/vpp
+# Also include any plugin directories that exist
+DOXY_INCLUDE_PATH += \
+ $(shell find $(WS_ROOT)/$(_vpp_br)/plugins -maxdepth 1 -type d | sed -e 's@^$(WS_ROOT)/*@@')
+endif
+
+# Discover if we have CPP available
+_cpp = $(shell which cpp)
+ifneq ($(strip $(_cpp)),)
+# Add whatever directories CPP normally includes to the header path
+DOXY_INCLUDE_PATH += $(shell set -e; $(_cpp) -v </dev/null 2>&1 | awk 'f&&/^ /{print $$1} /^\#include/{f=1}')
+endif
+
# Target directory for doxygen output
DOXY_OUTPUT ?= $(BR)/docs
SIPHON_DOCS = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .md,$(SIPHONS)))
$(BR)/.doxygen-bootstrap.ok:
+ @echo "Checking whether dependencies for Doxygen are installed..."
ifeq ($(OS_ID),ubuntu)
- @sudo -E apt-get $(CONFIRM) $(FORCE) install $(DOC_DEB_DEPENDS)
+ @set -e; inst=; \
+ for i in $(DOC_DEB_DEPENDS); do \
+ dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \
+ done; \
+ if [ "$$inst" ]; then sudo apt-get $(CONFIRM) $(FORCE) install $$inst; fi
+ @if [ ! -s /usr/lib/graphviz/config6a ]; then \
+ echo "Rebuidlding system Graphviz configuration."; \
+ sudo dot -c; \
+ fi
else ifneq ("$(wildcard /etc/redhat-release)","")
@sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS)
else
.DELETE_ON_ERROR: $(BR)/.doxygen-siphon.dep
$(BR)/.doxygen-siphon.dep: Makefile
- set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \
+ @echo "Building siphon dependencies..."
+ @set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \
find "$(WS_ROOT)/$$input" -type f \
- \( -name '*.[ch]' -or -name '*.dox' \) \
- -print | sed -e "s/^/\$$(SIPHON_FILES): /" >> $@; \
+ \( -name '*.[ch]' -or -name '*.dox' \) -print \
+ | grep -v -E '^$(WS_ROOT)/$(DOXY_EXCLUDE_REGEXP)' \
+ | sed -e "s/^/\$$(SIPHON_FILES): /" \
+ >> $@; \
done
# Include the source -> siphon dependencies
$(SIPHON_FILES): $(DOXY_DIR)/siphon_generate.py $(BR)/.doxygen-bootstrap.ok
@rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
@mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
- set -e; for input in $(DOXY_INPUT); do \
+ @touch $(SIPHON_INPUT)/files
+ @echo "Collating source file list for siphoning..."
+ @for input in $(DOXY_INPUT); do \
cd "$(WS_ROOT)"; \
find "$$input" -type f \
- \( -name '*.[ch]' -or -name '*.dox' \) \
- -print >> $(SIPHON_INPUT)/files; \
+ \( -name '*.[ch]' -or -name '*.dox' \) -print \
+ | grep -v -E '^$(DOXY_EXCLUDE_REGEXP)' \
+ >> $(SIPHON_INPUT)/files; \
done
- set -e; cd "$(WS_ROOT)"; $(DOXY_DIR)/siphon_generate.py \
+ @echo "Generating siphons..."
+ @set -e; cd "$(WS_ROOT)"; $(DOXY_DIR)/siphon_generate.py \
--output="$(SIPHON_INPUT)" \
"@$(SIPHON_INPUT)/files"
.DELETE_ON_ERROR: $(SIPHON_DOCS)
$(SIPHON_OUTPUT)/%.md: $(SIPHON_INPUT)/%.siphon $(DOXY_DIR)/siphon_process.py
- set -e; cd "$(WS_ROOT)"; \
+ @echo "Processing siphon from $(notdir $<)..."
+ @set -e; cd "$(WS_ROOT)"; \
$(DOXY_DIR)/siphon_process.py --type=$(basename $(notdir $<)) \
--output="$(SIPHON_OUTPUT)" $< > $@
# Generate the doxygen docs
doxygen: $(SIPHON_DOCS)
@mkdir -p "$(DOXY_OUTPUT)"
+ @echo "Running Doxygen..."
set -e; cd "$(WS_ROOT)"; \
ROOT="$(WS_ROOT)" \
BUILD_ROOT="$(BR)" \
INPUT="$(addprefix $(WS_ROOT)/,$(DOXY_INPUT)) $(EXTRA_DOXY_INPUT)" \
+ INCLUDE_PATH="$(DOXY_INCLUDE_PATH)" \
+ EXCLUDE="$(DOXY_EXCLUDE)" \
HTML=YES \
VERSION="`git describe --tags --dirty`" \
doxygen $(DOXY_DIR)/doxygen.cfg
Code Review / vpp.git / blobdiff