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
    ├── repositories.yaml           # Maps package names to Git repository URLs
    ├── secrets.yaml                # Stores GitHub API tokens (add to .gitignore!)
    └── RAISIN_IGNORE               # List of packages to exclude from builds


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

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

**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**
  Stores sensitive information, primarily the GitHub Personal Access Tokens (PATs) required for uploading releases. **This file should never be committed to version control.**

  .. code-block:: yaml

      # secrets.yaml
      gh_tokens:
        your-org: "ghp_xxxxxxxxxxxxxxxxxxxxxxxx"
        another-org: "ghp_yyyyyyyyyyyyyyyyyyyyyyyy"

**RAISIN_IGNORE**
  A simple text file listing the names of packages in ``src/`` that should be ignored by the build system. Each package name should be on a new line.

  .. code-block:: text

      # RAISIN_IGNORE
      experimental_package
      broken_package