merge: Merge branch 'improve_cmake' into 'main'

Improve handling with `cmake`

See merge request numerics/solver/comma!30

.gitlab-ci.yml

@@ -82,7 +82,7 @@ job:test_dbg:
     script:
         - cd $CUSTOM_CI_DIR
         - cd build
-        - ./Comma_test -r junit > test_a.xml
+        - ./CoMMA_test -r junit > test_a.xml
         - python3 -m gcovr --xml-pretty --exclude '\.\./pybind11/' --exclude '\.\./Catch2/' --exclude '\.\./build_rel/' --exclude '\.\./CoMMA_lib/CoMMA.cpp' --print-summary -o coverage.xml --root ..
     coverage: /^\s*lines:\s*\d+.\d+\%/
     artifacts:
@@ -121,7 +121,7 @@ job:test_rel:
     script:
         - cd $CUSTOM_CI_DIR
         - cd build_rel
-        - ./Comma_test
+        - ./CoMMA_test
 pages:
     stage: documentation
     needs: ['job:init', 'job:build_dbg', 'job:test_dbg']

CMakeLists.txt

@@ -3,10 +3,10 @@
 
 ###############################   CMAKE VERSION and FLAGS ##########################
 
-cmake_minimum_required(VERSION 3.14)
+cmake_minimum_required(VERSION 3.15)
 
 if(NOT CMAKE_BUILD_TYPE)
-  message("No build type received, using Debug")
+  message(STATUS "No build type received, using Debug")
   set(CMAKE_BUILD_TYPE Debug)  # Debug version
 endif()
 
@@ -15,19 +15,30 @@ set(CMAKE_CXX_STANDARD 17)
 # https://github.com/catchorg/Catch2/issues/1204
 
 ###################################  PROJECT #################################
-project(CoMMA VERSION 1.3)
+project(CoMMA
+  VERSION 1.3
+  DESCRIPTION "Geometric agglomerator for unstructured grids"
+  HOMEPAGE_URL "https://github.com/onera/CoMMA"
+  LANGUAGES CXX
+)
 
 # https://stackoverflow.com/questions/57860026/cmake-override-variable-set-in-cmakelists-txt-via-commandline
 # For the current application, better to use an `option`:
 # https://stackoverflow.com/questions/36358217/what-is-the-difference-between-option-and-set-cache-bool-for-a-cmake-variabl
 #set(BUILD_TESTS On CACHE BOOL "Build tests")
 option(BUILD_TESTS "Build tests" ON)
-set(CoMMA_TEST "Comma_test")
+set(CoMMA_TEST "CoMMA_test")
 option(COVERAGE "Build tests with coverage support" OFF)
 
 #set(BUILD_PYTHON_BINDINGS On CACHE BOOL "Build python bindings via pybind11")
 option(BUILD_PYTHON_BINDINGS "Build python bindings via pybind11" ON)
 
+# https://vicrucann.github.io/tutorials/quick-cmake-doxygen/ and
+# https://stackoverflow.com/questions/34878276/build-doxygen-from-cmake-script
+option(BUILD_DOC "Build documentation (with Doxygen)" OFF)
+
+option(PKGCONFIG_SUPPORT "Prepare and install file to be used with pkg-config" OFF)
+
 if ( CODAFLAGS )
    # We just do not set the optimization flags nor the parallelism-related ones
   if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
