Makefile revision 440cde68
1# Copyright (c) 2016 Comcast Cable Communications Management, LLC.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at:
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15#
16# Build the documentation
17#
18
19# These should be passed in by the root Makefile
20WS_ROOT ?= $(CURDIR)/..
21BR ?= $(WS_ROOT)/build-root
22OS_ID ?= $(shell grep '^ID=' /etc/os-release | cut -f2- -d= | sed -e 's/\"//g')
23
24# Package dependencies
25DOC_DEB_DEPENDS = doxygen graphviz python-pyparsing
26DOC_RPM_DEPENDS = doxygen graphviz pyparsing
27
28# Doxygen configuration and our utility scripts
29DOXY_DIR ?= $(WS_ROOT)/doxygen
30
31# Primary source directories
32DOXY_SRC_DIRECTORIES = \
33	nsh-plugin/build \
34	nsh-plugin/java \
35	nsh-plugin/nsh \
36	nsh-plugin/vpp-api
37
38# Input directories and files
39DOXY_INPUT ?= \
40	README.md \
41	nsh-plugin/README.md \
42	$(DOXY_SRC_DIRECTORIES)
43# nsh-plugin/build/nsh/nsh.api.h \
44
45# Files to exclude, from pre-Doxygen steps, eg because they're
46# selectively compiled.
47# Examples would be to exclude non-DPDK related sources when
48# there's a DPDK equivalent that conflicts.
49# These must be left-anchored paths for the regexp below to work.
50DOXY_EXCLUDE ?= \
51	nsh-plugin/build/java \
52	nsh-plugin/build/nsh \
53	nsh-plugin/build/vpp-api
54
55
56# Generate a regexp for filenames to exclude
57DOXY_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_EXCLUDE))' | sed -e 's/ /|/g')))
58
59# Include all the normal source directories in the include file path
60DOXY_INCLUDE_PATH = $(DOXY_SRC_DIRECTORIES)
61
62# Also include any plugin directories that exist
63#DOXY_INCLUDE_PATH += \
64#	$(shell find $(WS_ROOT)/plugins -maxdepth 1 -type d | sed -e 's@^$(WS_ROOT)/*@@')
65
66# Find API header directories and include them in the header path.
67# This is only useful if VPP and plugins are already built; nothing
68# here depends on those targets. We don't build documentation for these
69# header files, they're just added to the INCLUDE search path for Doxygen.
70#_vpp_br = $(shell find "$(BR)" -maxdepth 1 -type d \
71#	'(' -name build-vpp_debug-native -o -name build-vpp-native ')' -print \
72#	| sed -e 's@^$(WS_ROOT)/*@@' -e 1q)
73#ifneq ($(strip $(_vpp_br)),)
74#DOXY_INCLUDE_PATH += \
75#	$(_vpp_br)/vlib-api \
76#	$(_vpp_br)/vpp
77# Also include any plugin directories that exist
78#DOXY_INCLUDE_PATH += \
79#	$(shell find $(WS_ROOT)/$(_vpp_br)/plugins -maxdepth 1 -type d | sed -e 's@^$(WS_ROOT)/*@@')
80#endif
81
82# Discover if we have CPP available
83_cpp = $(shell which cpp)
84ifneq ($(strip $(_cpp)),)
85# Add whatever directories CPP normally includes to the header path
86DOXY_INCLUDE_PATH += $(shell set -e; $(_cpp) -v </dev/null 2>&1 | awk 'f&&/^ /{print $$1} /^\#include/{f=1}')
87endif
88
89# Target directory for doxygen output
90DOXY_OUTPUT ?= $(BR)/docs
91
92# Siphoned fragments end up in here
93SIPHON_INPUT ?= $(DOXY_OUTPUT)/siphon_fragments
94
95# Siphoned fragements are processed into here
96SIPHON_OUTPUT ?= $(DOXY_OUTPUT)/siphon_docs
97
98# Extra document inputs that are processed in addition to DOXY_INPUT
99EXTRA_DOXY_INPUT += $(SIPHON_OUTPUT)
100
101# All the siphon types we know about
102SIPHONS ?= clicmd
103
104SIPHON_FILES = $(addprefix $(SIPHON_INPUT)/,$(addsuffix .siphon,$(SIPHONS)))
105SIPHON_DOCS = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .md,$(SIPHONS)))
106
107$(BR)/.doxygen-bootstrap.ok:
108	@echo "Checking whether dependencies for Doxygen are installed..."
109ifeq ($(OS_ID),ubuntu)
110	@set -e; inst=; \
111		for i in $(DOC_DEB_DEPENDS); do \
112			dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \
113		done; \
114		if [ "$$inst" ]; then sudo apt-get $(CONFIRM) $(FORCE) install $$inst; fi
115	@if [ ! -s /usr/lib/graphviz/config6a ]; then \
116		echo "Rebuidlding system Graphviz configuration."; \
117		sudo dot -c; \
118	fi
119else ifneq ("$(wildcard /etc/redhat-release)","")
120	@sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS)
121else
122	$(error "This option currently works only on Ubuntu or Centos systems")
123endif
124	@touch $@
125
126.PHONY: bootstrap-doxygen
127bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok
128
129.DELETE_ON_ERROR: $(BR)/.doxygen-siphon.dep
130$(BR)/.doxygen-siphon.dep: Makefile
131	@echo "Building siphon dependencies..."
132	@set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \
133		find "$(WS_ROOT)/$$input" -type f \
134			\( -name '*.[ch]' -or -name '*.dox' \) -print \
135			| grep -v -E '^$(WS_ROOT)/$(DOXY_EXCLUDE_REGEXP)' \
136			| sed -e "s/^/\$$(SIPHON_FILES): /" \
137			>> $@; \
138	done
139
140# Include the source -> siphon dependencies
141-include $(BR)/.doxygen-siphon.dep
142
143.NOTPARALLEL: $(SIPHON_FILES)
144$(SIPHON_FILES): $(DOXY_DIR)/siphon_generate.py $(BR)/.doxygen-bootstrap.ok
145	@rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
146	@mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
147	@touch $(SIPHON_INPUT)/files
148	@echo "Collating source file list for siphoning..."
149	@for input in $(DOXY_INPUT); do \
150		cd "$(WS_ROOT)"; \
151		find "$$input" -type f \
152			\( -name '*.[ch]' -or -name '*.dox' \) -print \
153			| grep -v -E '^$(DOXY_EXCLUDE_REGEXP)' \
154			>> $(SIPHON_INPUT)/files; \
155	done
156	@echo "Generating siphons..."
157	@set -e; cd "$(WS_ROOT)"; $(DOXY_DIR)/siphon_generate.py \
158		--output="$(SIPHON_INPUT)" \
159		"@$(SIPHON_INPUT)/files"
160
161
162.DELETE_ON_ERROR: $(SIPHON_DOCS)
163$(SIPHON_OUTPUT)/%.md: $(SIPHON_INPUT)/%.siphon $(DOXY_DIR)/siphon_process.py
164	@echo "Processing siphon from $(notdir $<)..."
165	@set -e; cd "$(WS_ROOT)"; \
166		$(DOXY_DIR)/siphon_process.py --type=$(basename $(notdir $<)) \
167			--output="$(SIPHON_OUTPUT)" $< > $@
168
169# This target can be used just to generate the siphoned docs
170.PHONY: doxygen-siphon
171doxygen-siphon: $(SIPHON_DOCS)
172
173# Generate the doxygen docs
174doxygen: $(SIPHON_DOCS)
175	@mkdir -p "$(DOXY_OUTPUT)"
176	@echo "Running Doxygen..."
177	set -e; cd "$(WS_ROOT)"; \
178	    ROOT="$(WS_ROOT)" \
179	    BUILD_ROOT="$(BR)" \
180	    INPUT="$(addprefix $(WS_ROOT)/,$(DOXY_INPUT)) $(EXTRA_DOXY_INPUT)" \
181	    INCLUDE_PATH="$(DOXY_INCLUDE_PATH)" \
182	    EXCLUDE="$(DOXY_EXCLUDE)" \
183	    HTML=YES \
184	    VERSION="`git describe --tags --dirty`" \
185	    doxygen $(DOXY_DIR)/doxygen.cfg
186
187wipe-doxygen:
188	rm -rf "$(BR)/docs" "$(BR)/.doxygen-siphon.d"
189
190