[!324] Cmake documentation improvements

Merge branch 'feature/cmake-doc' into 'master'

See merge request [extensions/dune-codegen!324]

  [extensions/dune-codegen!324]: Noneextensions/dune-codegen/merge_requests/324

CMakeLists.txt

@@ -29,6 +29,7 @@ dune_register_package_flags(LIBRARIES dunecodegen)
 
 dune_enable_all_packages()
 
+add_subdirectory(doc)
 add_subdirectory(dune/codegen)
 add_subdirectory(cmake/modules)
 

cmake/modules/DuneCodegenMacros.cmake

 # File for module specific CMake tests.
 #
-# .. cmake_function:: add_generated_executable
+# .. cmake_function:: dune_add_generated_executable
 #
 #    .. cmake_param:: UFLFILE
 #       :single:
@@ -22,19 +22,20 @@
 #       The name given to the added executable target.
 #
 #    .. cmake_param:: SOURCE
+#       :single:
 #
 #       The cc source file to build from. If omitted, a minimal
 #       source file and a driver file will be generated.
 #
 #    .. cmake_param:: FORM_COMPILER_ARGS
 #       :multi:
-#       :argname arg:
+#       :argname: arg
 #
 #       Additional arguments as recognized by the form compiler.
 #
 #    .. cmake_param:: DEPENDS
 #       :multi:
-#       :argname dep:
+#       :argname: dep
 #
 #       Additional dependencies of the generated executable (changes in those
 #       will retrigger generation)
@@ -57,7 +58,7 @@
 #
 #    .. cmake_param:: ANALYZE_GRID_COMMAND
 #       :multi:
-#       :argname command:
+#       :argname: command
 #
 #       Use this to pass a custom grid analysis command. This is necessary
 #       if you use a custom grid generation methdod. The inifile and the
@@ -104,7 +105,7 @@ else()
 endif()
 file(GLOB_RECURSE UFL2PDELAB_SOURCES ${UFL2PDELAB_GLOB_PATTERN})
 
-function(add_generated_executable)
+function(dune_add_generated_executable)
   set(OPTIONS EXCLUDE_FROM_ALL ANALYZE_GRID)
   set(SINGLE TARGET SOURCE UFLFILE INIFILE)
   set(MULTI FORM_COMPILER_ARGS DEPENDS ANALYZE_GRID_COMMAND)
@@ -112,15 +113,15 @@ function(add_generated_executable)
   cmake_parse_arguments(GEN "${OPTIONS}" "${SINGLE}" "${MULTI}" ${ARGN})
 
   if(GEN_UNPARSED_ARGUMENTS)
-    message(FATAL_ERROR "Unrecognized arguments in add_generated_executable. This usually indicates a typo.")
+    message(FATAL_ERROR "Unrecognized arguments in dune_add_generated_executable. This usually indicates a typo.")
   endif()
 
   # Apply defaults and enforce requirements
   if(NOT GEN_TARGET)
-    message(FATAL_ERROR "Need to specify the TARGET parameter for add_generated_executable")
+    message(FATAL_ERROR "Need to specify the TARGET parameter for dune_add_generated_executable")
   endif()
   if(NOT GEN_UFLFILE)
-    message(FATAL_ERROR "Need to specify the UFLFILE parameter for add_generated_executable")
+    message(FATAL_ERROR "Need to specify the UFLFILE parameter for dune_add_generated_executable")
   endif()
   if(NOT IS_ABSOLUTE ${GEN_UFLFILE})
     set(GEN_UFLFILE ${CMAKE_CURRENT_SOURCE_DIR}/${GEN_UFLFILE})

cmake/modules/GeneratedSystemtests.cmake

