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:

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.

# 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).

# repositories.yaml
project_a:
  url: [email protected]:your-org/project_a.git
project_b:
  url: [email protected]: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.

# 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.

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