Build: Convert docs directory to modern cmake
Add cmake files to docs directory. Remove unneeded cmake files.
By default, the targets are generated but not run by `make all` or
`make`. The documentation can be generated by running `make docs`
Please refer to the tfm_build_instructions document for
reference examples.
WARNING: This change will not build in isolation, it requires _all_
other cmake changes to successfully build. It is split out only for ease
of understanding.
Change-Id: I1b004a8f8ccfba2df901d91b093576fdc6bfa40d
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
Signed-off-by: Raef Coles <raef.coles@arm.com>
diff --git a/CMakeLists.txt b/CMakeLists.txt
index d629418..68730c0 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -20,12 +20,6 @@
set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Build type: [Debug, Release, RelWithDebInfo, MinSizeRel]" FORCE)
endif()
-message(FATAL_ERROR "This commit is inside the patch chain for convertion of the
-old cmake buildsystem to the modern one. TFM will not build unless all of these
-patches have been applied, these commits are split only for ease of
-understanding. If you wish to build TFM, please checkout the commit
-\"Build: Convert docs directory to modern cmake\"")
-
############################ CONFIGURATION #####################################
# First load defaults.
@@ -61,6 +55,7 @@
add_subdirectory(lib/ext)
add_subdirectory(tools)
+add_subdirectory(docs)
if(NS)
# Set to ${TFM_TEST_REPO_PATH}/app by default
add_subdirectory(${TFM_APP_PATH} ${CMAKE_CURRENT_BINARY_DIR}/app)
diff --git a/cmake/Common/BuildDoxygenDoc.cmake b/cmake/Common/BuildDoxygenDoc.cmake
deleted file mode 100644
index d1b7cb0..0000000
--- a/cmake/Common/BuildDoxygenDoc.cmake
+++ /dev/null
@@ -1,167 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2018-2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-#This file adds build and install targets to build the Doxygen documentation
-#for TF-M. This currently means the "Reference Manual". Further documentation
-#builds may be added in the future.
-
-Include(CMakeParseArguments)
-
-#This function will find the location of tools needed to build the
-#documentation. These are:
-# - Mandatory:
-# - Doxygen v1.8.0 or higher
-# - dot
-# - PlantUML and it's dependencies
-# - Optional
-# - LateX/PDFLateX
-#
-#Inputs:
-# none (some global variables might be used by FindXXX modules used. For
-# details please check the used modules.)
-#
-#Outputs:
-# NODOC - will be defined and set to true is any mandatory
-# tool is missing.
-# LATEX_PDFLATEX_FOUND - defined if PDFLateX is available.
-# DOXYGEN_EXECUTABLE - path to doxygen
-# DOXYGEN_DOT_EXECUTABLE - path to dot
-# PLANTUML_JAR_PATH - path to PlantUML
-
-#Examples
-# DoxyFindTools()
-#
-function(DoxyFindTools)
- #Find doxygen and dot.
- find_package(Doxygen 1.8.0)
- #find_package(Doxygen) will not print an error if dot is not available,
- #emit a message here to help users.
- if (NOT DOXYGEN_DOT_FOUND)
- message(STATUS "Could NOT find Graphviz (missing: DOXYGEN_DOT_EXECUTABLE).")
- endif()
-
- #Find plantUML
- find_package(PlantUML)
-
- #Find tools needed for PDF generation.
- find_package(LATEX COMPONENTS PDFLATEX)
- set (LATEX_PDFLATEX_FOUND ${LATEX_PDFLATEX_FOUND} PARENT_SCOPE)
-
- if (DOXYGEN_FOUND AND DOXYGEN_DOT_FOUND AND PLANTUML_FOUND)
- #Export executable locations to global scope.
- set(DOXYGEN_EXECUTABLE "${DOXYGEN_EXECUTABLE}" PARENT_SCOPE)
- set(DOXYGEN_DOT_EXECUTABLE "${DOXYGEN_DOT_EXECUTABLE}" PARENT_SCOPE)
- set(PLANTUML_JAR_PATH "${PLANTUML_JAR_PATH}" PARENT_SCOPE)
- set(NODOC False PARENT_SCOPE)
- else()
- message(WARNING "Some tools are missing for document generation. Document generation target is not created.")
- set(NODOC True PARENT_SCOPE)
- endif()
-endfunction()
-
-#Find the needed tools.
-DoxyFindTools()
-
-#If mandatory tools are missing, skip creating document generation targets.
-#This means missing documentation tools is not a crytical error, and building
-#TF-M is still possible.
-if (NOT NODOC)
- #The doxygen configuration file needs some project specific configuration.
- #Variables with DOXYCFG_ prefix are settings related to that.
- set(DOXYCFG_TEMPLATE_FILE ${TFM_ROOT_DIR}/doxygen/Doxyfile.in)
- set(DOXYCFG_CONFIGURED_FILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-
- #This is where doxygen output will be written
- set(DOXYCFG_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}/doc")
-
- #Eclipse help ID. The help files shall be installed under the plugin
- #directory into a directory with a name matching this ID.
- set(DOXYCFG_ECLIPSE_DOCID "org.arm.tf-m-refman")
-
- #Version ID of TF-M.
- #TODO: this shall not be hard-coded here. A process need to defined for
- # versioning the document (and TF-M).
- set(DOXYCFG_TFM_VERSION "v1.1")
-
- #Using add_custom_command allows CMake to generate proper clean commands
- #for document generation.
- add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/doc"
- COMMAND "${DOXYGEN_EXECUTABLE}" "${DOXYCFG_CONFIGURED_FILE}"
- WORKING_DIRECTORY "${TFM_ROOT_DIR}"
- COMMENT "Running doxygen.")
-
- #Create build target to generate HTML documentation.
- add_custom_target(doc_refman
- WORKING_DIRECTORY ${TFM_ROOT_DIR}
- COMMENT "Generating TF-M Reference Manual..."
- DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/doc"
- VERBATIM)
-
- #Add the HTML documentation to install content
- install(DIRECTORY ${DOXYCFG_OUTPUT_PATH}/html DESTINATION doc/reference_manual
- COMPONENT refman EXCLUDE_FROM_ALL)
-
- #Add the HTML documentation to install content. This time to be copied to
- #eclipse plugin directory.
- #TODO: I could not find a working description how the doxygen output
- #can be installed to eclipse. Re-enable eclipse help generation after
- #this is investigated. (See Doxyfile.in::GENERATE_ECLIPSEHELP)
-
- #install(DIRECTORY "${DOXYCFG_OUTPUT_PATH}/html/"
- # DESTINATION "doc/reference_manual/${DOXYCFG_ECLIPSE_DOCID}"
- # COMPONENT refman
- # EXCLUDE_FROM_ALL)
-
- #If PDF documentation is being made.
- if (LATEX_PDFLATEX_FOUND)
- if (NOT CMAKE_GENERATOR MATCHES "Makefiles")
- message(WARNING "Generator is not make based. PDF document generation target is not created.")
- else()
- #This file shall not be included before cmake did finish finding the make tool and thus
- #setting CMAKE_MAKE_PROGRAM. Currently the search is triggered by the project() command.
- if(NOT CMAKE_MAKE_PROGRAM)
- message(FATAL_ERROR "CMAKE_MAKE_PROGRAM is not set. This file must be included after the project command is run.")
- endif()
-
- #The add_custom_command is not used here to get proper clean
- #command since the clean rules "added" above will remove the entire
- #doc directory, and thus clean the PDF output too.
- add_custom_target(doc_refman_pdf
- COMMAND "${CMAKE_MAKE_PROGRAM}" pdf
- WORKING_DIRECTORY ${DOXYCFG_OUTPUT_PATH}/latex
- COMMENT "Generating PDF version of TF-M reference manual..."
- DEPENDS doc_refman
- VERBATIM)
-
- #Add the pdf documentation to install content
- install(FILES "${DOXYCFG_OUTPUT_PATH}/latex/refman.pdf" DESTINATION "doc/reference_manual"
- RENAME "tf-m_reference_manual.pdf"
- COMPONENT refman EXCLUDE_FROM_ALL)
-
- set(DOXYCFG_TFM_GENERATE_PDF $(DOXYCFG_TFM_VERSION))
- endif()
- else()
- message(WARNING "PDF generation tools are missing. PDF document generation target is not created.")
- endif()
-
- #Generate build target which installs the documentation.
- if (TARGET doc_refman_pdf)
- add_custom_target(install_doc
- DEPENDS doc_refman doc_refman_pdf
- COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=refman
- -P "${CMAKE_BINARY_DIR}/cmake_install.cmake")
- else()
- add_custom_target(install_doc
- DEPENDS doc_refman
- COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=refman
- -P "${CMAKE_BINARY_DIR}/cmake_install.cmake")
- endif()
-
- #Now instantiate a doxygen configuration file from the template.
- message(STATUS "Writing doxygen configuration...")
- configure_file(${DOXYCFG_TEMPLATE_FILE} ${DOXYCFG_CONFIGURED_FILE} @ONLY)
-endif()
diff --git a/cmake/Common/BuildSphinxDoc.cmake b/cmake/Common/BuildSphinxDoc.cmake
deleted file mode 100644
index e95a927..0000000
--- a/cmake/Common/BuildSphinxDoc.cmake
+++ /dev/null
@@ -1,211 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2019-2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-#This file adds build and install targets to build the Sphinx documentation
-#for TF-M. This currently means the "User Guide". Further documentation
-#builds may be added in the future.
-
-Include(CMakeParseArguments)
-
-#This function will find the location of tools needed to build the
-#documentation. These are:
-# - Mandatory:
-# - Sphinx 1.9.0 or higher
-# - PlantUML and it's dependencies
-# - Optional
-# - LateX/PDFLateX
-#
-#Inputs:
-# none (some global variables might be used by FindXXX modules used. For
-# details please check the modules used.)
-#Outputs:
-# SPHINX_NODOC - will be defined and set to true is any mandatory tool is
-# missing.
-# LATEX_PDFLATEX_FOUND - true if pdflatex executable found
-# SPHINX_EXECUTABLE - path to sphinx-build
-# PLANTUML_JAR_PATH - path to PlantUML
-
-#Examples
-# SphinxFindTools()
-#
-function(SphinxFindTools)
- #Find Sphinx
- find_package(Sphinx)
-
- #Find additional needed Sphinx dependencies.
- find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme sphinxcontrib.plantuml)
-
- #Find plantUML
- find_package(PlantUML)
-
- #Find tools needed for PDF generation.
- find_package(LATEX COMPONENTS PDFLATEX)
- set (LATEX_PDFLATEX_FOUND "${LATEX_PDFLATEX_FOUND}" PARENT_SCOPE)
-
- if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R_FOUND
- AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
- #Export executable locations to global scope.
- set(SPHINX_EXECUTABLE "${SPHINX_EXECUTABLE}" PARENT_SCOPE)
- set(PLANTUML_JAR_PATH "${PLANTUML_JAR_PATH}" PARENT_SCOPE)
- set(Java_JAVA_EXECUTABLE "${Java_JAVA_EXECUTABLE}" PARENT_SCOPE)
- set(SPHINX_NODOC False PARENT_SCOPE)
- else()
- message(WARNING "Some tools are missing for Sphinx document generation. Document generation target is not created.")
- set(SPHINX_NODOC True PARENT_SCOPE)
- endif()
-endfunction()
-
-#Find the needed tools.
-SphinxFindTools()
-
-#If mandatory tools are missing, skip creating document generation targets.
-#This means missing documentation tools is not a critical error, and building
-#TF-M is still possible.
-if (NOT SPHINX_NODOC)
- #The Sphinx configuration file needs some project specific configuration.
- #Variables with SPHINXCFG_ prefix are setting values related to that.
- #This is where Sphinx output will be written
- set(SPHINXCFG_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}/doc_sphinx")
-
- set(SPHINX_TMP_DOC_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc_sphinx_in")
- set(SPHINXCFG_CONFIGURED_FILE "${TFM_ROOT_DIR}/build_docs/conf.py")
- set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/conf.py.in")
- set(SPHINXCFG_ENVIRONMENT_FILE "${TFM_ROOT_DIR}/docs/tfm_env.py.in")
- set(_PDF_FILE "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf")
-
- # Set the build-tool to copy over the files to ${SPHINX_TMP_DOC_DIR~
- set(SPHINXCFG_COPY_FILES True)
- # Set the config to render the conf.py. If needed to build it by cmake
- # set it to False
- set(SPHINXCFG_RENDER_CONF True)
-
- # TODO Reference example on how a doxygen build can be requested.
- # Currently the logic of BuildDoxygenDoc.cmake is still used for
- # compatibility purposes.
- set(DOXYCFG_DOXYGEN_BUILD False)
- if (SPHINXCFG_RENDER_CONF)
- find_package(Doxygen 1.8.0)
- set(DOXYCFG_DOXYGEN_CFG_DIR ${TFM_ROOT_DIR}/doxygen)
- set(DOXYCFG_OUTPUT_PATH ${SPHINXCFG_OUTPUT_PATH}/user_manual)
- set(DOXYCFG_ECLIPSE_DOCID "org.arm.tf-m-refman")
- file(MAKE_DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/user_manual)
- endif()
-
- #Version ID of TF-M.
- #TODO: this shall not be hard-coded here. We need a process to define the
- # version number of the document (and TF-M).
- set(SPHINXCFG_TFM_VERSION "v1.1")
- set(SPHINXCFG_TFM_VERSION_FULL "Version 1.1")
-
- #This command does not generates the specified output file and thus it will
- #always be run. Any other command or target depending on the "run-allways"
- #output will be always executed too.
- add_custom_command(OUTPUT run-allways
- COMMAND "${CMAKE_COMMAND}" -E echo)
-
- file(REMOVE_RECURSE ${SPHINX_TMP_DOC_DIR})
- file(MAKE_DIRECTORY ${SPHINX_TMP_DOC_DIR})
-
- #Call configure file to fill out the message template.
- configure_file("${SPHINXCFG_ENVIRONMENT_FILE}" "${SPHINX_TMP_DOC_DIR}/tfm_env.py" @ONLY)
-
- file(COPY "${SPHINXCFG_CONFIGURED_FILE}" DESTINATION ${SPHINX_TMP_DOC_DIR})
-
- add_custom_target(create_sphinx_input
- SOURCES "${SPHINX_TMP_DOC_DIR}"
- )
-
- add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html"
- COMMAND "${SPHINX_EXECUTABLE}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
- WORKING_DIRECTORY "${TFM_ROOT_DIR}"
- DEPENDS create_sphinx_input run-allways
- COMMENT "Running Sphinx to generate user guide (HTML)."
- VERBATIM
- )
-
- #Create build target to generate HTML documentation.
- add_custom_target(doc_userguide
- COMMENT "Generating User Guide with Sphinx..."
- #Copy document files from the top level dir to docs
- SOURCES "${SPHINXCFG_OUTPUT_PATH}/html"
- )
-
- #Add the HTML documentation to install content
- install(DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/html DESTINATION doc/user_guide
- EXCLUDE_FROM_ALL
- COMPONENT user_guide
- PATTERN .buildinfo EXCLUDE
- )
-
- if (DOXYCFG_DOXYGEN_BUILD)
- #Add the HTML documentation to install content
- install(DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/user_manual DESTINATION doc
- EXCLUDE_FROM_ALL
- COMPONENT user_guide
- PATTERN .buildinfo EXCLUDE
- )
- endif()
-
- #If PDF documentation is being made.
- if (LATEX_PDFLATEX_FOUND)
- if (NOT CMAKE_GENERATOR MATCHES "Makefiles")
- message(WARNING "Generator is not make based. PDF document generation target is not created.")
- else()
- #This file shall not be included before cmake did finish finding the make tool and thus
- #setting CMAKE_MAKE_PROGRAM. Currently the search is triggered by the project() command.
- if(NOT CMAKE_MAKE_PROGRAM)
- message(FATAL_ERROR "CMAKE_MAKE_PROGRAM is not set. This file must be included after the project command is run.")
- endif()
-
- add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex"
- COMMAND "${SPHINX_EXECUTABLE}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex"
- WORKING_DIRECTORY "${TFM_ROOT_DIR}"
- DEPENDS create_sphinx_input
- COMMENT "Running Sphinx to generate user guide (LaTeX)."
- VERBATIM
- )
-
- add_custom_command(OUTPUT "${_PDF_FILE}"
- COMMAND "${CMAKE_MAKE_PROGRAM}" all-pdf
- WORKING_DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/latex
- DEPENDS "${SPHINXCFG_OUTPUT_PATH}/latex"
- COMMENT "Generating PDF version of User Guide..."
- VERBATIM
- )
-
- #We do not use the add_custom_command trick here to get proper clean
- #command since the clean rules "added" above will remove the entire
- #doc directory, and thus clean the PDF output too.
- add_custom_target(doc_userguide_pdf
- COMMENT "Generating PDF version of TF-M User Guide..."
- SOURCES "${_PDF_FILE}"
- VERBATIM)
-
- #Add the pdf documentation to install content
- install(FILES "${_PDF_FILE}" DESTINATION "doc/user_guide"
- RENAME "tf-m_user_guide.pdf"
- COMPONENT user_guide
- EXCLUDE_FROM_ALL)
- endif()
- else()
- message(WARNING "PDF generation tools are missing. PDF document generation target is not created.")
- endif()
-
- #Generate build target which installs the documentation.
- if (TARGET doc_userguide_pdf)
- add_custom_target(install_userguide
- DEPENDS doc_userguide doc_userguide_pdf
- COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=user_guide
- -P "${CMAKE_BINARY_DIR}/cmake_install.cmake")
- else()
- add_custom_target(install_userguide
- DEPENDS doc_userguide
- COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=user_guide
- -P "${CMAKE_BINARY_DIR}/cmake_install.cmake")
- endif()
-
-endif()
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
new file mode 100644
index 0000000..f227c6e
--- /dev/null
+++ b/docs/CMakeLists.txt
@@ -0,0 +1,118 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2020, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+cmake_minimum_required(VERSION 3.13)
+
+add_custom_target(docs)
+
+find_package(Python3)
+find_package(Sphinx)
+find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme sphinxcontrib.plantuml)
+find_package(PlantUML)
+find_package(Doxygen 1.8.0)
+find_package(LATEX COMPONENTS PDFLATEX)
+
+################################## ENV #########################################
+
+set(SPHINXCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/user_guide)
+set(SPHINX_TMP_DOC_DIR ${CMAKE_CURRENT_BINARY_DIR}/temp)
+set(SPHINXCFG_TEMPLATE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in")
+set(DOXYCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/reference_manual)
+set(DOXYCFG_DOXYGEN_CFG_DIR ${CMAKE_SOURCE_DIR}/doxygen)
+
+# Enable to request the interface to build the doxygen documentation as well
+set(DOXYCFG_DOXYGEN_BUILD False)
+
+################################## SPHINX ######################################
+set(SPHINXCFG_COPY_FILES True)
+set(SPHINXCFG_RENDER_CONF True)
+
+add_custom_target(tfm_docs_sphinx_cfg
+ DEPENDS ${SPHINX_TMP_DOC_DIR}/conf.py
+)
+add_custom_command(OUTPUT ${SPHINX_TMP_DOC_DIR}/conf.py
+ COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_TMP_DOC_DIR}
+ COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/build_docs/conf.py ${SPHINX_TMP_DOC_DIR}/conf.py
+ MAIN_DEPENDENCY ${CMAKE_SOURCE_DIR}/build_docs/conf.py
+ BYPRODUCTS ${SPHINX_TMP_DOC_DIR}
+)
+
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/tfm_env.py.in ${SPHINX_TMP_DOC_DIR}/tfm_env.py @ONLY)
+
+if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
+
+ file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst)
+
+ add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
+ OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/"
+ COMMAND "${SPHINX_EXECUTABLE}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
+ WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+ DEPENDS tfm_docs_sphinx_cfg
+ DEPENDS ${SPHINXCFG_DOC_FILES}
+ )
+ add_custom_target(tfm_docs_userguide_html
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/"
+ )
+ add_dependencies(docs tfm_docs_userguide_html)
+
+ if (LATEX_PDFLATEX_FOUND)
+ add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.tex"
+ OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/"
+ COMMAND "${SPHINX_EXECUTABLE}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex"
+ WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+ DEPENDS tfm_docs_sphinx_cfg
+ DEPENDS ${SPHINXCFG_DOC_FILES}
+ )
+ add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf"
+ COMMAND ${PDFLATEX_COMPILER} TF-M.tex
+ COMMAND ${CMAKE_COMMAND} -E copy TF-M.tex ${SPHINXCFG_OUTPUT_PATH}/tf-m_user_guide.pdf
+ WORKING_DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/latex/
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.tex"
+ )
+ add_custom_target(tfm_docs_userguide_pdf
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf"
+ )
+ add_dependencies(docs tfm_docs_userguide_pdf)
+ endif()
+endif()
+
+################################## DOXYGEN #####################################
+
+configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+
+if (DOXYGEN_FOUND AND DOXYGEN_DOT_FOUND AND PLANTUML_FOUND)
+
+ file(GLOB_RECURSE DOXYCFG_DOC_FILES ${CMAKE_SOURCE_DIR}/*.c ${CMAKE_SOURCE_DIR}/*.h)
+
+ add_custom_command(OUTPUT ${DOXYCFG_OUTPUT_PATH}/html
+ OUTPUT ${DOXYCFG_OUTPUT_PATH}/latex
+ OUTPUT ${DOXYCFG_OUTPUT_PATH}/latex/refman.pdf
+ COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ DEPENDS ${DOXYCFG_DOC_FILES}
+ )
+ add_custom_target(tfm_docs_refman_html
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ DEPENDS ${DOXYCFG_OUTPUT_PATH}/html
+ )
+ add_dependencies(docs tfm_docs_refman_html)
+
+ if (LATEX_PDFLATEX_FOUND)
+ add_custom_command(OUTPUT "${DOXYCFG_OUTPUT_PATH}/latex/refman.pdf"
+ COMMAND "${PDFLATEX_COMPILER} refman.tex"
+ COMMAND ${CMAKE_COMMAND} -E copy refman.tex ${DOXYCFG_OUTPUT_PATH}/tf-m_reference_manual.pdf
+ WORKING_DIRECTORY ${DOXYCFG_OUTPUT_PATH}/latex/
+ DEPENDS "${DOXYCFG_OUTPUT_PATH}/latex/refman.tex"
+ )
+ add_custom_target(tfm_docs_refman_pdf
+ DEPENDS ${DOXYCFG_OUTPUT_PATH}/latex/refman.pdf
+ DEPENDS tfm_docs_refman_html
+ )
+ add_dependencies(docs tfm_docs_refman_pdf)
+ endif()
+endif()
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
index a8e890b..2fb81c4 100644
--- a/docs/getting_started/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -188,8 +188,8 @@
Using the CMake build-system
----------------------------
-Building PDF output is optional and can be disabled by removing LaTex from the
-PATH.
+Building PDF output can be requested by invoking `tfm_docs_userguide_pdf/
+tfm_docs_userguide_pdf`
.. Note::
For building the documentation all tools needed to build the firmware must
@@ -202,12 +202,13 @@
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
- cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=GNUARM
- cmake --build ./ -- install_doc
+ cmake -S .. -B . -G "Unix Makefiles" -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
+ make tfm_docs_refman_html
+ make tfm_docs_refman_pdf
The documentation files will be available under the directory::
- cmake_doc/install/doc/reference_manual
+ cmake_doc/docs/reference_manual
Building the User Guide
^^^^^^^^^^^^^^^^^^^^^^^
@@ -216,12 +217,13 @@
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
- cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
- cmake --build ./ -- install_userguide
+ cmake -S .. -B . -G "Unix Makefiles" -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
+ make tfm_docs_userguide_html
+ make tfm_docs_userguide_pdf
The documentation files will be available under the directory::
- cmake_doc/install/doc/user_guide
+ cmake_doc/docs/user_guide
Manually using documentation generation tools
---------------------------------------------
diff --git a/docs/tfm_env.py.in b/docs/tfm_env.py.in
index b96be48..cc2f8bf 100644
--- a/docs/tfm_env.py.in
+++ b/docs/tfm_env.py.in
@@ -8,21 +8,18 @@
# Interface file between cmake and sphynx-build. Variables will be populated
# by cmake and evaluated by the Python builder
-cmake_env = { "SPHINX_TMP_DOC_DIR": "@SPHINX_TMP_DOC_DIR@",
- "TFM_ROOT_DIR" : "@TFM_ROOT_DIR@",
- "PLANTUML_JAR_PATH" : "@PLANTUML_JAR_PATH@",
- "Java_JAVA_EXECUTABLE" : "@Java_JAVA_EXECUTABLE@",
- "SPHINX_TMP_DOC_DIR" : "@SPHINX_TMP_DOC_DIR@",
- "DOXYGEN_EXECUTABLE" : "@DOXYGEN_EXECUTABLE@",
- "DOXYGEN_DOT_EXECUTABLE" : "@DOXYGEN_DOT_EXECUTABLE@",
- "DOXYCFG_DOXYGEN_CFG_DIR": "@DOXYCFG_DOXYGEN_CFG_DIR@",
- "DOXYCFG_OUTPUT_PATH": "@DOXYCFG_OUTPUT_PATH@",
- "DOXYCFG_DOXYGEN_BUILD": "@DOXYCFG_DOXYGEN_BUILD@",
- "DOXYCFG_ECLIPSE_DOCID": "@DOXYCFG_ECLIPSE_DOCID@",
- "SPHINXCFG_TEMPLATE_FILE": "@SPHINXCFG_TEMPLATE_FILE@",
- "PDF_OUTPUT_FILE": "@_PDF_FILE@",
- "SPHINXCFG_COPY_FILES": "@SPHINXCFG_COPY_FILES@",
- "SPHINXCFG_RENDER_CONF": "@SPHINXCFG_RENDER_CONF@",
- "SPHINXCFG_TFM_VERSION" : "@SPHINXCFG_TFM_VERSION@",
- "SPHINXCFG_TFM_VERSION_FULL" : "@SPHINXCFG_TFM_VERSION_FULL@"
+cmake_env = { "SPHINX_TMP_DOC_DIR" : "@SPHINX_TMP_DOC_DIR@",
+ "TFM_ROOT_DIR" : "@CMAKE_SOURCE_DIR@",
+ "PLANTUML_JAR_PATH" : "@PLANTUML_JAR_PATH@",
+ "Java_JAVA_EXECUTABLE" : "@Java_JAVA_EXECUTABLE@",
+ "DOXYGEN_EXECUTABLE" : "@DOXYGEN_EXECUTABLE@",
+ "DOXYGEN_DOT_EXECUTABLE" : "@DOXYGEN_DOT_EXECUTABLE@",
+ "DOXYCFG_DOXYGEN_CFG_DIR" : "@DOXYCFG_DOXYGEN_CFG_DIR@",
+ "DOXYCFG_OUTPUT_PATH" : "@DOXYCFG_OUTPUT_PATH@",
+ "DOXYCFG_DOXYGEN_BUILD" : "@DOXYCFG_DOXYGEN_BUILD@",
+ "SPHINXCFG_TEMPLATE_FILE" : "@SPHINXCFG_TEMPLATE_FILE@",
+ "SPHINXCFG_COPY_FILES" : "@SPHINXCFG_COPY_FILES@",
+ "SPHINXCFG_RENDER_CONF" : "@SPHINXCFG_RENDER_CONF@",
+ "SPHINXCFG_TFM_VERSION" : "v@CMAKE_PROJECT_VERSION@",
+ "SPHINXCFG_TFM_VERSION_FULL" : "Version @CMAKE_PROJECT_VERSION@"
}
diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
index ccfa60c..60b1ea4 100644
--- a/doxygen/Doxyfile.in
+++ b/doxygen/Doxyfile.in
@@ -45,7 +45,7 @@
# could be handy for archiving the generated documentation or if some version
# control system is used.
-PROJECT_NUMBER = @DOXYCFG_TFM_VERSION@
+PROJECT_NUMBER = @CMAKE_PROJECT_VERSION@
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
@@ -58,7 +58,7 @@
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.
-PROJECT_LOGO = @TFM_ROOT_DIR@/doxygen/TrustedFirmware-Logo_icon.png
+PROJECT_LOGO = @CMAKE_SOURCE_DIR@/doxygen/TrustedFirmware-Logo_icon.png
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
@@ -169,7 +169,7 @@
# will be relative from the directory where doxygen is started.
# This tag requires that the tag FULL_PATH_NAMES is set to YES.
-STRIP_FROM_PATH = "@TFM_ROOT_DIR@"
+STRIP_FROM_PATH = "@CMAKE_SOURCE_DIR@"
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
# path mentioned in the documentation of a class, which tells the reader which
@@ -178,7 +178,7 @@
# specify the list of include paths that are normally passed to the compiler
# using the -I flag.
-STRIP_FROM_INC_PATH = "@TFM_ROOT_DIR@"
+STRIP_FROM_INC_PATH = "@CMAKE_SOURCE_DIR@"
# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
# less readable) file names. This can be useful is your file systems doesn't
@@ -797,10 +797,10 @@
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = "@TFM_ROOT_DIR@/doxygen" \
- "@TFM_ROOT_DIR@/interface" \
- "@TFM_ROOT_DIR@/secure_fw" \
- "@TFM_ROOT_DIR@/test"
+INPUT = "@CMAKE_SOURCE_DIR@/doxygen" \
+ "@CMAKE_SOURCE_DIR@/interface" \
+ "@CMAKE_SOURCE_DIR@/secure_fw" \
+ "@CMAKE_SOURCE_DIR@/test"
# This tag can be used to specify the character encoding of the source files
@@ -1423,7 +1423,7 @@
# The default value is: org.doxygen.Project.
# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES.
-ECLIPSE_DOC_ID = @DOXYCFG_ECLIPSE_DOCID@
+# ECLIPSE_DOC_ID = @DOXYCFG_ECLIPSE_DOCID@
# If you want full control over the layout of the generated HTML pages it might
# be necessary to disable the index and replace it with your own. The
diff --git a/tools/documentation/tfm_cmake_defaults.py b/tools/documentation/tfm_cmake_defaults.py
index e90bd60..a5761c2 100644
--- a/tools/documentation/tfm_cmake_defaults.py
+++ b/tools/documentation/tfm_cmake_defaults.py
@@ -211,7 +211,6 @@
"SPHINXCFG_TFM_VERSION_FULL": tfm_def_tfm_ver_full,
"Java_JAVA_EXECUTABLE": tfm_def_java_binary,
"DOXYCFG_OUTPUT_PATH": tfm_def_doxy_output_dir,
- "DOXYCFG_ECLIPSE_DOCID": "org.arm.tf-m-refman",
"DOXYCFG_TFM_VERSION": tfm_def_tfm_ver_full,
}
# Only Override the version