[CMake] Teach CMake to build the documentation for the API bindings

and install them. The target for building the documentation is
`api_docs`.

This is off by default but can be enabled with the
`BUILD_DOCUMENTATION` option. The C and C++ API documentation
is always built but the Python, ".NET", and Java documentation are
only built if they are enabled in the build system. The rationale
for this is that it would be confusing to install documentation
for API bindings that are not installed.

By default `ALWAYS_BUILD_DOCS` is on which will slow down builds
significantly but will ensure that when the `install` target is
invoked the documentation is up-to-date. Unfortunately I couldn't
find a better way to do this. `ALWAYS_BUILD_DOCS` can be disabled
to get faster builds and still have the `api_docs` target available.

CMakeLists.txt

@@ -43,10 +43,13 @@ message(STATUS "Z3 version ${Z3_VERSION}")
 # Set various useful variables depending on CMake version
 ################################################################################
 if (("${CMAKE_VERSION}" VERSION_EQUAL "3.2") OR ("${CMAKE_VERSION}" VERSION_GREATER "3.2"))
-  # In CMake >= 3.2 add_custom_command() supports a ``USES_TERMINAL`` argument
+  # In CMake >= 3.2 add_custom_command() and add_custom_target()
+  # supports a ``USES_TERMINAL`` argument
   set(ADD_CUSTOM_COMMAND_USES_TERMINAL_ARG "USES_TERMINAL")
+  set(ADD_CUSTOM_TARGET_USES_TERMINAL_ARG "USES_TERMINAL")
 else()
   set(ADD_CUSTOM_COMMAND_USES_TERMINAL_ARG "")
+  set(ADD_CUSTOM_TARGET_USES_TERMINAL_ARG "")
 endif()
 
 ################################################################################
@@ -528,3 +531,14 @@ option(ENABLE_EXAMPLE_TARGETS "Build Z3 api examples" ON)
 if (ENABLE_EXAMPLE_TARGETS)
   add_subdirectory(examples)
 endif()
+
+################################################################################
+# Documentation
+################################################################################
+option(BUILD_DOCUMENTATION "Build API documentation" OFF)
+if (BUILD_DOCUMENTATION)
+  message(STATUS "Building documentation enabled")
+  add_subdirectory(doc)
+else()
+  message(STATUS "Building documentation disabled")
+endif()

README-CMake.md

@@ -268,6 +268,7 @@ The following useful options can be passed to CMake whilst configuring.
 * ``CMAKE_INSTALL_PKGCONFIGDIR`` - STRING. The path to install pkgconfig files.
 * ``CMAKE_INSTALL_PYTHON_PKG_DIR`` - STRING. The path to install the z3 python bindings. This can be relative (to ``CMAKE_INSTALL_PREFIX``) or absolute.
 * ``CMAKE_INSTALL_Z3_CMAKE_PACKAGE_DIR`` - STRING. The path to install CMake package files (e.g. ``/usr/lib/cmake/z3``).
+* ``CMAKE_INSTALL_API_BINDINGS_DOC`` - STRING. The path to install documentation for API bindings.
 * ``ENABLE_TRACING_FOR_NON_DEBUG`` - BOOL. If set to ``TRUE`` enable tracing in non-debug builds, if set to ``FALSE`` disable tracing in non-debug builds. Note in debug builds tracing is always enabled.
 * ``BUILD_LIBZ3_SHARED`` - BOOL. If set to ``TRUE`` build libz3 as a shared library otherwise build as a static library.
 * ``ENABLE_EXAMPLE_TARGETS`` - BOOL. If set to ``TRUE`` add the build targets for building the API examples.
@@ -286,6 +287,11 @@ The following useful options can be passed to CMake whilst configuring.
 * ``Z3_JAVA_JNI_LIB_INSTALLDIRR`` - STRING. The path to directory to install the Z3 Java JNI bridge library. This path should be relative to ``CMAKE_INSTALL_PREFIX``.
 * ``INCLUDE_GIT_DESCRIBE`` - BOOL. If set to ``TRUE`` and the source tree of Z3 is a git repository then the output of ``git describe`` will be included in the build.
 * ``INCLUDE_GIT_HASH`` - BOOL. If set to ``TRUE`` and the source tree of Z3 is a git repository then the git hash will be included in the build.