@@ -37,7 +48,7 @@ if ( CODAFLAGS )
   elseif (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-finite-math-only -fno-math-errno -fvisibility-inlines-hidden -Wall -Wno-absolute-value -Wno-deprecated-register -Wno-unused-lambda-capture")
   endif()
-  message("Added CODA-like extra flags. Current flags are: ${CMAKE_CXX_FLAGS}")
+  message(STATUS "Added CODA-like extra flags. Current flags are: ${CMAKE_CXX_FLAGS}")
 endif()
 
 # Effective library
@@ -108,22 +119,88 @@ SET(TESTS
 
 # Generate a test executable with covergae report
 if ( BUILD_TESTS )
-  message("Tests enabled")
+  message(STATUS "Tests enabled")
   include_directories(Catch2/single_include)
   if ( COVERAGE )
-    message("Coverage support enabled")
+    message(STATUS "Coverage support enabled")
     add_compile_options("--coverage")
   endif()
   add_executable(${CoMMA_TEST} ${TESTS})
   if ( COVERAGE )
     target_link_libraries(${CoMMA_TEST} gcov)
   endif()
+
+  enable_testing()
+  add_test(NAME ${CoMMA_TEST}_global COMMAND ${CoMMA_TEST})
 endif()
-#target_link_libraries(Comma_test Boost)
-#set_source_files_properties( Comma_test PROPERTIES COMPILE_FLAGS "--coverage" )
+#target_link_libraries(${CoMMA_TEST} Boost)
+#set_source_files_properties(${CoMMA_TEST} PROPERTIES COMPILE_FLAGS "--coverage")
 ######################## Pybind11 bindings ####################################
 if ( BUILD_PYTHON_BINDINGS )
-  message("Python bindings enabled")
+  message(STATUS "Python bindings enabled")
+  # find the Python interpreter (including pybind might lead to other find files being used)
+  find_package(Python COMPONENTS Interpreter Development)
   add_subdirectory(pybind11)
   pybind11_add_module(${PROJECT_NAME} ${PYTHONBIND})
 endif()
+
+if ( BUILD_DOC )
+  message(STATUS "Documentation enabled")
+  find_package(Doxygen)
+  if ( NOT DOXYGEN_FOUND )
+    message(FATAL_ERROR "Doxygen is needed to build the documentation.")
+  endif()
+
+  # We add it to all-target as well
+  add_custom_target(doc
+    ALL
+    COMMAND ${DOXYGEN_EXECUTABLE} Documentation/Doxyfile
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    COMMENT "Generating documentation with Doxygen"
+  )
+endif()
+
+# installation
+include(GNUInstallDirs)
+
+
+# ${SOURCE_DIR} (no slash) considers the directory itself
+# ${SOURCE_DIR}/ (with slash) considers its files only
+install(DIRECTORY ${SOURCE_DIR}/
+  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}
+  FILES_MATCHING PATTERN "*.h"
+  REGEX "deprecated" EXCLUDE
+)
+install(FILES LICENSE DESTINATION ${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME})
+
+if ( PKGCONFIG_SUPPORT )
+  configure_file(config_files/comma.pc.in comma.pc @ONLY)
+  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/comma.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)
+endif()
+
+if ( BUILD_PYTHON_BINDINGS )
+  set(PYTHON_SUB_DIR "python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages")
+  # Install generated module
+  install(TARGETS ${PROJECT_NAME}
+    COMPONENT python
+    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
+    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}/${PYTHON_SUB_DIR}"
+    ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}/${PYTHON_SUB_DIR}"
+  )
+
+  # Install examples
+  install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/examples/scripts/
+    DESTINATION ${CMAKE_INSTALL_PREFIX}/examples/${PROJECT_NAME}
+    FILES_MATCHING
+    PATTERN "*.py"
+    PATTERN "*.md"
+    REGEX "deprecated" EXCLUDE
+    REGEX "cache" EXCLUDE
+  )
+endif()
+
+if ( BUILD_DOC )
+  # Instead of "TYPE DOC" could have use ${CMAKE_INSTALL_DOCDIR} or similarly ${CMAKE_INSTALL_FULL_DOCDIR}
+  install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/documentation/html TYPE DOC)
+  install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/Documentation/CoMMA_user_manual.pdf TYPE DOC)
+endif()

Documentation/Doxyfile

@@ -38,20 +38,22 @@ PROJECT_NAME           = "CoMMA"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "v1.3"
+PROJECT_NUMBER         = "1.3"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = ""
+PROJECT_BRIEF          = "A geometric agglomerator for unstructured meshes"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
+# PERSONAL EDIT: 55 looks good if no project brief. With the brief it's too
+# small. 70 looks good, might also be a little more, like 72, but 75 is too much
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = images/logos/logo-CoMMA_70x70.jpg
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is

README.md

