.. _integration:

Adding the CosmicSDK to your projects
=====================================

This section explains how to integrate the CosmicSDK library into your C or C++ projects, using CMake as the build system.

Prerequisites
-------------

Before integrating the SDK, ensure your development environment includes:

- A **C++17-compatible compiler**
- **CMake** version 3.10 or higher
- A **Binho Supernova** or **Binho Pulsar** USB Host Adapter
- **HIDAPI** installed and accessible to your build system *(required by CosmicSDK)*

Installation & Setup
---------------------

1. **Download the CosmicSDK**

   Follow the instructions in :ref:`download_and_install` to install the SDK for your platform.

2. **Add the SDK to Your Project**

   Use `target_include_directories` and `target_link_libraries` in your `CMakeLists.txt`:

   .. code-block:: cmake

      target_include_directories(your_project_name PUBLIC path/to/cosmicsdk/include)
      target_link_libraries(your_project_name path/to/cosmicsdk/library)

   Replace `path/to/...` with the actual paths to your CosmicSDK installation.

.. important::

   💡 Don't forget to also link **HIDAPI** to your project since it is a dependency of CosmicSDK.

3. **Runtime Considerations**

   - On **Windows**, ensure ``cosmicsdk.dll`` is discoverable (for example, copied near the executable or in ``PATH``).
   - On **macOS**, ensure ``libcosmicsdk.dylib`` is discoverable (for example, ``DYLD_LIBRARY_PATH`` or rpath).
   - On **Linux**, ensure ``libcosmicsdk.so`` is discoverable (for example, ``LD_LIBRARY_PATH`` or rpath).

Example
-------

Here’s a minimal example of a complete `CMakeLists.txt`:

.. code-block:: cmake

   cmake_minimum_required(VERSION 3.10)
   project(MyCosmicProject)

   set(CMAKE_CXX_STANDARD 17)

   add_executable(my_app main.cpp)

   target_include_directories(my_app PUBLIC /path/to/CosmicSDK/include)
   target_link_libraries(my_app /path/to/CosmicSDK/lib/libcosmicsdk.dylib)  # Or .dll on Windows

   find_package(HIDAPI REQUIRED)
   target_link_libraries(my_app HIDAPI::HIDAPI)


For more detailed examples and advanced usage, refer to the :ref:`examples` section of the documentation and the examples projects included with the CosmicSDK installation.