==============================
Plug-in Placement and Startup
==============================

Overview
--------

CLO automatically detects and loads plug-ins placed in specific directories at startup.  
This page explains where to place your compiled **.dll** (Windows) or **.dylib** (macOS) plug-ins,  
how each plug-in type behaves when CLO launches, and the required naming conventions for each plug-in type.

Default Plug-in Locations
-------------------------

Place your plug-in binaries in the following directories depending on your operating system:

- **Windows:** ``C:/Users/Public/Documents/CLO/Plugins``  
- **macOS:** ``$HOME/Documents/CLO/Plugins``

If the directory does not exist, create it manually.

Plug-in Behavior on Startup
---------------------------

+---------------------------+--------------------------------------------------------------+
| **Plug-in Type**          | **Behavior on Startup**                                      |
+===========================+==============================================================+
| **Library Window Plug-in**| Automatically loaded and executed when CLO starts.           |
|                           | Adds a custom tab or replaces the default Library view.      |
+---------------------------+--------------------------------------------------------------+
| **General API Plug-in**   | Loaded on startup and registered to the specified Export tab |
|                           | or menu location.                                            |
|                           | Developers can define a custom placement within the Export   |
|                           | menu during implementation.                                  |
+---------------------------+--------------------------------------------------------------+
| **Event Plug-in**         | Automatically activated at CLO startup, similar to the       |
|                           | Library plug-in. Runs event handlers in the background.      |
+---------------------------+--------------------------------------------------------------+

File Naming Rules
-----------------

CLO identifies plug-ins by their binary file names.  
Incorrect naming may prevent the plug-in from being loaded at startup.

+---------------------------+-------------------------------------------+-------------------------------------------+
| **Plug-in Type**          | **Windows (.dll)**                        | **macOS (.dylib)**                        |
+===========================+===========================================+===========================================+
| **Library Plug-in**       | ``CloLibraryAPI_Plugin.dll``              | ``libCloLibraryAPI_Plugin.dylib``         |
+---------------------------+-------------------------------------------+-------------------------------------------+
| **General API Plug-in**   | *Any file name is acceptable*             | *Any file name is acceptable*             |
+---------------------------+-------------------------------------------+-------------------------------------------+
| **Event Plug-in**         | ``cloEventAPI_Plugin.dll``                | ``libcloEventAPI_Plugin.dylib``           |
+---------------------------+-------------------------------------------+-------------------------------------------+

.. note::
   - The **Library** and **Event** plug-ins must use the exact names above for CLO to detect them.  
   - The **General API** plug-in can be freely named, as its registration depends on the plug-in code, not the filename.  
   - Filenames are **case-sensitive** on macOS.

Custom Plug-in Paths
--------------------

In addition to the default plug-in folders, CLO allows you to define custom plug-in search paths  
using the configuration file **defaultPlugInFolders.txt**.

Edit or create this file at the following location:

- **Windows:** ``C:\Users\Public\Documents\CLO\Configuration\API_Plug_in\defaultPlugInFolders.txt``  
- **macOS:** ``/Users/<username>/Documents/clo/Configuration/API_Plug_in/defaultPlugInFolders.txt``

**Example (macOS):**

.. code-block:: none

   /Users/alex/Projects/MyCLOPlugins
   /Users/alex/Documents/CLO/Plugins

CLO will check all folders listed in this file, along with the default locations,  
and automatically load valid plug-in binaries at startup.

Notes
-----

- **Release builds only:** Debug binaries (``.dll`` / ``.dylib``) will not load.  
- When updating a plug-in, replace the file and **restart CLO**.  
  Hot-reloading is not supported.  
- Ensure that all runtime dependencies (Qt, shared libraries) are accessible from your environment path.  
- You can include multiple plug-ins in the same folder, CLO will load all compatible plug-ins at startup.