CMake: Support RelWithDebInfo configuration

[bscottm]

Support optimized compiles with debugging info (e.g., "-O2 -g" for GCC/Clang.) Useful with 'valgrind' to produce intelligible output.

[pmetzger]

An Oxford comma would be good here, I think. It gets confusing otherwise.

[pmetzger]

Oxford comma is less needed here but I'd still recommend it.

[bscottm]

@pmetzger: My writing habits were pretty ingrained by my PhD advisor's admin, who proofed and edited my dissertation. She completely disabused me of writing with Oxford commas. Happy to have a five gin martini debate elsewhere.

[pmetzger]

She was wrong. Without an oxford comma, technical documentation becomes ambiguous. https://medium.com/english-language-style-usage/the-oxford-comma-15e3fb65ce21 and many other links will explain the issue.

[pmetzger]

I recommend an Oxford comma again.

[pmetzger]

FYI, I've applied a version of this to the ZIMH repository on a branch; see pmetzger/zimh@3b0346c9

[LegalizeAdulthood]

What's amazing to me is how much all of this isn't needed if you just use CMake presets, which have been available since November, 2020.

[pmetzger]

I'm always happy to get advice from CMake experts. I had no idea that CMake presets existed, but I am not a CMake expert; CMake is a big, complicated system and I don't know enough about using it. Thank you for pointing out their existence.

[LegalizeAdulthood]

For the benefit of readers, I'll summarize. The details are all covered in the CMake-Presets documentation.

The reason that people write helper scripts, like the powershell script in this PR, is because typing command lines like this more than once becomes tedious:

# configure
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_TESTING=OFF -B ../my-preferred-build-dir -S . -G "Ninja Multi-Config"
# build
cmake --build ../my-preferred-build-dir --config RelWithDebInfo
# we skipped the tests, so don't run ctest
# package
cd ../my-preferred-build-dir
cpack --config CPackConfig.cmake -G ZIP -C RelWithDebInfo

A preset is a JSON file that contains settings that you would normally by typing as command-line arguments above. For instance, the entirety of the above can be accomplished with a workflow preset:

cmake --workflow easy-peasy

The workflow preset defines the steps of configure, build and package:

"workflowPresets": [ {
  "name": "easy-peasy",
  "steps": [
    { "type": "configure", "name": "easy-peasy" },
    { "type": "build", "name": "easy-peasy" },
    { "type": "package", "name": "easy-peasy" }
    ]
} ]

With the corresponding configure preset:

"configurePresets":[{
  "name": "easy-peasy",
  "generator": "Ninja Multi-Config",
  "binaryDir": "../my-preferred-build-dir",
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "RelWithDebInfo",
    "BUILD_TESTING": false
  }
}]

and build preset:

"buildPresets": [{
  "name": "easy-peasy",
  "configurePreset": "easy-peasy",
  "configuration": "RelWithDebInfo"
}]

and package preset:

"packagePresets": [{
  "name": "easy-peasy",
  "configurePreset": "easy-peasy",
  "generators": [ "ZIP" ],
  "configurations": [ "RelWithDebInfo" ]
}]

For a small project, this probably suffices, but if you want to get fancier, you can define presets as building blocks and use an inheritance chain to compose presets together. There's also a limited form of macro expansion, access to environment variables and conditional usage of presets (for instance, disabling a preset that is macOS specific on a host environment that isn't macOS).

This is why I say that these helper scripts designed to supply repeated arguments to CMake, CTest, and CPack are superfluous. Presets already handle all that. This repository doesn't (yet) have a CMakePresets.json file that would define presets for everyone to use, but you can always create your own presets in the file CMakeUserPresets.json (which shouldn't be added to source control as it's not designed to be shared; use CMakePresets.json for shared presets).

In addition to making your life at the command-line easier, being a well-defined JSON file with a schema to validate the contents, various IDEs and other tools understand how to parse preset files and can supply you with options in the IDE to say "use this preset". Bespoke helper scripts will never be understood by IDEs and other tooling.