[cmake-developers] CMake policies

[Brad King]

On 11/19/2010 08:16 AM, Marcel Loose wrote:
> I have read these pieces of information before. However, from these
> pages, I couldn't really figure out how policies were supposed to work
> -- the whole OLD, NEW, WARN issue. The design document made that much
> clearer. So, I think the CMake documentation on Policies could be
> enhanced. 

The WARN mode is an implementation detail for "not set to OLD or NEW".
It should not appear in the API at all.  When cmake_policy(GET) is
asked about a policy that is not set to OLD or NEW (and is WARN
internally) then it reports the empty string.  Only developers that
are adding new policies need to understand such detail.

> It also wasn't really clear to me which policies are set be default. I
> know that for each policy described in the section Policies, there's a
> line saying "introduced in CMake <version>", but I didn't know that that
> also means that these policies are set to NEW by default when using
> CMake <version> or newer.

It's right there in the documentation of cmake_policy(VERSION):

"All policies introduced in the specified version or earlier will  be set
 to use NEW behavior. All policies introduced after the specified version
 will be unset."

which is referenced by cmake_minimum_required(VERSION):

 "When a version higher than 2.4 is specified the command implicitly invokes
  cmake_policy(VERSION major[.minor[.patch[.tweak]]])"

> I think a table providing a quick look-up would really be helpful.

Good idea.  It could be in the "Policies" section of the documentation.

> Finally, I think it would be good to cross-reference the commands
> cmake_policy and cmake_minimum_required, even though they appear
> immediately after one another.

The cmake_minimum_required command already references cmake_policy.
We could add one in the other direction in the introduction paragraph
to cmake_policy, right around the current sentence

 "Projects may set each policy to select the desired behavior."

Please construct a proposed patch for this and the above table.  You
can send it to me via "git format-patch".

> Now that I understand the concepts behind policies, I think it's a
> well-designed feature.

Thanks.

-Brad