Springclean CMake scripts and developer/client build/use interfaces

[drbenmorgan]

Whilst this may look a significant change from the diffs, it's primarily a clean and tidy of the CMake scripts and use for both developers and clients of PTL.

• Further "modern" CMake
  • Use of version ranges for CMake itself plus simpler PTL version handling/parsing
  • Canonical form of lowercase commands/macros/function, no repetition of conditional/loop in else()/endif()/end...() commands.
  • Use of target_compile_features to propagate the C++ standard to clients of PTL
  • CMake script simplification
  • Remove functions/macros/variables that are not used or can be replaced with CMake builtins
  • Some split/merge of modules on basis of responsibility and to try and keep options close to configuration required by that option (but this isn't hard and fast)
  • Add "report on change" for all options but reduce final reporting to enabled features only to make things a bit clearer. Things like compiler flags are not reported as these can change on a per-target or per build-mode basis, so only the actual compile commands are truly reliable here.
• Build simplification
  • Don't force PIC for static libs as this might be unexpected and can be left up to the builder/packager through the CMAKE_POSITION_INDEPENDENT_CODE variable
  • Creation of a PTL/Config.hh file to #define/#undef the PTL_USE_LOCKS and PTL_USE_TBB symbols. Since these determine (AFAICT) the API/ABI of PTL, they've got to be propagated to clients and this saves having to transport -D flags around.
  • The Threads::Threads and TBB::tbb targets are now linked directly to PTL rather than an intermediary INTERFACE target given the simplicity of the link required.
  • Despite modern CMake preferring targets, the flags for sanitisation/coverage have been migrated to append to the CMAKE_..._FLAGS instead of via INTERFACE targets. Given that these flags aren't propagated to the usage requirements of an installed PTL, setting via the FLAGS variables is o.k (and even suggested by CMake and used in VTK among others). This also results in less code and prevents the need to export and setup what become essentially empty interface targets in the install (since the flags only apply to the BUILD_INTERFACE), or to deal with potentially complex genexes (to only link in the BUILD_INTERFACE).
• Simpler support for using PTL as a CMake subproject via add_subdirectory
  • This part is somewhat specific to the Geant4 experience of vendoring PTL...
  • PTL options are no longer exposed directly to the user (i.e. they are not in the cache/GUI), but may still be set directly or exposed as options by the parent project if required. e.g. In Geant4, we have a GEANT4_USE_TBB option, so we don't want to expose the PTL_USE_TBB equivalent, just set it on the basis of the Geant4 one).
• Unify the PTLConfig.cmake.in template for the build and install trees
  • Primarily a simplification so that the differences in including/using the targets is handled fully by the PTLTargets.cmake files that's generated for each.
• Initial configuration/install of a pkg-config file for TBB
  • CMake's great, but good to support the other main tool for finding/using packages!
• Examples are now built all-in one, so can focus on the code rather than the build scripts

Even with all of that, there are a couple of things missing:

• I could not get the gpu example building either from the current master or here, so I'm not sure of its state or which CUDA/setup is needed.
• I'm not 100% sure that all the DLL export symbols will be consistent on Windows
  • There's PTL_ALLOC_EXPORT set as a -D flag globally at build time (so it is set when compiling examples)
  • There's also LIB_BUILD_DLL in source/PTL/Types.hh
  • The PTLConfig.cmake file sets _PTL_ARCHIVE as an interface compile definition of PTL::ptl but this symbol isn't present in the code anywhere.

Anyway, there's way more than enough already in this PR...

[jrmadsen]

@drbenmorgan Can you check that #8 (reproducible build) is still valid?

[drbenmorgan]

Good spot! I've fixed a mistake that was exporting a build tree path to the installed PTLConfig.cmake file. I've checked that different build/install dirs result in identical installed versions of PTLConfig.cmake per the issue in #8.

[jrmadsen]

Don't force PIC for static libs as this might be unexpected and can be left up to the builder/packager through the CMAKE_POSITION_INDEPENDENT_CODE variable

So I generally prefer to distribute these static libraries as PIC since the general idea behind static vs. shared libraries are static libraries copy the symbols by value whereas shared libraries copy the symbols by reference. Thus, its my understanding that if one is building libG4tasking.a as non-PIC then the PIC libptl.a symbols are copied into libG4tasking.a and effectively converted into non-PIC -- eliminating the runtime performance penalty.

[drbenmorgan]

So I generally prefer to distribute these static libraries as PIC since the general idea behind static vs. shared libraries are static libraries copy the symbols by value whereas shared libraries copy the symbols by reference. Thus, its my understanding that if one is building libG4tasking.a as non-PIC then the PIC libptl.a symbols are copied into libG4tasking.a and effectively converted into non-PIC -- eliminating the runtime performance penalty.

The argument to have non-PIC the default is that it's just that - generally users/packagers etc (and CMake itself) expect/default to non-PIC statics. CMake defaults, as does Autotools, to build non-PIC statics, but anticipates the use case of building them PIC by offering the CMAKE_POSITION_INDEPENDENT_CODE option (--with-pic in lib tool). If that's forced to ON in the scripts or the target property hard-coded, there's no way to change it.

Looking around different Linux distro packaging guidelines, some require non-PIC statics, others PIC, but the general expectation seems to be that statics are default built without PIC, or at least provide a documented/easy way to change this.

One could provide an additional CMake option in PTL to disable PIC, but given CMake provides a good and clear one already, it just feels simpler/cleaner/less surprising to use that along with the default non-PIC case, i.e.

# default, builds ptl-static non-PIC
cmake <args>

# at user discretion, build ptl-static with PIC
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON <args>

[jrmadsen]

@drbenmorgan Sorry for the delay, I will get this merged before the end of this next week.

[drbenmorgan]

@jrmadsen The remaining failure on clang-12 looks to be down to the change to not export nominally developer-only flags like sanitisers. I'm not totally sure why the other builds are fine with similar configurations though. Will try and reproduce locally.

[jrmadsen]

Ok @drbenmorgan the only way to fix it is to do:

    if(PTL_USE_SANITIZER AND NOT ("${PTL_SANITIZER_TYPE}" STREQUAL "leak"))
        string(REPLACE " " ";" _sanitize_args "${ptl_sanitize_args}")
        set_target_properties(ptl-shared PROPERTIES
            INTERFACE_LINK_OPTIONS "${_sanitize_args}")
    endif()

This is effectively just ensuring that libtsan or libasan is linked into the final exe.

[jrmadsen]

@drbenmorgan LMK if these changes work for you

[drbenmorgan]

Thanks for the updates @jmadsen, and apologies this totally slipped my mind. I'll try these out ASAP next week and post back here.

[jrmadsen]

@drbenmorgan I am just going to merge this