Fix re-running CommonGraph target and improve its documentation

Before this change, changing the COMMON_GRAPH_SHOW_OPTIONAL options
had no effect because CMake did not track changes on ${Name}.dot
after #536.
Using file(GENERATE) instead of a file(WRITE) works and avoids the
CMake warning "Policy CMP0058".

CHANGES.md

@@ -165,8 +165,8 @@
 * cmake 3 is required for finding a project with find_package() from
   outside the build tree/from the install tree.
 * Optimized cmake run speed significantly
-* New project-png target generating a dependency graph if graphviz is
-  found
+* New PROJECT_NAME-graph target generating a .png dependency graph if graphviz
+  is found
 * New explicit rebase target to update sub projects and externals to
   configured revision
 * FindPackages.cmake should no longer be used; use common_package() for each

CommonGraph.cmake

@@ -1,31 +1,51 @@
-# Provides functions to generate dependency graph images using graphviz.
-# Used by common_find_package.
-# common_graph_dep(): Write a dependency from->to into global properties
-# common_graph(): Write .dot from the global properties and add Name-graph rule
+# Copyright (c) 2017 [email protected]
+#                    [email protected]
+#
+# Provides functions to generate .png dependency graph images using graphviz:
+#   common_graph_dep(From To Required Source):
+#     Write a dependency From->To into global properties, called by
+#     common_find_package() and add_subproject().
+#   common_graph(Name):
+#     Write .dot from the global properties and add Name-graph target, called by
+#     common_find_package_post().
+#
+# CMake options:
+# * COMMON_GRAPH_SHOW_EXTERNAL include external dependencies in graphs.
+# * COMMON_GRAPH_SHOW_OPTIONAL include optional dependencies in graphs.
+#
+# Targets generated:
+# * graphs: generate .png graphs for all (sub)projects.
+# * ${PROJECT_NAME}-graph generate a .png graph for the project.
 
 include(CommonTarget)
 if(COMMON_GRAPH_DONE)
   return()
 endif()
 set(COMMON_GRAPH_DONE ON)
 
+option(COMMON_GRAPH_SHOW_EXTERNAL "Include external dependencies in graphs" ON)
+option(COMMON_GRAPH_SHOW_OPTIONAL "Include optional dependencies in graphs" OFF)
+
 find_program(DOT_EXECUTABLE dot)
 find_program(TRED_EXECUTABLE tred)
-common_target(graphs doxygen)
-option(COMMON_GRAPH_SHOW_OPTIONAL "Include optional dependencies in graphs" OFF)
 
 function(common_graph_dep From To Required Source)
   string(REPLACE "-" "_" Title ${From})
   string(REPLACE "-" "_" Dep ${To})
+  # prevent syntax error in tred, e.g. Magick++ -> MagickPP
+  string(REPLACE "+" "P" Title ${Title})
+  string(REPLACE "+" "P" Dep ${Dep})
 
   if(Source)
     set(style "style=bold")
+  elseif(NOT COMMON_GRAPH_SHOW_EXTERNAL)
+    return()
   elseif(Required)
     set(style "style=solid")
-  elseif(NOT COMMON_GRAPH_SHOW_OPTIONAL)
-    return()
-  else()
+  elseif(COMMON_GRAPH_SHOW_OPTIONAL)
     set(style "style=dashed")
+  else()
+    return()
   endif()
 
   set_property(GLOBAL APPEND_STRING PROPERTY ${From}_COMMON_GRAPH
@@ -59,22 +79,27 @@ function(common_graph Name)
     list(LENGTH graph_depends nDepends)
   endwhile()
 
-  # write .dot
-  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot
-    "strict digraph G { rankdir=\"RL\"; ${graph} }" )
-
   if(DOT_EXECUTABLE AND TRED_EXECUTABLE)
-    set(dest ${PROJECT_BINARY_DIR}/doc/images)
-    add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot
-      COMMAND ${TRED_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot >
-               ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot)
-    add_custom_command(OUTPUT ${dest}/${Name}.png
-      COMMAND ${CMAKE_COMMAND} -E make_directory ${dest}
-      COMMAND ${DOT_EXECUTABLE} -o ${dest}/${Name}.png -Tpng ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot
-      DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot)
-    add_custom_target(${Name}-graph DEPENDS ${dest}/${Name}.png)
+    set(_dot_file ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot)
+    file(GENERATE OUTPUT ${_dot_file}
+      CONTENT "strict digraph G { rankdir=\"RL\"; ${graph} }")
+
+    set(_tred_dot_file ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot)
+    add_custom_command(OUTPUT ${_tred_dot_file}
+      COMMAND ${TRED_EXECUTABLE} ${_dot_file} > ${_tred_dot_file}
+      DEPENDS ${_dot_file})
+
+    set(_image_folder ${PROJECT_BINARY_DIR}/doc/images)
+    set(_image_file ${_image_folder}/${Name}.png)
+    add_custom_command(OUTPUT ${_image_file}
+      COMMAND ${CMAKE_COMMAND} -E make_directory ${_image_folder}
+      COMMAND ${DOT_EXECUTABLE} -o ${_image_file} -Tpng ${_tred_dot_file}
+      DEPENDS ${_tred_dot_file})
+
+    add_custom_target(${Name}-graph DEPENDS ${_image_file})
     set_target_properties(${Name}-graph PROPERTIES EXCLUDE_FROM_DEFAULT_BUILD ON
       FOLDER ${Name}/doxygen)
+    common_target(graphs doxygen)
     add_dependencies(graphs ${Name}-graph)
   endif()
 endfunction()

README.md

@@ -100,5 +100,7 @@ Additional features:
   This is only implemented for Linux distributions using apt-get and yum
   package managers and MacPorts in OS X. The actual support depends on the
   project declaring its dependencies for each particular case.
+* [CommonGraph](CommonGraph.cmake) adds *graphs* target to generate .png tree
+  view of dependencies, gathered by CommonFindPackage and SubProject.
 
 [Detailed Change Log](CHANGES.md)