A.7. Version Control

The ML offers a version number and some features to check for version compatibility of related binaries. The project MLUtilities (see Section 2.6.2, “ MLUtilities) contains the necessary file mlVersion.h . Also see Section A.7, “Version Control” for source code changes. Usually, there is no need for additional checks in your code, because the ML automatically checks for the correct version (e.g., when calling MLInit() of the ML C-API (see Section 6.3, “mlAPI.h”) or when initializing a dynamically linked library with the ML_INIT_LIBRARY macro (see ML_INIT_LIBRARY)). It will print errors on version conflicts, but will not refuse operation when a version conflict occurs.

[Important]Important

The ML can check for correct versions when it is initialized and when dynamic linked libraries are linked on runtime. It, however, cannot check if different dynamic linked libraries are compatible between themselves.

The following macros are available on compile time for versioning:

  1. ML_MAJOR_VERSION

    The major release number that indicates general and essential changes to the ML (which usually imply binary and header file incompatibilities).

  2. ML_MAJOR_CAPI_VERSION

    Changes to this number indicate binary incompatibilities of the C-API of the ML which require a recompilation of applications using the ML via the C-API.

  3. ML_CPPAPI_VERSION

    Changes to this number indicate binary incompatibilities of the C++ interface of the ML which require a recompilation of all classes using C++ ML symbols. Also, changes to this number sometimes indicate C++ header file incompatibilities. Note that the C++ API is also considered changed when the C-API has changed.

  4. ML_CAPI_REVISION

    Changes to this number indicate a revision of the C-API of the ML which normally does not require a recompilation of applications using the ML via the C-API; this is typically caused by additional functionality in the C-API.

  5. ML_REVISION

    Changes to this number indicate any revision of the ML which does not influence the binary compatibility (also docs, comments, installers); thus dependent classes do not need to be recompiled.

  6. ML_VERSION_STRING

    The version string is put together by the above five strings, the individual strings are separated by ".". So, the version string would begin with:

    ML_MAJOR_VERSION.ML_MAJOR_CAPI_VERSION. (to be followed by the other three above strings).

The following functions are available for runtime version checks:

  1. void MLGetVersion(int *majorVersion, int *majorCAPIVersion, int *verCPPAPI, int *revCAPI, int *rev, const char **vString);

    Returns version information about the ML. It is legal to call it before the MLInitializeUtils() is called.

    For all parameters, a NULL may be passed if that parameter is not needed.

    • majorVersion Returns the compiled major release number specified by ML_MAJOR_VERSION.

    • majorCAPIVersion Returns the compiled major C-API version number specified by ML_MAJOR_CAPI_VERSION.

    • verCPPAPI Returns the compiled C++-API version number specified by ML_CPPAPI_VERSION.

    • rev Returns the compiled ML revision number specified ML_REVISION.

    • revCAPI Returns the compiled C-API revision number specified by ML_CAPI_REVISION.

    • vString Returns a null terminated character string as "majorVersion.majorCAPIVersion.revCAPI.verCPPAPI.rev".

  2. int MLIsCAPILinkCompatible(int majorVersion, int majorCAPIVersion, int revCAPI);

    Checks whether the ML API is link compatible. It is legal to call this function before MLInitializeUtils() is called. Normally, it is not necessary to call this function "manually" because the ML does these checks automatically when the ML is initialized or modules are loaded. A typical call looks like the following:

    Example A.2.  MLIsCAPILinkCompatible

    if (!MLIsCAPILinkCompatible(ML_MAJOR_VERSION, ML_MAJOR_CAPI_VERSION, ML_CAPI_REVISION))
    {
      handleErr();
    }

    A non-zero value (=true) is returned if binary compatibility is given, and 0 if not.

    Parameters are

    • majorVersion The major release number of the ML (normally specified by ML_MAJOR_VERSION).

    • majorCAPIVersion The major C-API version number of the ML-API (normally specified by ML_MAJOR_CAPI_VERSION).

    • revCAPI The revision number of the C-API of the ML-API (normally specified by ML_CAPI_REVISION).

  3. int MLIsCPPAPILinkCompatible(int majorVersion, int majorCAPIVersion, int verCPPAPI, int revCAPI);

    Checks whether the C++-API of the ML is link compatible. It is legal to call this function before MLInitializeUtils() is called.

    Normally, it is not necessary to call this function "manually" because the ML does these checks automatically when initializing the ML is initialized or modules are loaded. A typical call looks like the following:

    Example A.3.  MLIsCPPAPILinkCompatible

    if (!MLIsCPPAPILinkCompatible(ML_MAJOR_VERSION,
                                  ML_MAJOR_CAPI_VERSION,
                                  ML_CPPAPI_VERSION,
                                  ML_CAPI_REVISION))
    {
      handleErr();
    }

    It returns a non-zero value (=true) if binary compatibility is given, and it returns 0 if binary compatibility is not given. Parameters are

    • majorVersion The major release number of the ML (normally specified by ML_MAJOR_VERSION).

    • majorCAPIVersion The major C-API version number of the ML-API (normally specified by ML_MAJOR_CAPI_VERSION).

    • verCPPAPI The C++-API version number of the ML (normally specified by ML_CPPAPI_VERSION).

    • revCAPI The revision number of the C-API of the ML-API (normally specified by ML_CAPI_REVISION).