Porting Guide for New Versions

Modules
	Porting from FLAC 1.1.2 to 1.1.3
	Porting from FLAC 1.1.3 to 1.1.4
	Porting from FLAC 1.1.4 to 1.2.0
	Porting from FLAC 1.3.4 to 1.4.0

Detailed Description

This module describes differences in the library interfaces from version to version. It assists in the porting of code that uses the libraries to newer versions of FLAC.

One simple facility for making porting easier that has been added in FLAC 1.1.3 is a set of #defines in export.h of each library's includes (e.g. include/FLAC/export.h). The #defines mirror the libraries' libtool version numbers, e.g. in libFLAC there are FLAC_API_VERSION_CURRENT, FLAC_API_VERSION_REVISION, and FLAC_API_VERSION_AGE. These can be used to support multiple versions of an API during the transition phase, e.g.

#if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
  legacy code
#else
  new code
#endif

The source will work for multiple versions and the legacy code can easily be removed when the transition is complete.

Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in include/FLAC/export.h), which can be used to determine whether or not the library has been compiled with support for Ogg FLAC. This is simpler than trying to call an Ogg init function and catching the error.