#------------------------------------------------------------------------------- # 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()