.. _download_and_install:

Download and Installation
=========================

This section provides everything you need to download and install the **CosmicSDK** on your development machine.

Platform Support
----------------

CosmicSDK is currently available for the following platforms:

- **Windows** (x64 and x86 architectures, supporting both **MSVC** and **MinGW** compilers)
- **macOS** (both **Intel** and **Apple Silicon (ARM)** architectures)
- **Linux** (both **x64** and **ARM64** architectures)

Download Links
--------------

You can download the latest precompiled SDK binaries and development headers using the links below:

**Windows**

We provide two download options for Windows users: a standard `.exe` installer, and a `.rename` version to help bypass certain download restrictions.

- `x64 MinGW (.exe) <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-x64-mingw.exe>`__
- `x64 MinGW (.rename) <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-x64-mingw.rename>`__ – *Same installer file but with a `.rename` extension to prevent some systems from blocking direct `.exe` downloads. You will need to rename the file back to `.exe` before running it.*

- `x64 MSVC (.exe) <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-x64-msvc.exe>`__
- `x64 MSVC (.rename) <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-x64-msvc.rename>`__

- `x86 MSVC (.exe) <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-x86-msvc.exe>`__
- `x86 MSVC (.rename) <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-x86-msvc.rename>`__

Each installer will install the following components:

- Binary `.dll` files for Debug and Release profiles
- C/C++ headers
- Documentation files
- Example projects

**macOS**

The SDK is distributed as architecture-specific `.zip` archives:

- `Download for macOS (ARM - Apple Silicon) [.zip] <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-mac-arm-binaries.zip>`__
- `Download for macOS (Intel) [.zip] <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-mac-intel-binaries.zip>`__

Each archive contains:

- Dynamic libraries (`.dylib`)
- C/C++ headers
- Documentation files
- Example projects

After extracting the `.zip` file, no further installation is required. You can link directly to the provided libraries in your Xcode or command-line build environments.

**Linux**

The SDK is distributed for Linux as architecture-specific compressed archives.

- `Download for Linux (x64) [.zip] <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-linux-x64-binaries.zip>`__
- `Download for Linux (ARM64) [.zip] <https://cdn.binho.io/sw/CosmicSDK/latest/cosmic_sdk-linux-arm64-binaries.zip>`__

Each archive contains:

- Dynamic libraries (`.so`)
- Static libraries (`.a`)
- C/C++ headers
- Documentation files
- Example projects
- Linux setup helper script (`scripts/install_udev_rules.sh`)
- Linux udev rule file (`udev/65-binho-hid.rules`)

After extracting the archive, no installer is required.

Installation Instructions
-------------------------

**Windows**

To install the CosmicSDK on Windows:

1. **Download the Installer**

   Use one of the links provided above:
   
   - `.exe` file (recommended)
   - `.rename` file (rename it to `.exe` before running)

2. **Run the Installer**

   Double-click the installer to launch the setup wizard.

3. **Choose Installation Directory**

   By default, the SDK will be installed to:

   ::

       C:\CosmicSDK

   .. image:: ../_static/installation/windows_1.jpg
      :alt: Default installation path
      :scale: 80%

   If you'd like to install it to a different directory (e.g., `C:\\cosmicsdk110`), type the full path in the **Destination Folder** field or use the **Browse...** button.

   .. image:: ../_static/installation/windows_2.jpg
      :alt: Custom installation path
      :scale: 80%

.. note::
   
   If the specified directory does not exist, the installer will automatically create it.

4. **Complete Installation**

   Click **Install** to begin. Once the progress bar is complete, click **Close** to exit the installer.

   .. image:: ../_static/installation/windows_3.jpg
      :alt: Installation completed
      :scale: 80%

After installation, you can navigate to the installation directory to access the  `debug`, `examples`, and `include` folders, as well as the documentation files and release `.dll` files.

    .. image:: ../_static/installation/windows_4.jpg
        :alt: Installation completed
        :scale: 50%

**macOS**

To install the CosmicSDK on macOS:

1. **Download the Archive**

   Choose the correct `.zip` file for your system architecture:

   - Intel-based Macs: `cosmic_sdk-mac-intel-binaries.zip`
   - Apple Silicon (ARM) Macs: `cosmic_sdk-mac-arm-binaries.zip`

2. **Extract the Archive**

   After downloading, double-click the `.zip` file to extract its contents.

   You will see a folder named something like:

   ::

       cosmic_sdk-mac-{arch}-binaries/

   Inside this folder, you’ll find:

   - `include/` – C/C++ header files
   - `lib/` – Precompiled `.dylib` binaries
   - `examples/` – Sample projects to help you get started
   - `README.txt` and `LICENSE.txt`

3. **Use the SDK**

   There is no installation step required. You can begin using the SDK immediately. To do so, follow the steps described in :ref:`examples`.

.. tip::
   
   If you’re using a macOS security feature like Gatekeeper, you may need to allow execution of third-party libraries in System Settings > Security & Privacy.

**Linux**

To install the CosmicSDK on Linux:

1. **Download the Linux archive**

   Use one of the Linux links listed above.

2. **Extract the archive**

   .. code-block:: bash

      tar -xzf <linux-package-file>.tar.gz
      cd <cosmicsdk-linux-package-dir>

3. **Use the extracted artifacts directly**

   CosmicSDK does not require a system-wide installer on Linux. Use:

   - ``<cosmicsdk-linux-package-dir>/include`` for headers
   - ``<cosmicsdk-linux-package-dir>/lib`` for shared/static libraries
   - ``<cosmicsdk-linux-package-dir>/examples`` for sample projects

4. **(Recommended) Install udev rules for non-root USB access**

   .. code-block:: bash

      chmod +x ./scripts/install_udev_rules.sh
      sudo ./scripts/install_udev_rules.sh

   Unplug and replug your Binho device after installing rules.

5. **Validate with an example**

   .. code-block:: bash

      cd examples/blocking_api/system/cpp
      cmake -B build -DLIBRARY_PATH="<cosmicsdk-linux-package-dir>/lib" -DINCLUDE_PATH="<cosmicsdk-linux-package-dir>/include"
      cmake --build build
      LD_LIBRARY_PATH="<cosmicsdk-linux-package-dir>/lib:$LD_LIBRARY_PATH" ./build/example_cpp_dynamic
