// bsls_deprecatefeature.h -*-C++-*-
#ifndef INCLUDED_BSLS_DEPRECATEFEATURE
#define INCLUDED_BSLS_DEPRECATEFEATURE
//@PURPOSE: Provide machinery to deprecate entities in C++ code.
//
//@MACROS:
// BSLS_DEPRECATE_FEATURE: mark a C++ entity as deprecated
//
//@DESCRIPTION: This component provides facilities to identify deprecated C++
// entities. The deprecation annotations supplied by this component may,
// depending on the build configuration, instantiate as C++ '[[deprecated]]'
// annotations for which the compiler will emit a warning. Each deprecated
// entity annotated by the macros in this component is identified by a 'UOR'
// and 'FEATURE', allowing the use of that deprecated entity to be more easily
// uniquely identified and tracked over time via tooling. Here "UOR" means
// Unit-Of-Release, which is typically a package, package-group or library.
//
// **WARNING**: The build configuration flag,
// 'BB_DEPRECATE_ENABLE_ALL_DEPRECATIONS_FOR_TESTING', that enables compiler
// warnings for 'BSLS_DEPRECATE_FEATURE' should not be used in
// cross-organizational integration builds such as a production 'unstable'
// dpkg build.
//
///Concerns with Compiler Warnings
///- - - - - - - - - - - - - - - -
// In large development organization, where many teams may enable "warnings as
// errors", enabling deprecation warnings in a cross-organizational integration
// build will frequently prevent lower-level software from applying the
// deprecation annotation to any newly deprecated code.
//
// Instead this component is designed to support static analysis tools that
// identify deprecated entities, and allow them to be tracked and reported by
// systems outside of the normal compilation process. The expectation is that
// developers would use configuration options that generate compiler warnings
// in local builds when they are actively working to remove the use of
// deprecated code.
//
///Macro Reference
///---------------
// This section documents the preprocessor macros defined in this component.
//
//: 'BSLS_DEPRECATE_FEATURE(UOR, FEATURE, MESSAGE)':
//: This macro is used to annotate code to indicate that a name or entity
//: has been deprecated, and is associated with the specified 'UOR'
//: (Unit-Of-Release), deprecated 'FEATURE', and 'MESSAGE'. This macro can
//: be used as if it were the C++ standard attribute '[[deprecated]]', and
//: in appropriate build configurations will instantiate as a C++
//: '[[deprecated]]' annotation. 'UOR' and 'FEATURE' are character strings
//: intended to uniquely identify one or more related entities that have
//: been deprecated. 'MESSAGE' is a descriptive text intended for the a
//: user of the deprecated feature (for example informing them of a
//: replacement feature). For example, if several of the date and time
//: types in the 'bde' library were deprecated they might be marked with the
//: annotation:
//: 'BSLS_DEPRECATE_FEATURE("bde", "date-and-time", "Use bdlt instead")'.
//: 'UOR' and 'FEATURE' are meant to help uniquely identify a deprecation in
//: external systems (e.g., a dashboard monitoring the state of a
//: deprecation) so the supplied strings should start with a letter, and
//: contain only letters, numbers, underscore, and dash characters (i.e.,
//: matching the regular expression "[a-zA-Z][\w\-]*").
//:
//: 'BSLS_DEPRECATE_FEATURE_IS_SUPPORTED': This macro is defined if the
//: current platform supports instantiating the deprecation annotation
//: macros into annotation understood by the compiler.
//:
//: 'BSLS_DEPRECATE_FEATURE_ANNOTATION_IS_ACTIVE': This macro is defined if
//: deprecation annotation macros defined in this component *will* be
//: instantiated into annotations understood by the compiler (i.e., this
//: will be defined if 'BSLS_DEPRECATE_FEATURE_SUPPORTED_PLATFORM' is
//: defined and the build configuration macros are configured in a way
//: that the annotations will instantiate as the '[[deprecated]]'
//: attribute).
//
///Configuration Reference
///-----------------------
// There are a set of macros, not defined by this component, that users may
// supply (e.g., to their build system) to configure the behavior of the
// deprecation annotation macros provided by this component.
//
// The available configuration macros are described below:
//..
// * 'BB_DEPRECATE_ENABLE_ALL_DEPRECATIONS_FOR_TESTING': This macro, when
// defined, enables the instantiation of every deprecation macro as a C++
// '[[deprecated]]' annotation. This *MUST* *NOT* be defined as part of
// cross-organization integration build such as an 'unstable' dpkg build
// (see {Concerns with Compiler Warnings}).
//
// * 'BB_DEPRECATE_ENABLE_JSON_MESSAGE': Changes the messages reported by
// compiler deprecation annotations to be a JSON document intended to
// be useful for tools looking to identify and categorize deprecations.
//
// * 'BSLS_DEPRECATE_FEATURE_ENABLE_ALL_DEPRECATIONS_FOR_TESTING': This macro
// is a synonym for 'BB_DEPRECATE_ENABLE_ALL_DEPRECATIONS_FOR_TESTING'.
//
// * 'BSLS_DEPRECATE_FEATURE_ENABLE_JSON_MESSAGE': This macro is a synonym for
// 'BB_DEPRECATE_ENABLE_JSON_MESSAGE'.
//..
//
///Usage
///-----
// In this section we show intended usage of this component.
//
///Example 1: Deprecating a Feature
/// - - - - - - - - - - - - - - - -
// The following example demonstrates using the 'BSLS_DEPRECATE_FEATURE' macro
// to deprecate several C++ entities.
//
// The 'BSLS_DEPRECATE_FEATURE' macro can be applied in the same way as the C++
// '[[deprecated]]' annotation. For example, imagine we are deprecating a
// function 'oldFunction' in the 'bsl' library as part of migrating software to
// the linux platform, we might write:
//..
// BSLS_DEPRECATE_FEATURE("bsl", "oldFunction", "Use newFunction instead")
// void oldFunction();
//..
// Here the string "bsl" refers to the library or Unit-Of-Release (UOR) that
// the deprecation occurs in. "oldFunction" is an arbitrary identifier for
// the feature being deprecated. Together the 'UOR' and 'FEATURE' are
// intended to form a unique enterprise-wide identifier for the feature being
// deprecated. Finally the string "Use newFunction instead" is a message for
// users of the deprecated feature.
//
// Marking 'oldFunction' in this way makes the deprecation of 'oldFunction'
// visible to code analysis tools. In addition, in a local build, warnings
// for uses of the deprecated entity can be enabled using a build macro
// 'BB_DEPRECATE_ENABLE_ALL_DEPRECATIONS_FOR_TESTING' (this macro *MUST* *NOT*
// be used as part of a cross-organization integration build such as a
// 'unstable' dpkg build, see {Concerns with Compiler Warnings}).
//
// Similarly, if we were deprecating a class 'OldType' we might write:
//..
//
// class BSLS_DEPRECATE_FEATURE("bsl", "OldType", "Use NewType instead")
// OldType {
// // ...
// };
//..
// Frequently, more than one C++ related entity may be associated with a
// deprecated feature. In that case we would want to use the same identifier
// for each entity we mark deprecated. To simplify this we might create a
// deprecation macro that is local to the component. For example, if we were
// deprecating a queue and its iterator in the 'bde' library we might write:
//..
// #define BDEC_QUEUE_DEPRECATE \.
// BSLS_DEPRECATE_FEATURE("bde", "bdec_queue", "Use bsl::queue instead")
//
// class BDEC_QUEUE_DEPRECATE bdec_Queue {
// //...
// };
//
// class BDEC_QUEUE_DEPRECATE bdec_QueueIterator {
// //...
// };
//..
// Sometimes several entities are deprecated as part of the same feature where
// separate messages are appropriate. For example, imagine we had a component
// 'bsls_measurementutil' that we were converting from imperial to metric
// units:
//..
// #define BSLS_MEASUREMEANTUTIL_DEPRECATE_IMPERIAL(MESSAGE) \.
// BSLS_DEPRECATE_FEATURE("bsl", "deprecate-imperial-units", MESSAGE)
//
// struct MeasurementUtil {
//
// BSLS_MEASUREMEANTUTIL_DEPRECATE_IMPERIAL("Use getKilometers instead")
// static double getMiles();
//
// BSLS_MEASUREMEANTUTIL_DEPRECATE_IMPERIAL("Use getKilograms instead")
// static double getPounds();
// };
//..
//
///Deprecating a Feature Across Multiple Headers
///- - - - - - - - - - - - - - - - - - - - - - -
// Frequently a feature being deprecated may span multiple components. For
// example, we may want to deprecate all the date and time types in the 'bde'
// library. In those instances one may define a macro in the lowest level
// component (e.g., define 'BDET_DATE_DEPRECATE_DATE_AND_TIME' in 'bdet_date').
// Alternatively, one might create a component specifically for the deprecation
// (e.g., define 'BDET_DEPRECATE_DATE_AND_TIME' in a newly created
// 'bdet_deprecate' component). The following code shows the latter, creating
// a new component, 'bdet_deprecate' in which to provide macros to deprecate
// code across 'bdet'.
//
// First, we create a new component, 'bdet_deprecate` and define the following
// macro:
//..
// // bdet_deprecate.h
//
// #define BDET_DEPRECATE_DATE_AND_TIME(MESSAGE) \.
// BSLS_DEPRECATE_FEATURE("bde", "date-and-time", MESSAGE)
//..
// We can use that macro to mark various components deprecated. Next, we mark
// an old type name as deprecated:
//..
// // bdet_date.h
//
// BDET_DEPRECATE_DATE_AND_TIME("Use bdlt::Date") typedef bdlt::Date Date;
//..
// Then we mark a class declaration as deprecated:
//..
// // bdet_calendar.h
//
// class BDET_DEPRECATE_DATE_AND_TIME("Use bdlt::PackedCalendar") Calendar {
// // ...
// };
//..
// Finally we mark a function as deprecated:
//..
// // bdet_dateimputil.h
//
// struct DateUtil {
//
// BDET_DEPRECATE_DATE_AND_TIME("Use bdlt::DateUtil instead")
// static bool isValidYYYYMMDD(int yyyymmddValue);
//
// // ...
// };
//..
// ==============================
// Component Configuration Macros
// ==============================
// This could be replaced with BSLS_COMPILERFEATURES_CPLUSPLUS, but for the
// moment, this header has 0 dependencies, which may be a useful feature to
// maintain.
#if (defined(__cplusplus) && (__cplusplus >= 201703L)) || \
(defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))
#define BSLS_DEPRECATE_FEATURE_IS_SUPPORTED
#endif
#if defined(BSLS_DEPRECATE_FEATURE_IS_SUPPORTED) && \
(defined(BB_DEPRECATE_ENABLE_ALL_DEPRECATIONS_FOR_TESTING) || \
defined(BSLS_DEPRECATE_FEATURE_ENABLE_ALL_DEPRECATIONS_FOR_TESTING))
#define BSLS_DEPRECATE_FEATURE_ANNOTATION_IS_ACTIVE
#else
#undef BSLS_DEPRECATE_FEATURE_ANNOTATION_IS_ACTIVE
#endif
// ====================================
// Implementation Details: Do *NOT* Use
// ====================================
#ifndef BSLS_DEPRECATE_FEATURE_ANNOTATION_IS_ACTIVE
#define BSLS_DEPRECATE_FEATURE_IMP(UOR, FEATURE, MESSAGE)
#else
#if defined(BB_DEPRECATE_ENABLE_JSON_MESSAGE) || \
defined(BSLS_DEPRECATE_FEATURE_ENABLE_JSON_MESSAGE)
#define BSLS_DEPRECATE_FEATURE_IMP(UOR, FEATURE, MESSAGE) \
[[deprecated("{\"library\": \"" UOR "\", \"feature\": \"" FEATURE \
"\", \"message\": \"" MESSAGE "\"}")]]
#else
#define BSLS_DEPRECATE_FEATURE_IMP(UOR, FEATURE, MESSAGE) \
[[deprecated(MESSAGE)]]
#endif // BB_DEPRECATE_ENABLE_JSON_MESSAGE
#endif
// If the number of arguments needs to be expanded, commit
// abd14c70a7c9fb38d9bf3fe225eb0966cb036c9f contains a variadic implementation
// similar to 'BSLIM_TESTUTIL_ASSERTV'.
// =================
// Annotation Macros
// =================
#define BSLS_DEPRECATE_FEATURE(UOR, FEATURE, MESSAGE) \
BSLS_DEPRECATE_FEATURE_IMP(UOR, FEATURE, MESSAGE)
#endif // INCLUDED_BSLS_DEPRECATEFEATURE
// ----------------------------------------------------------------------------
// Copyright 2022 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------