Building & Distributing
=======================

The ForkBit CLI packages your plugin into a ``.forkbit`` file (a ZIP archive)
ready for installation.

Validate
--------

Always validate before building:

.. code-block:: bash

   forkbit plugin validate release_notes

The validator checks:

- ``plugin.json`` structure and field types
- Entry point file exists and has a ``BasePlugin`` subclass
- All imports are covered by stdlib, ``forkbit_sdk``, or declared requirements

Build for development
---------------------

.. code-block:: bash

   forkbit plugin build release_notes

This creates a ``.forkbit`` file for your current platform. Use this for
local testing.

Build for release
-----------------

.. code-block:: bash

   forkbit plugin release release_notes

This builds for all supported platforms by downloading platform-specific
wheels for each target:

- ``macos_arm64`` — Apple Silicon Macs
- ``macos_x86_64`` — Intel Macs
- ``windows_x86_64`` — Windows
- ``linux_x86_64`` — Linux

If your plugin has no native dependencies (only pure Python packages),
a single universal build is created.

Platform exclusions
~~~~~~~~~~~~~~~~~~~

If your plugin doesn't support a platform, exclude it in ``plugin.json``:

.. code-block:: json

   {
     "exclude_platforms": ["windows_x86_64", "linux_x86_64"]
   }

Source protection
~~~~~~~~~~~~~~~~~

To ship compiled ``.pyc`` files instead of source:

.. code-block:: bash

   forkbit plugin release release_notes --protect

Dependencies
------------

Add third-party packages to ``requirements`` in ``plugin.json``:

.. code-block:: json

   {
     "requirements": ["requests>=2.28", "pyyaml"]
   }

The build system automatically vendors dependencies into the ``.forkbit``
archive. Users don't need to install anything — the plugin is self-contained.

.. note::

   ``forkbit_sdk`` and ``PySide6`` are provided by the app and should
   **not** be listed in requirements.

Installation
------------

Users install plugins by opening the ``.forkbit`` file in ForkBit, or by
placing it in the plugin cache at
``~/.forkbit/plugin_cache/<plugin_id>/<version>/``.