cmake: Documentation targets always available regardless of `BUILD_DOC` option.

- Warn if BUILD_DOC is enabled but missing required programs
- CMake lint

cmake/modules-docs.cmake

@@ -4,166 +4,155 @@ option(BUILD_DOC "Build documentation" ON)
 find_program(XSLTPROC_EXECUTABLE xsltproc QUIET)
 find_program(LYNX_EXECUTABLE lynx QUIET)
 
-if(BUILD_DOC
-   AND NOT XSLTPROC_EXECUTABLE
-   AND NOT LYNX_EXECUTABLE
-)
-  message(
-    STATUS
-      "xsltproc or lynx not found but required for doc generation. Disabling documentation build."
-  )
+if(BUILD_DOC AND (NOT XSLTPROC_EXECUTABLE OR NOT LYNX_EXECUTABLE))
+  message(WARNING "xsltproc or lynx not found but required for doc generation.")
   set(BUILD_DOC OFF)
+endif()
+
+option(DOCS_XSL_VAIDATION "Docbook document validation" OFF)
+option(DOCS_NOCATALOG
+       "ON: Use standard catalog from OS | OFF: Use custom catalog " OFF)
+
+set(DOCS_SOURCES
+    "index.html"
+    CACHE STRING "Documentation files list")
+
+set(DOCS_README
+    ${DOCS_SOURCES}
+    CACHE STRING "Readme Documentation files list")
+
+set(DOCS_HTML
+    ${DOCS_SOURCES}
+    CACHE STRING "HTML Documentation files list")
+
+set(DOCS_TXT
+    ${DOCS_SOURCES}
+    CACHE STRING "TXT Documentation files list")
+
+set(DOCS_OUTPUT_DIR
+    ${CMAKE_BINARY_DIR}/doc/docbook
+    CACHE STRING "Path to build HTML docs")
+
+set(DOCBOOK_DIR ${CMAKE_SOURCE_DIR}/doc/docbook)
+set(DEPS_XSL ${DOCBOOK_DIR}/dep.xsl)
+set(SINGLE_HTML_XSL ${DOCBOOK_DIR}/html.xsl)
+set(CHUNKED_HTML_XSL ${DOCBOOK_DIR}/html.chunked.xsl)
+set(TXT_XSL ${DOCBOOK_DIR}/txt.xsl)
+set(README_XSL ${DOCBOOK_DIR}/readme.xsl)
+
+set(DOCS_HTML_CSS
+    "/css/sr-doc.css"
+    CACHE STRING "Path to the CSS file")
+
+set(CATALOG ${DOCBOOK_DIR}/catalog.xml)
+
+if(DOCS_NOCATALOG)
+  set(XMLCATATLOGX "")
 else()
-  option(DOCS_XSL_VAIDATION "Docbook document validation" OFF)
-  option(DOCS_NOCATALAOG
-         "ON: Use standard catalog from OS/ OFF: USE custom catalog " ON
-  )
-  set(DOCS_SOURCES
-      "index.html"
-      CACHE STRING "Documentation files list"
-  )
-  set(DOCS_README
-      ${DOCS_SOURCES}
-      CACHE STRING "Readme Documentation files list"
-  )
-  set(DOCS_HTML
-      ${DOCS_SOURCES}
-      CACHE STRING "HTML Documentation files list"
-  )
-  set(DOCS_TXT
-      ${DOCS_SOURCES}
-      CACHE STRING "TXT Documentation files list"
-  )
-
-  set(DOCS_OUTPUT_DIR
-      ${CMAKE_BINARY_DIR}/doc/docbook
-      CACHE STRING "Path to build HTML docs"
-  )
-
-  set(DOCBOOK_DIR ${CMAKE_SOURCE_DIR}/doc/docbook)
-  set(DEPS_XSL ${DOCBOOK_DIR}/dep.xsl)
-  set(SINGLE_HTML_XSL ${DOCBOOK_DIR}/html.xsl)
-  set(CHUNKED_HTML_XSL ${DOCBOOK_DIR}/html.chunked.xsl)
-  set(TXT_XSL ${DOCBOOK_DIR}/txt.xsl)
-  set(README_XSL ${DOCBOOK_DIR}/readme.xsl)
-
-  set(DOCS_HTML_CSS
-      "/css/sr-doc.css"
-      CACHE STRING "Path to the CSS file"
-  )
-
-  set(CATALOG ${DOCBOOK_DIR}/catalog.xml)
-
-  if(DOCS_NOCATALAOG)
-    set(XMLCATATLOGX "")
-  else()
-    set(XMLCATATLOGX XML_CATALOG_FILES=${CATALOG})
-  endif()
+  set(XMLCATATLOGX "XML_CATALOG_FILES=${CATALOG}")
+endif()
 
