Command-Line Usage
==================

The Raisin script is controlled via command-line arguments.

.. program:: raisin.py

.. code-block:: shell

    python raisin.py <command> [options]

Core Commands
-------------

.. cmdoption:: setup [target ...]

    Configures the project for a local development build.

    This command performs the core setup tasks:
    1. Finds all ``.msg``, ``.srv``, and ``.action`` files.
    2. Generates the corresponding C++ header files in the ``generated/`` directory.
    3. Scans all projects in ``src/`` to build a dependency graph.
    4. Generates a top-level ``CMakeLists.txt`` with all projects included in the correct build order.

    If one or more ``[target ...]`` names are provided, it will only configure the build for those specific targets and their dependencies. If no targets are provided, it configures all projects found in ``src/``.

.. cmdoption:: build <release|debug> [install]

    Compiles the project locally.

    This command runs ``cmake`` and ``ninja`` to build the code configured by the ``setup`` command.
    * You must specify the build type: ``release`` or ``debug``.
    * If the optional ``install`` argument is provided, the build artifacts will be installed into the ``install/`` directory after compilation.

.. cmdoption:: release <target ...> [build_type]

    Creates and distributes a formal release package.

    This command automates the entire release process for one or more targets. For each target, it:
    1. Reads the ``release.yaml`` file to get version and dependency information.
    2. Performs a clean build and installs the artifacts to a dedicated directory under ``release/install/``.
    3. Compresses the installed artifacts into a ``.zip`` archive named with the convention: ``{target}-{os}-{arch}-{build_type}-v{version}.zip``.
    4. Uploads the archive to the corresponding GitHub Release, creating the release if it doesn't exist.

    * ``build_type`` can be ``release`` (default) or ``debug``.

.. cmdoption:: install [package_spec ...] [build_type]

    Downloads and installs pre-compiled packages and their dependencies.

    This command functions as a package manager. It recursively resolves and installs all required packages.
    * A ``package_spec`` can be a simple name (e.g., ``my_pkg``) or include a version specifier (e.g., ``my_pkg>=1.2.3``).
    * If no packages are specified, it automatically scans for projects in the ``src/`` directory and treats them as targets to be fulfilled.
    * ``build_type`` can be ``release`` (default) or ``debug``.

.. cmdoption:: help, -h, --help

    Displays a detailed help message.