[cmake-developers] [CMake 0015222]: Need a way to determine when features were introduced into cmake

[Mantis Bug Tracker]

The following issue has been SUBMITTED. 
====================================================================== 
http://www.cmake.org/Bug/view.php?id=15222 
====================================================================== 
Reported By:                Charles Karney
Assigned To:                
====================================================================== 
Project:                    CMake
Issue ID:                   15222
Category:                   CMake
Reproducibility:            always
Severity:                   feature
Priority:                   normal
Status:                     new
====================================================================== 
Date Submitted:             2014-10-28 08:08 EDT
Last Modified:              2014-10-28 08:08 EDT
====================================================================== 
Summary:                    Need a way to determine when features were
introduced into cmake
Description: 
Authors of cmake scripts face a challenge ensuring that their scripts
are portable.  This is exacerbated by

* cmake is constantly evolving (which is good!);

* their cmake scripts are run by a diverse set of users (also good!);

* authors have little control over the version of cmake that end-users
  have installed;

* the relationship with end-users is even more tenuous with the
  package-config scripts (which are not read by the builder of the
  package but by a developer using the package).

There is cmake_minimum_required, but authors would normally not want to
set this to too recent a version.

The problem is that it's difficult to know when a particular feature
appeared in cmake.  There's no single changelog (and the format of the
changelog doesn't make it easy to search in).  Frequently I'm left doing
a binary search in the documentation!  Sometimes I need install old
versions to check their behavior.

For example I just noticed that install (TARGET ...) also an INCLUDES
DESTINATION option.  This seemed like a feature I should be using until
I noticed that it only appeared in 2.8.12 (or thereabouts).

Suggestions:

* Have a developer mode where cmake behaves as though it were at the
  version given by cmake_minimum_required.  (Probably this is
  unfeasible?)

* In the documentation, specify when each command, command option,
  variable, etc., was introduced.  (Might junk up the documentation.)

* Split this information off into a separate document.  (My favored
  solution.)


Steps to Reproduce: 
N/A

Additional Information: 
N/A
====================================================================== 

Issue History 
Date Modified    Username       Field                    Change               
====================================================================== 
2014-10-28 08:08 Charles Karney New Issue                                    
======================================================================