+* ``BUILD_DOCUMENTATION`` - BOOL. If set to ``TRUE`` then documentation for the API bindings can be built by invoking the ``api_docs`` target.
+* ``INSTALL_API_BINDINGS_DOCUMENTATION`` - BOOL. If set to ``TRUE`` and ``BUILD_DOCUMENTATION` is ``TRUE`` then documentation for API bindings will be installed
+    when running the ``install`` target.
+* ``ALWAYS_BUILD_DOCS`` - BOOL. If set to ``TRUE`` and ``BUILD_DOCUMENTATION`` is ``TRUE`` then documentation for API bindings will always be built.
+    Disabling this is useful for faster incremental builds. The documentation can be manually built by invoking the ``api_docs`` target.
 
 On the command line these can be passed to ``cmake`` using the ``-D`` option. In ``ccmake`` and ``cmake-gui`` these can be set in the user interface.
 
@@ -417,6 +423,7 @@ There are a few special targets:
 * ``clean`` all the built targets in the current directory and below
 * ``edit_cache`` will invoke one of the CMake tools (depending on which is available) to let you change configuration options.
 * ``rebuild_cache`` will reinvoke ``cmake`` for the project.
+* ``api_docs`` will build the documentation for the API bindings.
 
 ### Setting build type specific flags
 

contrib/cmake/doc/CMakeLists.txt

@@ -0,0 +1,93 @@
+find_package(Doxygen REQUIRED)
+message(STATUS "DOXYGEN_EXECUTABLE: \"${DOXYGEN_EXECUTABLE}\"")
+message(STATUS "DOXYGEN_VERSION: \"${DOXYGEN_VERSION}\"")
+
+set(DOC_DEST_DIR "${CMAKE_CURRENT_BINARY_DIR}/api")
+set(DOC_TEMP_DIR "${CMAKE_CURRENT_BINARY_DIR}/temp")
+set(MK_API_DOC_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/mk_api_doc.py")
+
+set(PYTHON_API_OPTIONS "")
+set(DOTNET_API_OPTIONS "")
+set(JAVA_API_OPTIONS "")
+SET(DOC_EXTRA_DEPENDS "")
+
+if (BUILD_PYTHON_BINDINGS)
+  # FIXME: Don't hard code this path
+  list(APPEND PYTHON_API_OPTIONS "--z3py-package-path" "${CMAKE_BINARY_DIR}/python/z3")
+  list(APPEND DOC_EXTRA_DEPENDS "build_z3_python_bindings")
+else()
+  list(APPEND PYTHON_API_OPTIONS "--no-z3py")
+endif()
+
+if (BUILD_DOTNET_BINDINGS)
+  # FIXME: Don't hard code these paths
+  list(APPEND DOTNET_API_OPTIONS "--dotnet-search-paths"
+    "${CMAKE_SOURCE_DIR}/src/api/dotnet"
+    "${CMAKE_BINARY_DIR}/src/api/dotnet"
+  )
+  list(APPEND DOC_EXTRA_DEPENDS "build_z3_dotnet_bindings")
+else()
+  list(APPEND DOTNET_API_OPTIONS "--no-dotnet")
+endif()
+
+if (BUILD_JAVA_BINDINGS)
+  # FIXME: Don't hard code these paths
+  list(APPEND JAVA_API_OPTIONS "--java-search-paths"
+    "${CMAKE_SOURCE_DIR}/src/api/java"
+    "${CMAKE_BINARY_DIR}/src/api/java"
+  )
+  list(APPEND DOC_EXTRA_DEPENDS "build_z3_java_bindings")
+else()
+  list(APPEND JAVA_API_OPTIONS "--no-java")
+endif()
+
+option(ALWAYS_BUILD_DOCS "Always build documentation for API bindings" ON)
+if (ALWAYS_BUILD_DOCS)
+  set(ALWAYS_BUILD_DOCS_ARG "ALL")
+else()
+  set(ALWAYS_BUILD_DOCS_ARG "")
+  # FIXME: This sucks but there doesn't seem to be a way to make the top level
+  # install target depend on the `api_docs` target.
+  message(WARNING "Building documentation for API bindings is not part of the"
+    " all target. This may result in stale files being installed when running"
+    " the install target. You should run the api_docs target before running"
+    " the install target. Alternatively Set ALWAYS_BUILD_DOCS to ON to"
+    " automatically build documentation when running the install target."
+  )
+endif()
+
+add_custom_target(api_docs ${ALWAYS_BUILD_DOCS_ARG}
+  COMMAND
+  "${PYTHON_EXECUTABLE}" "${MK_API_DOC_SCRIPT}"
+  --doxygen-executable "${DOXYGEN_EXECUTABLE}"
+  --output-dir "${DOC_DEST_DIR}"
+  --temp-dir "${DOC_TEMP_DIR}"
+  ${PYTHON_API_OPTIONS}
+  ${DOTNET_API_OPTIONS}
+  ${JAVA_API_OPTIONS}
+  DEPENDS
+    ${DOC_EXTRA_DEPENDS}
+  BYPRODUCTS "${DOC_DEST_DIR}"
+  COMMENT "Generating documentation"
+  ${ADD_CUSTOM_TARGET_USES_TERMINAL_ARG}
+)
+
+# Remove generated documentation when running `clean` target.
+set_property(DIRECTORY APPEND PROPERTY
+  ADDITIONAL_MAKE_CLEAN_FILES
+  "${DOC_DEST_DIR}"
+)
+
+option(INSTALL_API_BINDINGS_DOCUMENTATION "Install documentation for API bindings" ON)
+set(CMAKE_INSTALL_API_BINDINGS_DOC
+  "${CMAKE_INSTALL_DOCDIR}"
+  CACHE
+  PATH
+  "Path to install documentation for API bindings"
+)
+if (INSTALL_API_BINDINGS_DOCUMENTATION)
+  install(
+    DIRECTORY "${DOC_DEST_DIR}"
+    DESTINATION "${CMAKE_INSTALL_API_BINDINGS_DOC}"
+  )
+endif()