diff options
Diffstat (limited to 'doxygen/Makefile')
| -rw-r--r-- | doxygen/Makefile | 270 |
1 files changed, 0 insertions, 270 deletions
diff --git a/doxygen/Makefile b/doxygen/Makefile deleted file mode 100644 index e399b404a26..00000000000 --- a/doxygen/Makefile +++ /dev/null @@ -1,270 +0,0 @@ -# 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_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 </dev/null 2>&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 - $(error "Building documentation currently works only on Ubuntu, CentOS, MacOS and OpenSUSE systems.") -endif - @touch $@ - -.PHONY: bootstrap-doxygen -bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok - -.DELETE_ON_ERROR: $(BR)/.doxygen-siphon.dep -$(BR)/.doxygen-siphon.dep: Makefile \ - $(addprefix,$(WSROOT),$(DOXY_INPUT)) - @echo "Building siphon dependencies..." - @rm -f "$@"; for input in $(DOXY_INPUT); do \ - [ -e "$(WS_ROOT)/$$input" ] && \ - find "$(WS_ROOT)/$$input" -type f \ - \( -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 --include $(BR)/.doxygen-siphon.dep - -# Generate .siphon files that contain fragments of source file that -# relate to the siphons we support. -.NOTPARALLEL: $(SIPHON_FILES) -$(SIPHON_FILES): $(BR)/.doxygen-bootstrap.ok \ - $(DOXY_DIR)/siphon-generate \ - $(addprefix,$(WSROOT),$(DOXY_INPUT)) \ - $(wildcard $(DOXY_DIR)/siphon/*.py) - @echo "Validating source tree..." - @set -e; for input in $(DOXY_INPUT); do \ - if [ ! -e "$(WS_ROOT)/$$input" ]; then \ - echo "ERROR: Input path '$$input' does not exist." >&2; \ - exit 1; \ - fi; \ - done - @rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)" - @mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)" - @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 \ - | grep -v -E '^src/examples/' \ - | grep -v -E '^$(DOXY_EXCLUDE_REGEXP)' \ - >> $(SIPHON_INPUT)/files; \ - done - @echo "Generating siphons..." - @set -e; \ - cd "$(WS_ROOT)"; \ - $(DOXY_DIR)/siphon-generate \ - --output="$(SIPHON_INPUT)" \ - "@$(SIPHON_INPUT)/files" - -# Evaluate this to build a siphon doc output target for each desired -# output type: -# $(eval $(call siphon-process,file_extension,output_type_name)) -define siphon-process -$(SIPHON_OUTPUT)/%.$(1): $(SIPHON_INPUT)/%.siphon \ - $(DOXY_DIR)/siphon-process \ - $(wildcard $(DOXY_DIR)/siphon/*.py) \ - $(wildcard $(DOXY_DIR)/siphon_templates/$(2)/*/*.$(1)) - @echo "Processing siphon for $(2) from $$(notdir $$<)..." - @set -e; \ - cd "$(WS_ROOT)"; \ - $(DOXY_DIR)/siphon-process \ - --type=$$(basename $$(notdir $$<)) \ - --format=$(2) \ - --output="$$@" \ - "$$<" -endef - -# Process the .siphon source fragments and render them into doxygen flavored -# markdown documentation -.DELETE_ON_ERROR: $(SIPHON_DOCS) -$(eval $(call siphon-process,md,markdown)) - -# Process the .siphon source fragments and render them into a list of cli -# commands. -.DELETE_ON_ERROR: $(SIPHON_ITEMLIST) -$(eval $(call siphon-process,itemlist,itemlist)) - -# This target can be used just to generate the siphoned things -.PHONY: doxygen-siphon -doxygen-siphon: $(SIPHON_DOCS) $(SIPHON_ITEMLIST) - -# Generate the doxygen docs -.PHONY: doxygen -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 - -.PHONY: wipe-doxygen -wipe-doxygen: - @rm -rf $(BR)/docs - @rm -rf $(BR)/.doxygen-siphon.dep - @rm -rf $(BR)/.doxygen-bootstrap.ok - @rm -rf $(DOXY_DIR)/siphon/__pycache__ - -.PHONY: clean -clean: wipe-doxygen |