bsls_deprecatefeature

Macros
#define	BSLS_DEPRECATE_FEATURE_IMP(UOR, FEATURE, MESSAGE)
#define	BSLS_DEPRECATE_FEATURE(UOR, FEATURE, MESSAGE)    BSLS_DEPRECATE_FEATURE_IMP(UOR, FEATURE, MESSAGE)

Detailed Description

Outline

• Purpose
• Macros
• Description
  • Concerns with Compiler Warnings
  • Macro Reference
  • Configuration Reference
  • Usage
    • Example 1: Deprecating a Feature
    • Deprecating a Feature Across Multiple Headers

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);
 
    // ...
};

Macro Definition Documentation

BSLS_DEPRECATE_FEATURE

#define BSLS_DEPRECATE_FEATURE	(		UOR,
			FEATURE,
			MESSAGE
	)		BSLS_DEPRECATE_FEATURE_IMP(UOR, FEATURE, MESSAGE)

BSLS_DEPRECATE_FEATURE_IMP

#define BSLS_DEPRECATE_FEATURE_IMP	(		UOR,
			FEATURE,
			MESSAGE
	)