-# System testing for generated executables. All ideas taken from dune-testtools.
+# System testing for generated executables. All ideas taken from dune-testtools.
+#
+# .. cmake_function:: dune_add_formcompiler_system_test
+#
+#    .. cmake_param:: UFLFILE
+#       :single:
+#       :required:
+#
+#       The UFL file to create the generate code from.
+#
+#    .. cmake_param:: INIFILE
+#       :single:
+#       :required:
+#
+#       The ini file that controls the form compilation process.
+#       It is expected to contain a [formcompiler] section. This
+#       file may contain meta ini annotations.
+#
+#    .. cmake_param:: BASENAME
+#       :single:
+#       :required:
+#
+#       The basename for the generated executables.
+#
+#    .. cmake_param:: SCRIPT
+#       :single:
+#
+#       The python script that decides about test failure/success.
+#       Defaults to a script that simply runs the program and checks
+#       the exit code. More scripts to be found in dune-testtools.
+#
+#    .. cmake_param:: SOURCE
+#       :single:
+#
+#       The cc source file to build from. If omitted, a minimal
+#       source file and a driver file will be generated.
+#
+#    .. cmake_param:: CREATED_TARGETS
+#       :single:
+#
+#       A variable name that should be filled with the list of generated
+#       targets. This can be used to modify these lateron.
+#
+#    .. cmake_param:: DEPENDS
+#       :multi:
+#       :argname: dep
+#
+#       Additional dependencies of the generated executable (changes in those
+#       will retrigger generation)
+#
+#    .. cmake_param:: NO_TESTS
+#       :option:
+#
+#       If given, code will be generated and built normally, but no tests will
+#       be added to the test suite.
+#
+#    .. cmake_param:: ANALYZE_GRID
+#       :option:
+#
+#       Set this option to enable code generation time grid analysis.
+#       This is useful to reduce the variety of sum factorization kernels
+#       in unstructured grids. Note that the grid analysis tool needs to
+#       be able to construct your grid from the given inifile. If you have
+#       a custom grid construction method, you can use ANALYZE_GRID_COMMAND
+#       instead.
+#
+#    .. cmake_param:: ANALYZE_GRID_COMMAND
+#       :multi:
+#       :argname: command
+#
+#       Use this to pass a custom grid analysis command. This is necessary
+#       if you use a custom grid generation methdod. The inifile and the
+#       outputfile will be appended to this command. You can use the analysis code in
+#       dune/codegen/sumfact/analyzegrid.hh to write your own tool.
+#       Specifying this option will automatically set ANALYZE_GRID.
 #
 
 function(dune_add_formcompiler_system_test)
   # parse arguments
   set(OPTION DEBUG NO_TESTS ANALYZE_GRID)
-  set(SINGLE INIFILE BASENAME SCRIPT UFLFILE SOURCE)
-  set(MULTI CREATED_TARGETS DEPENDS)
+  set(SINGLE INIFILE BASENAME SCRIPT UFLFILE SOURCE CREATED_TARGETS)
+  set(MULTI DEPENDS ANALYZE_GRID_COMMAND)
   cmake_parse_arguments(SYSTEMTEST "${OPTION}" "${SINGLE}" "${MULTI}" ${ARGN})
 
   if(SYSTEMTEST_UNPARSED_ARGUMENTS)
@@ -25,6 +99,10 @@ function(dune_add_formcompiler_system_test)
   if(SYSTEMTEST_ANALYZE_GRID)
     set(ANALYZE_GRID_STR "ANALYZE_GRID")
   endif()
+  set(ANALYZE_GRID_COMMAND_STR "")
+  if(SYSTEMTEST_ANALYZE_GRID_COMMAND)
+    set(ANALYZE_GRID_COMMAND_STR "ANALYZE_GRID_COMMAND ${SYSTEMTEST_ANALYZE_GRID_COMMAND}")
+  endif()
 
   # set a default for the script. call_executable.py just calls the executable.
   # There, it is also possible to hook in things depending on the inifile
@@ -55,14 +133,15 @@ function(dune_add_formcompiler_system_test)
       endif()
     endif()
 
-    add_generated_executable(TARGET ${tname}
-                             UFLFILE ${SYSTEMTEST_UFLFILE}
-                             INIFILE "${CMAKE_CURRENT_BINARY_DIR}/${inifile}"
-                             DEPENDS ${SYSTEMTEST_INIFILE} ${SYSTEMTEST_DEPENDS}
-                             EXCLUDE_FROM_ALL
-                             ${SOURCE}
-                             ${ANALYZE_GRID_STR}
-                             )
+    dune_add_generated_executable(TARGET ${tname}
+                                  UFLFILE ${SYSTEMTEST_UFLFILE}
+                                  INIFILE "${CMAKE_CURRENT_BINARY_DIR}/${inifile}"
+                                  DEPENDS ${SYSTEMTEST_INIFILE} ${SYSTEMTEST_DEPENDS}
+                                  EXCLUDE_FROM_ALL
+                                  ${SOURCE}
+                                  ${ANALYZE_GRID_STR}
+                                  ${ANALYZE_GRID_COMMAND_STR}
+                                  )
 
     # Enrich the target with preprocessor variables from the __static section
     # just the way that dune-testtools does.

doc/CMakeLists.txt

+dune_cmake_sphinx_doc(MODULE_ONLY)