mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-04 21:02:39 +00:00
f5f1b22c5a
The module processing logic in Zephyr requires Python, since it uses a Python script to locate and process the modules. It is therefore required to find the Python executable using CMake before actually including the CMake script that processes the modules. In order to prevent this from happening again, move the inclusion of version.cmake as well in case that script chooses to use Python in the future. Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
346 lines
11 KiB
CMake
346 lines
11 KiB
CMake
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
cmake_minimum_required(VERSION 3.13.1)
|
|
project(Zephyr-Kernel-Doc LANGUAGES)
|
|
|
|
# Find west to (optionally) process modules for Kconfig
|
|
find_program(
|
|
WEST
|
|
west
|
|
)
|
|
if(${WEST} STREQUAL WEST-NOTFOUND)
|
|
unset(WEST)
|
|
endif()
|
|
|
|
file(TO_CMAKE_PATH "$ENV{ZEPHYR_BASE}" ZEPHYR_BASE)
|
|
|
|
message(STATUS "Zephyr base: ${ZEPHYR_BASE}")
|
|
|
|
find_package(PythonInterp 3.4)
|
|
set(DOXYGEN_SKIP_DOT True)
|
|
find_package(Doxygen REQUIRED)
|
|
find_package(LATEX)
|
|
|
|
find_program(
|
|
SPHINXBUILD
|
|
NAMES sphinx-build-3 sphinx-build
|
|
)
|
|
if(${SPHINXBUILD} STREQUAL SPHINXBUILD-NOTFOUND)
|
|
message(FATAL_ERROR "The 'sphinx-build' command was not found. Make sure you have Sphinx installed.")
|
|
endif()
|
|
|
|
# Include version info
|
|
include(${ZEPHYR_BASE}/cmake/version.cmake)
|
|
# Process modules
|
|
include(${ZEPHYR_BASE}/cmake/zephyr_module.cmake)
|
|
|
|
# Note that this won't force fatal error if latexmk is not found.
|
|
# Not having LaTeX tools should not prevent people from generating HTML docs.
|
|
find_program(
|
|
LATEXMK
|
|
latexmk
|
|
)
|
|
if(${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
|
|
message(WARNING "The 'latexmk' command was not found. Targets to build PDF will not be available.")
|
|
endif()
|
|
|
|
if(NOT DEFINED SPHINXOPTS)
|
|
set(SPHINXOPTS -q)
|
|
else()
|
|
separate_arguments(SPHINXOPTS)
|
|
endif()
|
|
|
|
if(NOT DEFINED SPHINX_OUTPUT_DIR)
|
|
set(SPHINX_OUTPUT_DIR_HTML ${CMAKE_CURRENT_BINARY_DIR}/html)
|
|
set(SPHINX_OUTPUT_DIR_LATEX ${CMAKE_CURRENT_BINARY_DIR}/latex)
|
|
set(SPHINX_OUTPUT_DIR_PDF ${CMAKE_CURRENT_BINARY_DIR}/pdf)
|
|
else()
|
|
# SPHINX_OUTPUT_DIR is used to specify exactly where HTML (or other
|
|
# outputs) are placed, so no /html, /latex, /pdf suffixes are needed.
|
|
set(SPHINX_OUTPUT_DIR_HTML ${SPHINX_OUTPUT_DIR})
|
|
set(SPHINX_OUTPUT_DIR_LATEX ${SPHINX_OUTPUT_DIR})
|
|
set(SPHINX_OUTPUT_DIR_PDF ${SPHINX_OUTPUT_DIR})
|
|
endif()
|
|
|
|
if(NOT DEFINED DOC_TAG)
|
|
set(DOC_TAG development)
|
|
endif()
|
|
|
|
# Internal variables.
|
|
set(ALLSPHINXOPTS -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees ${SPHINXOPTS})
|
|
if("-q" IN_LIST ALLSPHINXOPTS)
|
|
set(SPHINX_USES_TERMINAL )
|
|
else()
|
|
set(SPHINX_USES_TERMINAL USES_TERMINAL)
|
|
endif()
|
|
|
|
# the i18n builder cannot share the environment and doctrees with the others
|
|
set(I18NSPHINXOPTS ${SPHINXOPTS})
|
|
|
|
set(DOXYFILE_IN ${CMAKE_CURRENT_LIST_DIR}/zephyr.doxyfile.in)
|
|
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/zephyr.doxyfile)
|
|
set(DOXY_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
|
|
set(RST_OUT ${CMAKE_CURRENT_BINARY_DIR}/rst)
|
|
set(DOC_LOG ${CMAKE_CURRENT_BINARY_DIR}/doc.log)
|
|
set(DOXY_LOG ${CMAKE_CURRENT_BINARY_DIR}/doxy.log)
|
|
set(SPHINX_LOG ${CMAKE_CURRENT_BINARY_DIR}/sphinx.log)
|
|
set(DOC_WARN ${CMAKE_CURRENT_BINARY_DIR}/doc.warnings)
|
|
set(CONTENT_OUTPUTS ${CMAKE_CURRENT_BINARY_DIR}/extracted-content.txt)
|
|
|
|
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
|
|
|
|
# This command is used to copy all documentation source files from the
|
|
# ZEPHYR_BASE/ environment variable into the build directory,
|
|
#
|
|
# We need to make copies because Sphinx requires a single
|
|
# documentation root directory, but Zephyr's documentation is
|
|
# scattered around the tree in samples/, boards/, and doc/. Putting
|
|
# them into a single rooted tree in the build directory is a
|
|
# workaround for this limitation.
|
|
set(EXTRACT_CONTENT_COMMAND
|
|
${CMAKE_COMMAND} -E env
|
|
ZEPHYR_BASE=${ZEPHYR_BASE}
|
|
${PYTHON_EXECUTABLE} scripts/extract_content.py
|
|
# Ignore any files in the output directory.
|
|
--ignore ${CMAKE_CURRENT_BINARY_DIR}
|
|
# Copy all files in doc to the rst folder.
|
|
"*:doc:${RST_OUT}"
|
|
# We want to copy the .rst files in samples/ and boards/ to the rst
|
|
# folder, and also the doc folder inside rst.
|
|
#
|
|
# Some files refer to items in samples/ and boards/ relative to
|
|
# their actual position in the Zephyr tree. For example, in
|
|
# subsystems/sensor.rst:
|
|
#
|
|
# .. literalinclude:: ../../samples/sensor/mcp9808/src/main.c
|
|
#
|
|
# The additional copy is a hackaround so these references work.
|
|
"*.rst:samples:${RST_OUT}" "*.rst:boards:${RST_OUT}"
|
|
"*.rst:samples:${RST_OUT}/doc" "*.rst:boards:${RST_OUT}/doc")
|
|
|
|
add_custom_target(
|
|
content
|
|
# Copy all files in doc/ to the rst folder
|
|
COMMAND ${EXTRACT_CONTENT_COMMAND}
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
|
|
COMMENT "Copying files to ${RST_OUT}"
|
|
)
|
|
|
|
# For incremental builds not to miss any source change this MUST be kept
|
|
# a superset of INPUT= and FILE_PATTERNS= in zephyr.doxyfile.in
|
|
file(GLOB_RECURSE DOXY_SOURCES
|
|
${ZEPHYR_BASE}/include/*.[c,h,S]
|
|
${ZEPHYR_BASE}/lib/libc/*.[c,h,S]
|
|
${ZEPHYR_BASE}/tests/*.[h,c,S]
|
|
)
|
|
# For debug. Also find generated list in doc/_build/(build.ninja|CMakeFiles/)
|
|
# message("DOXY_SOURCES= " ${DOXY_SOURCES})
|
|
|
|
set(ARGS ${DOXYFILE_OUT})
|
|
set(DOXY_RUN_TSTAMP ${CMAKE_CURRENT_BINARY_DIR}/last_doxy_run_tstamp)
|
|
|
|
|
|
# Create timestamp first so we re-run if source files are edited while
|
|
# doxygen is running
|
|
add_custom_command(
|
|
OUTPUT ${DOXY_RUN_TSTAMP}
|
|
COMMAND cmake -E touch ${DOXY_RUN_TSTAMP}
|
|
COMMAND ${CMAKE_COMMAND}
|
|
-DCOMMAND=${DOXYGEN_EXECUTABLE}
|
|
-DARGS="${ARGS}"
|
|
-DOUTPUT_FILE=${DOXY_LOG}
|
|
-DERROR_FILE=${DOXY_LOG}
|
|
-DWORKING_DIRECTORY=${CMAKE_CURRENT_LIST_DIR}
|
|
-P ${ZEPHYR_BASE}/cmake/util/execute_process.cmake
|
|
DEPENDS ${DOXY_SOURCES}
|
|
COMMENT "Running ${DOXYGEN_EXECUTABLE}"
|
|
)
|
|
|
|
# Doxygen doesn't support incremental builds.
|
|
# It could be ok because it's pretty fast.
|
|
# But it's not because it has a cascade effect on sphinx:
|
|
# https://sourceforge.net/p/doxygen/mailman/message/36580807/
|
|
# For now this optimization speeds-up non-doxygen documentation work
|
|
# only (by one order of magnitude).
|
|
add_custom_target(
|
|
doxy_real_modified_times
|
|
COMMAND ${CMAKE_COMMAND} -E env
|
|
${PYTHON_EXECUTABLE} scripts/restore_modification_times.py
|
|
--loglevel WARN ${DOXY_OUT}/xml
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
|
|
DEPENDS ${DOXY_RUN_TSTAMP}
|
|
COMMENT "Fixing modification times of ${DOXY_OUT}/xml/ output"
|
|
)
|
|
|
|
add_custom_target(
|
|
pristine
|
|
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/pristine.cmake
|
|
)
|
|
|
|
if(WIN32)
|
|
set(SEP ;)
|
|
else()
|
|
set(SEP :)
|
|
endif()
|
|
|
|
add_custom_target(
|
|
kconfig
|
|
COMMAND ${CMAKE_COMMAND} -E make_directory ${RST_OUT}/doc/reference/kconfig
|
|
COMMAND ${CMAKE_COMMAND} -E env
|
|
PYTHONPATH="${ZEPHYR_BASE}/scripts/kconfig${SEP}$ENV{PYTHONPATH}"
|
|
ZEPHYR_BASE=${ZEPHYR_BASE}
|
|
srctree=${ZEPHYR_BASE}
|
|
KERNELVERSION=${KERNELVERSION}
|
|
BOARD_DIR=boards/*/*/
|
|
ARCH=*
|
|
ARCH_DIR=arch/
|
|
SOC_DIR=soc/
|
|
SRCARCH=x86
|
|
CMAKE_BINARY_DIR=${CMAKE_BINARY_DIR}
|
|
KCONFIG_WARN_UNDEF=y
|
|
KCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE}
|
|
KCONFIG_DOC_MODE=1
|
|
${PYTHON_EXECUTABLE} scripts/genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
|
|
COMMENT "Running genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/"
|
|
)
|
|
|
|
set(KI_SCRIPT ${ZEPHYR_BASE}/scripts/filter-known-issues.py)
|
|
set(FIX_TEX_SCRIPT ${ZEPHYR_BASE}/doc/scripts/fix_tex.py)
|
|
set(CONF_DIR ${ZEPHYR_BASE}/.known-issues/doc)
|
|
|
|
#
|
|
# HTML section
|
|
#
|
|
set(SPHINX_BUILD_HTML_COMMAND
|
|
${CMAKE_COMMAND} -E env
|
|
ZEPHYR_BASE=${ZEPHYR_BASE}
|
|
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
|
|
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b html ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_HTML})
|
|
|
|
# The sphinx-html target is provided as a convenience for incremental
|
|
# re-builds of content files without regenerating the entire docs
|
|
# pipeline. It can be significantly faster than re-running the full
|
|
# HTML build, but it has no idea if Doxygen, Kconfig, etc. need to be
|
|
# regenerated. Use with caution.
|
|
add_custom_target(
|
|
sphinx-html
|
|
COMMAND ${SPHINX_BUILD_HTML_COMMAND}
|
|
DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
|
|
COMMENT "Just re-generating HTML (USE WITH CAUTION)"
|
|
USES_TERMINAL
|
|
)
|
|
|
|
# "breathe", the sphinx plugin that parses XML output from doxygen, has
|
|
# an "everything on everything" dependency issue reported at:
|
|
# https://github.com/michaeljones/breathe/issues/420 In other words
|
|
# changing 1 source file costs the same build time than changing all
|
|
# source files. breathe is fortunately smart enough not to run at all
|
|
# when *nothing* has changed.
|
|
add_custom_target(
|
|
html
|
|
COMMAND ${SPHINX_BUILD_HTML_COMMAND}
|
|
# Merge the Doxygen and Sphinx logs into a single file
|
|
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
|
|
COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONF_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
|
|
COMMENT "Generating HTML documentation with ${SPHINXBUILD} ${SPHINXOPTS}"
|
|
${SPHINX_USES_TERMINAL}
|
|
)
|
|
|
|
#
|
|
# LaTEX section
|
|
#
|
|
set(SPHINX_BUILD_LATEX_COMMAND
|
|
${CMAKE_COMMAND} -E env
|
|
ZEPHYR_BUILD=${CMAKE_CURRENT_BINARY_DIR}
|
|
${SPHINXBUILD} -w ${SPHINX_LOG} -N -t ${DOC_TAG} -b latex -t svgconvert ${ALLSPHINXOPTS} ${RST_OUT}/doc ${SPHINX_OUTPUT_DIR_LATEX})
|
|
|
|
# The sphinx-latex target works similarly to sphinx-html, and carries
|
|
# the same warnings.
|
|
add_custom_target(
|
|
sphinx-latex
|
|
COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
|
|
DEPENDS ${EXTRACT_CONTENT_OUTPUTS}
|
|
COMMENT "Just re-generating LaTeX (USE WITH CAUTION)"
|
|
USES_TERMINAL
|
|
)
|
|
|
|
add_custom_command(
|
|
OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
|
|
COMMAND ${SPHINX_BUILD_LATEX_COMMAND}
|
|
# Merge the Doxygen and Sphinx logs into a single file
|
|
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/util/fmerge.cmake ${DOC_LOG} ${DOXY_LOG} ${SPHINX_LOG}
|
|
COMMAND ${PYTHON_EXECUTABLE} ${KI_SCRIPT} --config-dir ${CONF_DIR} --errors ${DOC_WARN} --warnings ${DOC_WARN} ${DOC_LOG}
|
|
COMMAND ${PYTHON_EXECUTABLE} ${FIX_TEX_SCRIPT} ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
|
|
COMMENT "Generating LaTeX documentation"
|
|
${SPHINX_USES_TERMINAL}
|
|
)
|
|
|
|
add_custom_target(
|
|
latex
|
|
DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
|
|
)
|
|
|
|
#
|
|
# PDF section
|
|
#
|
|
if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
|
|
|
|
add_custom_command(
|
|
OUTPUT ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
|
|
DEPENDS latexdocs ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.tex
|
|
COMMAND ${CMAKE_COMMAND} -E env
|
|
LATEXOPTS="-halt-on-error -no-shell-escape"
|
|
${LATEXMK} -quiet -pdf -dvi- -ps-
|
|
WORKING_DIRECTORY ${SPHINX_OUTPUT_DIR_LATEX}
|
|
COMMENT "Generating PDF documentation"
|
|
)
|
|
|
|
if(NOT DEFINED SPHINX_OUTPUT_DIR)
|
|
# Although latexmk allows specifying output directory,
|
|
# makeindex fails if one is specified.
|
|
# Hence the need of this to copy the PDF file over.
|
|
add_custom_command(
|
|
OUTPUT ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
|
|
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR_PDF}
|
|
COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
|
|
DEPENDS ${SPHINX_OUTPUT_DIR_LATEX}/zephyr.pdf
|
|
)
|
|
endif()
|
|
|
|
add_custom_target(
|
|
pdf
|
|
DEPENDS ${SPHINX_OUTPUT_DIR_PDF}/zephyr.pdf
|
|
)
|
|
|
|
endif()
|
|
|
|
#
|
|
# Dependencies and final targets
|
|
#
|
|
add_dependencies(html content doxy_real_modified_times kconfig)
|
|
|
|
add_custom_target(
|
|
htmldocs
|
|
)
|
|
add_dependencies(htmldocs html)
|
|
|
|
add_dependencies(latex content doxy_real_modified_times kconfig)
|
|
|
|
add_custom_target(
|
|
latexdocs
|
|
)
|
|
add_dependencies(latexdocs latex)
|
|
|
|
if(NOT ${LATEXMK} STREQUAL LATEXMK-NOTFOUND)
|
|
|
|
add_custom_target(
|
|
pdfdocs
|
|
DEPENDS latexdocs pdf
|
|
)
|
|
add_dependencies(pdfdocs pdf)
|
|
|
|
endif()
|