Raisin master files and folders
===================================

A Raisin-managed project relies on a specific directory structure and a few key configuration files.

Directory Layout
---------------------

A typical project root will look like this:

.. code-block:: text

    my_raisin_project/
    ├── generated/                  # Auto-generated C++ headers from .msg/.srv/.action
    ├── install/                    # Output directory for local development builds
    ├── messages/                   # (Optional) Global .msg/.srv/.action files
    ├── precompiled/                # (Optional) Pre-compiled third-party libraries
    ├── release/                    # Contains release builds, archives, and installed packages
    │   ├── build/                  # Build artifacts for each target
    │   └── install/                # Directory for installed packages
    ├── src/                        # Source code for all your C++ subprojects
    │   ├── repo_a/                 # This repo is a collection of raisin packages
    │   │   ├── raisin_package_a/   # this folder is a raisin package
    │   │   ├── raisin_package_b/
    │   │   ├── raisin_package_c/
    │   │   └── ...
    │   └── raisin_package_d/       # this repo is a single raisin package
    ├── templates/                  # C++ header templates for code generation and some code templates for raisin packages
    ├── CMakeLists.txt              # Top-level CMake file, auto-generated by Raisin
    ├── raisin.py                   # The main Raisin script
    ├── configuration_setting.yaml  # Main configuration (tokens, user_type, packages to ignore)
    ├── repositories.yaml           # Maps package names to Git repository URLs
    ├── secrets.yaml                # (Deprecated) Use configuration_setting.yaml instead
    └── RAISIN_IGNORE               # (Deprecated) Use packages_to_ignore in configuration_setting.yaml


The details of the raisin package structure can be found in the raisin package chapter.

Configuration Files
-------------------

**configuration_setting.yaml** (Required)
  The main configuration file for Raisin. **This file should never be committed to version control** as it contains sensitive tokens.

  .. code-block:: yaml

      # configuration_setting.yaml
      user_type: devel  # Required: either 'user' or 'devel'

      gh_tokens:
        your-org: "ghp_xxxxxxxxxxxxxxxxxxxxxxxx"
        another-org: "ghp_yyyyyyyyyyyyyyyyyyyyyyyy"

      packages_to_ignore:
        - experimental_package
        - broken_package

  **Required fields:**

  * ``user_type``: Must be either ``'user'`` or ``'devel'``. This determines the build behavior and access permissions.

  **Optional fields:**

  * ``gh_tokens``: GitHub Personal Access Tokens (PATs) required for uploading releases and accessing private repositories. Keys are organization/owner names, values are the tokens.
  * ``packages_to_ignore``: List of package names in ``src/`` that should be excluded from builds.

**repositories.yaml**
  Maps package names to their source Git repository URLs. This is essential for the ``release`` command (to know where to upload) and the ``install`` command (to know where to download from).

  .. code-block:: yaml

      # repositories.yaml
      project_a:
        url: git@github.com:your-org/project_a.git
      project_b:
        url: git@github.com:your-org/project_b.git

**secrets.yaml** (Deprecated)
  Legacy configuration file for GitHub tokens. For backward compatibility, Raisin will fall back to this file if ``configuration_setting.yaml`` doesn't exist. New projects should use ``configuration_setting.yaml`` instead.

  .. code-block:: yaml

      # secrets.yaml (deprecated - use configuration_setting.yaml)
      gh_tokens:
        your-org: "ghp_xxxxxxxxxxxxxxxxxxxxxxxx"
      user_type: devel

**RAISIN_IGNORE** (Deprecated)
  Legacy file for listing packages to ignore. For backward compatibility, this is still supported, but new projects should use the ``packages_to_ignore`` field in ``configuration_setting.yaml`` instead.

  .. code-block:: text

      # RAISIN_IGNORE (deprecated - use configuration_setting.yaml)
      experimental_package
      broken_package