cmake-3.1.1-Linux-x86_64.tar.gz

.. 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