cmake build disregards CMAKE_BUILD_TYPE for the Visual Studio generator

I tried building via the command line interface:

cmake ../path_to_source -G "Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Release 
cmake --build .

But when I ran the built target I got some strange dll errors. II discovered that the built executable was the debug version of my application, even though I specified -DCMAKE_BUILD_TYPE=Release.

To actually build the release version of the executable I had to specify the config when triggering the build:

cmake --build . --config Release

The documentation for the build command do not mention this. Maybe it should be amended with this information:

I think the documentation of CMAKE_BUILD_TYPE already explains that behavior:

Specifies the build type on single-configuration generators.

This variable is only meaningful to single-configuration generators (such as Makefile Generators and Ninja) i.e. those which choose a single configuration when CMake runs to generate a build tree as opposed to multi-configuration generators which offer selection of the build configuration within the generated build environment.

Maybe the documentation for the CMake build command should be amended with similar information as well. Maybe something along the lines of:

“Note that multi-configuration generators will not use the CMAKE_BUILD_TYPE variable and hence default to a debug configuration unless another configuration is specified with the --config option.”