Browse
 
Tools
Rss Categories

Deprecated Functionality

Reference Number: AA-01934 Views: 6740 0 Rating/ Voters

As we improve the LumenVox API over time, we sometimes remove or change functionality. We try to avoid making these changes, as maintaining backwards compatibility is an important goal for us, but as the interface changes it is sometimes in the best interest of developers for us to deprecate certain functionality.

Rather than just dropping functions without warning, we generally mark them as deprecated, which means they will be removed in a future release. Developers who attempt to compile their code with deprecated functions will see a warning message.

For instance, if your code were to call  LV_SRE_LoadGlobalGrammar (deprecated in version 12.1), the output from the compiler will be the following warning:

"The API function is deprecated. Use LV_SRE_LoadGrammar instead."  

The compiler will typically indicate the line number that this warning comes from.

Our goal is to give developers plenty of notice before functionality is removed. This alone does not prevent the application from compiling successfully, or being used successfully.

Also, depending on the circumstances, we may leave some functions marked as deprecated, but change them so they do not actually do anything -- thus developers who use them will not receive compilation errors (except the warnings mentioned earlier).

Deprecated functionality is moved to the LV_SRE_Deprecated header file, along with the macros that provide the warning messages. Developers are welcome to browse that header file and find a list of all the functionality that is currently deprecated

After a reasonable period of time and several versions of the software, deprecated functionality is removed entirely. Compiling software using these removed functionality will generate an error message like:

"This class of API functions is no longer supported."

More rare than deprecated functions are deprecated/removed type declarations. In the event that we do remove a type, a warning would be generated that looks like:

"The type is deprecated. Use NEW_AND_IMPROVED_TYPE instead."

Ignoring Deprecated Warnings

In LumenVox 12.1 and later, developers can set a flag called IGNORE_LV_DEPRECATED in the compiler which will suppress warnings related to deprecated functionality. We encourage developers to take heed of these warnings -- as they are likely to become errors in the future -- but we do support suppressing these messages.

In both Windows and Linux, this flag can be defined inline within an application's code, such as:

#define IGNORE_LV_DEPRECATED

This should be done so that the definition exists before any LumenVox headers are read (e.g. at the top of every file, or at the top of a common header file).

Or, for both Windows and Linux, these can be defined as a compiler preprocessor directive. We recommend using the preprocessor directive, as there is no way to accidentally add a source module to the project which does not have the declaration. 

Windows (Visual Studio)

  1. In Visual Studio, go to Project Properties
  2. Select C/C++
  3. Select Preprocessor
  4. Under the "Preprocessor Definitions" option, add the new IGNORE_LV_DEPRECATED flag.  If there are existing declarations there, simply add a semi-colon immediately before this new entry.

This has the effect of passing a /D declaration with the IGNORE_LV_DEPRECATED to the compiler whenever building.

For more information, see the MSDN article on using preprocessor declarations in Visual Studio.

Linux (GCC)

In GCC, modify the makefile to add the following to the CPPFLAGS (c++ code) or CFLAGS (c-code) line:

 -DIGNORE_LV_DEPRECATED 

(Note the space both before and after the declaration.)

If you don't have a CPPFLAGS or CFLAGS line in your makefile, or if you don't have a makefile, or if you are setting compiler flags in some other way, then however you are doing it will have to include the -DIGNORE_LV_DEPRECATED declaration.

See the GCC Preprocessor options for more details.