Add CMake-based builds and prerequisites to README (#123)

* Add CMake-based builds to README

* Small addendum

* Update README.md

Co-authored-by: Hendrik Ranocha <[email protected]>

* Allow macOS builds with CMake

* Add prerequisites

* Fix formatting

---------

Co-authored-by: Hendrik Ranocha <[email protected]>
Co-authored-by: Andrew Winters <[email protected]>

.gitignore

@@ -23,6 +23,11 @@ CVS
 HOHQMesh
 HOHQMesh.exe
 
+# CMake builds
+build-ftol
+build-hm
+install
+
 # test output files
 Benchmarks/MeshFiles/Tests/*
 Benchmarks/PlotFiles/Tests/*

CMakeLists.txt

@@ -1,28 +1,26 @@
-CMAKE_MINIMUM_REQUIRED(VERSION 3.0.2)
+cmake_minimum_required(VERSION 3.5)
 
-SET(FFLAGS "-cpp -O" CACHE STRING "Fortran compiler flags")
+set(FFLAGS "-cpp -O" CACHE STRING "Fortran compiler flags")
 
-MESSAGE("---------------  cmake START -------------------")
-MESSAGE("-- FC:                   ${FC}")
-MESSAGE("-- FFLAGS:               ${FFLAGS}")
-MESSAGE("-- CMAKE_INSTALL_PREFIX: ${CMAKE_INSTALL_PREFIX}")
-MESSAGE("------------------------------------------------")
+message("---------------  cmake START -------------------")
+message("-- FC:                   ${FC}")
+message("-- FFLAGS:               ${FFLAGS}")
+message("-- CMAKE_INSTALL_PREFIX: ${CMAKE_INSTALL_PREFIX}")
+message("------------------------------------------------")
 
-SET(CMAKE_Fortran_COMPILER_INIT ${FC})
-SET(CMAKE_Fortran_FLAGS "${FFLAGS} ${CMAKE_Fortran_FLAGS}")
+set(CMAKE_Fortran_COMPILER_INIT ${FC})
+set(CMAKE_Fortran_FLAGS "${FFLAGS} ${CMAKE_Fortran_FLAGS}")
 
-FIND_PACKAGE(FTObjectLibrary REQUIRED)
+find_package(FTObjectLibrary REQUIRED)
 
-INCLUDE_DIRECTORIES("${FTOBJECTLIBRARY_INCLUDE_DIRS}")
+include_directories("${FTOBJECTLIBRARY_INCLUDE_DIRS}")
 
-PROJECT(HOHQMesh Fortran)
-SET(VERSION 1.0.2-pre)
-SET(CMAKE_VERBOSE_MAKEFILE ON)
+project(HOHQMesh Fortran)
 
-IF(NOT CMAKE_Fortran_COMPILER_SUPPORTS_F90)
-    MESSAGE(FATAL_ERROR "Fortran compiler does not support F90")
-ENDIF(NOT CMAKE_Fortran_COMPILER_SUPPORTS_F90)
+if(NOT CMAKE_Fortran_COMPILER_SUPPORTS_F90)
+    message(FATAL_ERROR "Fortran compiler does not support F90")
+endif(NOT CMAKE_Fortran_COMPILER_SUPPORTS_F90)
 
-ADD_SUBDIRECTORY(${CMAKE_SOURCE_DIR}/Source)
+add_subdirectory(${CMAKE_SOURCE_DIR}/Source)
 
 message("-- HOHQMESH -------------  cmake DONE --------------------")

README.md

@@ -26,6 +26,16 @@ FreeBSD. If you would like to use HOHQMesh directly from the command line,
 please continue reading the next sections for instructions on how to obtain
 the sources and compile HOHQMesh yourself.
 
+### Prerequisites
+To build and install HOHQMesh, you need the following tools:
+
+* A Fortran compiler (we recommend [GFortran](https://gcc.gnu.org/fortran/))
+* [GNU Make](https://www.gnu.org/software/make/)
+* [CMake](https://cmake.org/) (optional; only for CMake-based builds)
+
+Building on Linux and macOS should be straightforward, building on Windows requires
+[MSYS2](https://www.msys2.org/).
+
 
 ### Install with Spack
 You can install HOHQMesh using the [Spack package manager](https://spack.io).
@@ -58,6 +68,15 @@ before proceeding, which will download the `FTObjectLibrary` sources for you.
 This step is required only once.
 
 ### Building
+There are two ways to build HOHQMesh from source: Using plain `make` or by using
+[CMake](https://cmake.org/). The `make`-based build is conceptually simpler but only works
+as an in-source build, thus populating your HOHQMesh root directory with build artifacts.
+The CMake-based build is slightly more involved but also allows you to do out-of-source
+builds.
+
+HOHQMesh is tested to run with the `gfortran` and `ifort` compilers. We recommend the `gfortran` compiler. Our experience on the test suite is that it runs about 50% slower with the `ifort` compiler.
+
+#### Using plain `make`
 Enter the HOHQMesh directory and execute
 ```shell
 make
@@ -74,7 +93,41 @@ For example, to build HOHQMesh specifically with the Fortran compiler
 make -j 4 FC=gfortran-10
 ```
 
-HOHQMesh is tested to run with the `gfortran` and `ifort` compilers. We recommend the `gfortran` compiler. Our experience on the test suite is that it runs about 50% slower with the `ifort` compiler.
+#### Using CMake
+For a CMake-based build, you first need to build the 
+[FTObjectLibrary](https://github.com/trixi-framework/FTObjectLibrary), install it, and then
+build HOHQMesh itself. If you followed the steps for obtaining the sources
+[above](#obtaining-the-sources), all required files are already present.
+
+For convenience, we will assume that you are executing the following from within the
+HOHQMesh root directory. However, after modifying the paths appropriately, you can use these
+steps also from anywhere else:
+```shell
+# Build and install FTObjectLibrary
+mkdir build-ftol && cd build-ftol
+cmake ../Contrib/FTObjectLibrary/ -DCMAKE_INSTALL_PREFIX=../install
+cmake --build .
+cmake --install .
+cd ..
+
+# Build and install HOHQMesh
+mkdir build-hm && cd build-hm
+CMAKE_PREFIX_PATH=../install cmake .. -DCMAKE_INSTALL_PREFIX=../install
+cmake --build .
+cmake --install .
+cd ..
+
+# Copy HOHQMesh executable to root directory
+cp install/bin/HOHQMesh .
+```
+The HOHQMesh executable can be moved around freely and does not rely on any other files in
+the install prefix or in the build directories (which can thus be deleted safely if so desired).
+
+By default, HOHQMesh (and FTObjectLibrary) will be built by the standard Fortran compiler
+configured for CMake.  The compiler choice can be overridden by setting the environment
+variable `FC=<pathToCompiler>` when invoking the configure step of CMake, e.g.,
+```FC=gfortran-10 cmake ..`.
+
 
 ### Testing
 After building HOHQMesh, you can verify that everything works as expected by

Source/CMakeLists.txt

@@ -1,25 +1,25 @@
-PROJECT(HOHQMesh)
+set(HOHQMESH "HOHQMesh")
+set(HOHQMESH_LIB "hohqmesh")
 
-SET(HOHQMESH "HOHQMesh")
-SET(HOHQMESH_LIB "hohqmesh")
+file(GLOB_RECURSE HOHQMESH_SRC ${CMAKE_CURRENT_SOURCE_DIR} "*.f90")
 
-FILE(GLOB_RECURSE HOHQMESH_SRC ${CMAKE_CURRENT_SOURCE_DIR} "*.f90")
-
-SET(CMAKE_Fortran_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/include)
-
-ADD_LIBRARY(${HOHQMESH_LIB} STATIC 
-            ${HOHQMESH_SRC})
+set(CMAKE_Fortran_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/include)
 
-ADD_EXECUTABLE(${HOHQMESH} ${HOHQMESH_SRC})
-TARGET_LINK_LIBRARIES(${HOHQMESH} "${FTOBJECTLIBRARY_LIBRARY}")
+add_executable(${HOHQMESH} ${HOHQMESH_SRC})
+target_link_libraries(${HOHQMESH} "${FTOBJECTLIBRARY_LIBRARY}")
 
-# Install libhohqmesh.a
-INSTALL(TARGETS ${HOHQMESH_LIB} 
-        ARCHIVE DESTINATION lib
-        LIBRARY DESTINATION lib)
+install(TARGETS ${HOHQMESH})
 
+# Note: Separate library build disabled in https://github.com/trixi-framework/HOHQMesh/pull/123
+#       since it caused issues on macOS
+#
+# add_library(${HOHQMESH_LIB} STATIC 
+#             ${HOHQMESH_SRC})
+# 
+# Install libhohqmesh.a
+# INSTALL(TARGETS ${HOHQMESH_LIB} 
+#         ARCHIVE DESTINATION lib
+#         LIBRARY DESTINATION lib)
+#
 # Add .mod files to include/ directory 
-INSTALL(DIRECTORY ${CMAKE_BINARY_DIR}/include DESTINATION .)
-
-# Install HOHQMesh binary under bin/
-INSTALL(TARGETS ${HOHQMESH} DESTINATION bin)
+# install(DIRECTORY ${CMAKE_BINARY_DIR}/include DESTINATION .)