Code Depreciation - CGAL/cgal GitHub Wiki

Although we try hard to stay backward compatible, sometimes changes are necessary. When such changes affect documented code, one possibility is to document breaking changes. The other, which should be preferred - especially in the case of removal or replacement of functionalities -, is to use depreciation. Depreciation introduces a warning at compilation for users, indicating that the way to use this functionality has been altered and users should update their code to alternatives. Deprecated code might be removed in the future, at least 2 major releases after it has been deprecated.

On this page we explain what should be done to depreciate a functionality. Note that the deprecation affects documented code and thus must go though the submission of a Small Feature.

Deprecating a Complete Header File

Sometimes a complete header gets deprecated, for example when it has been renamed. The following boiler plate code is self-explanatory:

#define CGAL_DEPRECATED_HEADER "<CGAL/AABB_polyhedral_oracle.h>"
#define CGAL_DEPRECATED_MESSAGE_DETAILS \
  "The 3D Mesh Generation package (see https://doc.cgal.org/latest/Mesh_3/) should be used instead."
#include <CGAL/Installation/internal/deprecation_warning.h>

Deprecating a Single Function

Deprecated code must be placed behind a macro - CGAL_NO_DEPRECATED_CODE. By defining this macro, one can ensure that no deprecated code is used within CGAL, or other downstream software.

Deprecated documentation uses the doxygen command \deprecated, and must document in which CGAL release did the depreciation happen, and give alternatives. The function itself is prefixed with the macro CGAL_DEPRECATED, which is nothing more than a wrapper around the C++ attribute [[deprecated]], but not all compilers support it.

#ifndef CGAL_NO_DEPRECATED_CODE

/*!
  \ingroup PkgSurfaceMeshIOFuncDeprecated
  \deprecated This function is deprecated since \cgal 5.3, `CGAL::IO::read_polygon_mesh()` should be used instead.
*/
template <typename K>
CGAL_DEPRECATED bool read_mesh(Surface_mesh<K>& sm, const std::string& filename);
#endif // CGAL_NO_DEPRECATED_CODE

Besides CGAL_DEPRECATED, another macro exists to issue a message during compilation:

template <class PolygonMesh>
CGAL_DEPRECATED_MSG("you are using the deprecated API of CatmullClark_subdivision(), please update your code")
void CatmullClark_subdivision(PolygonMesh& pmesh, int step);

Testing Deprecated Code

Although the code is deprecated, it should still be tested to ensure that it remains functional. To avoid false-positive deprecation warning / errors in testing code, the test must include the following specific header file before any other.

#include <CGAL/Installation/internal/disable_deprecation_warnings_and_errors.h>

Home

⚠️ **GitHub.com Fallback** ⚠️