Modernize CMake usage

[biagas]

It's time VisIt's CMake usage was updated to modern CMake.
I have created a branch and draft PR (#18257) demonstrating some of the new principles.

Some on-line resources I've read in this regard:

CMake's guide to importing and exporting

A github gist post from user mbinna

A blog post on the subject from Pablo Arias

A CPPCon2017 Tutorial on Using Modern CMake

Daniel Pfeifer's talk at cppcon 2017

Some take-aways:

• Use lowercase when calling CMake function/macros, uppercase is for variables
  • Question: Should VisIt-defined functions follow the same rule, and should they be prepended with visit_ ?
• Declare dependencies as PUBLIC or PRIVATE
• Don't use these cmake functions/macros, instead use the target-specific versions with the proper INTERFACE
  • include_directories
  • link_directories
• Export targets to Package config files.
• CMakeLists.txt should live as close to source as possible.
• Reduce creation of CMake variables (eg don't need to create a CMake variable to list a target's sources, unless that information is also needed elsewhere).
• Prefer creation of functions over macros, unless there is an output, then use macro. Related: cmake_parse_arguments is your friend.
• Don't add the condition in else or end calls unless needed for clarity.
• CMake now has 'automoc' capability, to automatically generate our Qt moc files, instead of us listing every file individually.
  • XMLEdit was changed to utilize automoc
• Our Find modules for TP libraries should utilize find_package(... CONFIG) option when we know the TP library provides CMake package configs. This will hopefully provide import targets that correctly populate their own INTERFACE_INCLUDE_DIRECTORIES and LINK_LIBRARIES properties.
  • For those TP that don't provide CMake package configs (or don't create them properly), there are two options:
    • Use CMake's Find module for the TP if available, because CMake's module may create the import targets for us
    • Create import targets manually from the results of our current Find logic for the TP library.
    • We should try CMake's first before creating our own.
    • In practice, I've noticed you actually need to know what the name of the target will be (eg find_package(zlib) creates a target named "ZLIB::ZLIB".
    • I modified our FindBoxlib as a demonstration for a third party that doesn't create cmake pkg files.

Additional proposals and questions:

• Reorganization of root CMakeLists.txt: lets make the root as simple as possible by moving functionality elsewhere:
  • move functions/macros into a separate files, based on functionality
    • VisItOptions,
    • ThirdParty library handling
    • Plugins
    • General (new VisItFunctions.cmake has already been created for general use).
    • setting up parallel (finding mpi, setting flags, etc) could be in its own file
    • Platform-specific logic in platform-specific files. This make sense if the logic is, say, only for WIndows or only for Mac.
• Should VisIt adopt use of CMake's GNUInstallDirs(link to doc), which sets up GNU standard installation directories (eg CMAKE_INSTALL_LIBDIR, location to install libs, based on arch: lib, lib64 or lib/multiarch-tuple on Debian). Could then possibly eliminate need for VISIT_INSTALLED_VERSION_LIB _BIN, etc.
• When it comes time to convert our Find modules for TP packages, should we make modifications to use the imported target directly or use our current XXX_LIBRARY naming convention
  • eg mfem instead of currently used ${MFEM_LIBRARY}, or ZLIB::ZLIB instead of ${ZLIB_LIBRARY}) ?
  • We can set the value of ${XXX_LIBRARY} to be the target, and AFAICT, CMake respects the imported target's interfaces.
• Should see if all current VisIt-defined CMake functions/macros are still necessary and being used.

The CMake package export is at the bottom of the root CMakeLists.txt. It currently is minimal and may need customizations.
I created a temporary folder to house the files that got created with 'make install' on Windows as an example.
visitConfig.cmake
visitConfigVersion.cmake
visitTargets.cmake
visitTargets-release.cmake

[griffin28]

Transitioning to CMake's ExternalProject module to create a VisIt Superbuild option that builds VisIt and all of the TP libraries would be a great way to integrate all of these changes into a pretty clean CMake build system for VisIt.

[cyrush]

We should have special topics meetings to chip away at this.

There are a lot of lessons / choices we should consider from Conduit, Ascent, etc.

TPLs are going to make a wide range of choices for the naming and style of find options and imported targets.
These have evolved as CMake has evolved -- we should always rectify those to a VisIt standard (via aliased targets, our own standard names etc) that we use in our build system.

