# Copyright (c) 2016 Comcast Cable Communications Management, LLC. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at: # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # Build the documentation # # Default target .PHONY: all all: doxygen # These should be passed in by the root Makefile WS_ROOT ?= $(CURDIR)/.. BR ?= $(WS_ROOT)/build-root # We support MacOS for docs generation ifeq ($(shell uname),Darwin) OS_ID = darwin endif # Work out the OS if we haven't already OS_ID ?= $(shell grep '^ID=' /etc/os-release | cut -f2- -d= | sed -e 's/\"//g') # Package dependencies DOC_DEB_DEPENDS = doxygen graphviz python3-pyparsing python3-jinja2 DOC_RPM_DEPENDS = doxygen graphviz python3-pyparsing python3-jinja2 DOC_SUSE_RPM_DEPENDS = doxygen graphviz python3-pyparsing python3-Jinja2 DOC_MAC_BIN_DEPENDS = doxygen dot git DOC_MAC_PY_DEPENDS = pyparsing jinja2 # Doxygen configuration and our utility scripts DOXY_DIR ?= $(WS_ROOT)/doxygen # Primary source directories DOXY_SRC ?= $(WS_ROOT)/src DOXY_SRC_DIRECTORIES = \ $(shell find $(DOXY_SRC) -name '*.md' -print | xargs dirname \ | sort | uniq) \ $(DOXY_SRC)/vppinfra \ $(DOXY_SRC)/svm \ $(DOXY_SRC)/vlib \ $(DOXY_SRC)/vlibapi \ $(DOXY_SRC)/vlibmemory \ $(DOXY_SRC)/vnet \ $(DOXY_SRC)/vpp \ $(DOXY_SRC)/vpp-api \ $(DOXY_SRC)/examples # Input directories and files DOXY_INPUT ?= \ $(wildcard $(WS_ROOT)/*.md) \ $(wildcard $(DOXY_DIR)/*.md) \ $(DOXY_SRC_DIRECTORIES) \ $(DOXY_SRC)/plugins \ extras # 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 ?= \ $(DOXY_SRC)/vpp-api/lua # 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) # 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 &1 | awk 'f&&/^ /{print $$1} /^\#include/{f=1}') endif # Target directory for doxygen output DOXY_OUTPUT ?= $(BR)/docs # Siphoned fragments end up in here SIPHON_INPUT ?= $(DOXY_OUTPUT)/siphon_fragments # Siphoned fragements are processed into here SIPHON_OUTPUT ?= $(DOXY_OUTPUT)/siphon_docs # Extra document inputs that are processed in addition to DOXY_INPUT EXTRA_DOXY_INPUT += $(SIPHON_OUTPUT) # All the siphon types we know about SIPHONS ?= clicmd syscfg SIPHON_FILES = $(addprefix $(SIPHON_INPUT)/,$(addsuffix .siphon,$(SIPHONS))) SIPHON_DOCS = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .md,$(SIPHONS))) SIPHON_ITEMLIST = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .itemlist,$(filter clicmd,$(SIPHONS)))) $(BR)/.doxygen-bootstrap.ok: Makefile @echo "Checking whether dependencies for Doxygen are installed..." ifeq ($(OS_ID),ubuntu) @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 update; \ sudo apt-get $(CONFIRM) $(FORCE) install $$inst; \ fi @if [ ! -s /usr/lib/graphviz/config6a ]; then \ echo "Rebuilding system Graphviz configuration."; \ sudo dot -c; \ fi else ifneq ("$(wildcard /etc/redhat-release)","") @sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS) else ifeq ($(OS_ID),darwin) @set -e; \ for bin in $(DOC_MAC_BIN_DEPENDS); do \ which -s $${bin} || (\ echo "Program '$${bin}' not found, please install it."; \ false; \ ); \ done @set -e; \ for py in $(DOC_MAC_PY_DEPENDS); do \ python -c "import $${py}" >/dev/null 2>&1 || (\ echo "Python package '$${py}' not found, please install it."; \ false; \ ); \ done else ifeq ($(OS_ID),opensuse