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.
• [ ] Fix Opencascade throwing errors when used with -Werror (by using "-isystem" instead of "-I"?)

[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