.. cmake-manual-description: CMake Developer Reference
cmake-developer(7)
******************
.. only:: html
.. contents::
Introduction
============
This manual is intended for reference by developers modifying the CMake
source tree itself.
Permitted C++ Subset
====================
CMake is required to build with ancient C++ compilers and standard library
implementations. Some common C++ constructs may not be used in CMake in order
to build with such toolchains.
std::vector::at
---------------
The ``at()`` member function of ``std::vector`` may not be used. Use
``operator[]`` instead:
.. code-block:: c++
std::vector<int> someVec = getVec();
int i1 = someVec.at(5); // Wrong
int i2 = someVec[5]; // Ok
std::string::append and std::string::clear
------------------------------------------
The ``append()`` and ``clear()`` member functions of ``std::string`` may not
be used. Use ``operator+=`` and ``operator=`` instead:
.. code-block:: c++
std::string stringBuilder;
stringBuilder.append("chunk"); // Wrong
stringBuilder.clear(); // Wrong
stringBuilder += "chunk"; // Ok
stringBuilder = ""; // Ok
std::set const iterators
------------------------
The ``find()`` member function of a ``const`` ``std::set`` instance may not be
used in a comparison with the iterator returned by ``end()``:
.. code-block:: c++
const std::set<std::string>& someSet = getSet();
if (someSet.find("needle") == someSet.end()) // Wrong
{
// ...
}
The return value of ``find()`` must be assigned to an intermediate
``const_iterator`` for comparison:
.. code-block:: c++
const std::set<std::string>& someSet;
const std::set<std::string>::const_iterator i = someSet.find("needle");
if (i != propSet.end()) // Ok
{
// ...
}
Char Array to ``string`` Conversions with Algorithms
----------------------------------------------------
In some implementations, algorithms operating on iterators to a container of
``std::string`` can not accept a ``const char*`` value:
.. code-block:: c++
const char* dir = /*...*/;
std::vector<std::string> vec;
// ...
std::binary_search(vec.begin(), vec.end(), dir); // Wrong
The ``std::string`` may need to be explicitly constructed:
.. code-block:: c++
const char* dir = /*...*/;
std::vector<std::string> vec;
// ...
std::binary_search(vec.begin(), vec.end(), std::string(dir)); // Ok
std::auto_ptr
-------------
Some implementations have a ``std::auto_ptr`` which can not be used as a
return value from a function. ``std::auto_ptr`` may not be used. Use
``cmsys::auto_ptr`` instead.
std::vector::insert and std::set
--------------------------------
Use of ``std::vector::insert`` with an iterator whose ``element_type`` requires
conversion is not allowed:
.. code-block:: c++
std::set<const char*> theSet;
std::vector<std::string> theVector;
theVector.insert(theVector.end(), theSet.begin(), theSet.end()); // Wrong
A loop must be used instead:
.. code-block:: c++
std::set<const char*> theSet;
std::vector<std::string> theVector;
for(std::set<const char*>::iterator li = theSet.begin();
li != theSet.end(); ++li)
{
theVector.push_back(*li);
}
std::set::insert
----------------
Use of ``std::set::insert`` is not allowed with any source container:
.. code-block:: c++
std::set<cmTarget*> theSet;
theSet.insert(targets.begin(), targets.end()); // Wrong
A loop must be used instead:
.. code-block:: c++
ConstIterator it = targets.begin();
const ConstIterator end = targets.end();
for ( ; it != end; ++it)
{
theSet.insert(*it);
}
.. MSVC6, SunCC 5.9
Template Parameter Defaults
---------------------------
On ancient compilers, C++ template must use template parameters in function
arguments. If no parameter of that type is needed, the common workaround is
to add a defaulted pointer to the type to the templated function. However,
this does not work with other ancient compilers:
.. code-block:: c++
template<typename PropertyType>
PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
PropertyType* = 0) // Wrong
{
}
.. code-block:: c++
template<typename PropertyType>
PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
PropertyType*) // Ok
{
}
and invoke it with the value ``0`` explicitly in all cases.
std::min and std::max
---------------------
``min`` and ``max`` are defined as macros on some systems. ``std::min`` and
``std::max`` may not be used. Use ``cmMinimum`` and ``cmMaximum`` instead.
size_t
------
Various implementations have differing implementation of ``size_t``. When
assigning the result of ``.size()`` on a container for example, the result
should be assigned to ``size_t`` not to ``std::size_t``, ``unsigned int`` or
similar types.
Templates
---------
Some template code is permitted, but with some limitations. Member templates
may not be used, and template friends may not be used.
Adding Compile Features
=======================
CMake reports an error if a compiler whose features are known does not report
support for a particular requested feature. A compiler is considered to have
known features if it reports support for at least one feature.
When adding a new compile feature to CMake, it is therefore necessary to list
support for the feature for all CompilerIds which already have one or more
feature supported, if the new feature is available for any version of the
compiler.
When adding the first supported feature to a particular CompilerId, it is
necessary to list support for all features known to cmake (See
:variable:`CMAKE_C_COMPILE_FEATURES` and
:variable:`CMAKE_CXX_COMPILE_FEATURES` as appropriate), where available for
the compiler.
It is sensible to record the features for the most recent version of a
particular CompilerId first, and then work backwards. It is sensible to
try to create a continuous range of versions of feature releases of the
compiler. Gaps in the range indicate incorrect features recorded for
intermediate releases.
Generally, features are made available for a particular version if the
compiler vendor documents availability of the feature with that
version. Note that sometimes partially implemented features appear to
be functional in previous releases (such as ``cxx_constexpr`` in GNU 4.6,
though availability is documented in GNU 4.7), and sometimes compiler vendors
document availability of features, though supporting infrastructure is
not available (such as ``__has_feature(cxx_generic_lambdas)`` indicating
non-availability in Clang 3.4, though it is documented as available, and
fixed in Clang 3.5). Similar cases for other compilers and versions
need to be investigated when extending CMake to support them.
When a vendor releases a new version of a known compiler which supports
a previously unsupported feature, and there are already known features for
that compiler, the feature should be listed as supported in CMake for
that version of the compiler as soon as reasonably possible.
Standard-specific/compiler-specific variables such
``CMAKE_CXX98_COMPILE_FEATURES`` are deliberately not documented. They
only exist for the compiler-specific implementation of adding the ``-std``
compile flag for compilers which need that.
Help
====
The ``Help`` directory contains CMake help manual source files.
They are written using the `reStructuredText`_ markup syntax and
processed by `Sphinx`_ to generate the CMake help manuals.
.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
.. _`Sphinx`: http://sphinx-doc.org
Markup Constructs
-----------------
In addition to using Sphinx to generate the CMake help manuals, we
also use a C++-implemented document processor to print documents for
the ``--help-*`` command-line help options. It supports a subset of
reStructuredText markup. When authoring or modifying documents,
please verify that the comman