.. _getting-started-imagesdk-cpp-label:

ImageSDK : C++
~~~~~~~~~~~~~~

The following section describe how to setup a CMake project, that works for both Windows and Linux based operating systems. Further, the CMake project automatically downloads the newest SDK binaries.

Build & Runtime Prerequisites
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Depending on the target platform, our SDK's depends on different system libraries.

Windows
"""""""

* Windows 10 (x64)
* CMake 3.13 or later
* MSVC 2019 or later

On Windows CMake will output Visual Studio (``*.vcxproj``) project files. So, if you prefer to work in Visual Studio, you can do that.

.. tip::
    Visual Studio 2019 actually include (optional) built-in support for working directly with CMake files. This means there is no need to output ``vcxproj`` files at all.

    However, the way to configure projects and debug parameters are different from the approach used with normal Visual C++ projects.

    You can add the optional CMake component from the *Visual Studio Installer* application.

Linux
"""""

* Ubuntu 20.04 (Focal) or later
* CMake 3.13 or later
* Either: *GCC 7.5 or later* or *Clang 10 or later*
* ``libpthread``

You can of course use older Ubuntu's or other Linux distros. We use Ubuntu 20.04 here, because it has a later CMake than 3.13 built into its *apt-get* repositories.

.. caution:: *Ubuntu 18.04 (Bionic Beaver)* has a too old CMake (3.10) as part of its default *apt-get* repositories. If you wish to use *Bionic*, you must install CMake directly from its website.

We provide 3 different binary versions of our SDK libraries for Linux, compiled with these compilers:

+-------+-------+-------+
|       | AMD64 | ARM64 |
+=======+=======+=======+
| GCC   | 7.5   | 8.2   |
+-------+-------+-------+
| Clang | 10    | *N/A* |
+-------+-------+-------+

You should use the same or a newer GCC or Clang version, to ensure the :term:`ABI`'s are compatible.

.. note:: In contrast to our Windows releases, we provide only a *Release* build of our libraries on Linux. Since GCC / Clang allows linking between libraries built using *Debug* and *Release* configurations.

Get the ImageSDK
^^^^^^^^^^^^^^^^

Getting a copy of the ImageSDK library files is a straightforward process. Simply fill out the request form to get access to the download.

`ImageSDK Download`_

We will return to you with a link where you can download the ImageSDK library version you need. This documentation pertains to the release: |imgsdkversion|.

Set up Your Project
^^^^^^^^^^^^^^^^^^^

Continue here once your download request has been processed and you have the ImageSDK in your possession.

Create a project directory and name it something like ``hello_world``. This folder will serve as the home for your sample project, including the ImageSDK library you downloaded.

.. code:: sh

    $ mkdir hello_world
    $ cd hello_world

Unzip the ImageSDK archive into your ``hello_world`` project directory.

Source Code
^^^^^^^^^^^

Now, let us add some example code that calls the ImageSDK. Create a new (empty) text file called ``main.cpp``. Open the file in your favorite text editor and insert this content:

.. literalinclude:: ../../labels/cppImageProjectTemplateSource
    :language: cpp

CMake File
^^^^^^^^^^

Still inside the ``hello_world`` directory, create a new text file called ``CMakeLists.txt`` and insert this content:

.. literalinclude:: ../../labels/cppImageProjectTemplate
    :language: cmake
    :linenos:

.. content-if::
    :format: html


The CMake project file assumes that ImageSDK is located in the same directory as the ``CMakeLists.txt`` file itself.

In short, everything above line 27 determines the correct library files to use for *Windows*, *Linux*, and *Linux ARM64* systems.

Below line 27, we define our executable (called ``hello_world``) and specify that it should link dynamically with ImageSDK. Below line 40, we instruct CMake to copy all the runtime dependencies to the target output directory.

.. note:: **On Linux**, CMake automatically builds our executable with an embedded :term:`RPATH` that points to the SDK library files inside the project directory. The :term:`RPATH` will ensure the executable works without requiring any file copying, as long as we run within the development setup.

.. See :ref:`cmake-in-depth-label` where we examine this ``CMakeLists.txt`` in greater detail.

Build & Run
^^^^^^^^^^^

By CMake convention, we should create a new directory called ``build``, inside our project folder. Therefore, ``cd`` into this new ``build`` directory, before running two ``cmake`` commands to configure CMake, and compile the project:

.. code:: sh

    $ mkdir build
    $ cd build
    $ cmake ..
    $ cmake --build .

The first ``cmake`` command tells CMake to generate a :term:`target build system` project, from our ``CMakeLists.txt`` file. The second ``cmake`` command triggers CMake to build the project using that target build system.

.. tip::
    **On Windows** the default target build system is *Visual Studio projects*. When you run ``cmake ..`` a ``.vcxproj`` is created for the executable in our project. Then the ``cmake --build`` command will trigger the *MSBuild* tool, to build the Visual Studio project.

    **On Linux** the default target build system is *Unix Makefiles*. When ``cmake ..`` is run, *Makefiles* are created from your CMake project file. The second command ``cmake --build`` simply triggers the ``make`` command.

Lastly, let's run the ``hello_world`` application. You should see something similar to this:

.. content-if::
    :format: html

    .. code-tabs::

        .. code-tab:: sh
            :title: Linux (sh)

            $ ./hello_world
            Open IIQ file
            Do the conversion...
            Write image to tiff file...
            Done!
            $

        .. code-tab:: powershell
            :title: Windows (PS)

            PS> .\\Debug\\hello_world.exe
            Open IIQ file
            Do the conversion...
            Write image to tiff file...
            Done!
            PS>

.. content-if::
    :format: pdf

    **On Linux:**

    .. code:: sh

        $ ./hello_world
        Open IIQ file
        Do the conversion...
        Write image to tiff file...
        Done!
        $

    **On Windows:**

    .. code:: powershell

        PS> .\\Debug\\hello_world.exe
        Open IIQ file
        Do the conversion...
        Write image to tiff file...
        Done!
        PS>

Notice, that the location of the executable file differs between the *target build systems*. Visual Studio likes to position the binary inside a directory named after the compile configuration.