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

The Raisin script is controlled via command-line arguments. This page provides a quick reference of all available commands.

For detailed information, see:

* :doc:`package_management` - Package installation and index commands
* :doc:`git_integration` - Git repository management commands

.. program:: raisin.py

.. code-block:: shell

    python raisin.py <command> [options]

Global Options
--------------

.. cmdoption:: --yes

    Answers 'yes' to all prompts, like overwriting release assets.

Build & Release Commands
-------------------------

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

    Configures the project for a local development build.

    Running ``python raisin.py`` with no arguments performs the same setup for all packages.

    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 only configures the build for those specific targets and their dependencies. Target names map to entries in ``RAISIN_BUILD_TARGETS.yaml`` (see :doc:`raisin_package`); each entry can expand to multiple glob patterns that control which packages are included. If no targets are provided, all projects discovered in ``src/`` are configured.

.. cmdoption:: build [target ...] [debug|release ...] [install]

    Compiles the project locally.

    This command runs the ``setup`` step with the same target filtering rules, then compiles the project using Ninja.
    * Omit build types to build in ``debug`` by default.
    * Provide one or both build types (``debug`` and/or ``release``) to run them sequentially.
    * Add ``install`` to run ``ninja install`` after each build.
    * When targets are provided, they must match entries in ``RAISIN_BUILD_TARGETS.yaml``; otherwise all detected projects are built.

.. cmdoption:: release <target ...> [debug|release]

    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 defaults to ``release`` if not specified.

Package Management Commands
----------------------------

See :doc:`package_management` for detailed documentation.

.. cmdoption:: install [pkg>=1.0] [debug|release]

    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 specifier can be a simple name (e.g., ``my_pkg``) or include a version constraint (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 defaults to ``release`` if not specified.

.. cmdoption:: index local

    Scans local packages and validates their dependency graph.

    This command scans local ``src/`` and ``release/install/`` packages and validates their dependency graph, printing a colored report of the status.

.. cmdoption:: index release [<package_name>]

    Lists available remote packages from GitHub Releases.

    * Without a package name, it lists all available packages.
    * With a package name, it lists all available versions for that package.

Git Integration Commands
-------------------------

See :doc:`git_integration` for detailed documentation.

.. cmdoption:: git status

    Fetches and shows the detailed sync status for all local repositories.

.. cmdoption:: git pull [remote]

    Pulls changes for all local repositories from the specified remote.

    * Defaults to 'origin' if no remote is specified.

.. cmdoption:: git setup <remote:user ...>

    Clears all existing remotes and sets up new ones for all repos in ``src/``.

    Example:

    .. code-block:: shell

        python raisin.py git setup origin:raisim raion:raionrobotics

Help
----

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

    Displays a detailed help message.