From b3ffd8d1ebe2cfd3f84bfd3d9e926e1a291ffbf6 Mon Sep 17 00:00:00 2001 From: Eike Ziller Date: Tue, 19 May 2020 09:42:44 +0200 Subject: [PATCH] CMake build: Move documentation functions to re-usable location Removes "install_..._docs" and "clean_docs" special targets. Instead install documentation with "--install . --component qch_docs" and "--install . --component html_docs" which have the advantage that the install prefix can be specified later on with --prefix. Also removes export of IDE_SOURCE_DIR, which is not used. Change-Id: I4fce0b9aa8c7fc40b7e94e065777ddf4c0b76c41 Reviewed-by: Cristian Adam --- CMakeLists.txt | 35 +--- cmake/QtCreatorDocumentation.cmake | 285 ++++++++++++++++++++++++++++ doc/CMakeLists.txt | 287 +++-------------------------- scripts/build.py | 11 +- scripts/build_plugin.py | 14 ++ src/CMakeLists.txt | 7 +- 6 files changed, 331 insertions(+), 308 deletions(-) create mode 100644 cmake/QtCreatorDocumentation.cmake diff --git a/CMakeLists.txt b/CMakeLists.txt index 926cd34165c..062a3218722 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -6,6 +6,7 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") include(FeatureSummary) include(QtCreatorIDEBranding) include(QtCreatorTranslations) +include(QtCreatorDocumentation) set(IDE_REVISION FALSE CACHE BOOL "Marks the presence of IDE revision string.") set(IDE_REVISION_STR "" CACHE STRING "The IDE revision string.") @@ -46,40 +47,6 @@ find_package(Qt5 COMPONENTS LinguistTools) find_package(Threads) -# Get information on directories from qmake -# as this is not yet exported by cmake. -function(qt5_query_qmake) - if (NOT TARGET Qt5::qmake) - message(FATAL_ERROR "Qmake was not found.") - endif() - - get_target_property(_qmake_binary Qt5::qmake IMPORTED_LOCATION) - execute_process(COMMAND "${_qmake_binary}" "-query" - TIMEOUT 10 - RESULT_VARIABLE _qmake_result - OUTPUT_VARIABLE _qmake_stdout - OUTPUT_STRIP_TRAILING_WHITESPACE) - - if (NOT "${_qmake_result}" STREQUAL "0") - message(FATAL_ERROR "Qmake did not execute successfully: ${_qmake_result}.") - endif() - - # split into lines: - string(REPLACE "\n" ";" _lines "${_qmake_stdout}") - - foreach(_line ${_lines}) - # split line into key/value pairs - string(REPLACE ":" ";" _parts "${_line}") - list(GET _parts 0 _key) - list(REMOVE_AT _parts 0) - string(REPLACE ";" ":" _value "${_parts}") - - set("${_key}" "${_value}" CACHE PATH "qmake import of ${_key}" FORCE) - endforeach() -endfunction() - -qt5_query_qmake() - find_package(Qt5 COMPONENTS Designer Help Script SerialPort Svg QUIET) function (set_if_target var target) if (TARGET "${target}") diff --git a/cmake/QtCreatorDocumentation.cmake b/cmake/QtCreatorDocumentation.cmake new file mode 100644 index 00000000000..82735999f9e --- /dev/null +++ b/cmake/QtCreatorDocumentation.cmake @@ -0,0 +1,285 @@ +# Options: +option(WITH_DOCS "Build documentation" OFF) +add_feature_info("Build documentation" WITH_DOCS "") + +option(WITH_ONLINE_DOCS "Build online documentation" OFF) +add_feature_info("Build online documentation" WITH_ONLINE_DOCS "") + +# Get information on directories from qmake +# as this is not yet exported by cmake. +# Used for QT_INSTALL_DOCS +function(qt5_query_qmake) + if (NOT TARGET Qt5::qmake) + message(FATAL_ERROR "Qmake was not found. Add find_package(Qt5 COMPONENTS Core) to CMake to enable.") + endif() + # dummy check for if we already queried qmake + if (QT_INSTALL_BINS) + return() + endif() + + get_target_property(_qmake_binary Qt5::qmake IMPORTED_LOCATION) + execute_process(COMMAND "${_qmake_binary}" "-query" + TIMEOUT 10 + RESULT_VARIABLE _qmake_result + OUTPUT_VARIABLE _qmake_stdout + OUTPUT_STRIP_TRAILING_WHITESPACE) + + if (NOT "${_qmake_result}" STREQUAL "0") + message(FATAL_ERROR "Qmake did not execute successfully: ${_qmake_result}.") + endif() + + # split into lines: + string(REPLACE "\n" ";" _lines "${_qmake_stdout}") + + foreach(_line ${_lines}) + # split line into key/value pairs + string(REPLACE ":" ";" _parts "${_line}") + list(GET _parts 0 _key) + list(REMOVE_AT _parts 0) + string(REPLACE ";" ":" _value "${_parts}") + + set("${_key}" "${_value}" CACHE PATH "qmake import of ${_key}" FORCE) + endforeach() +endfunction() + +# Find programs: +function(_doc_find_program result_var) + if (NOT TARGET Qt5::qmake) + message(FATAL_ERROR "QDoc is only available in Qt5 projects") + endif() + + get_target_property(_qmake_binary Qt5::qmake IMPORTED_LOCATION) + get_filename_component(_qmake_dir "${_qmake_binary}" DIRECTORY) + find_program("_prg_${result_var}" ${ARGN} HINTS "${_qmake_dir}") + if ("_prg_${result_var}" STREQUAL "_prg_${result_var}-NOTFOUND") + set("_prg_${result_var}" "${result_var}-NOTFOUND") + message(WARNING "Could not find binary for ${result_var}") + endif() + + set(${result_var} "${_prg_${result_var}}" PARENT_SCOPE) +endfunction() + +function(_setup_doc_targets) + # Set up important targets: + if (NOT TARGET html_docs) + add_custom_target(html_docs COMMENT "Build HTML documentation") + endif() + if (NOT TARGET qch_docs) + add_custom_target(qch_docs COMMENT "Build QCH documentation") + endif() + if (NOT TARGET docs) + add_custom_target(docs COMMENT "Build documentation") + add_dependencies(docs html_docs qch_docs) + endif() +endfunction() + +function(_setup_qdoc_targets _qdocconf_file _retval) + cmake_parse_arguments(_arg "" "HTML_DIR;INSTALL_DIR;POSTFIX" + "INDEXES;INCLUDE_DIRECTORIES;FRAMEWORK_PATHS;ENVIRONMENT_EXPORTS" ${ARGN}) + + foreach(_index ${_arg_INDEXES}) + list(APPEND _qdoc_index_args "-indexdir;${_index}") + endforeach() + + set(_env "") + foreach(_export ${_arg_ENVIRONMENT_EXPORTS}) + if (NOT DEFINED "${_export}") + message(FATAL_ERROR "${_export} is not known when trying to export it to qdoc.") + endif() + list(APPEND _env "${_export}=${${_export}}") + endforeach() + + set(_full_qdoc_command "${_qdoc}") + if (_env) + set(_full_qdoc_command "${CMAKE_COMMAND}" "-E" "env" ${_env} "${_qdoc}") + endif() + + if (_arg_HTML_DIR STREQUAL "") + set(_arg_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc") + endif() + + get_filename_component(_target "${_qdocconf_file}" NAME_WE) + + set(_html_outputdir "${_arg_HTML_DIR}/${_target}${_arg_POSTFIX}") + file(MAKE_DIRECTORY "${_html_outputdir}") + + set(_qdoc_include_args "") + if (_arg_INCLUDE_DIRECTORIES OR _arg_FRAMEWORK_PATHS) + # pass include directories to qdoc via hidden @ option, since we need to generate a file + # to be able to resolve the generators inside the include paths + set(_qdoc_includes "${CMAKE_CURRENT_BINARY_DIR}/cmake/qdoc_${_target}.inc") + set(_qdoc_include_args "@${_qdoc_includes}") + set(_includes "") + if (_arg_INCLUDE_DIRECTORIES) + set(_includes "-I$\n") + endif() + set(_frameworks "") + if (_arg_FRAMEWORK_PATHS) + set(_frameworks "-F$\n") + endif() + file(GENERATE + OUTPUT "${_qdoc_includes}" + CONTENT "${_includes}${_frameworks}" + ) + endif() + + set(_html_target "html_docs_${_target}") + add_custom_target("${_html_target}" + ${_full_qdoc_command} -outputdir "${_html_outputdir}" "${_qdocconf_file}" + ${_qdoc_index_args} ${_qdoc_include_args} + COMMENT "Build HTML documentation from ${_qdocconf_file}" + DEPENDS "${_qdocconf_file}" + SOURCES "${_qdocconf_file}" + WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" + VERBATIM + ) + add_dependencies(html_docs "${_html_target}") + + # Install HTML files as a special component + install(DIRECTORY "${_html_outputdir}" DESTINATION "${_arg_INSTALL_DIR}" + COMPONENT html_docs EXCLUDE_FROM_ALL) + + set("${_retval}" "${_html_outputdir}" PARENT_SCOPE) +endfunction() + +function(_setup_qhelpgenerator_targets _qdocconf_file _html_outputdir) + cmake_parse_arguments(_arg "" "QCH_DIR;INSTALL_DIR" "" ${ARGN}) + if (_arg_UNPARSED_ARGUMENTS) + message(FATAL_ERROR "qdoc_build_qdocconf_file has unknown arguments: ${_arg_UNPARSED_ARGUMENTS}.") + endif() + + if (NOT _arg_QCH_DIR) + set(_arg_QCH_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc") + endif() + + if (NOT TARGET Qt5::qhelpgenerator) + message(WARNING "qhelpgenerator missing: No QCH documentation targets were generated. Add find_package(Qt5 COMPONENTS Help) to CMake to enable.") + return() + endif() + + get_filename_component(_target "${_qdocconf_file}" NAME_WE) + + set(_qch_outputdir "${_arg_QCH_DIR}") + file(MAKE_DIRECTORY "${_qch_outputdir}") + + set(_qch_target "qch_docs_${_target}") + set(_html_target "html_docs_${_target}") + add_custom_target("${_qch_target}" + Qt5::qhelpgenerator "${_html_outputdir}/${_target}.qhp" -o "${_qch_outputdir}/${_target}.qch" + COMMENT "Build QCH documentation from ${_qdocconf_file}" + WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" + VERBATIM + ) + add_dependencies("${_qch_target}" "${_html_target}") + add_dependencies(qch_docs "${_qch_target}") + + install(FILES "${_qch_outputdir}/${_target}.qch" DESTINATION "${_arg_INSTALL_DIR}" + COMPONENT qch_docs EXCLUDE_FROM_ALL) +endfunction() + +# Helper functions: +function(qdoc_build_qdocconf_file _qdocconf_file) + _setup_doc_targets() + + _doc_find_program(_qdoc NAMES qdoc qdoc-qt5) + if (_qdoc STREQUAL "_qdoc-NOTFOUND") + message(WARNING "No qdoc binary found: No documentation targets were generated") + return() + endif() + + cmake_parse_arguments(_arg "QCH" "HTML_DIR;QCH_DIR;INSTALL_DIR;POSTFIX" + "INDEXES;INCLUDE_DIRECTORIES;FRAMEWORK_PATHS;ENVIRONMENT_EXPORTS" ${ARGN}) + if (_arg_UNPARSED_ARGUMENTS) + message(FATAL_ERROR "qdoc_build_qdocconf_file has unknown arguments: ${_arg_UNPARSED_ARGUMENTS}.") + endif() + + if (NOT _arg_INSTALL_DIR) + message(FATAL_ERROR "No INSTALL_DIR set when calling qdoc_build_qdocconf_file") + endif() + + _setup_qdoc_targets("${_qdocconf_file}" _html_outputdir + HTML_DIR "${_arg_HTML_DIR}" INSTALL_DIR "${_arg_INSTALL_DIR}" + INDEXES ${_arg_INDEXES} ENVIRONMENT_EXPORTS ${_arg_ENVIRONMENT_EXPORTS} + POSTFIX "${_arg_POSTFIX}" + INCLUDE_DIRECTORIES ${_arg_INCLUDE_DIRECTORIES} + FRAMEWORK_PATHS ${_arg_FRAMEWORK_PATHS} + ) + + if (_arg_QCH) + _setup_qhelpgenerator_targets("${_qdocconf_file}" "${_html_outputdir}" + QCH_DIR "${_arg_QCH_DIR}" INSTALL_DIR "${_arg_INSTALL_DIR}") + endif() +endfunction() + +set(QtCreatorDocumentation_LIST_DIR ${CMAKE_CURRENT_LIST_DIR}) + +function(qtc_docs_dir varName) + if (QtCreator_SOURCE_DIR) + # Qt Creator build or super-repo + set(${varName} "${QtCreator_SOURCE_DIR}/doc" PARENT_SCOPE) + elseif(QtCreatorDocumentation_LIST_DIR MATCHES /lib/cmake/QtCreator$) + # Dev package + set(${varName} "${QtCreatorDocumentation_LIST_DIR}/../../../doc" PARENT_SCOPE) + else() + message(FATAL_ERROR "Could not find qtc_docs_dir") + endif() +endfunction() + +function(qtc_index_dir varName) + if (QtCreator_BINARY_DIR) + # Qt Creator build or super-repo + set(${varName} "${QtCreator_BINARY_DIR}/doc/html" PARENT_SCOPE) + elseif(QtCreatorDocumentation_LIST_DIR MATCHES /lib/cmake/QtCreator$) + # Dev package + set(${varName} "${QtCreatorDocumentation_LIST_DIR}/../../../${IDE_DOC_PATH}" PARENT_SCOPE) + else() + message(FATAL_ERROR "Could not find qtc_index_dir") + endif() +endfunction() + +function(add_qtc_documentation qdocconf_file) + cmake_parse_arguments(_arg "" "" + "INCLUDE_DIRECTORIES;FRAMEWORK_PATHS" ${ARGN}) + if (_arg_UNPARSED_ARGUMENTS) + message(FATAL_ERROR "add_qtc_documentation has unknown arguments: ${_arg_UNPARSED_ARGUMENTS}.") + endif() + + ### Skip docs setup if that is not needed! + if (NOT WITH_ONLINE_DOCS AND NOT WITH_DOCS) + return() + endif() + + + qt5_query_qmake() + qtc_output_binary_dir(_output_binary_dir) + qtc_docs_dir(QTC_DOCS_DIR) + qtc_index_dir(QTC_INDEX_DIR) + + set(_qch_params) + if (WITH_DOCS) + set(_qch_params QCH QCH_DIR "${_output_binary_dir}/${IDE_DOC_PATH}") + endif() + set(_qdoc_params HTML_DIR "${_output_binary_dir}/doc/html") + list(APPEND _qdoc_params INDEXES "${QT_INSTALL_DOCS}" "${QTC_INDEX_DIR}") + list(APPEND _qdoc_params INSTALL_DIR "${IDE_DOC_PATH}") + + # Set up environment for qdoc: + set(QTC_VERSION "${IDE_VERSION_DISPLAY}") + set(QTCREATOR_COPYRIGHT_YEAR "${IDE_COPYRIGHT_YEAR}") + string(REPLACE "." "" QTC_VERSION_TAG "${IDE_VERSION}") + set(QDOC_INDEX_DIR "${QT_INSTALL_DOCS}") + if (QT_INSTALL_DOCS_src) + set(QT_INSTALL_DOCS "${QT_INSTALL_DOCS_src}") + endif() + list(APPEND _qdoc_params ENVIRONMENT_EXPORTS + IDE_ID IDE_CASED_ID IDE_DISPLAY_NAME + QTC_DOCS_DIR QTC_VERSION QTC_VERSION_TAG + QTCREATOR_COPYRIGHT_YEAR + QT_INSTALL_DOCS QDOC_INDEX_DIR + ) + + qdoc_build_qdocconf_file(${qdocconf_file} ${_qch_params} ${_qdoc_params} + INCLUDE_DIRECTORIES ${_arg_INCLUDE_DIRECTORIES} + FRAMEWORK_PATHS ${_arg_FRAMEWORK_PATHS} + ) +endfunction() diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 80f2b4cf66c..c453903cf09 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,12 +1,5 @@ # Generate documentation -# Options: -option(WITH_DOCS "Build documentation" OFF) -add_feature_info("Build documentation" WITH_DOCS "") - -option(WITH_ONLINE_DOCS "Build online documentation" OFF) -add_feature_info("Build online documentation" WITH_ONLINE_DOCS "") - option(BUILD_DEVELOPER_DOCS "Include developer documentation" OFF) add_feature_info("Include developer documentation" BUILD_DEVELOPER_DOCS "") @@ -38,265 +31,29 @@ function(_find_all_includes _ret_includes _ret_framework_paths) endif() endfunction() -# Find programs: -function(_doc_find_program result_var) - if (NOT TARGET Qt5::qmake) - message(FATAL_ERROR "QDoc is only available in Qt5 projects") - endif() - - get_target_property(_qmake_binary Qt5::qmake IMPORTED_LOCATION) - get_filename_component(_qmake_dir "${_qmake_binary}" DIRECTORY) - find_program("_prg_${result_var}" ${ARGN} HINTS "${_qmake_dir}") - if ("_prg_${result_var}" STREQUAL "_prg_${result_var}-NOTFOUND") - set("_prg_${result_var}" "${result_var}-NOTFOUND") - message(WARNING "Could not find binary for ${result_var}") - endif() - - set(${result_var} "${_prg_${result_var}}" PARENT_SCOPE) -endfunction() - -function(_setup_doc_targets) - # Set up important targets: - if (NOT TARGET html_docs) - add_custom_target(html_docs COMMENT "Build HTML documentation") - endif() - if (NOT TARGET qch_docs) - add_custom_target(qch_docs COMMENT "Build QCH documentation") - endif() - if (NOT TARGET docs) - add_custom_target(docs COMMENT "Build documentation") - add_dependencies(docs html_docs qch_docs) - endif() - if (NOT TARGET install_docs) - add_custom_target(install_docs COMMENT "Install documentation") - add_dependencies(install_docs docs) - endif() - if (NOT TARGET clean_docs) - add_custom_target(clean_docs COMMENT "Clean documentation files from build directory") - endif() -endfunction() - -function(_setup_qdoc_targets _qdocconf_file _retval) - cmake_parse_arguments(_arg "" "HTML_DIR;INSTALL_DIR;POSTFIX" - "INDEXES;INCLUDE_DIRECTORIES;FRAMEWORK_PATHS;ENVIRONMENT_EXPORTS" ${ARGN}) - - foreach(_index ${_arg_INDEXES}) - list(APPEND _qdoc_index_args "-indexdir;${_index}") - endforeach() - - set(_env "") - foreach(_export ${_arg_ENVIRONMENT_EXPORTS}) - if (NOT DEFINED "${_export}") - message(FATAL_ERROR "${_export} is not known when trying to export it to qdoc.") - endif() - list(APPEND _env "${_export}=${${_export}}") - endforeach() - - set(_full_qdoc_command "${_qdoc}") - if (_env) - set(_full_qdoc_command "${CMAKE_COMMAND}" "-E" "env" ${_env} "${_qdoc}") - endif() - - if (_arg_HTML_DIR STREQUAL "") - set(_arg_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc") - endif() - - get_filename_component(_target "${_qdocconf_file}" NAME_WE) - - set(_html_outputdir "${_arg_HTML_DIR}/${_target}${_arg_POSTFIX}") - file(MAKE_DIRECTORY "${_html_outputdir}") - - set(_qdoc_include_args "") - if (_arg_INCLUDE_DIRECTORIES OR _arg_FRAMEWORK_PATHS) - # pass include directories to qdoc via hidden @ option, since we need to generate a file - # to be able to resolve the generators inside the include paths - set(_qdoc_includes "${CMAKE_CURRENT_BINARY_DIR}/cmake/qdoc_${_target}.inc") - set(_qdoc_include_args "@${_qdoc_includes}") - set(_includes "") - if (_arg_INCLUDE_DIRECTORIES) - set(_includes "-I$\n") - endif() - set(_frameworks "") - if (_arg_FRAMEWORK_PATHS) - set(_frameworks "-F$\n") - endif() - file(GENERATE - OUTPUT "${_qdoc_includes}" - CONTENT "${_includes}${_frameworks}" +if (WITH_DOCS) + add_qtc_documentation("qtcreator/qtcreator.qdocconf") + if (BUILD_DEVELOPER_DOCS) + _find_all_includes(_all_includes _framework_paths) + add_qtc_documentation("qtcreatordev/qtcreator-dev.qdocconf" + INCLUDE_DIRECTORIES ${_all_includes} + FRAMEWORK_PATHS ${_framework_paths} ) endif() - - set(_html_target "html_docs_${_target}") - add_custom_target("${_html_target}" - ${_full_qdoc_command} -outputdir "${_html_outputdir}" "${_qdocconf_file}" - ${_qdoc_index_args} ${_qdoc_include_args} - COMMENT "Build HTML documentation from ${_qdocconf_file}" - DEPENDS "${_qdocconf_file}" - SOURCES "${_qdocconf_file}" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - VERBATIM - ) - add_dependencies(html_docs "${_html_target}") - - # Install HTML files as a special component - install(DIRECTORY "${_html_outputdir}" DESTINATION "${_arg_INSTALL_DIR}" - COMPONENT ${_html_target} EXCLUDE_FROM_ALL) - - add_custom_target("install_${_html_target}" - "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=${_html_target} - -P "${CMAKE_BINARY_DIR}/cmake_install.cmake" - COMMENT "Install HTML documentation from ${_qdocconf_file}" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - VERBATIM - ) - add_dependencies(install_docs "install_${_html_target}") - - add_custom_target("clean_${_html_target}" - "${CMAKE_COMMAND}" -E remove_directory "${_html_outputdir}" - COMMENT "Clean HTML documentation from ${_qdocconf_file}" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - VERBATIM - ) - add_dependencies(clean_docs "clean_${_html_target}") - - set("${_retval}" "${_html_outputdir}" PARENT_SCOPE) -endfunction() - -function(_setup_qhelpgenerator_targets _qdocconf_file _html_outputdir) - cmake_parse_arguments(_arg "" "QCH_DIR;INSTALL_DIR" "" ${ARGN}) - if (_arg_UNPARSED_ARGUMENTS) - message(FATAL_ERROR "qdoc_build_qdocconf_file has unknown arguments: ${_arg_UNPARSED_ARGUMENTS}.") - endif() - - if (NOT _arg_QCH_DIR) - set(_arg_QCH_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc") - endif() - - if (NOT TARGET Qt5::qhelpgenerator) - message(WARNING "qhelpgenerator missing: No QCH documentation targets were generated") - return() - endif() - - get_filename_component(_target "${_qdocconf_file}" NAME_WE) - - set(_qch_outputdir "${_arg_QCH_DIR}") - file(MAKE_DIRECTORY "${_qch_outputdir}") - - set(_qch_target "qch_docs_${_target}") - set(_html_target "html_docs_${_target}") - add_custom_target("${_qch_target}" - Qt5::qhelpgenerator "${_html_outputdir}/${_target}.qhp" -o "${_qch_outputdir}/${_target}.qch" - COMMENT "Build QCH documentation from ${_qdocconf_file}" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - VERBATIM - ) - add_dependencies("${_qch_target}" "${_html_target}") - add_dependencies(qch_docs "${_qch_target}") - - install(FILES "${_qch_outputdir}/${_target}.qch" DESTINATION "${_arg_INSTALL_DIR}" - COMPONENT ${_qch_target} EXCLUDE_FROM_ALL) - - add_custom_target("install_${_qch_target}" - "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=${_qch_target} - -P "${CMAKE_BINARY_DIR}/cmake_install.cmake" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - VERBATIM - ) - add_dependencies(install_docs "install_${_qch_target}") - - add_custom_target("clean_${_qch_target}" - "${CMAKE_COMMAND}" -E remove -f "${_qch_outputdir}/${_target}.qch" - COMMENT "Clean QCH documentation generated from ${_qdocconf_file}" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - VERBATIM - ) - add_dependencies(clean_docs "clean_${_qch_target}") -endfunction() - -# Helper functions: -function(qdoc_build_qdocconf_file _qdocconf_file) - _setup_doc_targets() - - _doc_find_program(_qdoc NAMES qdoc qdoc-qt5) - if (_qdoc STREQUAL "_qdoc-NOTFOUND") - message(WARNING "No qdoc binary found: No documentation targets were generated") - return() - endif() - - cmake_parse_arguments(_arg "QCH" "HTML_DIR;QCH_DIR;INSTALL_DIR;POSTFIX" - "INDEXES;INCLUDE_DIRECTORIES;FRAMEWORK_PATHS;ENVIRONMENT_EXPORTS" ${ARGN}) - if (_arg_UNPARSED_ARGUMENTS) - message(FATAL_ERROR "qdoc_build_qdocconf_file has unknown arguments: ${_arg_UNPARSED_ARGUMENTS}.") - endif() - - if (NOT _arg_INSTALL_DIR) - message(FATAL_ERROR "No INSTALL_DIR set when calling qdoc_build_qdocconf_file") - endif() - - _setup_qdoc_targets("${_qdocconf_file}" _html_outputdir - HTML_DIR "${_arg_HTML_DIR}" INSTALL_DIR "${_arg_INSTALL_DIR}" - INDEXES ${_arg_INDEXES} ENVIRONMENT_EXPORTS ${_arg_ENVIRONMENT_EXPORTS} - POSTFIX "${_arg_POSTFIX}" - INCLUDE_DIRECTORIES ${_arg_INCLUDE_DIRECTORIES} - FRAMEWORK_PATHS ${_arg_FRAMEWORK_PATHS} - ) - - if (_arg_QCH) - _setup_qhelpgenerator_targets("${_qdocconf_file}" "${_html_outputdir}" - QCH_DIR "${_arg_QCH_DIR}" INSTALL_DIR "${_arg_INSTALL_DIR}") - endif() -endfunction() - -### Skip docs setup if that is not needed! -if (WITH_ONLINE_DOCS OR WITH_DOCS) - if (WITH_DOCS) - set(_qch_params "QCH;QCH_DIR;${PROJECT_BINARY_DIR}/${IDE_DOC_PATH}") - endif() - - set(_qdoc_params HTML_DIR "${PROJECT_BINARY_DIR}/doc/html") - list(APPEND _qdoc_params INDEXES "${QT_INSTALL_DOCS}" "${PROJECT_BINARY_DIR}/doc") - list(APPEND _qdoc_params INSTALL_DIR "${IDE_DOC_PATH}") - - # Set up environment for qdoc: - set(QTC_VERSION "${IDE_VERSION_DISPLAY}") - set(QTCREATOR_COPYRIGHT_YEAR "${IDE_COPYRIGHT_YEAR}") - set(IDE_SOURCE_TREE "${PROJECT_SOURCE_DIR}") - string(REPLACE "." "" QTC_VERSION_TAG "${IDE_VERSION}") - set(QTC_DOCS_DIR "${CMAKE_CURRENT_SOURCE_DIR}") - set(QDOC_INDEX_DIR "${QT_INSTALL_DOCS}") - if (QT_INSTALL_DOCS_src) - set(QT_INSTALL_DOCS "${QT_INSTALL_DOCS_src}") - endif() - - list(APPEND _qdoc_params ENVIRONMENT_EXPORTS - IDE_ID IDE_CASED_ID IDE_DISPLAY_NAME - - IDE_SOURCE_TREE - - QTC_DOCS_DIR QTC_VERSION QTC_VERSION_TAG - - QTCREATOR_COPYRIGHT_YEAR - - QT_INSTALL_DOCS QDOC_INDEX_DIR) - - if (WITH_DOCS) - qdoc_build_qdocconf_file("qtcreator/qtcreator.qdocconf" ${_qch_params} ${_qdoc_params}) - if (BUILD_DEVELOPER_DOCS) - _find_all_includes(_all_includes _framework_paths) - qdoc_build_qdocconf_file("qtcreatordev/qtcreator-dev.qdocconf" ${_qch_params} ${_qdoc_params} - INCLUDE_DIRECTORIES ${_all_includes} - FRAMEWORK_PATHS ${_framework_paths} - ) - endif() - endif() - if(WITH_ONLINE_DOCS) - qdoc_build_qdocconf_file("qtcreator/qtcreator-online.qdocconf" ${_qdoc_params}) - if (BUILD_DEVELOPER_DOCS) - _find_all_includes(_all_includes _framework_paths) - qdoc_build_qdocconf_file("qtcreatordev/qtcreator-dev-online.qdocconf" ${_qdoc_params} - INCLUDE_DIRECTORIES ${_all_includes} - FRAMEWORK_PATHS ${_framework_paths} - ) - endif() +endif() +if(WITH_ONLINE_DOCS) + add_qtc_documentation("qtcreator/qtcreator-online.qdocconf") + if (BUILD_DEVELOPER_DOCS) + _find_all_includes(_all_includes _framework_paths) + add_qtc_documentation("qtcreatordev/qtcreator-dev-online.qdocconf" + INCLUDE_DIRECTORIES ${_all_includes} + FRAMEWORK_PATHS ${_framework_paths} + ) endif() endif() + +install(DIRECTORY config + DESTINATION doc + COMPONENT Devel + EXCLUDE_FROM_ALL +) diff --git a/scripts/build.py b/scripts/build.py index e7e414f5087..4547bf647c7 100755 --- a/scripts/build.py +++ b/scripts/build.py @@ -153,17 +153,12 @@ def build_qtcreator(args, paths): paths.build) if not args.no_docs: common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, - '--component', 'qtc_docs_qtcreator'], + '--component', 'qch_docs'], paths.build) common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, - '--component', 'html_docs_qtcreator'], - paths.build) - common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, - '--component', 'html_docs_qtcreator-dev'], - paths.build) - common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, - '--component', 'html_docs_qtcreator-dev'], + '--component', 'html_docs'], paths.build) + def build_wininterrupt(args, paths): if not common.is_windows_platform(): return diff --git a/scripts/build_plugin.py b/scripts/build_plugin.py index 97c4829745e..9df8c64f747 100755 --- a/scripts/build_plugin.py +++ b/scripts/build_plugin.py @@ -51,6 +51,8 @@ def get_arguments(): parser.add_argument('--add-config', help=('Adds the argument to the CMake configuration call. ' 'Use "--add-config=-DSOMEVAR=SOMEVALUE" if the argument begins with a dash.'), action='append', dest='config_args', default=[]) + parser.add_argument('--with-docs', help='Build and install documentation.', + action='store_true', default=False) parser.add_argument('--deploy', help='Installs the "Dependencies" component of the plugin.', action='store_true', default=False) parser.add_argument('--debug', help='Enable debug builds', action='store_true', default=False) @@ -79,6 +81,9 @@ def build(args, paths): # TODO this works around a CMake bug https://gitlab.kitware.com/cmake/cmake/issues/20119 cmake_args += ['-DBUILD_WITH_PCH=OFF'] + if args.with_docs: + cmake_args += ['-DWITH_DOCS=ON'] + ide_revision = common.get_commit_SHA(paths.src) if ide_revision: cmake_args += ['-DQTC_PLUGIN_REVISION=' + ide_revision] @@ -88,8 +93,17 @@ def build(args, paths): cmake_args += args.config_args common.check_print_call(cmake_args + [paths.src], paths.build) common.check_print_call(['cmake', '--build', '.'], paths.build) + if args.with_docs: + common.check_print_call(['cmake', '--build', '.', '--target', 'docs'], paths.build) common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, '--strip'], paths.build) + if args.with_docs: + common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, + '--component', 'qch_docs'], + paths.build) + common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, + '--component', 'html_docs'], + paths.build) if args.deploy: common.check_print_call(['cmake', '--install', '.', '--prefix', paths.install, '--component', 'Dependencies'], diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 89b4e253bfb..af0c062c7be 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -22,7 +22,6 @@ install( install( DIRECTORY - ${PROJECT_SOURCE_DIR}/doc ${PROJECT_SOURCE_DIR}/scripts DESTINATION ./ COMPONENT Devel EXCLUDE_FROM_ALL @@ -53,6 +52,10 @@ if (NOT DEFINED add_translation_targets) include(\${CMAKE_CURRENT_LIST_DIR}/QtCreatorTranslations.cmake) endif() +if (NOT DEFINED add_qtc_documentation) + include(\${CMAKE_CURRENT_LIST_DIR}/QtCreatorDocumentation.cmake) +endif() + if (NOT TARGET QtCreator::Core) include(\${CMAKE_CURRENT_LIST_DIR}/QtCreatorTargets.cmake) endif() @@ -66,6 +69,7 @@ export(EXPORT QtCreator file(COPY ${PROJECT_SOURCE_DIR}/cmake/QtCreatorIDEBranding.cmake ${PROJECT_SOURCE_DIR}/cmake/QtCreatorTranslations.cmake + ${PROJECT_SOURCE_DIR}/cmake/QtCreatorDocumentation.cmake ${PROJECT_SOURCE_DIR}/cmake/QtCreatorAPI.cmake ${PROJECT_SOURCE_DIR}/cmake/QtCreatorAPIInternal.cmake DESTINATION ${CMAKE_BINARY_DIR}/cmake @@ -76,6 +80,7 @@ install( FILES ${PROJECT_SOURCE_DIR}/cmake/QtCreatorIDEBranding.cmake ${PROJECT_SOURCE_DIR}/cmake/QtCreatorTranslations.cmake + ${PROJECT_SOURCE_DIR}/cmake/QtCreatorDocumentation.cmake ${PROJECT_SOURCE_DIR}/cmake/QtCreatorAPI.cmake ${PROJECT_SOURCE_DIR}/cmake/QtCreatorAPIInternal.cmake ${CMAKE_BINARY_DIR}/cmake/QtCreatorConfig.cmake