-  # Set flags for xtproc for generating documentation and allow user defined
-  set(DOCS_XSLTPROC_FLAGS
-      ""
-      CACHE STRING "Xsltransform processor flags"
-  )
-  if(NOT DOCS_XSL_VAIDATION)
-    message(STATUS "Disabling validation when generating documentation")
-    list(APPEND DOCS_XSLTPROC_FLAGS --novalid)
+# Set flags for xtproc for generating documentation and allow user defined
+set(DOCS_XSLTPROC_FLAGS
+    ""
+    CACHE STRING "Xsltransform processor flags")
+if(NOT DOCS_XSL_VAIDATION)
+  if(VERBOSE)
+    message(STATUS "DOCS_XSL_VAIDATION=OFF"
+                   "Disabling xsl validation when generating documentation")
   endif()
+  list(APPEND DOCS_XSLTPROC_FLAGS --novalid)
+endif()
 
-  # Set lynx flags for generating readmes and allow user defined
-  set(DOCS_LYNX_FLAGS
-      "-nolist"
-      CACHE STRING "Lynx readme generator flags"
-  )
-
-  # Function to add a module docs entry
-  function(docs_add_module MODULE_NAME)
-    # message(STATUS "Adding documentation for module ${MODULE_NAME}")
-    set(MODULE_PATH "${MODULES_DIR}/${MODULE_NAME}")
-    set(MODULE_DOC_PATH "${MODULE_PATH}/doc")
-
-    add_custom_target(
-      ${MODULE_NAME}_doc_text
-      DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt
-      COMMENT "Processing target ${MODULE_NAME}_doc_text")
-
-    # This is essentialy an alias of doc_text target but with extra copy
-    # command to copy the text file to the source tree directory.
-    add_custom_target(
-      ${MODULE_NAME}_readme
-      DEPENDS ${MODULE_NAME}_doc_text
-      COMMENT "Processing target ${MODULE_NAME}_readme")
-
-    add_custom_target(
-      ${MODULE_NAME}_doc_html
-      DEPENDS ${DOCS_OUTPUT_DIR}/${MODULE_NAME}.html
-      COMMENT "Processing target ${MODULE_NAME}_doc_html")
-
-    add_custom_target(
-      ${MODULE_NAME}_doc
-      DEPENDS ${MODULE_NAME}_doc_text ${MODULE_NAME}_doc_html
-              ${MODULE_NAME}_readme
-      COMMENT "Processing target ${MODULE_NAME}_doc")
-
-    # Each version has seperate custon commands for not recompiling all if 1
-    # gets changed.
-    if(XSLTPROC_EXECUTABLE)
-      if(LYNX_EXECUTABLE)
-        add_custom_command(
-          OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt
-          COMMAND
-            # TXT version - just plain text
-            ${XMLCATATLOGX} ${XSLTPROC_EXECUTABLE} ${DOCS_XSLTPROC_FLAGS}
-            --xinclude ${TXT_XSL} ${MODULE_NAME}.xml | ${LYNX_EXECUTABLE}
-            ${DOCS_LYNX_FLAGS} -stdin -dump >
-            ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt
-          DEPENDS
-            ${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/doc/${MODULE_NAME}.xml
-            ${TXT_XSL}
-            # ${SINGLE_HTML_XSL}
-          WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/doc
-          COMMENT
-            "Generating text documentation with xsltproc and lynx for ${MODULE_NAME}"
-        )
-
-        # Add custom command to copy the README file after the readme target is built.
-        # The readme target depends on doc_text so it will regenerate if it's input changed.
-        add_custom_command(
-          TARGET ${MODULE_NAME}_readme
-          POST_BUILD
-          COMMAND
-            ${CMAKE_COMMAND} -E copy
-            ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt
-            ${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/README
-          COMMENT "Copying README file to source tree for ${MODULE_NAME}")
-
-        add_custom_command(
-          OUTPUT ${DOCS_OUTPUT_DIR}/${MODULE_NAME}.html
-          COMMAND
-            # HTML version
-            ${XMLCATATLOGX} ${XSLTPROC_EXECUTABLE} ${DOCS_XSLTPROC_FLAGS}
-            --xinclude --stringparam base.dir ${DOCS_OUTPUT_DIR} --stringparam
-            root.filename ${MODULE_NAME} --stringparam html.stylesheet
-            ${DOCS_HTML_CSS} --stringparam html.ext ".html" ${SINGLE_HTML_XSL}
-            ${MODULE_NAME}.xml
-          DEPENDS
-            ${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/doc/${MODULE_NAME}.xml
-            ${SINGLE_HTML_XSL}
-          WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/doc
-          COMMENT
-            "Generating html documentation with xsltproc and lynx for ${MODULE_NAME}"
-        )
-      endif()
-
-      install(
-        FILES ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt
-        RENAME README.${MODULE_NAME}
-        DESTINATION ${CMAKE_INSTALL_DOCDIR}/modules
-        COMPONENT kamailio_docs
-        # Since the depepndencies might not have been build as they are not in the default target
-        # and required to build explicitly using `make kamailio_docs`, allow them to be optional.
-        OPTIONAL
-      )
+# Set lynx flags for generating readmes and allow user defined
+set(DOCS_LYNX_FLAGS
+    "-nolist"
+    CACHE STRING "Lynx readme generator flags")
+
+# Function to add a module docs entry
+function(docs_add_module module_name)
+  # message(STATUS "Adding documentation for module ${MODULE_NAME}")
+  set(module_path "${MODULES_DIR}/${module_name}")
+  set(module_doc_path "${module_path}/doc")
+
+  add_custom_target(
+    ${module_name}_doc_text
+    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${module_name}/${module_name}.txt
+    COMMENT "Processing target ${module_name}_doc_text")
+
+  # This is essentialy an alias of doc_text target but with extra copy command
+  # to copy the text file to the source tree directory.
+  add_custom_target(
+    ${module_name}_readme
+    DEPENDS ${module_name}_doc_text
+    COMMENT "Processing target ${module_name}_readme")
+
+  add_custom_target(
+    ${module_name}_doc_html
+    DEPENDS ${DOCS_OUTPUT_DIR}/${module_name}.html
+    COMMENT "Processing target ${module_name}_doc_html")
+
+  add_custom_target(
+    ${module_name}_doc
+    DEPENDS ${module_name}_doc_text ${module_name}_doc_html
+            ${module_name}_readme
+    COMMENT "Processing target ${module_name}_doc")
+
+  # Each version has seperate custon commands for not recompiling all if 1 gets
+  # changed.
+  if(XSLTPROC_EXECUTABLE)
+    if(LYNX_EXECUTABLE)
+      add_custom_command(
+        OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${module_name}/${module_name}.txt
+        COMMAND
+          # TXT version - just plain text
+          ${XMLCATATLOGX} ${XSLTPROC_EXECUTABLE} ${DOCS_XSLTPROC_FLAGS}
+          --xinclude ${TXT_XSL} ${module_name}.xml | ${LYNX_EXECUTABLE}
+          ${DOCS_LYNX_FLAGS} -stdin -dump >
+          ${CMAKE_CURRENT_BINARY_DIR}/${module_name}/${module_name}.txt
+        DEPENDS
+          ${CMAKE_CURRENT_SOURCE_DIR}/${module_name}/doc/${module_name}.xml
+          ${TXT_XSL}
+          # ${SINGLE_HTML_XSL}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${module_name}/doc
+        COMMENT "Generating text documentation with for ${module_name}")
+
+      # Add custom command to copy the README file after the readme target is
+      # built. The readme target depends on doc_text so it will regenerate if
+      # it's input changed.
+      add_custom_command(
+        TARGET ${module_name}_readme
+        POST_BUILD
+        COMMAND
+          ${CMAKE_COMMAND} -E copy
+          ${CMAKE_CURRENT_BINARY_DIR}/${module_name}/${module_name}.txt
+          ${CMAKE_CURRENT_SOURCE_DIR}/${module_name}/README
+        COMMENT "Copying README file to source tree for ${module_name}")
+
+      add_custom_command(
+        OUTPUT ${DOCS_OUTPUT_DIR}/${module_name}.html
+        COMMAND
+          # HTML version
+          ${XMLCATATLOGX} ${XSLTPROC_EXECUTABLE} ${DOCS_XSLTPROC_FLAGS}
+          --xinclude --stringparam base.dir ${DOCS_OUTPUT_DIR} --stringparam
+          root.filename ${module_name} --stringparam html.stylesheet
+          ${DOCS_HTML_CSS} --stringparam html.ext ".html" ${SINGLE_HTML_XSL}
+          ${module_name}.xml
+        DEPENDS
+          ${CMAKE_CURRENT_SOURCE_DIR}/${module_name}/doc/${module_name}.xml
+          ${SINGLE_HTML_XSL}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${module_name}/doc
+        COMMENT "Generating html documentation for ${module_name}")
     endif()
-  endfunction()
-endif()
+
+    install(
+      FILES ${CMAKE_CURRENT_BINARY_DIR}/${module_name}/${module_name}.txt
+      RENAME README.${module_name}
+      DESTINATION ${CMAKE_INSTALL_DOCDIR}/modules
+      COMPONENT kamailio_docs
+      # Since the depepndencies might not have been build as they are not in the
+      # default target and required to build explicitly using `make
+      # kamailio_docs`, allow them to be optional.
+      OPTIONAL)
+  endif()
+endfunction()

src/modules/CMakeLists.txt

@@ -85,6 +85,7 @@ function(add_module_group group_modules)
             "-ffile-prefix-map=${CMAKE_SOURCE_DIR}/src/modules/${module_name}/="
         )
 
+        # Set the RPATH of the module to include the installation directory of
         set_target_properties(
           ${module_name} PROPERTIES INSTALL_RPATH
                                     "${CMAKE_INSTALL_FULL_LIBDIR}/${MAIN_NAME}")
@@ -97,11 +98,9 @@ function(add_module_group group_modules)
           COMPONENT kamailio_modules)
         # Add the module to the list of added modules
         set_property(GLOBAL APPEND PROPERTY ADDED_MODULES_LIST ${module_name})
-        if(BUILD_DOC)
-          docs_add_module(${module_name})
-          set_property(GLOBAL APPEND PROPERTY ALL_MODULE_DOC_TARGETS
-                                              ${module_name}_doc)
-        endif()
+        docs_add_module(${module_name})
+        set_property(GLOBAL APPEND PROPERTY ALL_MODULE_DOC_TARGETS
+                                            ${module_name}_doc)
       else()
         message(FATAL_ERROR "Module directory ${module_path} does not exist.")
       endif()
@@ -147,26 +146,18 @@ message(STATUS "Modules to be built: ${ADDED_MODULES_LIST}")
 add_custom_target(modules COMMENT "Building modules")
 add_dependencies(modules ${ADDED_MODULES_LIST})
 
-# Add a kamailio_docs target that depends on all module documentation targets
-if(BUILD_DOC)
-  get_property(ADDED_MODULES_LIST GLOBAL PROPERTY ADDED_MODULES_LIST)
-  if(VERBOSE)
-    message(STATUS "Enabled documentation generation for: ${ADDED_MODULES_LIST}.
-        To override, use '-DBUILD_DOC=OFF'")
-  endif()
+get_property(ALL_MODULE_DOC_TARGETS GLOBAL PROPERTY ALL_MODULE_DOC_TARGETS)
+# message(STATUS "ALL_MODULE_DOC_TARGETS: ${ALL_MODULE_DOC_TARGETS}")
 
-  get_property(ALL_MODULE_DOC_TARGETS GLOBAL PROPERTY ALL_MODULE_DOC_TARGETS)
-  # message(STATUS "ALL_MODULE_DOC_TARGETS: ${ALL_MODULE_DOC_TARGETS}")
-
-  add_custom_target(
-    kamailio_docs
-    DEPENDS ${ALL_MODULE_DOC_TARGETS}
-    COMMENT "Generating Kamailio documentation")
-
-  add_custom_target(
-    install_kamailio_docs
-    COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR} --component
-            kamailio_docs
-    DEPENDS kamailio_docs
-    COMMENT "Installing Kamailio documentation")
-endif()
+# Add a kamailio_docs target that depends on all module documentation targets
+add_custom_target(
+  kamailio_docs
+  DEPENDS ${ALL_MODULE_DOC_TARGETS}
+  COMMENT "Generating Kamailio documentation")
+
+add_custom_target(
+  install_kamailio_docs
+  COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR} --component
+          kamailio_docs
+  DEPENDS kamailio_docs
+  COMMENT "Installing Kamailio documentation")