After giving the new Ninja Multi-Config generator a spin and trying to wrap my head around its associated documentation, I’m concerned that things are currently more confusing than they should be and that the defaults are not consistent with the behavior of other multi-config generators. There seems to be too much focus on cross-config support at the expense of the much more likely scenario where cross-config support isn’t needed. I think we can and should address this before the 3.17 release.
Default configuration (part 1)
My first experience was typing
ninja with no command line arguments and being met with an error that
build.ninja was missing. I later worked out that I had to set the
CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG variable if I wanted that to work. For other multi-config generators like Xcode and Visual Studio, you get the Debug config by default if you don’t specify a configuration. Indeed, if you do
cmake --build . without specifying
--config, you also get the Debug configuration with the Ninja Multi-Config generator, so it seems inconsistent that invoking the
ninja build tool directly doesn’t work out-of-the-box.
After wrapping my head around the relevant variables, it seems to me that we shouldn’t need the
CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG variable at all. In my opinion, we should always have a default config if one isn’t specified and we can use the first one listed in the
CMAKE_CONFIGURATION_TYPES variable for that choice. This is what the Xcode generator does. The Visual Studio generator always builds the Debug config by default if you invoke
msbuild from the command line without specifying a configuration, but the Xcode generator’s behavior is more intuitive (to me). Edit: Invoking
xcodebuild directly will build the first config in
CMAKE_CONFIGURATION_TYPES, but invoking
cmake --build apparently always builds the Debug config regardless of the generator type (see this comment by @kyle.edwards) .
Proposed change: Get rid of
CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG and use the first config listed in
CMAKE_CONFIGURATION_TYPES instead. This also means there will always be a default configuration and there will always be a
Default configurations (part 2)
CMAKE_NMC_DEFAULT_CONFIGS variable is currently used to define the set of configs that should be built if no configuration is specified when providing a target. I’m wondering if we really should be providing this. Shouldn’t that be the job of whatever is driving the build step? You can loop over the configs if driving it from a script. For an end user, how often is anyone realistically going to want to build more than one config in a non-scripted scenario? I’m sure there are valid use cases for this, but I have reservations whether the complexity and potential confusion this feature introduces is worth it.
Proposed change: Remove the support for building multiple configs with one command. This will mean we can remove
The use of
_NMC in the variable names is not particularly user-friendly – new users probably won’t know what it stands for if they see the variable without any context (e.g. in a project’s scripts, etc.). I’m wondering if we need to specify anything generator-specific in these variable names at all. We could leave it out and then document that those variables only apply to the Ninja Multi-Config generator. Other generators could just ignore them, or if they gain equivalent functionality in the future, then we already have the api ready to support it for them.
Proposed change: Remove the
_NMC_ from any variable names and document them as only being supported by the Ninja Multi-Config generator.
The main Ninja Multi-Config documentation page could be reworked to give the reader a gentler introduction to the features. I would recommend moving things related to cross-configs to a dedicated section at the end of the page. Let the start of the page be about multi-config support that looks and behaves like the other multi-config generators. That will encourage more people to try it out, especially if they are already familiar with Xcode or Visual Studio. We already acknowledge that most people probably won’t be interested in cross-config support, so better to leave it to the end where those not interested in it can just skip it and be happy with the basic features.
Proposed change: Rework the Ninja Multi-Config generator’s main doc page to move the cross-config contents to its own section at the end.
Documentation of individual variables
The separate pages that document each variable contain minimal content and instead refer back to the main Ninja Multi-Config page for details. This seems backwards. These separate pages are supposed to be the definitive reference for these variables, so they should be the most detailed and contain all information relevant to them.
Proposed change: Move the detailed descriptions into the individual variable pages and use the main Ninja Multi-Config generator page to focus on examples and how the variables work together. The main generator page could become more scenario-based rather than feature/variable-based.