@@ -27,16 +27,20 @@ IDDN.FR.001.420013.000.S.X.2023.000.31235.
 CoMMA is a `C++` **header-only library** hence it does not need compilation, per
 se. Nonetheless, a `python` module can be generated using `pybind11`: this is
 very convenient for testing and debugging purposes. Moreover, some tests via
-`Catch2` have been written to check the integrity of CoMMA. Both the `python`
-module and the tests need compilation.
+`Catch2` have been written to check the integrity of CoMMA (for more details see
+the [dedicated section](#mag-testing-comma) below). Both the `python` module and
+the tests need compilation. Finally, one can install the headers and, when
+applies, the `python` module in a given directory.
 
-To build this library you just need a fairly recent `cmake` (3.14+). Then, a
+To build this library you just need a fairly recent `cmake` (3.15+). Then, a
 standard out-of-source build with `cmake` in a freshly created directory will
 suffice to compile
 ```shell
-mkdir build
+mkdir build install
 cd build
-cmake ..
+cmake --prefix=../install ..
+make
+make install
 ```
 `cmake` should be able to find the simple dependencies by itself if they're
 installed in standard location.
@@ -56,15 +60,24 @@ support (default is off)
 cmake -DCOVERAGE=On ..
 ```
 
+Support for `pkg-config` can be enabled by passing the related option to
+`cmake`:
+```shell
+cmake -DPKGCONFIG_SUPPORT=On --prefix=../install ..
+```
+A template of such configuration file can be found
+[in the repository](config_files/comma.pc.in); given the prefix provided above,
+it will be installed in `path/to/CoMMA/install/lib64/pkgconfig`.
+
 An option is available to use the flags usually considered when compiling the
 CODA-CFD library:
 ```shell
-cmake -DCODAFLAGS=ON ..
+cmake -DCODAFLAGS=On ..
 ```
 
 ## :construction_worker: Usage
 The interface to CoMMA is very simple and consists in only one function
-[`agglomerate_one_level`](https://numerics.gitlab-pages.onera.net/solver/comma/_co_m_m_a_8h.html#abfb7a4b061c35873233941bb1329ea09).
+[`agglomerate_one_level`](https://onera.github.io/CoMMA/_co_m_m_a_8h.html#a906c231be20a1f53a240618bae81d95f).
 
 ## :book: Documentation
 CoMMA is documented via `doxygen`. If you have it and wish to have the full
@@ -74,7 +87,7 @@ doxygen Documentation/Doxyfile
 ```
 and related html pages will be built in `documentation`.
 
-An [online version](https://numerics.gitlab-pages.onera.net/solver/comma/) of
+An [online version](https://onera.github.io/CoMMA/) of
 the doc hosted by GitLab is available.
 
 A user manual is also available, see
@@ -90,18 +103,18 @@ how they will impact the final results...).
 Here are two animations about the agglomeration on a 2D mesh of a ring for two
 different option settings:
 * Seeds pool with
-  [full initialization](https://numerics.gitlab-pages.onera.net/solver/comma/struct_s_p_full_initializator.html)
+  [full initialization](https://onera.github.io/CoMMA/struct_s_p_full_initializator.html)
   and
-  [boundary priority](https://numerics.gitlab-pages.onera.net/solver/comma/class_seeds___pool___boundary___priority.html)
+  [boundary priority](https://onera.github.io/CoMMA/class_seeds___pool___boundary___priority.html)
 
 <div align="center">
     <img src="images/videos/bnd_full_init.gif" alt="" width="512" height="auto"/>
 </div>
 
 * Seeds pool with
-  [one-point initialization](https://numerics.gitlab-pages.onera.net/solver/comma/struct_s_p_one_point_initializator.html)
+  [one-point initialization](https://onera.github.io/CoMMA/struct_s_p_one_point_initializator.html)
   and
-  [neighbourhood priority](https://numerics.gitlab-pages.onera.net/solver/comma/class_seeds___pool___neighbourhood___priority.html)
+  [neighbourhood priority](https://onera.github.io/CoMMA/class_seeds___pool___neighbourhood___priority.html)
 
 <div align="center">
     <img src="images/videos/neigh_pt_init.gif" alt="" width="512" height="auto"/>
@@ -126,29 +139,31 @@ A set of tests to verify code and algorithm integrity has been set up, see
 framework, which is why the related submodule is included in this repository. To
 run the tests, build the library (see [above](#wrench-building-the-library), the
 `cmake` commands related to the tests are already part of the reference
-[`CMakeLists.txt`](CMakeLists.txt)),
-this will generate an executable `Comma_test` in the building directory, simply
-run it.
+[`CMakeLists.txt`](CMakeLists.txt)), this will generate an executable
+`CoMMA_test` in the building directory, simply run it.
 ```shell
 mkdir build
 cd build
 cmake ..
 make
-./Comma_test
+./CoMMA_test
 ```
 
 Tests are included in the
 [continuous integration](#robot-continuous-integration) set of actions.
 
 ## :snake: A `python` interface to CoMMA
-A `python` module which interfaces to CoMMA can be obtained using `pybind11` (a submodule of
-CoMMA). To have it, just "build" (see [above](#wrench-building-the-library),
-related the `cmake` commands are already part of the reference
-[`CMakeLists.txt`](CMakeLists.txt)): a library called
-`CoMMA.cpython-38-x86_64-linux-gnu.so` (or similar) appears in the build
-directory. To use it, add the directory to your `python` path:
+A `python` module which interfaces to CoMMA can be obtained using `pybind11` (a
+submodule of CoMMA). To have it, just "build" (see
+[above](#wrench-building-the-library), related the `cmake` commands are already
+part of the reference [`CMakeLists.txt`](CMakeLists.txt)). A library called
+`CoMMA.cpython-38-x86_64-linux-gnu.so` (or similar) is installed in the
+`${CMAKE_INSTALL_LIBDIR}/python3.X/site-packages`, which, supposing one has
+given `install` as prefix in the `cmake` configuration step and using
+`python3.10`, will develop to `install/lib64/python3.10/site-packages`. To use
+it, add that directory to your `python` path:
 ```shell
-export PYTHONPATH:/path/to/CoMMA/build:$PYTHONPATH
+export PYTHONPATH:/path/to/CoMMA/install/lib64/python3.10/site-packages:$PYTHONPATH
 ```
 then just load CoMMA module in a `python` session:
 ```python
@@ -175,9 +190,9 @@ fc_to_cc, aggloLines_Idx, aggloLines = CoMMA.agglomerate_one_level(*[args])
 ```
 
 Several `python` scripts showcasing the CoMMA package (as well as its two main
-dependencies, `meshio` and `dualGPy`are [available](examples/scripts).
+dependencies, `meshio` and `dualGPy`) are [available](examples/scripts).
 
-## :robot: Continuous Integration
+<!-- ## :robot: Continuous Integration
 A Continuous Integration (CI) [workflow](.gitlab-ci.yml) is available and it
 runs at each push event concerning `C++` or CI files (at least with the current
 configuration). The workflow performs several steps:
@@ -191,4 +206,4 @@ configuration). The workflow performs several steps:
    and the coverage
    [![coverage report](https://gitlab.onera.net/numerics/solver/comma/badges/main/coverage.svg)](https://gitlab.onera.net/numerics/solver/comma/-/commits/main)
 4. Build the documentation (same as [above](#book-documentation)) and deploy it
-   on a [GitLab page](https://numerics.gitlab-pages.onera.net/solver/comma/)
+   on a [GitLab page](https://numerics.gitlab-pages.onera.net/solver/comma/) -->

config_files/comma.pc.in

@@ -0,0 +1,12 @@
+prefix="@CMAKE_INSTALL_PREFIX@"
+exec_prefix="${prefix}"
+libdir="@CMAKE_INSTALL_FULL_LIBDIR@"
+includedir="@CMAKE_INSTALL_FULL_INCLUDEDIR@"
+
+Name: @PROJECT_NAME@
+Description: @CMAKE_PROJECT_DESCRIPTION@
+Version: @PROJECT_VERSION@
+Cflags: -I${includedir}
+Libs: -L${libdir} @LINK_FLAGS@
+
+Requires: