TODOS for fully featured CMake Build System

[jmark]

A non-exhaustive list of open todos for the still experimental cmake build system in t8code:

• [x] Build t8code in Github CI
• [x] Run tests in Github CI
• [x] Add compile with OCC option
• [ ] Reorganize CMakeLists.txt files. Maybe adapt the structure as done in libsc/p4est.
• [x] Support MPI parallel testing.
• [x] Add enable debug mode option
• [x] Add external libsc and/or external p4est option
• [x] Write detailed wiki article about compiling t8code with cmake
• [ ] Investigate other compiler and/or linker utilities to speed-up building, e.g. https://github.com/rui314/mold
• [x] Automatic generation of documentation. For example with doxygen.
• [ ] Generation of release tarballs.
• [ ] Convert the tarball test to cmake
• [x] #1236
• [ ] Add ENABLE FORTRAN option.
• [ ] (Re-)build all unit tests when calling make test or make check or similar.

[dutkalex]

Write detailed wiki article about compiling t8code with cmake

Regarding documentation, I already provided a basic (incomplete but better than nothing) wiki page file in #929 (grep for Installation-CMake.md)

[dutkalex]

Add enable debug mode option

I believe that with what is already currently in main, it is possible to achieve the equivalent for configure CFLAGS="-Wall -O0 -g" CXXFLAGS="-Wall -O0 -g" --enable-mpi --enable-debug --enable-static --disable-shared CC=mpicc CXX=mpicxx with something like cmake .. -DCMAKE_BUILD_TYPE=Debug -DT8CODE_ENBALE_MPI=ON -DT8CODE_BUILD_AS_SHARED_LIBRARY=OFF

[jmark]

Write detailed wiki article about compiling t8code with cmake

Regarding documentation, I already provided a basic (incomplete but better than nothing) wiki page file in #929 (grep for Installation-CMake.md)

Thanks for reminding! Has been incorporated: https://github.com/DLR-AMR/t8code/wiki/Installation#build-t8code-with-cmake

[jmark]

Add enable debug mode option

I believe that with what is already currently in main, it is possible to achieve the equivalent for configure CFLAGS="-Wall -O0 -g" CXXFLAGS="-Wall -O0 -g" --enable-mpi --enable-debug --enable-static --disable-shared CC=mpicc CXX=mpicxx with something like cmake .. -DCMAKE_BUILD_TYPE=Debug -DT8CODE_ENBALE_MPI=ON -DT8CODE_BUILD_AS_SHARED_LIBRARY=OFF

There is a T8_ENABLE_DEBUG macro in t8code. This is not set by any cmake option as of now.

[dutkalex]

Ah yes indeed! This should be very easy to fix though EDIT: see #956 @jmark

[CsatiZoltan]

I would also add the documentation building to the list. My project is based on CMake and uses t8code. To generate the API documentation for my project, I use Doxygen. It is a build target, so I just have to type make docs to regenerate the HTML output of the documentation. I can share my CMakeFiles.txt if you want.

[cburstedde]

I would also add to the list the documentation building. My project is based on CMake and uses t8code. To generate the API documentation for my project, I use Doxygen. It is a build target, so I just have to type make docs to regenerate the HTML output of the documentation. I can share my CMakeFiles.txt if you want.

In the autoconf system we use make doxygen. There is by now a good working structure in p4est and libsc using doc and doc/doxygen. Would it be synergetic to align the t8code doxygen generation by CMake analogously?

[CsatiZoltan]

Would it be synergetic to align the t8code doxygen generation by CMake analogously?

That I don't know. I am not a core developer of t8code, so I just propose ideas. @jmark could answer this question better.

[jmark]

Would it be synergetic to align the t8code doxygen generation by CMake analogously?

That I don't know. I am not a core developer of t8code, so I just propose ideas. @jmark could answer this question better.

@CsatiZoltan Thank you for bringing up this suggestion! Is added to the list! You can send me the lines from yourCMakeList.txt or alternatively create a PR adding this feature. I can take over then from there.

@cburstedde Your suggestions using doxygen sounds reasonable! If you allow to do so I'll take inspiration from the documentation structure in libsc and p4est. I think there already is a doxygen infrastructure in t8code. I'll check it out and report back.

[CsatiZoltan]

My main CMakeList.txt (minor modifications added to this code):

cmake_minimum_required(VERSION 3.12.0) # VTK requires CMake 3.12 in order to reliably be used
project(PROJ DESCRIPTION "Your project description" VERSION 0.1.0 LANGUAGES C CXX)

add_subdirectory(examples)
add_subdirectory(tests)

# Documentation
find_package(Doxygen)

if(DOXYGEN_FOUND)
    set(PROJ ${CMAKE_CURRENT_SOURCE_DIR})
    set(PROJ_SRC ${PROJ}/src)
    set(PROJ_DOC ${PROJ}/docs)
    set(PROJ_EXAMPLES ${PROJ}/examples)

    # set input and output files
    set(DOXYGEN_IN ${PROJ_DOC}/Doxyfile.in)
    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.out)

    # request to configure the file
    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
    message("Doxygen build started")

    # Note: do not put "ALL" - this builds docs together with application EVERY TIME!
    add_custom_target(docs
        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "Generating API documentation with Doxygen"
        VERBATIM)
else(DOXYGEN_FOUND)
    message("Doxygen need to be installed to generate the doxygen documentation")
endif(DOXYGEN_FOUND)

To make sure that the user or the CI uses a recent-enough Doxygen (older versions may not have the keywords that you expect), you can check for a minimum version.

---

My Doxyfile.in fetches the values of the environment variables that exist when the cmake build is called. Relevant entries:

PROJECT_NAME           = @CMAKE_PROJECT_NAME@
OUTPUT_DIRECTORY       = @CMAKE_CURRENT_BINARY_DIR@/docs/
CITE_BIB_FILES         = @PROJ_DOC@/references.bib
INPUT                  = @PROJ_SRC@ \
                         @PROJ_EXAMPLES@ \
                         @PROJ_DOC@/mainpage.dox \
                         @PROJ_DOC@/about.dox \
                       # $(T8_INCLUDE) \
HTML_FOOTER            = @PROJ_DOC@/doxygen_footer.html

[dutkalex]

Reorganize CMakeLists.txt files. Maybe adapt the structure as done in libsc/p4est.

IMHO the libsc/p4est structure is not the way to go. The build system is code, just like the rest of the repo, and we should apply the same best practices as for any other piece of code (encapsulation, separation of concerns etc.). The p4est build system falls short of these requirements on several aspects:

• the cmake folder should be dedicated to implementation details and FindXXX.cmake files. High-level aspects such as config options, and everything the user should be aware of generally speaking, belong in the top-level CMakeLists.txt file(s)
• including a cmake/XXX.cmake file should not have side effects. I know that this can be tricky to achieve sometimes, but it should nevertheless be what we strive for...
• The build system should be designed with inclusion into downstream projects in mind. This means that CMAKE_XXX variables should not be hardcoded, or that variable names should be prefixed to avoid name collisions for example