[cmake-developers] cmake --help-concept

[Stephen Kelly]

Hi there,

There are a few concepts in CMake whose documentation is dotted around 
various places, but without a single location to learn about the concept 
itself, how it should be used, and what needs to be kept in mind when using 
it.

A new documentation section for concepts could be introduced.

For example,

* cmake --help-concept usage_requirements

Describe the INTERFACE_ properties, that the requirements can be exported, 
commands used to populate the properties, tll to use them, and overriding 
the order with 

 target_include_directories(foo 
   PRIVATE $<TARGET_PROPERTY:bar,INCLUDE_DIRECTORIES>)

etc.


* cmake --help-concept generator_expressions

Describe how they are evaluated (and should be read), where they are needed 
and what they're useful for (config-specific things mostly), file(GENERATE) 
etc.


* cmake --help-concept imported_targets

How to export targets, creating a FooConfig.cmake and what should be in it 
etc.


* cmake --help-concept compiler_features

List possible compiler_feature names and meanings (eg, the final 
compiler_feature means sealed on old MSVC).


What do you think?

Thanks,

Steve.