BLT (https://github.com/llnl/blt) can also help here and is in use across many projects. It especially helps in the case that projects don't provide CONFIG targets.

For exporting VisIt targets so they can be imported -- will folks actually use VisIt in that way (as a library?) Would this be the case we expect for plugin development? There are a lot of nuances to get these exports right. For example:
https://github.com/LLNL/conduit/blob/56bee65f4f5db1c1d0cfba5b062484ff2870c409/src/config/ConduitConfig.cmake.in#L6

I personally don't like GNUInstallDirs b/c only a handful of projects use it and I have had to use special logic to handle those projects. Example: https://github.com/Alpine-DAV/ascent/blob/a5b8c20ca8b1e9ff67dfc02421c496370ee1576a/src/cmake/thirdparty/SetupKokkos.cmake#L21

That said, this might be b/c I had to supporting a wide range of CMakes.

I think the biggest class of changes and where we have the most choices are going to be related to TPL imports.

Also, should we buy some copies of the modern cmake book to digest more?

[markcmiller86]

Also, should we buy some copies of the modern cmake book to digest more?

I like the idea of having a "book" but FWIW my preference is something electronic that I can search easily.

[griffin28]

I found this book to be good. Pretty sure you can get it in an electronic format.

[markcmiller86]

Some other CMake resources (some of which are on line), https://bssw.io/items/cmake-tutorial-and-reference-resources

[biagas]

For exporting VisIt targets so they can be imported -- will folks actually use VisIt in that way (as a library?) Would this be the case we expect for plugin development?

I am expecting the export of VisIt targets to aid in plugin development against an installed VisIt, and hopefully do away with all the hacks and library path parsing we currently do. Would it help with libsim as well?

[cyrush]

That sounds like what we should aim for.

[biagas]

From our group discussion today:

• Add BLT as subproject for VisIt. Using BLT could simplify our Third Party logic.

• Create visit alias for Third Party imports, for consistent naming:

  • visit_tpl::zlib, visit_tpl::hdf5, etc
  • for vtk, see if commonly used targets can be grouped together, like visit_tpl::vtk_rendering, etc

• Visit exports: create plugin specific exports like 'visit::database_plugin' that has all the visit dependencies needed for a database plugin

• Update to newer CMake and make it the minimum version required. Kathleen will test 3.24.3 (latest release).

• Since this will be a large task, it will be completed in incremental stages for easier review.

  • Each stage should not break visit builds or testing.
  • It is understood that the plugin-vs-install tests will likely remain broken until the work is final, so they will be added to the skip list until then.

• visit defined CMake functions/macros will be renamed to use all-lowercase and prepend 'visit_' to the name.

[biagas]

@cyrush

TPLs are going to make a wide range of choices for the naming and style of find options and imported targets.
These have evolved as CMake has evolved -- we should always rectify those to a VisIt standard (via aliased targets, our own standard names etc) that we use in our build system.

In terms of 'aliased' targets, did you have something specific in mind?

I did some experimenting, first with Boxlib that doesn't have CMake config. I used the library and include information obtained from a find to create an import target for use with VisIt.

I tried creating a target with a namespaced name visit_tpl::Boxlib2d, but encountered issues with CMake when it came to using those. Using a prefix, eg visit_tpl_Boxlib2d worked better.

Right now we use CMake variables a lot for our TP libs, like ${BOXLIB2D_LIBRARY}.
Do we want to still use this paradigm, but change them to point to a proper CMake import target instead of just the library, or change to use the target names directly? The latter seems a bit more straightforward, especially when I think about using them in export sets for use with building plugins against an installed VisIt.

[cyrush]

If visit_ works better let's use that.

Ideally, we can logically group the TPL details into a single target (or into one for ser and one for par for some cases). Whatever you feel is the most tractable way to do this we should go with.

So, for example -- our own cmake target: visit_boxlib2d

Would handle all inlcude dirs, libs, and compiler options needed to use boxlib2d

[biagas]

Yes, creating our own cmake target is just what I was thinking. I have the boxlib version working on Windows. Hadn't considered the serial/parallel TP libs yet. I like the idea of adding ser and par like we do for VisIt targets.