Get Started with TCM
====================

To install Thread Composability Manager (TCM), follow one of the approaches below.

Install from Release Packages
-----------------------------

To install Thread Composability Manager from the release packages do the following:

1. Extract the downloaded binary archive;
2. Set the environment variables by using the script from the ``env`` subdirectory in the extracted
   path.


Example for Linux* OS:

.. code-block:: bash

    tar -xvf tcm-*.tgz
    cd tcm-<version>
    source env/vars.sh

Example for Windows* OS:

.. code-block:: bat

    powershell -Command "Expand-Archive -Path tcm-*.zip -DestinationPath . -Force"
    cd tcm-<version>
    call env\vars.bat

Install from Sources
--------------------

To install from sources do the following:

1. Download TCM sources either by checking out the repository or downloading sources from the
   releases page;
2. Configure and build TCM using CMake and a C++ compiler;
3. Install using CMake's :code:`--install` command.

Prerequisites
~~~~~~~~~~~~~

- CMake version 3.5 (or newer).
- C++ compiler that supports at least C++17 version of the C++ standard.
- HWLOC version 2.5 (or newer).

Configuring and building TCM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Assuming TCM sources are in the current working directory, configuration involves running
:code:`cmake`.

For example, to build TCM in the :code:`build` subdirectory, invoke

.. code-block:: bash

    cmake -S . -B build

Additionally, the following configuration options can be passed to :code:`cmake`:

+--------------------------------+-----------------------------------------------------------------+
| Configuration Option           | Description                                                     |
+================================+=================================================================+
| :code:`-DTCM_TEST={ON,OFF}`    | When set to :code:`ON` (the default), targets for TCM tests     |
|                                | will also be created.                                           |
+--------------------------------+-----------------------------------------------------------------+
| :code:`-DTCM_STRICT={ON,OFF}`  | When set to :code:`ON` (the default), warnings generated by     |
|                                | the compiler will be treated as errors.                         |
+--------------------------------+-----------------------------------------------------------------+

To build the TCM project, invoke :code:`cmake --build .` from the directory where the project was
configured.

Installing the project
~~~~~~~~~~~~~~~~~~~~~~

To install the built TCM, invoke :code:`cmake --install .` from the directory where the project was
built.

.. note:: Refer to `CMake Reference Documentation <https://cmake.org/cmake/help/latest/>`_ for
          additional options that can be provided to CMake, including build type and installation
          path.

Version Information
-------------------

TCM provides macros, an environment variable, and a function that helps determine version and
runtime information of the library used.

Version Macros
~~~~~~~~~~~~~~

TCM defines the following macros related to versioning.

+---------------------------+----------------------------------------------------------------------+
| Name                      | Description                                                          |
+===========================+======================================================================+
| :code:`TCM_VERSION_MAJOR` | Macro defined to integral value representing major version of the    |
|                           | library.                                                             |
+---------------------------+----------------------------------------------------------------------+
| :code:`TCM_VERSION_MINOR` | Macro defined to integral value representing minor version of the    |
|                           | library.                                                             |
+---------------------------+----------------------------------------------------------------------+
| :code:`TCM_VERSION_PATCH` | Macro defined to integral value representing patch version of the    |
|                           | library.                                                             |
+---------------------------+----------------------------------------------------------------------+
| :code:`TCM_VERSION`       | Macro defined to integral value combining major, minor, and patch    |
|                           | version together.                                                    |
+---------------------------+----------------------------------------------------------------------+

TCM Runtime Version
~~~~~~~~~~~~~~~~~~~

Runtime version information can be obtained using the function :code:`tcmGetVersion`:

.. code:: cpp

    unsigned tcmGetVersion()

Returns the value of the :code:`TCM_VERSION` macro.

Environment Variable
~~~~~~~~~~~~~~~~~~~~

When the environment variable :code:`TCM_VERSION` is set to :code:`1`, additional information is
printed to :code:`stderr`. The lines start with :code:`"TCM: <value>"`, and may change from version
to version.

Enabling Thread Composability Manager
-------------------------------------

By default, Thread Composability Manager is disabled. To enable it, set :code:`TCM_ENABLE=1`
environment variable when starting an application.