Binary compatibility

Binary compatibility

This plugin, located in the cache extensions/plugins/compatibility/compatibility.py allows defining custom rules for the binary compatibility of packages across settings and options. It has some built-in logic implemented, but can be customized.

The interface is a single function called def compatibility(conanfile) that receives a single conanfile object as argument. Its return will be equal to the compatibility() recipe method, an ordered list of variations over settings, options that is considered to be binary compatible. Conan will check that list in order for binary existence until one binary is found. The following would be valid syntax (but not an useful or working one, as it will fail in Windows, for example):

def compatibility(conanfile):
    result = []
    if conanfile.settings.build_type == "Debug":
        result.append({"settings": [("build_type", "Release")]})
    return result

Conan provides a default compatibility.py implementation that implements binary compatibility for different compiler.cppstd and compiler.cstd values. That is, by default it assumes that binaries built with different cppstd and cstd values (for the same compiler and compiler version) are binary compatible, and can be linked together without issues.

The compiler.cppstd must be defined in profiles in most C++ scenarios. If a binary for a given compiler.cppstd value doesn’t exist (that means, a binary built with exactly that setting), Conan default compatibility.py will iterate the supported cppstd values by that compiler version. It is possible to disable this behavior for any specific package, adding to the package conanfile.py recipe the extension_properties = {"compatibility_cppstd": False} attribute, read the extension_properties docs.

From Conan 2.4, the compiler.cstd setting is available. It will only be taken into account in the computation of packages package_id when their recipes explicitly declare the languages = "C" attribute.

Some important rules:

The built-in compatibility.py is subject to changes in future releases. To avoid being updated in the future, please remove the first comment # This file was generated by Conan.

Warning

The compatibility.py feature is in preview. The current default compatibility.py is experimental. See the Conan stability section for more information.